@tangle-network/agent-runtime 0.43.0 → 0.45.0

package/README.md

@@ -1,38 +1,25 @@
 # @tangle-network/agent-runtime
 
-The task-lifecycle substrate for domain agents. It owns the **chat-turn engine**, the **driven-loop kernel** (refine / fanout-vote / agent-authored *dynamic* topologies), **delegated loops** (build-in-a-loop, valid-only research, review, audit, self-improve), **identity-gated prompt optimization**, **OpenTelemetry GenAI tracing**, knowledge readiness, sanitized telemetry, and the declarative `defineAgent` manifest — and delegates domain behavior (models, tools, KB) to adapters. Long-running execution durability lives in [`@tangle-network/sandbox`](https://www.npmjs.com/package/@tangle-network/sandbox); evals + gates in [`@tangle-network/agent-eval`](https://www.npmjs.com/package/@tangle-network/agent-eval).
+The shared task-lifecycle skeleton for agents. It runs an agent (a chat turn, a one-shot task, or a multi-attempt loop), captures every run as a trace, and feeds those traces into eval-gated self-improvement.
+
+It owns the lifecycle and the loop kernel. It delegates domain behavior (models, tools, knowledge) to adapters, scoring and the ship gate to [`@tangle-network/agent-eval`](https://www.npmjs.com/package/@tangle-network/agent-eval), and sandboxed long-running execution to [`@tangle-network/sandbox`](https://www.npmjs.com/package/@tangle-network/sandbox).
 
 ```bash
 pnpm add @tangle-network/agent-runtime @tangle-network/agent-eval @tangle-network/sandbox
 ```
 
----
-
-## Contents
-
-- [Getting started](#getting-started) — the 20-line production chat turn
-- [Which entry point do I reach for?](#which-entry-point-do-i-reach-for)
-- [Capabilities](#capabilities)
-  - [1. Chat turns — `handleChatTurn`](#1-chat-turns--handlechatturn)
-  - [2. Driven loops + topology drivers](#2-driven-loops--topology-drivers)
-  - [3. Agent-authored topology — `createDynamicDriver`](#3-agent-authored-topology--createdynamicdriver)
-  - [4. Delegated loop-runner — `runDelegatedLoop`](#4-delegated-loop-runner--rundelegatedloop)
-  - [5. Reliable build-in-a-loop — the coder delegate](#5-reliable-build-in-a-loop--the-coder-delegate)
-  - [6. Valid-only research — `createKbGate`](#6-valid-only-research--createkbgate)
-  - [7. Identity-gated prompt optimization — `optimizePrompt`](#7-identity-gated-prompt-optimization--optimizeprompt)
-  - [8. OpenTelemetry GenAI topology tracing](#8-opentelemetry-genai-topology-tracing)
-  - [9. MCP delegation server — `agent-runtime-mcp`](#9-mcp-delegation-server--agent-runtime-mcp)
-- [Defaults](#defaults)
-- [Composition with the stack](#composition-with-the-stack)
-- [Subpath exports](#subpath-exports)
-- [Adoption skill](#adoption-skill)
-- [Stability · Tests · Docs](#stability--tests--docs)
-
----
+## The model
+
+One recursive `Agent` atom, run at two timescales, over many tasks. `docs/architecture.md` is the canonical spine. The short version:
+
+1. **One atom.** `driver`, `worker`, `selector`, and `coordinator` are not separate types. They are what a single `Agent` returns from `act`. The recursion bottoms out at execution.
+2. **Two timescales, one machinery.** The same loop runs at inference time (steer a worker over k attempts) and at optimization time (search the steer or the prompt with GEPA, gated on a held-out split).
+3. **A benchmark is an adapter.** A new task is a loader plus a worker plus a judge. The loop, the drivers, the corpus, and the selector are the shared spine, written once.
+4. **The selector is not the judge.** At inference time the selector picks which answer to return without seeing the judge's verdict. The judge is write-only. A steer may read the trace but never the verdict (the firewall that keeps the loop from gaming its own score).
 
 ## Getting started
 
-Every product agent is a `handleChatTurn` call inside a route. This is what gtm / creative / legal / tax all run in production:
+Every product agent is a `handleChatTurn` call inside a route. This is what the gtm, creative, legal, and tax products run in production:
 
 ```ts
 import { handleChatTurn } from '@tangle-network/agent-runtime'
@@ -57,181 +44,95 @@ export async function POST({ request, env, ctx }: { request: Request; env: Env;
 }
 ```
 
-That's the centerpiece. Everything below is *"when one chat turn isn't enough"* — multi-shot loops, delegation, optimization, and the telemetry that makes them auditable.
-
----
+That is the common case. Everything below is for when one chat turn is not enough: multi-attempt loops, delegation, optimization, and the telemetry that makes them auditable.
 
 ## Which entry point do I reach for?
 
-| You want to… | Reach for | Subpath |
+| You want to | Reach for | Subpath |
 |---|---|---|
-| Run a production chat turn (90% of products) | `handleChatTurn` | root |
-| Declare an agent (profile + surfaces + adapters) | `defineAgent` | `/agent` |
-| One-shot task with verification + eval | `runAgentTask` | root |
-| Multi-shot loop (refine / fanout-vote) | `runLoop` + a driver | `/loops` |
-| Let the **agent choose** the loop shape per round | `createDynamicDriver` + `createSandboxPlanner` | `/loops` |
-| Delegate a disciplined loop by mode (code/research/…) | `runDelegatedLoop` / `agent-runtime-loop` | root |
+| Run a production chat turn (most products) | `handleChatTurn` | root |
+| Declare an agent (profile, surfaces, adapters) | `defineAgent` | `/agent` |
+| Run a one-shot task with verification and eval | `runAgentTask` | root |
+| Run a multi-attempt loop (refine or fanout-vote) | `runLoop` plus a driver | `/loops` |
+| Let the agent choose the loop shape per round | `createDynamicDriver` plus `createSandboxPlanner` | `/loops` |
+| Delegate a disciplined loop by mode (code, research, ...) | `runDelegatedLoop` or `agent-runtime-loop` | root |
 | Build code reliably (reviewed, gated) | `createDefaultCoderDelegate` | `/mcp` |
-| Grow a KB with only grounded facts | `createKbGate` | `/mcp` |
-| Improve a prompt safely (identity-gated) | `optimizePrompt` | `/improvement` |
-| Ship loop traces to a GenAI viewer | `buildLoopOtelSpans` + `createOtelExporter` | root |
-| Expose delegation as MCP tools to a sandbox agent | `createMcpServer` / `agent-runtime-mcp` | `/mcp` |
+| Grow a knowledge base with only grounded facts | `createKbGate` | `/mcp` |
+| Improve a prompt safely (identity-gated) | `selfImprove` | `@tangle-network/agent-eval/contract` |
+| Ship loop traces to a GenAI viewer | `buildLoopOtelSpans` plus `createOtelExporter` | root |
+| Expose delegation as MCP tools to a sandbox agent | `createMcpServer` or `agent-runtime-mcp` | `/mcp` |
 | Mutate surfaces from trace findings | `runAnalystLoop` | `/analyst-loop` |
-| Persist a run + cost ledger | `startRuntimeRun` | root |
-
----
-
-## Capabilities
-
-### 1. Chat turns — `handleChatTurn`
+| Persist a run plus its cost ledger | `startRuntimeRun` | root |
 
-The production turn envelope: frames a producer with the `session.run.*` NDJSON protocol, the persist → post-process → trace-flush hook order, and a stable execution id for client-retry replay. See [Getting started](#getting-started) and [`examples/chat-handler/`](./examples/chat-handler/).
+## The loop kernel
 
-### 2. Driven loops + topology drivers
-
-`runLoop` is a topology-agnostic kernel: each iteration spawns a sandbox on an `AgentRunSpec`, decodes the output, validates it, and asks a **driver** what to do next. The driver owns topology; the validator owns scoring; the kernel owns iteration accounting, concurrency, cost/token aggregation, and trace emission.
+`runLoop` is a topology-agnostic kernel. Each iteration spawns a sandbox on an `AgentRunSpec`, decodes the output, validates it, and asks a driver what to do next. The driver owns topology. The validator owns scoring. The kernel owns iteration accounting, concurrency, cost and token aggregation, and trace emission.
 
 ```ts
 import { runLoop, createFanoutVoteDriver } from '@tangle-network/agent-runtime/loops'
 
 const result = await runLoop({
-  driver: createFanoutVoteDriver({ n: 3 }),       // 3 parallel attempts, pick the best valid one
-  agentRuns: [claudeSpec, codexSpec, glmSpec],    // heterogeneous: one harness per branch
-  output,                                          // events → typed Output
-  validator,                                       // Output → { valid, score }
+  driver: createFanoutVoteDriver({ n: 3 }),    // 3 parallel attempts, pick the best valid one
+  agentRuns: [claudeSpec, codexSpec, glmSpec], // heterogeneous: one harness per branch
+  output,                                       // events to typed Output
+  validator,                                    // Output to { valid, score }
   task,
   ctx: { sandboxClient: sandbox },
 })
 result.winner // highest-scoring valid attempt
 ```
 
-Shipped drivers (`/loops/drivers`): **`createRefineDriver`** (single task, iterate until valid) and **`createFanoutVoteDriver`** (N parallel, vote). See [`examples/coder-loop/`](./examples/coder-loop/) and [`examples/researcher-loop/`](./examples/researcher-loop/).
+Shipped drivers (`/loops/drivers`): `createRefineDriver` (single task, iterate until valid), `createFanoutVoteDriver` (N parallel, vote), and `createDynamicDriver` (the agent authors the topology at runtime). The dynamic driver emits one `TopologyMove` per round (`refine`, `fanout`, or `stop`) from an injected planner; a malformed move throws `PlannerError`, so the loop never runs a topology nobody chose. Topology is orthogonal to harness: the planner never names a backend, and the kernel's `agentRuns` decide which harness runs each branch.
 
-### 3. Agent-authored topology — `createDynamicDriver`
+`runProgram` (also in `/loops`) is the recursive op-set (`sample`, `steer`, `fork`, `parallel`, `select`, `seq`, `stop`) plus a tree executor, for programs that compose sub-loops.
 
-The third driver lets the **agent author the loop topology at runtime** — refine, fan out, or stop, decided per round by an injected planner. Topology is orthogonal to harness: the planner never names a backend; the kernel's `agentRuns` round-robin decides which harness runs each branch.
+## Self-improvement
 
-```ts
-import { runLoop, createDynamicDriver, createSandboxPlanner } from '@tangle-network/agent-runtime/loops'
+The same machinery, run at the optimization timescale.
 
-const planner = createSandboxPlanner({
-  client: sandbox,
-  profile: { name: 'planner', metadata: { backendType: 'claude-code' } }, // cheap model is fine
-  decodeTask: (raw) => raw as Task,
-})
+The one entry point is agent-eval's **`selfImprove`** (`@tangle-network/agent-eval/contract`). It runs a closed loop over any text/config surface, identity-gated by construction: it evaluates, proposes candidates (default `gepaDriver`), and a held-out gate ships a winner only if it beats the baseline. `result.winner.surface` is the baseline unless `result.gateDecision === 'ship'`, so registering a surface for optimization can never regress it.
 
-const result = await runLoop({
-  driver: createDynamicDriver({ planner, maxIterations: 8 }),
-  agentRuns: [claudeSpec, codexSpec],   // the planner can fan a single round across both
-  output, validator, task,
-  ctx: { sandboxClient: sandbox },
+```ts
+import { selfImprove } from '@tangle-network/agent-eval/contract'
+
+const result = await selfImprove({
+  baselineSurface: CURRENT_SYSTEM_PROMPT,
+  agent: (surface, scenario, ctx) => runYourThing(surface, scenario),
+  scenarios,
+  judge,
+  budget: { holdoutScenarios, generations: 3 },
+  llm: { baseUrl, apiKey, model: 'claude-sonnet-4-6' },
 })
+// result.winner.surface is the safe one — the baseline unless gateDecision === 'ship'
 ```
 
-The planner emits one `TopologyMove` per round (`refine` | `fanout` | `stop`) with a rationale; a malformed move throws `PlannerError` (the loop never runs a topology nobody chose).
+agent-runtime contributes the runtime-specific piece: the **CODE-surface `improvementDriver`** (`/improvement`) — a git-worktree mutator you pass to `selfImprove` as `driver` to optimize code instead of a string.
 
-### 4. Delegated loop-runner — `runDelegatedLoop`
+`runAnalystLoop` (`/analyst-loop`) mines real run traces into findings; `createAnalystDriverHook` feeds those findings to a dynamic-driver planner via `PlannerContext.analyses`, with a firewall (`assertTraceDerivedFindings`) that rejects any finding derived from a judge verdict. Production intake — turning real run traces into the corpus `selfImprove` optimizes against — is agent-eval's `analyzeRuns` / `partitionRunsByAuthoringModel` (`/contract`).
 
-One configured entrypoint a worker agent (or a scheduled routine) calls to run a disciplined loop in a chosen **mode**, over the hardened engines below. Fail-loud on an unwired mode; a thrown engine is captured as `{ ok: false }` so unattended runs *record* rather than crash.
+## Delegated loops
+
+`runDelegatedLoop` is one entrypoint a worker agent or a scheduled routine calls to run a disciplined loop in a chosen mode, over the hardened engines below. It fails loud on an unwired mode; a thrown engine is captured as `{ ok: false }`, so unattended runs record rather than crash.
 
 ```ts
-import {
-  runDelegatedLoop, coderLoopRunner, researchLoopRunner, type DelegatedLoopRegistry,
-} from '@tangle-network/agent-runtime'
+import { runDelegatedLoop, coderLoopRunner, researchLoopRunner, type DelegatedLoopRegistry } from '@tangle-network/agent-runtime'
 
 const registry: DelegatedLoopRegistry = {
-  code: coderLoopRunner({
-    sandboxClient,
-    args: { goal: 'fix the flaky retry test', repoRoot: '/repo' },
-    reviewer,                       // optional adversarial gate
-    winnerSelection: 'smallest-diff',
-  }),
+  code: coderLoopRunner({ sandboxClient, args: { goal: 'fix the flaky retry test', repoRoot: '/repo' }, reviewer, winnerSelection: 'smallest-diff' }),
   research: researchLoopRunner({ research, gate: { selfArtifactKinds: ['spec'] }, maxRounds: 3 }),
 }
-
 const result = await runDelegatedLoop('code', registry)
-// → { mode: 'code', ok: true, output: CoderOutput, durationMs }
-```
-
-Modes: `code` · `review` · `research` · `audit` · `self-improve` · `dynamic` — each with a default factory (`coderLoopRunner`, `reviewLoopRunner`, `researchLoopRunner`, `dynamicLoopRunner`, `selfImproveLoopRunner`, `auditLoopRunner`).
-
-**Schedulable**: the `agent-runtime-loop` bin runs it from a cron/routine. The config module wires the registry (with full env/creds access):
-
-```bash
-agent-runtime-loop --mode research --config ./loops.config.js
-# exits 0 (ok) · 1 (recorded failure) · 2 (usage/config error); prints the result as JSON
-```
-
-```ts
-// loops.config.js — default-exports a DelegatedLoopRegistry (or a factory)
-import { researchLoopRunner } from '@tangle-network/agent-runtime'
-export default { research: researchLoopRunner({ research: myResearchEngine, maxRounds: 3 }) }
-```
-
-### 5. Reliable build-in-a-loop — the coder delegate
-
-`createDefaultCoderDelegate` drives a coder loop with **default-on safety gates** so it never ships junk:
-
-- **no-op rejection** — an empty patch can't "pass" trivially,
-- **secret-path floor** — always-on, independent of `forbiddenPaths` (`.env`, keys, wallets, …),
-- optional **`reviewer`** gate — a candidate must pass tests/typecheck **and** be approved to win,
-- **`winnerSelection`** — `highest-score` (default) · `smallest-diff` · `highest-readiness` · `first-approved`.
-
-```ts
-import { createDefaultCoderDelegate } from '@tangle-network/agent-runtime/mcp'
-
-const coder = createDefaultCoderDelegate({
-  sandboxClient,
-  fanoutHarnesses: ['claude-code', 'codex'],
-  reviewer: async (output, task) => ({ approved: output.testResult.passed, recommendation: 'ship', readiness: 0.9 }),
-  winnerSelection: 'highest-readiness',
-})
-const out = await coder({ goal: 'add a retry with backoff', repoRoot: '/repo', variants: 2 }, ctx)
 ```
 
-See [`examples/coder-loop/`](./examples/coder-loop/) and [`examples/agent-into-reviewer/`](./examples/agent-into-reviewer/).
-
-### 6. Valid-only research — `createKbGate`
-
-A fail-closed gate so a knowledge base grows with **only grounded facts**. The always-on floor: a fact's `verbatimPassage` must literally appear in its `sourceText` (anti-hallucination), the asserted value must be in the passage, and citations can't point at self-generated artifacts (laundering). Plug in your own judges; verdict-only (remediation is yours).
-
-```ts
-import { createKbGate } from '@tangle-network/agent-runtime/mcp'
-
-const gate = createKbGate({ selfArtifactKinds: ['spec', 'cad_params'] })
-const verdict = await gate({
-  claim: 'revenue was $1.2B in 2025',
-  value: 1_200_000_000,
-  verbatimPassage: 'total revenue was $1,200,000,000 for the fiscal year',
-  sourceText: rawSource,
-})
-if (verdict.accepted) writeToKb(fact)
-else console.warn('vetoed by', verdict.vetoedBy, verdict.reason)
-```
-
-`researchLoopRunner` (mode `research`) wraps this with a correct-on-veto remediation loop: research → gate → re-research the vetoed gaps up to `maxRounds`, then **return** the unverified ones (escalate, never silently drop).
-
-### 7. Identity-gated prompt optimization — `optimizePrompt`
+Modes: `code`, `review`, `research`, `audit`, `self-improve`, `dynamic`. The `agent-runtime-loop` bin runs the registry from a cron or routine and exits 0 (ok), 1 (recorded failure), or 2 (usage or config error).
 
-Optimize any text prompt over agent-eval's `runImprovementLoop`, **identity-gated by construction**: it runs evals, proposes candidates (default `gepaDriver`), and the held-out gate compares candidate vs baseline. `result.prompt` is the **baseline unless the gate decided `ship`** — so registering a prompt for optimization can never regress it.
+The coder delegate (`createDefaultCoderDelegate`, `/mcp`) has default-on safety gates: no-op rejection (an empty patch cannot pass trivially), an always-on secret-path floor (`.env`, keys, wallets), an optional `reviewer` gate, and a `winnerSelection` policy (`highest-score`, `smallest-diff`, `highest-readiness`, `first-approved`).
 
-```ts
-import { optimizePrompt } from '@tangle-network/agent-runtime/improvement'
-
-const { prompt, improved, delta } = await optimizePrompt({
-  baselinePrompt: CURRENT_SYSTEM_PROMPT,
-  runWithPrompt: (candidate, scenario, ctx) => runYourThing(candidate, scenario),
-  scenarios, holdoutScenarios, judges, runDir,
-  reflection: { llm, model: 'claude-sonnet-4-6' },
-})
-// assign `prompt` unconditionally — it's the safe one
-```
+The knowledge-base gate (`createKbGate`, `/mcp`) is fail-closed: a fact's `verbatimPassage` must appear in its `sourceText`, the asserted value must be in the passage, and citations cannot point at self-generated artifacts. `researchLoopRunner` wraps it with a correct-on-veto loop that re-researches the vetoed gaps up to `maxRounds`, then returns the unverified ones rather than dropping them.
 
-See [`examples/self-improving-loop/`](./examples/self-improving-loop/).
+## Tracing
 
-### 8. OpenTelemetry GenAI topology tracing
-
-`runLoop` emits a structured event stream; `buildLoopOtelSpans` turns it into a **nested, real-duration span tree** that any GenAI trace viewer (Phoenix, Langfuse, Grafana Tempo, Tangle Intelligence) renders natively. Attributes follow the current GenAI semantic conventions (`gen_ai.operation.name`, `gen_ai.agent.name`, `gen_ai.usage.input_tokens/output_tokens`) plus a `tangle.loop.*` extension for the topology (move kind/rationale, edge lineage, verdict, placement, cost).
+`runLoop` emits a structured event stream. `buildLoopOtelSpans` turns it into a nested, real-duration span tree that any GenAI trace viewer (Phoenix, Langfuse, Grafana Tempo, Tangle Intelligence) renders natively. Attributes follow the current GenAI semantic conventions (`gen_ai.operation.name`, `gen_ai.agent.name`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) plus a `tangle.loop.*` extension for the topology (move kind and rationale, edge lineage, verdict, placement, cost).
 
 ```ts
 import { buildLoopOtelSpans, createOtelExporter } from '@tangle-network/agent-runtime'
@@ -241,94 +142,87 @@ for (const span of buildLoopOtelSpans(loopEvents, traceId)) exporter?.exportSpan
 await exporter?.flush()
 ```
 
-The shape: `loop → loop.round (move + rationale) → loop.iteration (agent, usage, verdict, cost, parent edge)`. See [`examples/with-intelligence-export/`](./examples/with-intelligence-export/).
+The shape: `loop` to `loop.round` (move plus rationale) to `loop.iteration` (agent, usage, verdict, cost, parent edge).
 
-### 9. MCP delegation server — `agent-runtime-mcp`
+## MCP delegation server
 
-Expose the five delegation tools (`delegate_code`, `delegate_research`, `delegate_feedback`, `delegation_status`, `delegation_history`) to a sandbox coding-harness agent — mount the canonical server, don't fork delegation logic.
+Expose the delegation tools (`delegate_code`, `delegate_research`, `delegate_feedback`, `delegation_status`, `delegation_history`) to a sandbox coding agent. Mount the canonical server instead of forking delegation logic.
 
 ```ts
 import { createMcpServer, createDefaultCoderDelegate } from '@tangle-network/agent-runtime/mcp'
 
-const server = createMcpServer({
-  coderDelegate: createDefaultCoderDelegate({ sandboxClient }),
-  researcherDelegate, // wire your KB-backed researcher
-})
+const server = createMcpServer({ coderDelegate: createDefaultCoderDelegate({ sandboxClient }), researcherDelegate })
 ```
 
-Or mount the `agent-runtime-mcp` stdio bin on a production `AgentProfile.mcp`. See [`examples/mcp-delegation/`](./examples/mcp-delegation/) and [`examples/fleet-delegation/`](./examples/fleet-delegation/).
+Or mount the `agent-runtime-mcp` stdio bin on a production `AgentProfile.mcp`.
 
----
+## The experiment harness (bench/)
 
-## Defaults
+`bench/` is the internal harness that asks the binding empirical question: does any non-blind topology beat blind compute at equal k, under a deployable (non-oracle) selector, on a real benchmark? It runs through the same kernel, not a reimplementation.
 
-When nothing is specified:
+One entrypoint, `runExperiment(adapter, { sandboxClient, agentRun, arms, ... })`: N instances times a set of arms, each arm a topology driven through `runLoop`, judged by the adapter, written to a durable canonical corpus. An arm is one steer function `f(rootPrompt, history) => nextPrompt`: `random` ignores history (the compute control), `refine` carries the prior answer plus a directive, `diverse` rotates a strategy lens. The cost dial is the backend type (`hermes` for a direct router call, `opencode` or `claude-code` or `codex` for agent CLIs). The deep statistics (paired bootstrap with Benjamini-Hochberg correction, selector replay) come from `corpus-report.mts` and `corpus-replay.mts` over the written corpus, computed once. See `bench/HARNESS.md` and `docs/learning-flywheel.md`.
+
+## Defaults
 
 | Knob | Default | Override |
 |---|---|---|
-| Backend model | `gpt-4o-mini` (via `createOpenAICompatibleBackend`) | `model` option / `MODEL_NAME` env |
+| Backend model | `gpt-4o-mini` (via `createOpenAICompatibleBackend`) | `model` option or `MODEL_NAME` env |
 | Backend provider | `openai-compat` when `TANGLE_API_KEY`, else `openai` if `OPENAI_API_KEY` | `MODEL_PROVIDER` env |
 | Router base URL | `https://router.tangle.tools/v1` | `TANGLE_ROUTER_BASE_URL` env |
 | Sandbox base URL | `https://sandbox.tangle.tools` | `SANDBOX_API_URL` env |
-| Loop iteration cap | 10 (`runLoop`); dynamic driver 8 | `runLoop({ maxIterations })` |
-| Driver | none — required by `runLoop` | `createRefineDriver` / `createFanoutVoteDriver` / `createDynamicDriver` |
+| Loop iteration cap | 10 (`runLoop`), 8 (dynamic driver) | `runLoop({ maxIterations })` |
+| Driver | none, required by `runLoop` | `createRefineDriver`, `createFanoutVoteDriver`, `createDynamicDriver` |
 | Winner selection (coder delegate) | `highest-score` | `winnerSelection` option |
 | KB gate min passage | 12 chars | `createKbGate({ minPassageChars })` |
-| `optimizePrompt` gate | `heldOutGate` | `defaultProductionGate` for red-team hardening |
+| `selfImprove` gate | held-out gate (default) | pass `gate: defaultProductionGate` for red-team hardening |
 | OTEL export | off | set `OTEL_EXPORTER_OTLP_ENDPOINT` |
 | Loop-runner mode failure | recorded as `{ ok: false }` | `runDelegatedLoop` never crashes on a thrown engine |
 
----
-
 ## Composition with the stack
 
 ```
-agent-runtime  ──  handleChatTurn · runLoop + drivers · runDelegatedLoop · createMcpServer
-                   optimizePrompt · createKbGate · buildLoopOtelSpans · defineAgent
+agent-runtime   handleChatTurn, runLoop + drivers, runProgram, runDelegatedLoop, createMcpServer,
+                improvementDriver, createKbGate, buildLoopOtelSpans, defineAgent
 
-agent-eval     ──  runEvalCampaign · runImprovementLoop (gepaDriver) · heldOutGate · runAgentMatrix
-                   (consumes runtime traces, scores, gates promotion)
+agent-eval      selfImprove (the optimization entry point), runEvalCampaign,
+                runImprovementLoop (gepaDriver), heldOutGate, runAgentMatrix, analyzeRuns.
+                Consumes runtime traces, scores, gates promotion. agent-runtime depends on it,
+                never the reverse.
 
-agent-knowledge ─  proposeKnowledgeWrites / applyKnowledgeWriteBlocks
-                   (analyst-loop produces these; runtime + createKbGate consume them)
+agent-knowledge proposeKnowledgeWrites, applyKnowledgeWriteBlocks. The analyst loop produces
+                these; the runtime and createKbGate consume them.
 
-sandbox        ──  AgentProfile · Sandbox.create · streamPrompt · exportTraceBundle
-                   (the harness execution surface every loop runs on)
+sandbox         AgentProfile, Sandbox.create, streamPrompt, exportTraceBundle. The harness
+                execution surface every loop runs on.
 ```
 
----
-
 ## Subpath exports
 
 | Import | Owns |
 |---|---|
 | `@tangle-network/agent-runtime` | chat turns, delegated loop-runner, OTEL export, errors, model resolution |
-| `…/agent` | `defineAgent` + surfaces / outcome adapters |
-| `…/loops` | `runLoop` kernel + `refine` / `fanout-vote` / **`dynamic`** drivers + `loopDispatch` |
-| `…/profiles` | `coderProfile`, `researcherProfile` presets |
-| `…/mcp` | `createMcpServer`, `createDefaultCoderDelegate`, **`createKbGate`**, `agent-runtime-mcp` bin |
-| `…/improvement` | **`optimizePrompt`** (text) + `improvementDriver` (code/worktree) |
-| `…/analyst-loop` | `runAnalystLoop` — analyst registry driver |
-| `…/platform` | cross-site SSO + integrations hub |
-
-Bins: `agent-runtime-mcp` (delegation MCP server) · `agent-runtime-loop` (schedulable delegated loop-runner).
+| `.../agent` | `defineAgent` plus surface and outcome adapters |
+| `.../loops` | the `runLoop` kernel, the `refine` / `fanout-vote` / `dynamic` drivers, `runProgram`, `loopDispatch` |
+| `.../profiles` | `coderProfile`, `researcherProfile` presets |
+| `.../mcp` | `createMcpServer`, `createDefaultCoderDelegate`, `createKbGate`, the `agent-runtime-mcp` bin |
+| `.../improvement` | `improvementDriver` (code/worktree `CandidateGenerator`), `agenticGenerator`, `reflectiveGenerator` — the code-surface driver you pass to agent-eval's `selfImprove` |
+| `.../analyst-loop` | `runAnalystLoop`, the analyst registry driver |
+| `.../platform` | cross-site SSO and the integrations hub |
 
----
+Bins: `agent-runtime-mcp` (delegation MCP server), `agent-runtime-loop` (schedulable delegated loop-runner).
 
 ## Adoption skill
 
-This package ships a **self-contained adoption skill** at [`skills/agent-runtime-adoption/SKILL.md`](./skills/agent-runtime-adoption/SKILL.md) — driven loops, topology drivers, the `loopDispatch` campaign bridge, MCP delegation, and identity-gated `optimizePrompt`. It needs only this package + `@tangle-network/agent-eval`, so external consumers need nothing private. For the full self-improving pipeline (trace sink → analyst loop → scorecard → production loop → CI), see the `agent-eval-adoption` / `agent-stack-adoption` skills.
-
----
+This package ships a self-contained adoption skill at [`skills/agent-runtime-adoption/SKILL.md`](./skills/agent-runtime-adoption/SKILL.md): driven loops, topology drivers, the `loopDispatch` campaign bridge, MCP delegation, and the code-surface `improvementDriver` for agent-eval's `selfImprove`. It needs only this package plus `@tangle-network/agent-eval`. For the full self-improving pipeline (trace sink, analyst loop, scorecard, production loop, CI), see the `agent-eval-adoption` and `agent-stack-adoption` skills.
 
-## Stability · Tests · Docs
+## Stability, tests, docs
 
-Every public export is annotated `@stable` or `@experimental`. `@stable` exports don't change shape inside a minor; `@experimental` ones may and require a deliberate consumer bump.
+Every public export is annotated `@stable` or `@experimental`. `@stable` exports do not change shape inside a minor version; `@experimental` ones may, and require a deliberate consumer bump.
 
 ```bash
-pnpm test       # full suite across the kernel, drivers, MCP, delegate hardening, kb-gate, loop-runner, backends
+pnpm test       # kernel, drivers, MCP, delegate hardening, kb-gate, loop-runner, backends
 pnpm typecheck
 pnpm build
 ```
 
-Deeper docs: [`docs/concepts.md`](./docs/concepts.md) (mental model) · [`docs/agent-bus-protocol.md`](./docs/agent-bus-protocol.md) (cross-gateway header contract) · [`docs/conversation-economics.md`](./docs/conversation-economics.md) (who pays — `authSource`) · [`docs/durability-adapters.md`](./docs/durability-adapters.md) (SQL-backed `ConversationJournal`).
+Deeper docs: [`docs/architecture.md`](./docs/architecture.md) (the canonical spine), [`docs/learning-flywheel.md`](./docs/learning-flywheel.md) (the self-improvement thesis and the open gate), [`docs/concepts.md`](./docs/concepts.md) (mental model), [`docs/agent-bus-protocol.md`](./docs/agent-bus-protocol.md) (cross-gateway header contract), [`docs/conversation-economics.md`](./docs/conversation-economics.md) (who pays), [`docs/durability-adapters.md`](./docs/durability-adapters.md) (SQL-backed `ConversationJournal`).

package/dist/agent.d.ts

@@ -1,11 +1,12 @@
 import * as _tangle_network_agent_eval from '@tangle-network/agent-eval';
 import { TraceAnalystKindSpec, AnalystFinding } from '@tangle-network/agent-eval';
-import { R as RuntimeStreamEvent, L as LoopSandboxClient, a as OutputAdapter, A as AgentRunSpec } from './types-Bcp071Jg.js';
-import { A as AgentSurfaces } from './improvement-adapter-BC4HhuAR.js';
-export { C as CreateSurfaceImprovementAdapterOpts, D as DraftPatchInput, a as DraftPatchOutput, R as ResolvedSurface, S as SurfaceImprovementEdit, b as SurfaceValidationIssue, c as createSurfaceImprovementAdapter, r as renderSurfaceIssues, d as resolveSubjectPath, v as validateSurfaces } from './improvement-adapter-BC4HhuAR.js';
-import { K as KnowledgeAdapter, a as RunAnalystLoopResult } from './types-p8dWBIXL.js';
+import { R as RuntimeStreamEvent, b as LoopSandboxClient, O as OutputAdapter, A as AgentRunSpec } from './types-DdzkffAm.js';
+import { A as AgentSurfaces } from './improvement-adapter-CWegd3vw.js';
+export { C as CreateSurfaceImprovementAdapterOpts, D as DraftPatchInput, a as DraftPatchOutput, R as ResolvedSurface, S as SurfaceImprovementEdit, b as SurfaceValidationIssue, c as createSurfaceImprovementAdapter, r as renderSurfaceIssues, d as resolveSubjectPath, v as validateSurfaces } from './improvement-adapter-CWegd3vw.js';
+import { K as KnowledgeAdapter, a as RunAnalystLoopResult } from './types-BtRLF2U3.js';
 import { AgentProfile, SandboxEvent } from '@tangle-network/sandbox';
 import { C as ComposeProductionAgentProfileOptions } from './delegation-profile-1GbW5yA3.js';
+import './runtime-hooks-C7JwKb9E.js';
 
 /**
  * The full agent manifest. Each agent ships ONE of these.

package/dist/agent.js

@@ -2,11 +2,11 @@ import {
   composeProductionAgentProfile
 } from "./chunk-7JITYN6T.js";
 import {
-  createSandboxForSpec,
+  createSandboxForSpec
+} from "./chunk-KEWO4KI6.js";
+import {
   mapSandboxEvent
-} from "./chunk-EKBSQYZE.js";
-import "./chunk-PY6NMZYX.js";
-import "./chunk-SQSCRJ7U.js";
+} from "./chunk-PRX45WE2.js";
 import {
   __require
 } from "./chunk-DGUM43GV.js";
@@ -193,9 +193,7 @@ function defineAgent(manifest) {
 // src/agent/improvement-adapter.ts
 import { spawnSync } from "child_process";
 import { readFileSync } from "fs";
-import {
-  parseFindingSubject
-} from "@tangle-network/agent-eval";
+import { parseFindingSubject } from "@tangle-network/agent-eval/analyst";
 var DEFAULT_CREATE_KINDS = [
   "knowledge.wiki",
   "knowledge.claim",