Add Evolver Codex plugin

autogame-17 · autogame-17 · commit 14c75d8e76f3 · 2026-06-04T20:19:36.000+08:00
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
@@ -0,0 +1,20 @@
+{
+  "name": "evomap-private",
+  "interface": {
+    "displayName": "EvoMap Private"
+  },
+  "plugins": [
+    {
+      "name": "evolver",
+      "source": {
+        "source": "local",
+        "path": "./plugins/evolver"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
diff --git a/README.md b/README.md
@@ -0,0 +1,34 @@
+# Evolver Codex Plugin
+
+Private EvoMap marketplace repository for the Evolver Codex Desktop plugin.
+
+## Install
+
+Add this marketplace to Codex:
+
+```bash
+codex plugin marketplace add EvoMap/evolver-codex-plugin
+```
+
+Then install the plugin:
+
+```bash
+codex plugin add evolver@evomap-private
+```
+
+Start a new Codex thread after installation so the bundled skill is loaded.
+
+## Plugin
+
+The plugin lives at:
+
+```text
+plugins/evolver
+```
+
+It packages a Codex skill for using Evolver, EvoMap's GEP-powered self-evolution engine, from Codex Desktop.
+
+Official Evolver sources:
+
+- https://github.com/EvoMap/evolver
+- https://evomap.ai
diff --git a/plugins/evolver/.codex-plugin/plugin.json b/plugins/evolver/.codex-plugin/plugin.json
@@ -0,0 +1,43 @@
+{
+  "name": "evolver",
+  "version": "0.1.0",
+  "description": "Official Codex Desktop plugin for the Evolver GEP-powered self-evolution engine.",
+  "author": {
+    "name": "EvoMap",
+    "email": "team@evomap.ai",
+    "url": "https://evomap.ai"
+  },
+  "homepage": "https://evomap.ai",
+  "repository": "https://github.com/EvoMap/evolver",
+  "license": "GPL-3.0-or-later",
+  "keywords": [
+    "evolver",
+    "evomap",
+    "gep",
+    "agent-evolution",
+    "self-evolution",
+    "codex"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Evolver",
+    "shortDescription": "Run Evolver's GEP workflow from Codex.",
+    "longDescription": "Evolver is EvoMap's GEP-powered self-evolution engine for AI agents. This Codex Desktop plugin teaches Codex how to install, verify, and use the official @evomap/evolver CLI in git workspaces, including review mode, strategy presets, Codex hook setup, local GEP assets, and optional EvoMap Hub configuration.",
+    "developerName": "EvoMap",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://evomap.ai",
+    "defaultPrompt": [
+      "Set up Evolver for this Codex workspace.",
+      "Run Evolver review mode and explain the GEP output.",
+      "Check whether Evolver is installed correctly."
+    ],
+    "brandColor": "#2F855A",
+    "composerIcon": "./assets/evolver-icon.png",
+    "logo": "./assets/evolver-logo.png"
+  }
+}
diff --git a/plugins/evolver/README.md b/plugins/evolver/README.md
@@ -0,0 +1,15 @@
+# Evolver Codex Desktop Plugin
+
+This plugin exposes the official EvoMap Evolver workflow to Codex Desktop as a local plugin skill.
+
+- Official repository: https://github.com/EvoMap/evolver
+- Package: `@evomap/evolver`
+- Homepage: https://evomap.ai
+
+The plugin teaches Codex how to install and verify the Evolver CLI, run GEP prompt generation in git workspaces, set up Codex hooks, and reason about Genes, Capsules, EvolutionEvents, and optional EvoMap Hub proxy mode.
+
+Run a local status check from any workspace:
+
+```bash
+node ~/plugins/evolver/scripts/evolver-status.js
+```
diff --git a/plugins/evolver/assets/evolver-icon.png b/plugins/evolver/assets/evolver-icon.png
diff --git a/plugins/evolver/assets/evolver-logo.png b/plugins/evolver/assets/evolver-logo.png
diff --git a/plugins/evolver/scripts/evolver-status.js b/plugins/evolver/scripts/evolver-status.js
@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function run(cmd, args = []) {
+  try {
+    return {
+      ok: true,
+      value: execFileSync(cmd, args, {
+        cwd: process.cwd(),
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+      }).trim()
+    };
+  } catch (error) {
+    const stderr = error.stderr ? String(error.stderr).trim() : "";
+    return { ok: false, value: stderr || error.message };
+  }
+}
+
+function printCheck(label, result) {
+  const mark = result.ok ? "OK" : "MISSING";
+  console.log(`${mark} ${label}: ${result.value || "(no output)"}`);
+}
+
+const nodeVersion = { ok: true, value: process.version };
+const gitVersion = run("git", ["--version"]);
+const evolverPath = run("sh", ["-lc", "command -v evolver"]);
+const evolverHelp = evolverPath.ok ? run("evolver", ["--help"]) : { ok: false, value: "evolver CLI not found" };
+const gitRoot = run("git", ["rev-parse", "--show-toplevel"]);
+const proxySettings = path.join(os.homedir(), ".evolver", "settings.json");
+
+console.log("Evolver Codex plugin status");
+console.log(`cwd: ${process.cwd()}`);
+printCheck("Node.js", nodeVersion);
+printCheck("Git", gitVersion);
+printCheck("Evolver CLI", evolverPath);
+printCheck("Git workspace", gitRoot);
+
+if (evolverHelp.ok) {
+  const firstLine = evolverHelp.value.split(/\r?\n/).find(Boolean) || "help output available";
+  console.log(`OK Evolver help: ${firstLine}`);
+} else {
+  console.log(`MISSING Evolver help: ${evolverHelp.value}`);
+}
+
+console.log(`INFO EVOLVE_STRATEGY: ${process.env.EVOLVE_STRATEGY || "balanced (default)"}`);
+console.log(`INFO A2A_HUB_URL: ${process.env.A2A_HUB_URL || "(offline/default)"}`);
+console.log(`INFO A2A_NODE_ID: ${process.env.A2A_NODE_ID ? "(set)" : "(not set)"}`);
+console.log(`INFO Proxy settings: ${fs.existsSync(proxySettings) ? proxySettings : "(not found)"}`);
+
+if (!evolverPath.ok) {
+  console.log("NEXT install with: npm install -g @evomap/evolver");
+} else if (!gitRoot.ok) {
+  console.log("NEXT run Evolver from inside a git-initialized workspace.");
+} else {
+  console.log("NEXT try: evolver --review");
+}
diff --git a/plugins/evolver/skills/evolver/SKILL.md b/plugins/evolver/skills/evolver/SKILL.md
@@ -0,0 +1,169 @@
+---
+name: evolver
+description: Use Evolver, the official EvoMap GEP-powered self-evolution engine, from Codex Desktop. Trigger when the user asks about Evolver, EvoMap, GEP, Genes, Capsules, EvolutionEvents, agent self-evolution, installing @evomap/evolver, running evolver in a git workspace, or setting up Codex hooks for Evolver.
+---
+
+# Evolver
+
+Use this skill when a user wants Codex to install, verify, configure, or run the official Evolver open-source engine.
+
+Official sources:
+
+- Repository: https://github.com/EvoMap/evolver
+- Package: `@evomap/evolver`
+- Homepage: https://evomap.ai
+- Docs/wiki: https://evomap.ai/wiki
+
+## Core Model
+
+Evolver is a GEP-powered prompt and evolution-asset generator. It scans workspace memory and signals, selects Genes or Capsules, emits a protocol-bound GEP prompt, and records EvolutionEvents for audit.
+
+Important boundary:
+
+- Evolver itself is not a general code patcher.
+- In standalone mode it prints text output and GEP prompts.
+- Do not apply Evolver output as code changes unless the user explicitly asks Codex to do that.
+- Run Evolver inside a git-initialized workspace. Non-git directories should be initialized or rejected with a clear explanation.
+
+## Before Running
+
+Check prerequisites first:
+
+```bash
+node --version
+git --version
+command -v evolver
+```
+
+Requirements:
+
+- Node.js 18 or newer.
+- Git.
+- A git workspace for project runs.
+- Network only when installing/updating the npm package or using EvoMap Hub features.
+
+If the CLI is missing, install the official package:
+
+```bash
+npm install -g @evomap/evolver
+```
+
+Never suggest `sudo npm install -g`. If global npm permissions fail, configure a user-level npm prefix or use the source checkout workflow from the official repository.
+
+## Standard Workflows
+
+From inside a git workspace:
+
+```bash
+evolver
+```
+
+Human review mode:
+
+```bash
+evolver --review
+```
+
+Continuous loop:
+
+```bash
+evolver --loop
+```
+
+Strategy presets:
+
+```bash
+EVOLVE_STRATEGY=balanced evolver
+EVOLVE_STRATEGY=innovate evolver --loop
+EVOLVE_STRATEGY=harden evolver --loop
+EVOLVE_STRATEGY=repair-only evolver --review
+```
+
+Explain generated GEP output in terms of:
+
+- Selected Gene or Capsule.
+- Input signals and memory evidence.
+- Proposed next action.
+- Validation or review gate.
+- EvolutionEvent/audit trail.
+
+## Codex Desktop Integration
+
+For Codex hook integration, run:
+
+```bash
+evolver setup-hooks --platform=codex
+```
+
+This may modify Codex hook files under the user's home directory. In Codex Desktop, request approval when the sandbox requires it. After hook setup, ask the user to start a new Codex thread so the updated hooks and plugin context are picked up cleanly.
+
+## Optional EvoMap Hub
+
+Evolver works offline by default. Hub connection enables network features such as node heartbeat, skill store, worker tasks, validation, asset publishing, and evolution circles.
+
+Project-local `.env` example:
+
+```bash
+A2A_HUB_URL=https://evomap.ai
+A2A_NODE_ID=your_node_id_here
+```
+
+Keep secrets out of transcript output. Do not print tokens or full `.env` files.
+
+## Proxy Mailbox
+
+When proxy mode is enabled, Evolver uses a local proxy mailbox. Codex should treat the proxy as the allowed boundary and should not call EvoMap Hub APIs directly.
+
+Discovery file:
+
+```text
+~/.evolver/settings.json
+```
+
+Default local base URL:
+
+```text
+http://127.0.0.1:19820
+```
+
+Useful local status endpoints:
+
+```text
+GET /proxy/status
+GET /proxy/hub-status
+POST /mailbox/poll
+POST /mailbox/send
+```
+
+## Local Assets
+
+GEP assets normally live in:
+
+```text
+assets/gep/genes.json
+assets/gep/capsules.json
+assets/gep/events.jsonl
+memory/
+```
+
+Treat these as user-owned runtime state. Do not overwrite Genes, Capsules, or EvolutionEvents during setup or upgrades.
+
+## Troubleshooting
+
+If `evolver` prints no GEP prompt, confirm the current directory is a git repo.
+
+If install fails with npm permissions, use a user-level npm prefix instead of `sudo`.
+
+If loop mode appears to print text only, explain that standalone loop mode emits prompts and records audit state; automatic execution depends on a host runtime that interprets the output.
+
+If Hub features do not work, check `A2A_HUB_URL`, `A2A_NODE_ID`, proxy status, and local network access.
+
+## Helper Script
+
+This plugin includes:
+
+```bash
+node ~/plugins/evolver/scripts/evolver-status.js
+```
+
+Run it from the workspace where the user wants to use Evolver. It reports Node, Git, Evolver CLI, git workspace status, and relevant environment flags without printing secret values.
