plugin: let users select/run algorithms from examples/ via EvolveSpec / CLI / MCP #384

Problem

The plugin (#165) lets a person say "evolve this skill against these examples" from inside Claude Code, Codex, DSH or OpenCode, and the run goes through EvolveSpec → compose() → evolve(). But every run uses the one default recipe for its kind (SingleSlot/FileTree + reflector/tree_reflector + the default merge). The 20+ published algorithms ported under examples/ (ACE, GEPA, EvoSkill, SkillOpt, ADAS, DGM, OpenEvolve, ERA, Genesis, TextGrad, Reflexion, Self-Refine, Voyager, …) cannot be chosen from the plugin at all. The only way to run one is python -m examples.<algo>.<script> from a source checkout, and each script hard-wires its own dataset, reward, strategy and aggregator_factory.

Users who install the plugin (CLI agentdescent plan/evolve/..., MCP server, host skills) need to be able to use these algorithms directly: list them, pick one by name, give it parameters, and run it on their own artifact and data, with the same plan → start → status → show → apply flow.

Current state (verified against main @ dfa1f5c, fresh clone, pip install . into a clean venv)

What I ran:

There is also no existing selection field: EvolveSpec.reflect only picks the model that proposes, and policies accepts only the SHORT_REFS names (SingleHead/Beam/ParetoFrontier/Archive/MCTS, RoundRobin/…, AdvantageAcceptance, reflective_merge, …) plus agentdescent.* refs. kind has text / skill_dir / agent_dir / agent_code / plugin (and policy_slot for #164). MCP exposes doctor plan start status show apply cancel resume audit_* and no discovery tool. The shipped SKILL.md and /evolve command never mention a choice of algorithm.

Examples vs. how reachable they are through the plugin

The 23 ports are documented in docs/self-evolution-examples.md and docs/port-fidelity.md, with a uniform CLI contract tested in tests/test_example_entrypoints.py. That contract is about scripts, not about a plugin-facing surface.

Why this is not just "allow examples in the allowlist"

1. examples/ is not shipped, so the CLI/MCP/host plugin cannot import it, by design.
2. The algorithm is bundled with a benchmark. Each port loads a fixed dataset (FiNER, HotpotQA, OfficeQA, SWE-bench ids, …) and a fixed reward; a plugin user wants the algorithm applied to their target + data + score.
3. The seams are already in the package (Policies, SelectionPolicy, AcceptancePolicy, Strategy, aggregator_factory), so each port's mechanism is separable from its domain. That separation is the work.
4. Related: Ship AgentDescent as a plugin for DeepSeek Harness, Claude Code, Codex and OpenCode #165 (plugin, this builds on it), meta_evolve: 演化 evolve() 自己的决策插槽，并在科研 agent 基准上验证迁移 #164 / kind: policy_slot (evolving a slot value, which is orthogonal: that evolves the algorithm, this lets you choose one), Support Google RRSI for regularized harness self-improvement #221 and 【第 20 个移植】EvoX Genesis(持久递归世界):完全对齐需要三处引擎缺口,以及两处必须声明的偏离 #183 (RRSI / Genesis, which would be early registry entries rather than special cases).

Proposed design

1. An algorithm registry inside the package (agentdescent/algorithms/, shipped in the wheel). An entry is a name, a one-line summary, the kinds it applies to, a fidelity class (benchmark_faithful / mechanism_microport / …, reusing docs/port-fidelity.md vocabulary), a typed/validated params schema with defaults, and a build(spec, params) -> Overrides that returns what to apply on top of the compose() row: a strategy, Policies fields, aggregator_factory, propose, and agg_config/evolve defaults. The example scripts keep their domains and CLIs but import their mechanism from the registry, so there is one implementation (the repo already did this for the engine stacks in #93).

2. EvolveSpec.algorithm: "gepa" or {"name": "gepa", "params": {...}}, validated in compose() with the same ref/SpecError discipline as policies. Unknown names list the registered ones; params are validated against the schema; an algorithm that does not support the spec's kind is rejected in plan. Explicit policies / agg_config / evolve entries in the spec still override the algorithm's defaults. plan echoes the resolved algorithm (name, params, fidelity, deviations) and counts its extra calls in estimate.

3. Close the spec.evolve gap. Either resolve strategy / aggregator_factory refs (through allow) or reject non-JSON-safe values for those keys in plan, so plan ok:true can no longer precede a crash.

4. CLI: agentdescent algorithms list [--kind K] [--json] and agentdescent algorithms show NAME (params, defaults, fidelity, what it changes); agentdescent init --algorithm NAME writes the field into the starter spec; plan/evolve --algorithm NAME [--param k=v] is sugar over the spec field.

5. MCP: list_algorithms (name, summary, kinds, params schema) and describe_algorithm(name); plan/start accept algorithm inside the spec like any other field. Tool descriptions say: "call list_algorithms when the user asks for a specific method, don't invent a name".

6. Host plugins/docs: update the shared agentdescent/integrations/SKILL.md (and claude-code/commands/evolve.md, the DSH plugin README, the OpenCode config text) with a short "choosing an algorithm" step: default to none; offer a named one when the user asks or the artifact fits; always show it in the plan. Add a docs/plugins.md section and a docs/algorithms.md catalog page generated from the registry (the repo already checks docs/api.md this way). Add a test that each registered name appears in the catalog and in docs/self-evolution-examples.md.

Non-goals: running the benchmark datasets through the plugin (the examples remain the way to reproduce paper numbers); changing engine semantics; auto-selecting an algorithm for the user; shipping examples/ itself in the wheel.

Acceptance criteria

• agentdescent algorithms list / show work from a plain pip install agentdescent (no checkout, no examples/), in text and --json.
• A spec with "algorithm": {"name": "<registered>", "params": {...}} passes plan, runs with evolve/start for each kind the entry declares, and plan output shows the resolved algorithm and its cost impact.
• Unknown algorithm, unknown param, wrong param type, or unsupported kind fail in plan with a message naming the field and the valid choices. None of them reaches a run.
• plan never returns ok: true for a spec whose evolve.strategy / aggregator_factory is an unresolved string (regression test for the AttributeError: 'str' object has no attribute 'initial' above).
• MCP list_algorithms / describe_algorithm return the same data as the CLI; covered in tests/test_mcp.py.
• Shared SKILL.md, the Claude Code command, the DSH README and the OpenCode install text mention algorithm selection; the install/skill drift tests still pass.
• Each registered algorithm has: a registry test (build with a fake agent, one offline round), the example script importing it from the registry (no duplicated mechanism), and a row in docs/algorithms.md stating fidelity and deviations.
• The offline agentdescent demo path is unchanged, and engine/aggregator/ledger code is untouched.

Kind filter + fidelity (design-review addendum, 2026-11-07)

From an internal product-surface review: same-name Algorithm cards vs examples/ research ports (e.g. gepa card vs examples/gepa/, and the same pattern for ACE / DGM / SkillOpt / EvoSkill) must not be conflated, and host pick/run must not offer cards that cannot run on that host.

• Kind filter: algorithms list / show and every host-facing pick surface (CLI flag, MCP list_algorithms, /algorithms / host skill) MUST filter (or clearly mark ineligible) by host kind (text / skill_dir / agent_dir / …). Users must not be offered cards that cannot run on that host. Selecting an unsupported kind fails in plan with the valid kinds listed (no silent accept).
• Card vs port distinction: list / show (and host pick UI copy) MUST distinguish Algorithm cards (mechanism slices shipped in the wheel) from full research ports under examples/ (paper-faithful scripts, source-only). Same name ≠ same fidelity. Output names fidelity class (reuse docs/port-fidelity.md vocabulary) and never silently claims paper-method fidelity when only a mechanism-slice card will run.
• Honest run echo: plan / start / host status copy that resolves "algorithm": "gepa" (etc.) states which surface ran (card vs port) and its fidelity; no wording that implies the benchmark-faithful examples/<algo>/ path unless that path actually ran.
• Related same-name card-vs-port pattern to cover in catalog/docs rows: at least ACE, GEPA, DGM, SkillOpt, EvoSkill (link docs/port-fidelity.md, Ship AgentDescent as a plugin for DeepSeek Harness, Claude Code, Codex and OpenCode #165).

Breakdown into single-PR slices

1. Registry + list + two algorithms end-to-end (small, ship first). agentdescent/algorithms/ with Algorithm, register, get, list; EvolveSpec.algorithm (from_dict, to_dict, compose() hook, plan echo); agentdescent algorithms list|show; wire two entries that need no new engine work. Suggested: one Policies-only (RRSI bundle, which already has a clean build_rrsi_bundle) and one selection-only (e.g. gepa Pareto selection over a text spec, or Beam/ParetoFrontier as named presets). Tests: registry, validation errors, plan for each, one offline evolve() round with the echo agent. No MCP/doc changes beyond a CHANGELOG fragment in changelog.d/.
2. spec.evolve ref-resolution / plan guard (acceptance bullet 4). Independent of slice 1, can land in parallel.
3. MCP list_algorithms / describe_algorithm + CLI init --algorithm / --param. Includes tool descriptions and tests/test_mcp.py.
4. Host skill and docs: SKILL.md, Claude Code command, DSH README, OpenCode text, docs/plugins.md section, generated docs/algorithms.md, drift tests.
5. Move mechanisms out of examples/ into the registry, in groups (one PR per group; scripts keep their CLIs and tests/test_example_entrypoints.py stays green):
   • 5a. Benchmark-faithful skill/prompt ports: ACE, GEPA, SkillOpt, EvoSkill (strategy + aggregator_factory).
   • 5b. Harness/program ports: ADAS, DGM, OpenEvolve, ERA, which are agent_dir/agent_code shaped and need FileTree params.
   • 5c. MethodPolicy microports (14), which need a spec-friendly way to supply solve/propose/reward from score/agent instead of the example's own tasks. Likely the largest design question, so settle it in a short design note first.
   • 5d. Genesis (【第 20 个移植】EvoX Genesis(持久递归世界):完全对齐需要三处引擎缺口,以及两处必须声明的偏离 #183) and anything that needs engine gaps.
6. Optional follow-up: let a spec name an external algorithm via an entry-point group (agentdescent.algorithms), so third-party ports can register without a PR here.

Slices 1 and 2 are the minimum to make the surface real; 3 and 4 make it usable from a host; 5 is where the catalog actually grows.