@tangle-network/agent-runtime 0.52.0 → 0.54.0

package/skills/agent-runtime-adoption/SKILL.md

@@ -35,58 +35,66 @@ A `Driver<Task, Output, Decision>` is just `plan(task, history) → Task[]`
 (`[task]`→refine, N copies→fanout, `[]`→stop) + `decide(history) → Decision`.
 Topology is data; the kernel is topology-agnostic.
 
-### Topology drivers — `@tangle-network/agent-runtime/loops`
-
-> **Stale-name correction (gen-6 consolidation, #165):** the standalone
-> `createRefineDriver` / `createFanoutVoteDriver` factories were **removed** —
-> refine/fanout collapsed into the one recursive agent tree. Canonical today:
-> the personify combinators `loopUntil`(depth/refine) / `fanout`(breadth/vote)
-> and the `Strategy` values `refine` / `sample`, plus `createDriver` for an
-> agent-authored topology. Verify names in `src/runtime/index.ts`; see
-> `build-with-agent-runtime` + `docs/canonical-api.md` §3.1/§3.3 for the live
-> signatures. Likewise `createSandboxPlanner` is gone — pass a `TopologyPlanner`
-> to `createDriver({ planner })` directly.
+### Topology — `@tangle-network/agent-runtime/loops`
+
+Topology is the **one recursive agent tree**: each round an agent decides to refine, fan out, spawn a sub-agent, or stop — and a spawned child can itself be a driver. The surfaces:
 
 - **`refine` / `loopUntil`** — one attempt/round, validator-gated; iterate over
   one evolving artifact until valid or budget-capped. Use for incremental
-  patches, document revision, anything monotonic. (Replaces `createRefineDriver`.)
+  patches, document revision, anything monotonic.
 - **`sample` / `fanout`** — N attempts at equal budget, score once, pick the
   winner via the single-sourced selector. Use for multi-harness coder fanout,
-  redundant research with disagreement detection. (Replaces `createFanoutVoteDriver`.)
-- **`createDriver({ planner, maxIterations?, maxFanout? })`** — **the
-  agent authors the topology.** `plan`/`decide` are backed by an injected
-  `TopologyPlanner` that emits one `TopologyMove` per round
-  (`{kind:'refine',task}` | `{kind:'fanout',tasks}` | `{kind:'stop'}`). The
-  planner is invoked once per round in `plan()`; `decide()` reads the cached move
-  so an LLM planner is never double-called. Use when the right shape is
-  task-dependent (scout-then-fanout, refine-then-branch, decompose).
-
-Topology is **orthogonal to harness**: a driver returns `Task[]`; the kernel
-round-robins `agentRuns[]` to decide which harness (claude-code / codex /
-opencode / pi) runs each branch. One driver spans all backends, including
-fanning a single round across several.
-
-### Wiring an LLM planner — inject a `TopologyPlanner`
-
-`createDriver({ planner })` takes an injected `TopologyPlanner` (the standalone
-`createSandboxPlanner` factory was removed in the gen-6 consolidation — verify
-the live shape in `src/runtime/driver.ts` / `src/runtime/index.ts`). The planner
-is the brain (it may call any harness/LLM to author the move); the driver maps
-each `TopologyMove` onto kernel structure.
+  redundant research with disagreement detection.
+- **`runAgentic({ surface, task, mode|strategy, budget })`** /
+  **`defineStrategy(name, body)`** — author the topology as a `Strategy` on the
+  keystone `Supervisor`. `runAgentic` runs a built-in `mode` (`'depth'`→refine,
+  `'breadth'`→sample) or a custom `strategy`; `defineStrategy` composes
+  `ctx.shot()` (one harness-scored attempt) + `ctx.critique()` (the firewalled
+  analyst — trajectory in, never scores) in ~15 lines. Equal-k holds by
+  construction; the body is harness-re-verified, so an authored strategy can't
+  fabricate a win. Use when the right shape is task-dependent (scout-then-fanout,
+  refine-then-branch, decompose).
+- **`createCoordinationTools`** — the agent-driving-agent loop: a driver agent
+  spawns / steers / awaits child agents (and sub-drivers) through MCP verbs over a
+  live `Scope`, recursively. Use when a driver should reason about and orchestrate
+  its workers in natural language.
+
+Topology is **orthogonal to harness** — a strategy decides the shape; the executor
+decides which harness (claude-code / codex / opencode / pi / router) runs each
+node. One driver spans all backends.
+
+### Authoring an agent-chosen topology — `runAgentic` / `defineStrategy`
+
+The agent authors its own topology by composing two firewalled steps inside a
+`Strategy` on the keystone `Supervisor` — `ctx.shot()` (one harness-scored worker
+attempt over an artifact) and `ctx.critique()` (the analyst — trajectory in,
+never scores). `runAgentic` runs it over one `AgenticSurface` on a conserved
+budget pool, so equal-k holds by construction.
 
 ```ts
-import { createDriver, runLoop, type TopologyPlanner } from '@tangle-network/agent-runtime/loops'
-
-const planner: TopologyPlanner<Task, Out> = {/* plan() → one {kind:'refine'|'fanout'|'stop',…} per round */}
-const result = await runLoop({
-  driver: createDriver({ planner, maxIterations: 8 }),
-  agentRuns: workerSpecs, output, validator, task, ctx: { sandboxClient: client },
+import { runAgentic, defineStrategy } from '@tangle-network/agent-runtime/loops'
+
+const sampleThenRefine = defineStrategy('sampleThenRefine', async (ctx) => {
+  const h = await ctx.surface.open(ctx.task)
+  let best = await ctx.shot({ handle: h })                 // one breadth attempt
+  for (let i = 1; i < ctx.budget && best && best.score < 1; i++) {
+    const steer = await ctx.critique(best.messages)        // analyst — trajectory only
+    if (!steer) break
+    best = await ctx.shot({ handle: h, messages: best.messages, steer })
+  }
+  await ctx.surface.close(h)
+  return { score: best?.score ?? 0, resolved: (best?.score ?? 0) >= 1, completions: 0, progression: [], shots: 0 }
 })
+
+const result = await runAgentic({ surface, task, strategy: sampleThenRefine, budget: 4 })
 ```
 
-The planner emits a JSON envelope (`{ kind, tasks?, n?, rationale }`); a missing,
-unparseable, or unknown-kind envelope throws `PlannerError` — the loop never runs
-a topology nobody chose.
+The deliverable score is **harness-verified** — computed from the shots the
+harness actually brokered and scored via `surface.score()`, never the value the
+(possibly authored) body returns; an authored strategy can only report what its
+real shots achieved. For an LLM driving *another* agent through MCP verbs (the
+agent-driving-agent loop), expose `createCoordinationTools` over a live `Scope`
+(see the recursive-driver section below) instead of authoring a fixed strategy.
 
 ### Driver gotchas
 
@@ -173,10 +181,10 @@ Mount it on a production `AgentProfile.mcp`; do not re-implement delegation.
 
 ## Acceptance checklist
 
-- [ ] Topology is a `Driver`/combinator, not hard-coded control flow. Reuse
-      `refine`/`loopUntil`, `sample`/`fanout`, or the agent-authored `createDriver`;
-      build a custom `Driver` against `loops/types.ts:Driver` only when none fit —
-      never fork the kernel.
+- [ ] Topology is a combinator/`Strategy`, not hard-coded control flow. Reuse
+      `refine`/`loopUntil`, `sample`/`fanout`, or author one with
+      `runAgentic`/`defineStrategy` (or `createCoordinationTools` for an
+      agent-driving-agent loop) — never fork the kernel.
 - [ ] `runLoop` is bridged to campaigns via `loopDispatch` (usage + trace
       auto-forwarded), not a hand-rolled ExecCtx.
 - [ ] Every optimizable prompt is registered through `selfImprove` (or the

package/skills/build-with-agent-runtime/SKILL.md

@@ -60,7 +60,7 @@ signature + the exact "do NOT build".
 | **Author a new topology/strategy compactly** | `defineStrategy(name, body)` w/ `ctx.shot()`+`ctx.critique()` — `/loops` | canonical-api §3.3 |
 | **Add a stateful tool-using domain** | implement `AgenticSurface` (5 hooks) — `/loops` | canonical-api §3.3 |
 | **Benchmark: compare strategies + significance + Pareto on a domain** | `runBenchmark({ environment, tasks, worker, strategies })` — `/loops` | canonical-api §3.3 |
-| **Benchmark: add/run an external benchmark from the harness** | `ADAPTERS`/`resolveAdapter(key)` + `runExperiment` — `bench` | canonical-api §3.3 |
+| **Benchmark: add/run an external benchmark from the harness** | `ADAPTERS`/`resolveAdapter(key)` + a bench gate (`*-gate.mts`) over `openSandboxRun` + `sandboxAgentRun` (`bench/src/sandbox-run.ts`) | canonical-api §3.3 |
 | **Sandbox coding rollout** (fresh box/round, or persistent+resume) | `runLoop(options)` / `openSandboxRun(client, opts, deliverable)` — `/runtime` | canonical-api §3.1 |
 | **Optimize a CODE surface** in a gated loop | `improvementDriver({ worktree, generator })` — `/improvement` | canonical-api §3.4 |
 | **Optimize a PROMPT/config surface** (one call) | `selfImprove({ agent, scenarios, judge, baselineSurface })` — `agent-eval/contract` | canonical-api §3.4 |
@@ -68,7 +68,7 @@ signature + the exact "do NOT build".
 | **Gate: ship/hold from a `BenchmarkReport`** (per-task cells) | `promotionGate({ report, incumbent, candidate })` — `/runtime` | canonical-api §3.4 |
 | **Run the full multi-generation flywheel + certify** | `runStrategyEvolution(config)` — `/runtime` | canonical-api §3.4 |
 | **Compose the prod sandbox profile** (eval/prod parity) | `composeProductionAgentProfile(base, opts)` — `/mcp` | canonical-api §3.2 |
-| **Observe a run** (cost/time waterfall, live tree, OTLP) | `createWaterfallCollector` / `createTopologyView` / `createOtelExporter` via `composeRuntimeHooks(...)` — root | canonical-api §3.5 |
+| **Observe a run** (cost/time waterfall, live tree, OTLP) | `createWaterfallCollector` / `createOtelExporter` via `composeRuntimeHooks(...)` — root; `createTopologyView` / `renderTopologyTree` — `/topology` | canonical-api §3.5 |
 | **State any A/B claim** | `pairedLift` (bench) over `pairedBootstrap`/`heldoutSignificance` (substrate) | canonical-api §3.5 |
 | **Observe/ship with billing-boundary** | `withTangleIntelligence(agent, { project, effort })` — `/intelligence` | canonical-api §7 (now live on main — verify) |
 
@@ -105,18 +105,22 @@ surface with `selfImprove` → certify on a frozen holdout with the gate.** For
 multi-generation flywheel, replace the measure/certify steps with one
 `runStrategyEvolution(...)` and read `report.verdict` (NOT `report.trajectory`)
 as the evidence. For a sandbox coding rollout judged by an external deterministic
-checker, use the bench path: `runExperiment({ adapter: resolveAdapter(...),
-sandboxClient, agentRun: sandboxAgentRun({ profile }), arms: [randomArm(...),
-analystArm(...)] })` — `arms[0]` is the mandatory equal-compute control.
+checker, use the bench-gate path: `resolveAdapter(...)` to pick the benchmark,
+then `openSandboxRun(client, { agentRun: sandboxAgentRun({ profile }), ... },
+deliverable)` per task, A/B-ing a blind arm against an `llmAnalyst`-steered arm
+at equal compute (both helpers live in `bench/src/sandbox-run.ts`; the blind arm
+is the mandatory equal-compute control). See `bench/src/commit0-gate.mts` /
+`gate.ts` for the live shape.
 
 ## Two substrates — pick one, don't invent a third
 
 Both implement the same recursive-decision atom over the one `Executor` port and
 share `defaultSelectWinner`. **Reactive** (`Supervisor`/`Scope` + personify
 combinators: `runPersonified`/`runAgentic`/`runBenchmark`) — prefer for NEW
-recursive work; equal-k by construction. **Round-synchronous** (`runLoop` +
-`createDriver`, `runExperiment`) — sandbox coding rollouts against external
-benchmarks. The full when-which map is `docs/canonical-api.md` §6.
+recursive work; equal-k by construction. **Round-synchronous** (`runLoop` driven
+by a caller-supplied `Driver`, plus the bench gates over `openSandboxRun`) —
+sandbox coding rollouts against external benchmarks. The full when-which map is
+`docs/canonical-api.md` §6.
 
 ## Observe / ship with the Intelligence SDK
 

package/skills/loop-writer/SKILL.md

@@ -37,9 +37,17 @@ If a fixed combinator solves it, do not use a dynamic driver.
 ## Minimal Sandbox Loop
 
 ```ts
+// runLoop takes a caller-supplied Driver directly (plan() → Task[]; decide() → terminal).
+// `[task]` → refine, N copies → fanout, `[]` → stop. Keep it this small or use a Strategy.
+const refineDriver: Driver<Task, Out, 'done' | 'fail'> = {
+  name: 'refine',
+  plan: async (task, history) => (history.at(-1)?.verdict?.valid ? [] : [task]),
+  decide: (history) => (history.at(-1)?.verdict?.valid ? 'done' : 'fail'),
+}
+
 const trace: unknown[] = []
 const result = await runLoop({
-  driver: createDriver({ planner, maxIterations: 4 }),
+  driver: refineDriver,
   agentRun: agentRunSpec,
   output,
   validator: executableGate,

package/skills/supervise/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: supervise
+description: Decompose a task into sub-tasks, author a worker AgentProfile for each, drive and verify the workers, and settle only when a deployable check passes. Carrying this skill is what makes an agent a supervisor.
+---
+
+# Supervise
+
+You are a supervisor. You do NOT do the work yourself — you design and drive specialist worker agents.
+
+## Loop
+
+1. **Decompose** the task into the smallest set of sub-tasks a single focused worker can each deliver.
+2. **Author** a worker per sub-task by calling `spawn_worker` with a complete `profile`:
+   - `name` — a short id.
+   - `skills` — the skill files the worker should carry (by name), OR `systemPrompt` — rich, specific instructions for this sub-task.
+   - `model` — the model best suited to this sub-task (optional).
+   Write the instructions a power user would write — never a one-liner. **Never spawn a worker with an empty profile.** The quality of the worker is the quality of the profile you author.
+3. **Await** each worker with `await_next`. Its result reports `valid: true` only if the worker's deployable check passed.
+4. **On failure**, author a *new* worker whose profile names the specific failure and how to fix it — never blindly retry the same profile.
+5. **Stop** (reply with no tool call) once the work is delivered. Only a delivered (`valid: true`) worker counts; you cannot declare done yourself.
+
+## Authoring sub-supervisors
+
+If a sub-task is itself too large for one worker, author it as a **sub-supervisor**: give its profile a `skills` list that includes `supervise`. It will decompose and drive its own workers one level deeper. This is not a special call — it is the same `spawn_worker`, just a profile that carries this skill.