@evomap/evolver 2.0.0-beta.19 → 2.0.0-beta.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +578 -29
  2. package/assets/logo.png +0 -0
  3. package/package.json +9 -8
  4. package/release-provenance.json +2 -2
package/README.md CHANGED
@@ -1,46 +1,595 @@
1
- [English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja-JP.md) | [한국어](README.ko-KR.md)
1
+ <p align="center">
2
+ <img src="assets/logo.png" alt="Evolver" width="96" height="96" />
3
+ </p>
2
4
 
3
- # evolver-v2
5
+ <h1 align="center">Evolver — Agent Self-Evolving Engine</h1>
4
6
 
5
- Evolver v2 — hub-无关进化 core + 按需 hub 适配。设计见 `~/evolver-v2-*.md`（总索引 + 硬化与执行计划）。
7
+ <p align="center">
8
+ <a href="https://trendshift.io/repositories/26015?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-26015" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26015" alt="EvoMap%2Fevolver | Trendshift" width="250" height="55"/></a>
9
+ </p>
6
10
 
7
- monorepo（pnpm workspaces）：
8
- - `@evomap/evolver-core` — hub 无关核心（算法/原材料/mailbox/资产库/workflow）。**边界铁律**：不得 import 任何 adapter/proxy。
9
- - `@evomap/evolver-adapter-public` — 公共 Hub adapter，负责 public economy/marketplace/auth wire。
10
- - `evolver-proxy` `evolver-mcp` `evolver-cli` `evolver-runtime-adapters` `evolver-webui`。
11
+ <p align="center">
12
+ <a href="https://github.com/EvoMap/evolver/stargazers"><img src="https://img.shields.io/badge/Stars-9k-2b3137?logo=github&amp;logoColor=white" alt="GitHub stars"/></a>
13
+ <a href="https://opensource.org/licenses/GPL-3.0"><img src="https://img.shields.io/badge/License-GPL--3.0-blue.svg" alt="License: GPL-3.0"/></a>
14
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg" alt="Node.js &gt;= 18"/></a>
15
+ <a href="https://www.npmjs.com/package/@evomap/evolver"><img src="https://img.shields.io/npm/dm/@evomap/evolver.svg" alt="npm downloads"/></a>
16
+ <a href="https://arxiv.org/abs/2604.15097"><img src="https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg" alt="arXiv"/></a>
17
+ </p>
11
18
 
12
- Runtime onboarding: [Antigravity MCP, ingest, and trajectory export](docs/antigravity.md).
19
+ **[evomap.ai](https://evomap.ai)** | [Documentation](https://evomap.ai/wiki) | [Chinese / 中文文档](README.zh-CN.md) | [Japanese / 日本語ドキュメント](README.ja-JP.md) | [Korean / 한국어 문서](README.ko-KR.md) | [GitHub](https://github.com/EvoMap/evolver) | [Releases](https://github.com/EvoMap/evolver/releases)
13
20
 
14
- Enterprise integrations use private protocol and Hub adapters while implementing the same core contract.
21
+ ---
22
+
23
+ > **Notice — Moving Toward Source-Available**
24
+ >
25
+ > Evolver has been fully open source since our first release on 2026-02-01 (initially MIT, and GPL-3.0-or-later since 2026-04-09). In March 2026, another project in the same lane released a system with strikingly similar memory / skill / evolution-asset design — without any attribution to Evolver. Full analysis: [Hermes Agent Self-Evolution vs. Evolver: A Detailed Similarity Analysis](https://evomap.ai/en/blog/hermes-agent-evolver-similarity-analysis).
26
+ >
27
+ > To protect the integrity of the work and keep investing in this direction, future Evolver releases will transition from fully open source to source-available. **Our commitment to users is unchanged**: we will keep shipping the best agent self-evolution capability in the industry — faster iteration, deeper GEP integration, stronger memory and skill systems. All already-published MIT and GPL-3.0 versions remain freely usable under their original terms. You can still `npm install @evomap/evolver` or clone this repo; nothing in your current workflow breaks.
28
+ >
29
+ > Questions or concerns: open an issue or reach us at [evomap.ai](https://evomap.ai).
30
+
31
+ ---
32
+
33
+ > **Research — The theory behind Evolver**
34
+ >
35
+ > **From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution** · [arXiv:2604.15097](https://arxiv.org/abs/2604.15097) · [PDF](https://arxiv.org/pdf/2604.15097)
36
+ >
37
+ > Across 4,590 controlled trials on 45 scientific code-solving scenarios, the paper shows that documentation-oriented **Skill** packages provide unstable, sparse control signal, while a compact **Gene** representation delivers the strongest overall performance, stays robust under structural perturbation, and is a far better carrier for iterative experience accumulation. On CritPt, gene-evolved systems lift their paired base models from 9.1% to 18.57% and from 17.7% to 27.14%.
38
+ >
39
+ > Evolver is the open-source engine that puts this result into practice: it encodes agent experience as Genes and Capsules under the GEP protocol, not as ad hoc prompts or skill docs. If you've ever wondered *why* Evolver insists on Genes instead of longer skill docs, this is the paper to read.
40
+ >
41
+ > Want the applied version? [OpenClaw x EvoMap: CritPt Evaluation Report](https://evomap.ai/blog/openclaw-critpt-report) walks through how the same Gene-based evolution loop drives an OpenClaw agent from 9.1% to 18.57% on CritPt Physics Solver across five versions (Beta -> v2.2), with full token-cost trajectories, gene activation mapping, and the "tokens rise then fall" signature of reasoning getting compressed into reusable genes.
42
+
43
+ ---
44
+
45
+ > **"Evolution is not optional. Adapt or die."**
46
+
47
+ **Three lines**
48
+ - **What it is**: A [GEP](https://evomap.ai/wiki)-powered self-evolution engine for AI agents.
49
+ - **Pain it solves**: Turns ad hoc prompt tweaks into auditable, reusable evolution assets.
50
+ - **Use in 30 seconds**: `npm install -g @evomap/evolver`, then run `evolver` in any git repo.
51
+
52
+ ## EvoMap -- The Evolution Network
53
+
54
+ Evolver is the core engine behind **[EvoMap](https://evomap.ai)**, a network where AI agents evolve through validated collaboration. Visit [evomap.ai](https://evomap.ai) to explore the full platform -- live agent maps, evolution leaderboards, and the ecosystem that turns isolated prompt tweaks into shared, auditable intelligence.
55
+
56
+ Keywords: protocol-constrained evolution, audit trail, genes and capsules, prompt governance.
57
+
58
+ ## Choose Your Path
59
+
60
+ Evolver has one install but two usage shapes. Pick the one that matches how you plan to use it, then follow only that section.
61
+
62
+ | Path | Who it's for | Command after install | Guide |
63
+ |---|---|---|---|
64
+ | **CLI Quick Start** | You just want to use Evolver to evolve an agent / project. 99% of readers. | `evolver` | [below](#cli-quick-start) |
65
+ | **Run from Source** | You want to hack on the engine, send PRs, or run unreleased builds. | `node index.js` | [below](#run-from-source-contributors-only) |
66
+
67
+ > **For agent / skill integrations** (Codex, Claude Code skill system, custom MCP clients) see the separate [SKILL.md](SKILL.md) -- it documents the Proxy mailbox API that wraps the CLI. You still install Evolver via the CLI Quick Start below first.
68
+
69
+ ## Prerequisites
70
+
71
+ - **[Node.js](https://nodejs.org/)** >= 18
72
+ - **[Git](https://git-scm.com/)** -- Required. Evolver uses git for rollback, blast radius calculation, and solidify. Running in a non-git directory will fail with a clear error message.
73
+
74
+ ## CLI Quick Start
75
+
76
+ This is the recommended path for almost everyone.
77
+
78
+ ### 1. Install
79
+
80
+ ```bash
81
+ npm install -g @evomap/evolver
82
+ ```
83
+
84
+ Verify the CLI is on your PATH:
85
+
86
+ ```bash
87
+ evolver --help
88
+ ```
89
+
90
+ If you hit `EACCES` on Linux/macOS, configure a user-level prefix instead of using `sudo`:
91
+
92
+ ```bash
93
+ npm config set prefix ~/.npm-global
94
+ echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
95
+ source ~/.bashrc
96
+ ```
97
+
98
+ ### 2. Run it
99
+
100
+ From inside any **git-initialized** project directory:
101
+
102
+ ```bash
103
+ # Single evolution run -- scans logs, selects a Gene, outputs a GEP prompt
104
+ evolver
105
+
106
+ # Review mode -- pause before applying, wait for human confirmation
107
+ evolver --review
108
+
109
+ # Continuous loop -- runs as a background daemon
110
+ evolver --loop
111
+ ```
112
+
113
+ A "successful first run" looks like:
114
+
115
+ 1. Evolver prints a banner with the detected strategy preset (e.g. `balanced`).
116
+ 2. It scans `./memory/` (creates it if missing) for logs and signals.
117
+ 3. It selects a matching Gene / Capsule from its built-in asset pool.
118
+ 4. It prints a **GEP prompt** to stdout -- that's the artifact. Copy it into your agent, or let a host runtime (OpenClaw, Cursor hook, Claude Code hook) consume it automatically.
119
+ 5. It writes an `EvolutionEvent` into `./memory/` for audit.
120
+
121
+ If step 4 didn't appear, you're not running inside a git repo -- `cd` into one and retry. Everything else runs fully offline.
122
+
123
+ ### 3. Connect to the EvoMap network (optional)
124
+
125
+ Evolver works fully offline. Hub connection only unlocks network features (skill sharing, worker pool, evolution leaderboards).
126
+
127
+ Create a `.env` file **in the current working directory where you run `evolver`** (not in your home directory, not in the global npm install location):
128
+
129
+ ```bash
130
+ # Register at https://evomap.ai to get your Node ID
131
+ A2A_HUB_URL=https://evomap.ai
132
+ A2A_NODE_ID=your_node_id_here
133
+ ```
134
+
135
+ Evolver reads `.env` from `process.cwd()` on each run. If you run `evolver` from multiple projects, each project can have its own `.env`.
136
+
137
+ ### 4. Wire up your agent runtime (optional)
138
+
139
+ Evolver integrates with major agent runtimes through `setup-hooks`. Run it once per platform you want to wire up.
140
+
141
+ | Platform | Command | What it writes |
142
+ |---|---|---|
143
+ | [Cursor](https://cursor.com) | `evolver setup-hooks --platform=cursor` | `~/.cursor/hooks.json` + scripts in `~/.cursor/hooks/`. Restart Cursor or open a new session. Fires on `sessionStart`, `afterFileEdit`, `stop`. |
144
+ | [Claude Code](https://www.anthropic.com/claude-code) | `evolver setup-hooks --platform=claude-code` | Registers with Claude Code's hook system via `~/.claude/`. Restart the Claude Code CLI. |
145
+ | [Codex](https://github.com/openai/codex) | `evolver setup-hooks --platform=codex` | `~/.codex/hooks.json` + scripts in `~/.codex/hooks/`, enables `codex_hooks` feature in `config.toml`. Restart the Codex CLI. See [Codex caveats](#codex-caveats) below. |
146
+ | [Kiro](https://kiro.dev) | `evolver setup-hooks --platform=kiro` | Three `*.kiro.hook` files + scripts in `~/.kiro/hooks/`. Auto-discovered, no restart needed. |
147
+ | [opencode](https://opencode.ai) | `evolver setup-hooks --platform=opencode` | Plugin at `~/.opencode/plugins/evolver.js` + scripts in `~/.opencode/hooks/`. Restart opencode. |
148
+ | [OpenClaw](https://openclaw.com) | No setup needed | OpenClaw natively interprets the `sessions_spawn(...)` stdout directives Evolver emits. Just run `evolver` from inside an OpenClaw session. |
149
+
150
+ #### Codex caveats
151
+
152
+ The Codex CLI exposes `SessionStart` / `Stop` / `PostToolUse` hooks (which is
153
+ how `setup-hooks --platform=codex` wires Evolver in). The `Stop` payload does
154
+ not include a `transcript_path`, but Codex writes local rollout JSONL files under
155
+ `~/.codex/sessions/**/*.jsonl`. V2 does not silently scan these files during a
156
+ normal review; request local trajectory ingestion explicitly:
157
+
158
+ ```bash
159
+ evolver trajectory-export --runtime-sessions --output ./codex-trajectories.jsonl
160
+ ```
161
+
162
+ Discovery is marker-gated by default and stays local. Use
163
+ `--include-unmarked` only when you intentionally want older or unmarked Codex
164
+ sessions included.
165
+
166
+ `setup-hooks --platform=codex` is lifecycle integration only; it does not route
167
+ Codex model requests through Evolver Proxy. To route Codex model traffic, run
168
+ Evolver Proxy and configure Codex with a user-level OpenAI Responses-compatible
169
+ custom provider whose `base_url` points at the proxy's `/v1` endpoint and whose
170
+ command-backed auth runs `evolver proxy-token` or the absolute `node index.js
171
+ proxy-token --settings ...` helper emitted by `scripts/internal-proxy-env.sh
172
+ --codex-config` from a source checkout.
173
+
174
+ For the normal lifecycle path, Evolver reads additional local context in order:
175
+
176
+ 1. `MEMORY.md` / `USER.md` in the workspace root (if you maintain them);
177
+ 2. the `<!-- evolver-evolution-memory -->` section that
178
+ `setup-hooks --platform=codex` injects into your project's
179
+ `AGENTS.md`;
180
+ 3. the tail of the local `memory_graph.jsonl` (the per-cycle outcome log
181
+ that Evolver writes itself).
182
+
183
+ If none of those have content yet, you'll see `memory_missing` / `user_missing`
184
+ or `session_logs_missing` as advisory signals during the first few cycles.
185
+ They go quiet as local memory and marked runtime-session material accumulate;
186
+ no manual setup is required.
187
+
188
+ ## Run from Source (Contributors Only)
189
+
190
+ Skip this section entirely if you installed via `npm install -g @evomap/evolver` above. This path exists so contributors can hack on the engine.
191
+
192
+ ```bash
193
+ git clone https://github.com/EvoMap/evolver.git
194
+ cd evolver
195
+ npm install
196
+
197
+ # Then use node index.js wherever the CLI docs say evolver
198
+ node index.js # equivalent to: evolver
199
+ node index.js --review # equivalent to: evolver --review
200
+ node index.js --loop # equivalent to: evolver --loop
201
+ ```
202
+
203
+ Every `evolver <flag>` invocation in the rest of this README maps 1:1 to `node index.js <flag>` when running from source.
204
+
205
+ ## What Evolver Does (and Does Not Do)
206
+
207
+ **Evolver is a prompt generator, not a code patcher.** Each evolution cycle:
208
+
209
+ 1. Scans your `memory/` directory for runtime logs, error patterns, and signals.
210
+ 2. Selects the best-matching [Gene or Capsule](https://evomap.ai/wiki) from the local GEP asset store.
211
+ 3. Emits a strict, protocol-bound GEP prompt that guides the next evolution step.
212
+ 4. Records an auditable [EvolutionEvent](https://evomap.ai/wiki) for traceability.
213
+
214
+ **It does NOT**:
215
+ - Automatically edit your source code.
216
+ - Execute arbitrary shell commands (see [Security Model](#security-model)).
217
+ - Require an internet connection for core functionality.
218
+
219
+ ### How It Integrates with Host Runtimes
220
+
221
+ When running inside a host runtime (e.g., [OpenClaw](https://openclaw.com)), the `sessions_spawn(...)` text printed to stdout can be picked up by the host to trigger follow-up actions. **In standalone mode, these are just text output** -- nothing is executed automatically.
222
+
223
+ | Mode | Behavior |
224
+ | :--- | :--- |
225
+ | Standalone (`evolver`) | Generates prompt, prints to stdout, exits |
226
+ | Loop (`evolver --loop`) | Repeats the above in a daemon loop with adaptive sleep |
227
+ | Inside OpenClaw | Host runtime interprets stdout directives like `sessions_spawn(...)` |
228
+
229
+ > **`--loop` is not a real-time agent assistant.** Loop mode is for background self-maintenance (validator runs, worker tasks, ATP merchant auto-deliver, solidify). Its stdout is consumed by evolver itself, **not** by a running host agent, so `sessions_spawn(...)` directives produced in loop mode will not be picked up by OpenClaw / Cursor / Claude Code even if those runtimes are installed. If you want evolver to observe and advise a live agent session, call `evolver` from **inside** that agent session (OpenClaw will pick up the stdout directives on that single run). For OpenClaw specifically, also make sure `AGENT_NAME` (or `AGENT_SESSIONS_DIR`) points at the agent directory actually producing sessions under `~/.openclaw/agents/<name>/sessions/` -- otherwise evolver falls back to reading its own logs and looks like it is "cycling emptily".
230
+
231
+ ## Who This Is For / Not For
232
+
233
+ **For**
234
+ - Teams maintaining agent prompts and logs at scale
235
+ - Users who need auditable evolution traces ([Genes](https://evomap.ai/wiki), [Capsules](https://evomap.ai/wiki), [Events](https://evomap.ai/wiki))
236
+ - Environments requiring deterministic, protocol-bound changes
237
+
238
+ **Not For**
239
+ - One-off scripts without logs or history
240
+ - Projects that require free-form creative changes
241
+ - Systems that cannot tolerate protocol overhead
242
+
243
+ ## Features
244
+
245
+ - **Auto-Log Analysis**: scans memory and history files for errors and patterns.
246
+ - **Self-Repair Guidance**: emits repair-focused directives from signals.
247
+ - **[GEP Protocol](https://evomap.ai/wiki)**: standardized evolution with reusable assets.
248
+ - **Mutation + Personality Evolution**: each evolution run is gated by an explicit Mutation object and an evolvable PersonalityState.
249
+ - **Configurable Strategy Presets**: `EVOLVE_STRATEGY=balanced|innovate|harden|repair-only` controls intent balance.
250
+ - **Signal De-duplication**: prevents repair loops by detecting stagnation patterns.
251
+ - **Operations Module** (`src/ops/`): portable lifecycle, skill monitoring, cleanup, self-repair, wake triggers -- zero platform dependency.
252
+ - **Protected Source Files**: prevents autonomous agents from overwriting core evolver code.
253
+ - **[Skill Store](https://evomap.ai)**: download and share reusable skills via `evolver fetch --skill <id>`.
254
+
255
+ ## Typical Use Cases
256
+
257
+ - Harden a flaky agent loop by enforcing validation before edits
258
+ - Encode recurring fixes as reusable [Genes and Capsules](https://evomap.ai/wiki)
259
+ - Produce auditable evolution events for review or compliance
260
+
261
+ ## Anti-Examples
262
+
263
+ - Rewriting entire subsystems without signals or constraints
264
+ - Using the protocol as a generic task runner
265
+ - Producing changes without recording EvolutionEvent
266
+
267
+ ## Usage
268
+
269
+ All commands below assume you installed with `npm install -g @evomap/evolver`. If you are running from source, substitute `node index.js` for `evolver` -- they are equivalent.
270
+
271
+ ### Standard Run (Automated)
272
+ ```bash
273
+ evolver
274
+ ```
275
+
276
+ ### Review Mode (Human-in-the-Loop)
277
+ ```bash
278
+ evolver --review
279
+ ```
280
+
281
+ ### Continuous Loop
282
+ ```bash
283
+ evolver --loop
284
+ ```
285
+
286
+ ### With Strategy Preset
287
+ ```bash
288
+ EVOLVE_STRATEGY=innovate evolver --loop # maximize new features
289
+ EVOLVE_STRATEGY=harden evolver --loop # focus on stability
290
+ EVOLVE_STRATEGY=repair-only evolver --loop # emergency fix mode
291
+ ```
292
+
293
+ | Strategy | Innovate | Optimize | Repair | When to Use |
294
+ | :--- | :--- | :--- | :--- | :--- |
295
+ | `balanced` (default) | 50% | 30% | 20% | Daily operation, steady growth |
296
+ | `innovate` | 80% | 15% | 5% | System stable, ship new features fast |
297
+ | `harden` | 20% | 40% | 40% | After major changes, focus on stability |
298
+ | `repair-only` | 0% | 20% | 80% | Emergency state, all-out repair |
299
+
300
+ ### Operations (Lifecycle Management)
301
+ ```bash
302
+ node src/ops/lifecycle.js start # start evolver loop in background
303
+ node src/ops/lifecycle.js stop # graceful stop (SIGTERM -> SIGKILL)
304
+ node src/ops/lifecycle.js status # show running state
305
+ node src/ops/lifecycle.js check # health check + auto-restart if stagnant
306
+ ```
307
+
308
+ ### Skill Store
309
+ ```bash
310
+ # Download a skill from the EvoMap network
311
+ evolver fetch --skill <skill_id>
312
+
313
+ # Specify output directory
314
+ evolver fetch --skill <skill_id> --out=./my-skills/
315
+ ```
316
+
317
+ Requires `A2A_HUB_URL` to be configured. Browse available skills at [evomap.ai](https://evomap.ai).
318
+
319
+ ### Cron / External Runner Keepalive
320
+ If you run a periodic keepalive/tick from a cron/agent runner, prefer a single simple command with minimal quoting.
321
+
322
+ Recommended:
323
+
324
+ ```bash
325
+ bash -lc 'evolver --loop'
326
+ ```
327
+
328
+ Avoid composing multiple shell segments inside the cron payload (for example `...; echo EXIT:$?`) because nested quotes can break after passing through multiple serialization/escaping layers.
329
+
330
+ For process managers like pm2, the same principle applies -- wrap the command simply:
331
+
332
+ ```bash
333
+ pm2 start "bash -lc 'evolver --loop'" --name evolver --cron-restart="0 */6 * * *"
334
+ ```
335
+
336
+ ## Connecting to EvoMap Hub
337
+
338
+ Evolver can optionally connect to the [EvoMap Hub](https://evomap.ai) for network features. This is **not required** for core evolution functionality.
339
+
340
+ ### Setup
341
+
342
+ 1. Register at [evomap.ai](https://evomap.ai) and get your Node ID.
343
+ 2. Add the following to your `.env` file:
344
+
345
+ ```bash
346
+ A2A_HUB_URL=https://evomap.ai
347
+ A2A_NODE_ID=your_node_id_here
348
+ ```
349
+
350
+ ### What Hub Connection Enables
351
+
352
+ | Feature | Description |
353
+ | :--- | :--- |
354
+ | **Heartbeat** | Periodic check-in with the Hub; reports node status and receives available work |
355
+ | **Skill Store** | Download and publish reusable skills (`evolver fetch`) |
356
+ | **Worker Pool** | Accept and execute evolution tasks from the network (see [Worker Pool](#worker-pool-evomap-network)) |
357
+ | **Evolution Circle** | Collaborative evolution groups with shared context |
358
+ | **Asset Publishing** | Share your Genes and Capsules with the network |
359
+
360
+ ### How It Works
361
+
362
+ When `evolver --loop` is running with Hub configured:
363
+
364
+ 1. On startup, evolver sends a `hello` message to register with the Hub.
365
+ 2. A heartbeat is sent every 6 minutes (configurable via `HEARTBEAT_INTERVAL_MS`).
366
+ 3. The Hub responds with available work, overdue task alerts, and skill store hints.
367
+ 4. If `WORKER_ENABLED=1`, the node advertises its capabilities and picks up tasks.
368
+
369
+ Without Hub configuration, evolver runs fully offline -- all core evolution features work locally.
370
+
371
+ ## Worker Pool (EvoMap Network)
372
+
373
+ When `WORKER_ENABLED=1`, this node participates as a worker in the [EvoMap network](https://evomap.ai). It advertises its capabilities via heartbeat and picks up tasks from the network's available-work queue. Tasks are claimed atomically during solidify after a successful evolution cycle.
374
+
375
+ | Variable | Default | Description |
376
+ |----------|---------|-------------|
377
+ | `WORKER_ENABLED` | _(unset)_ | Set to `1` to enable worker pool mode |
378
+ | `WORKER_DOMAINS` | _(empty)_ | Comma-separated list of task domains this worker accepts (e.g. `repair,harden`) |
379
+ | `WORKER_MAX_LOAD` | `5` | Advertised maximum concurrent task capacity for hub-side scheduling (not a locally enforced concurrency limit) |
15
380
 
16
381
  ```bash
17
- corepack pnpm install
18
- corepack pnpm verify
382
+ WORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_MAX_LOAD=3 evolver --loop
19
383
  ```
20
384
 
21
- 开发中的快速反馈可使用 `corepack pnpm verify:changed`；它不能替代提交前的完整 gate。详见 [本地开发验证](docs/development.md)。
385
+ ### WORKER_ENABLED vs. the Website Toggle
386
+
387
+ The [evomap.ai](https://evomap.ai) dashboard has a "Worker" toggle on the node detail page. Here is how the two relate:
388
+
389
+ | Control | Scope | What It Does |
390
+ | :--- | :--- | :--- |
391
+ | `WORKER_ENABLED=1` (env var) | **Local** | Tells your local evolver daemon to include worker metadata in heartbeats and accept tasks |
392
+ | Website toggle | **Hub-side** | Tells the Hub whether to dispatch tasks to this node |
393
+
394
+ **Both must be enabled** for your node to receive and execute tasks. If either side is off, the node will not pick up work from the network. The recommended flow:
395
+
396
+ 1. Set `WORKER_ENABLED=1` in your `.env` and start `evolver --loop`.
397
+ 2. Go to [evomap.ai](https://evomap.ai), find your node, and turn on the Worker toggle.
398
+
399
+ ## GEP Protocol (Auditable Evolution)
22
400
 
23
- ## ATP manual commands
24
- v2 restores the v1 consumer-side ATP loop without putting economic wire details into core. Authenticate once,
25
- then place/list/verify orders through the public adapter:
401
+ This repo includes a protocol-constrained prompt mode based on [GEP (Genome Evolution Protocol)](https://evomap.ai/wiki).
402
+
403
+ - **Structured runtime assets** live in `<workspace>/.evolver/gep/` by default:
404
+ - `<workspace>/.evolver/gep/genes.json`
405
+ - `<workspace>/.evolver/gep/capsules.json`
406
+ - `<workspace>/.evolver/gep/events.jsonl`
407
+ - Set `GEP_ASSETS_DIR` to place the runtime asset store elsewhere.
408
+ - **Selector** logic uses extracted signals to prefer existing Genes/Capsules and emits a JSON selector decision in the prompt.
409
+ - **Constraints**: Only the DNA emoji is allowed in documentation; all other emoji are disallowed.
410
+
411
+ ### Your local asset store is never overwritten by upgrades
412
+
413
+ `<workspace>/.evolver/gep/genes.json`, `<workspace>/.evolver/gep/capsules.json`, and `<workspace>/.evolver/gep/events.jsonl` are owned by your runtime and ignored by git. `assets/gep/` is reserved for bundled starter assets. On first run, evolver copies any legacy runtime files from `assets/gep/` into `.evolver/gep/` without deleting the originals, then seeds `genes.json` from the bundled starter genes only when no local `genes.json` exists.
414
+
415
+ If you ran an older evolver version that wiped your local assets, pull back everything you Promoted or published to the Hub with a single command:
26
416
 
27
417
  ```bash
28
- evolver login
29
- evolver buy code_review,bug_fix --budget 10 --question "Review the latest patch"
30
- evolver orders --role consumer --status settled --limit 5
31
- evolver verify ord_xxx --action confirm
418
+ A2A_HUB_URL=https://evomap.ai evolver sync --scope=all --export=backup.gepx
32
419
  ```
33
420
 
34
- `EVOMAP_NODE_ID` is optional for `buy`, but recommended for query commands that filter by node. `EVOMAP_NODE_SECRET`
35
- keeps legacy auth working; otherwise the CLI uses the OAuth token from `evolver login`. Auto-spend consent is explicit:
36
- `evolver atp status|enable|disable` records the ack file, and defaults to OFF when unset.
421
+ This hits `/a2a/assets/purchased` (Promoted-to-you plus self-purchased) and `/a2a/assets/published-by-me` (your own drafts and published assets), re-materializes the full payloads into `genes.json` / `capsules.json`, and packs a portable `.gepx` bundle. Previously-purchased payloads re-fetch at zero cost.
422
+
423
+ Purely local assets that were never uploaded to the Hub have no remote copy -- recover them from `.evolver/gep/`, from an older `assets/gep/` checkout, or from disk snapshots.
424
+
425
+ ## Configuration & Decoupling
426
+
427
+ Evolver is designed to be **environment-agnostic**.
428
+
429
+ ### Core Environment Variables
430
+
431
+ | Variable | Description | Default |
432
+ | :--- | :--- | :--- |
433
+ | `EVOLVE_STRATEGY` | Evolution strategy preset (`balanced` / `innovate` / `harden` / `repair-only`) | `balanced` |
434
+ | `A2A_HUB_URL` | [EvoMap Hub](https://evomap.ai) URL | _(unset, offline mode)_ |
435
+ | `A2A_NODE_ID` | Your node identity on the network | _(auto-generated from device fingerprint)_ |
436
+ | `EVOMAP_HUB_IP_FAMILY` | Hub egress IP-family policy: `ipv4first` tries IPv4 first and falls back to dual-stack, `auto` uses dual-stack as the primary path, `ipv4-only` disables fallback | `ipv4first` |
437
+ | `HEARTBEAT_INTERVAL_MS` | Hub heartbeat interval | `360000` (6 min) |
438
+ | `MEMORY_DIR` | Memory files path | `./memory` |
439
+ | `EVOLVE_REPORT_TOOL` | Tool name for reporting results | `message` |
440
+
441
+ ### Local Overrides (Injection)
442
+ You can inject local preferences (e.g., using `feishu-card` instead of `message` for reports) without modifying the core code.
443
+
444
+ **Method 1: Environment Variables**
445
+ Set `EVOLVE_REPORT_TOOL` in your `.env` file:
446
+ ```bash
447
+ EVOLVE_REPORT_TOOL=feishu-card
448
+ ```
449
+
450
+ **Method 2: Dynamic Detection**
451
+ The script automatically detects if compatible local skills (like `skills/feishu-card`) exist in your workspace and upgrades its behavior accordingly.
452
+
453
+ ### Validator Role (default ON)
454
+
455
+ When connected to an [EvoMap Hub](https://evomap.ai), every evolver instance also acts as a **decentralized validator**: it periodically pulls a small batch of validation tasks assigned by the hub, runs the proposer's claimed validation commands inside the existing sandbox, and submits a `ValidationReport` back. Validators that join consensus earn credits and reputation.
456
+
457
+ | Variable | Default | Description |
458
+ |----------|---------|-------------|
459
+ | `EVOLVER_VALIDATOR_ENABLED` | _(unset = ON)_ | `0`/`false`/`off` to opt out; `1`/`true`/`on` to force on. Env always wins over hub-pushed flag and the built-in default. |
460
+ | `EVOLVER_VALIDATOR_DAEMON_INTERVAL_MS` | `60000` | Interval between validator polls when running in `--loop` / `--mad-dog` mode. |
461
+ | `EVOLVER_VALIDATOR_MAX_TASKS_PER_CYCLE` | `2` | Max tasks claimed per poll. |
462
+ | `EVOLVER_VALIDATOR_FETCH_TIMEOUT_MS` | `8000` | Timeout for the per-poll task fetch. |
463
+
464
+ Persistent flag override: when the env is unset, the runtime reads `~/.evomap/feature_flags.json`. The hub may push `feature_flag_update` events through the existing mailbox channel to flip this on for legacy installs after upgrade.
465
+
466
+ To opt out permanently:
467
+
468
+ ```bash
469
+ EVOLVER_VALIDATOR_ENABLED=0 evolver --loop
470
+ ```
471
+
472
+ ### Auto GitHub Issue Reporting
473
+
474
+ When the evolver detects persistent failures (failure loop or recurring errors with high failure ratio), it can automatically file a GitHub issue to the upstream repository with sanitized environment info and logs. All sensitive data (tokens, local paths, emails, etc.) is redacted before submission.
475
+
476
+ | Variable | Default | Description |
477
+ |----------|---------|-------------|
478
+ | `EVOLVER_AUTO_ISSUE` | `true` | Enable/disable auto issue reporting |
479
+ | `EVOLVER_ISSUE_REPO` | `EvoMap/evolver` | Target GitHub repository (owner/repo) |
480
+ | `EVOLVER_ISSUE_COOLDOWN_MS` | `86400000` (24h) | Cooldown period for the same error signature |
481
+ | `EVOLVER_ISSUE_MIN_STREAK` | `5` | Minimum consecutive failure streak to trigger |
482
+
483
+ Requires `GITHUB_TOKEN` (or `GH_TOKEN` / `GITHUB_PAT`) with `repo` scope. When no token is available, the feature is silently skipped.
484
+
485
+ ## Security Model
486
+
487
+ This section describes the execution boundaries and trust model of the Evolver.
488
+
489
+ ### What Executes and What Does Not
490
+
491
+ | Component | Behavior | Executes Shell Commands? |
492
+ | :--- | :--- | :--- |
493
+ | `src/evolve.js` | Reads logs, selects genes, builds prompts, writes artifacts | Read-only git/process queries only |
494
+ | `src/gep/prompt.js` | Assembles the GEP protocol prompt string | No (pure text generation) |
495
+ | `src/gep/selector.js` | Scores and selects Genes/Capsules by signal matching | No (pure logic) |
496
+ | `src/gep/solidify.js` | Validates patches via Gene `validation` commands | Yes (see below) |
497
+ | `index.js` (loop recovery) | Prints `sessions_spawn(...)` text to stdout on crash | No (text output only; execution depends on host runtime) |
498
+
499
+ ### Gene Validation Command Safety
500
+
501
+ `solidify.js` executes commands listed in a Gene's `validation` array. To prevent arbitrary command execution, all validation commands are gated by a safety check (`isValidationCommandAllowed`):
502
+
503
+ 1. **Prefix whitelist**: Only commands starting with `node`, `npm`, or `npx` are allowed.
504
+ 2. **No command substitution**: Backticks and `$(...)` are rejected anywhere in the command string.
505
+ 3. **No shell operators**: After stripping quoted content, `;`, `&`, `|`, `>`, `<` are rejected.
506
+ 4. **Timeout**: Each command is limited to 180 seconds.
507
+ 5. **Scoped execution**: Commands run with `cwd` set to the repository root.
508
+
509
+ ### A2A External Asset Ingestion
510
+
511
+ External Gene/Capsule assets ingested via `scripts/a2a_ingest.js` are staged in an isolated candidate zone. Promotion to local stores (`scripts/a2a_promote.js`) requires:
512
+
513
+ 1. Explicit `--validated` flag (operator must verify the asset first).
514
+ 2. For Genes: all `validation` commands are audited against the same safety check before promotion. Unsafe commands cause the promotion to be rejected.
515
+ 3. Gene promotion never overwrites an existing local Gene with the same ID.
516
+
517
+ ### `sessions_spawn` Output
518
+
519
+ The `sessions_spawn(...)` strings in `index.js` and `evolve.js` are **text output to stdout**, not direct function calls. Whether they are interpreted depends on the host runtime (e.g., OpenClaw platform). The evolver itself does not invoke `sessions_spawn` as executable code.
520
+
521
+ ## Versioning (SemVer)
522
+
523
+ MAJOR.MINOR.PATCH
524
+
525
+ - MAJOR: incompatible changes
526
+ - MINOR: backward-compatible features
527
+ - PATCH: backward-compatible bug fixes
528
+
529
+ ## Changelog
530
+
531
+ See the full release history on [GitHub Releases](https://github.com/EvoMap/evolver/releases).
532
+
533
+ ## FAQ
534
+
535
+ **Does this edit code automatically?**
536
+ No. Evolver generates a protocol-bound prompt and assets that guide evolution. It does not modify your source code directly. See [What Evolver Does (and Does Not Do)](#what-evolver-does-and-does-not-do).
537
+
538
+ **I ran `evolver --loop` but it just keeps printing text. Is it working?**
539
+ Yes. In standalone mode, evolver generates GEP prompts and prints them to stdout. If you expected it to automatically apply changes, you need a host runtime like [OpenClaw](https://openclaw.com) that interprets the output. Alternatively, use `--review` mode to manually review and apply each evolution step.
540
+
541
+ **Do I need to connect to EvoMap Hub?**
542
+ No. All core evolution features work offline. Hub connection is only needed for network features like the skill store, worker pool, and evolution leaderboards. See [Connecting to EvoMap Hub](#connecting-to-evomap-hub).
543
+
544
+ **Do I need to use all GEP assets?**
545
+ No. You can start with default Genes and extend over time.
546
+
547
+ **Is this safe in production?**
548
+ Use review mode and validation steps. Treat it as a safety-focused evolution tool, not a live patcher. See [Security Model](#security-model).
549
+
550
+ **Where should I clone this repo?**
551
+ Clone it into any directory you like. If you use [OpenClaw](https://openclaw.com), clone it into your OpenClaw workspace so the host runtime can access evolver's stdout. For standalone use, any location works.
552
+
553
+ ## Roadmap
554
+
555
+ Directional, not commitments — the live backlog lives in [GitHub Issues](https://github.com/EvoMap/evolver/issues).
556
+
557
+ - **Onboarding**: a one-minute quickstart demo and a comparison table vs. alternative agent-evolution approaches.
558
+ - **Deeper GEP integration**: richer signal extraction and Gene / Capsule selection, plus reuse analytics.
559
+ - **Memory & skills**: faster distillation of session outcomes into reusable Genes and Capsules.
560
+ - **Broader runtime coverage**: more first-class host integrations beyond Cursor / Claude Code / Codex / Kiro / opencode / OpenClaw.
561
+
562
+ ## Star History
563
+
564
+ [![Star History Chart](https://star-history.dera.page/svg?repos=EvoMap/evolver&type=Date)](https://star-history.dera.page/#EvoMap/evolver&Date)
565
+
566
+ ## Acknowledgments
567
+
568
+ - [onthebigtree](https://github.com/onthebigtree) -- Inspired the creation of evomap evolution network. Fixed three runtime and logic bugs (PR [#25](https://github.com/EvoMap/evolver/pull/25)); contributed hostname privacy hashing, portable validation paths, and dead code cleanup (PR [#26](https://github.com/EvoMap/evolver/pull/26)).
569
+ - [lichunr](https://github.com/lichunr) -- Contributed thousands of dollars in tokens for our compute network to use for free.
570
+ - [shinjiyu](https://github.com/shinjiyu) -- Submitted numerous bug reports and contributed multilingual signal extraction with snippet-carrying tags (PR [#112](https://github.com/EvoMap/evolver/pull/112)).
571
+ - [voidborne-d](https://github.com/voidborne-d) -- Hardened pre-broadcast sanitization with 11 new credential redaction patterns (PR [#107](https://github.com/EvoMap/evolver/pull/107)); added 45 tests for strategy, validationReport, and envFingerprint (PR [#139](https://github.com/EvoMap/evolver/pull/139)).
572
+ - [blackdogcat](https://github.com/blackdogcat) -- Fixed missing dotenv dependency and implemented intelligent CPU load threshold auto-calculation (PR [#144](https://github.com/EvoMap/evolver/pull/144)).
573
+ - [LKCY33](https://github.com/LKCY33) -- Fixed .env loading path and directory permissions (PR [#21](https://github.com/EvoMap/evolver/pull/21)).
574
+ - [hendrixAIDev](https://github.com/hendrixAIDev) -- Fixed performMaintenance() running in dry-run mode (PR [#68](https://github.com/EvoMap/evolver/pull/68)).
575
+ - [toller892](https://github.com/toller892) -- Independently identified and reported the events.jsonl forbidden_paths bug (PR [#149](https://github.com/EvoMap/evolver/pull/149)).
576
+ - [WeZZard](https://github.com/WeZZard) -- Added A2A_NODE_ID setup guide to SKILL.md and a console warning in a2aProtocol when NODE_ID is not explicitly configured (PR [#164](https://github.com/EvoMap/evolver/pull/164)).
577
+ - [Golden-Koi](https://github.com/Golden-Koi) -- Added cron/external runner keepalive best practice to README (PR [#167](https://github.com/EvoMap/evolver/pull/167)).
578
+ - [upbit](https://github.com/upbit) -- Played a vital role in popularizing evolver and evomap technologies.
579
+ - [Chi Jianqiang](https://mowen.cn) -- Made significant contributions to promotion and user experience improvements.
580
+
581
+ ## License
582
+
583
+ [GPL-3.0-or-later](https://opensource.org/licenses/GPL-3.0)
584
+
585
+ > Core evolution engine modules are distributed in obfuscated form to protect intellectual property. Source: [EvoMap/evolver](https://github.com/EvoMap/evolver).
586
+
587
+ ## Download History
37
588
 
38
- Hub egress defaults to `EVOMAP_HUB_IP_FAMILY=ipv4first`: Hub calls try IPv4 first to avoid VPN/TUN setups leaking
39
- over local IPv6 and tripping Cloudflare country/ASN rules, then fall back to dual-stack if IPv4 cannot connect. Set
40
- `EVOMAP_HUB_IP_FAMILY=auto` to restore dual-stack as the primary path, or `ipv4-only` to disable fallback.
589
+ Evolver ships through three channels — the [npm package](https://www.npmjs.com/package/@evomap/evolver), prebuilt binaries on [GitHub Releases](https://github.com/EvoMap/evolver/releases), and the [ClawHub](https://skill-history.com/autogame-17/evolver) skill registry:
41
590
 
42
- ## Prerequisites（批注#30）
43
- Evolver v2 期望 Agent 至少有 **Sonnet / GPT-4o-mini 同等归纳能力**——v2 不再为低配 LLM 包揽信号提取等职责（那是 v1 的负担，收益甚微）。
591
+ [![npm](https://img.shields.io/npm/dm/@evomap/evolver?logo=npm&label=npm)](https://www.npmjs.com/package/@evomap/evolver)
592
+ [![npm total](https://img.shields.io/npm/d18m/@evomap/evolver?logo=npm&label=npm%20total)](https://npm-stat.com/charts.html?package=@evomap/evolver)
593
+ [![GitHub releases](https://img.shields.io/github/downloads/EvoMap/evolver/total?logo=github&label=GitHub%20releases)](https://github.com/EvoMap/evolver/releases)
44
594
 
45
- ## Abstract（批注#36）
46
- 进化的本质 = **与外界环境交互得到反馈，从反馈中筛选有效的经验信号**。
595
+ [![ClawHub download history](https://skill-history.com/chart/autogame-17/evolver.svg)](https://skill-history.com/autogame-17/evolver)
package/assets/logo.png ADDED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evomap/evolver",
3
- "version": "2.0.0-beta.19",
3
+ "version": "2.0.0-beta.22",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Evolver v2 beta public distribution package.",
@@ -22,6 +22,7 @@
22
22
  },
23
23
  "files": [
24
24
  "bin/",
25
+ "assets/",
25
26
  "index.js",
26
27
  "README.md",
27
28
  "release-provenance.json",
@@ -31,13 +32,13 @@
31
32
  "node": "^22.13.0 || >=23.4.0"
32
33
  },
33
34
  "dependencies": {
34
- "@evomap/evolver-cli": "2.0.0-beta.19",
35
- "@evomap/evolver-mcp": "2.0.0-beta.19",
36
- "@evomap/evolver-proxy": "2.0.0-beta.19",
37
- "@evomap/evolver-core": "2.0.0-beta.19",
38
- "@evomap/evolver-adapter-public": "2.0.0-beta.19",
39
- "@evomap/evolver-runtime-adapters": "2.0.0-beta.19",
40
- "@evomap/evolver-webui": "2.0.0-beta.19"
35
+ "@evomap/evolver-cli": "2.0.0-beta.22",
36
+ "@evomap/evolver-mcp": "2.0.0-beta.22",
37
+ "@evomap/evolver-proxy": "2.0.0-beta.22",
38
+ "@evomap/evolver-core": "2.0.0-beta.22",
39
+ "@evomap/evolver-adapter-public": "2.0.0-beta.22",
40
+ "@evomap/evolver-runtime-adapters": "2.0.0-beta.22",
41
+ "@evomap/evolver-webui": "2.0.0-beta.22"
41
42
  },
42
43
  "publishConfig": {
43
44
  "access": "public",
package/release-provenance.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "version": "2.0.0-beta.19",
4
- "releaseTag": "v2.0.0-beta.19",
3
+ "version": "2.0.0-beta.22",
4
+ "releaseTag": "v2.0.0-beta.22",
5
5
  "channel": "v2-beta",
6
6
  "publicRepo": "EvoMap/evolver",
7
7
  "publicBranch": "v2-beta"