@tangle-network/agent-runtime 0.50.0 → 0.52.0

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

@@ -35,14 +35,24 @@ 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.
 
-### Three shipped drivers — `@tangle-network/agent-runtime/loops`
-
-- **`createRefineDriver({ maxIterations?, refineTask? })`** — one task/iteration,
-  validator-gated; replay or rewrite the task until valid or capped. Use for
-  incremental patches, document revision, anything monotonic.
-- **`createFanoutVoteDriver({ n, selector? })`** — N parallel attempts in
-  iteration 0, score once, pick the winner (default: highest valid score). Use
-  for multi-harness coder fanout, redundant research with disagreement detection.
+### 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.
+
+- **`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`.)
+- **`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
@@ -56,16 +66,18 @@ 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 — `createSandboxPlanner`
+### 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.
 
 ```ts
-import { createDriver, createSandboxPlanner, runLoop } from '@tangle-network/agent-runtime/loops'
+import { createDriver, runLoop, type TopologyPlanner } from '@tangle-network/agent-runtime/loops'
 
-const planner = createSandboxPlanner<Task, Out>({
-  client, profile: plannerProfile,          // any harness; cheap model is fine
-  decodeTask: (raw) => raw as Task,          // envelope task → domain Task
-  // buildPrompt?  — defaults to a history-summary prompt; override to customize
-})
+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 },
@@ -88,23 +100,25 @@ a topology nobody chose.
 - Dynamic driver: set the kernel's `runLoop` `maxIterations >=` the driver's so
   the driver's cap governs and the loop closes on a clean `'done'`.
 
-## Campaign bridge — `loopDispatch` / `loopCampaignDispatch`
+## Campaign bridge — `loopDispatch`
 
 To run `runLoop` as an agent-eval campaign cell, do NOT hand-build the ExecCtx +
 forward trace + report usage every time (the third is silent — forgetting it
-yields a `{0,0}` cell `assertRealBackend` reads as a stub). Use the adapter:
+yields a `{0,0}` cell `assertRealBackend` reads as a stub). Use the one bridge,
+`loopDispatch` (the old `loopCampaignDispatch` name was consolidated away; verify
+in `src/runtime/index.ts`):
 
 ```ts
-import { loopCampaignDispatch } from '@tangle-network/agent-runtime/loops'
-const dispatch = loopCampaignDispatch({
+import { loopDispatch } from '@tangle-network/agent-runtime/loops'
+const dispatch = loopDispatch({
   sandboxClient,
-  toLoopOptions: (scenario) => ({ driver, agentRun, output, validator, task: toTask(scenario) }),
+  toLoopOptions: (scenario, profile) => ({ driver, agentRun, output, validator, task: toTask(scenario) }),
   // toArtifact? — defaults to result.winner?.output
 })
 // pass `dispatch` to runCampaign / runEvalCampaign; usage + trace are auto-forwarded
 ```
 
-`loopDispatch` is the `runProfileMatrix` variant (profile is an axis).
+`loopDispatch` doubles as the `runProfileMatrix` variant (the `profile` arg is an axis).
 
 ## Identity-gated optimization — agent-eval's `selfImprove`
 
@@ -159,11 +173,12 @@ Mount it on a production `AgentProfile.mcp`; do not re-implement delegation.
 
 ## Acceptance checklist
 
-- [ ] Topology is a `Driver`, not hard-coded control flow. Reuse refine /
-      fanout-vote / dynamic; build a custom `Driver` against
-      `loops/types.ts:Driver` only when none fit — never fork the kernel.
-- [ ] `runLoop` is bridged to campaigns via `loopDispatch` / `loopCampaignDispatch`
-      (usage + trace auto-forwarded), not a hand-rolled ExecCtx.
+- [ ] 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.
+- [ ] `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
       product's existing `runImprovementLoop`), identity-gated on a held-out set.
 - [ ] Boundaries fail loud: no `null` sandbox client, no silent adapter return,

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

@@ -0,0 +1,143 @@
+---
+name: build-with-agent-runtime
+description: Use before hand-rolling a tool loop, driver, corpus, or optimizer wrapper. Create an agent genome, run it on a benchmark, optimize+gate it, observe/ship it with @tangle-network/agent-runtime. The genome→run→optimize→observe spine.
+---
+
+# build-with-agent-runtime
+
+The one create→run→optimize→observe seam for `@tangle-network/agent-runtime`. A
+**genome** (an `AgentProfile`/`AgentSurfaces` — systemPrompt + skills + tools +
+mcp + knowledge + memory + rag as ONE combined surface) runs as a
+**driver⟷worker** shape over a **benchmark**, gets **optimized by a gated loop**
+that evolves the genome and certifies wins on a **frozen holdout**, and is
+**observed** through the one lifecycle stream. The selector is never the judge;
+observation attaches to the loop, never to the portable genome.
+
+If you are about to write a `runConversation`, a "skill optimizer", a
+"profile-seam", a depth-vs-breadth A/B harness, a bootstrap loop, or a
+`new Sandbox(...)` + stream + read dance — **stop.** It exists, and a parallel
+silently breaks a load-bearing invariant (equal-k, selector≠judge,
+capture-integrity, or eval/prod parity).
+
+## Load order — point at source, never freeze snippets
+
+This skill carries **no API snippets**. The barrel MOVES (`./loops` is a
+back-compat alias of `./runtime`), the agent-eval pin drifts, and signatures get
+corrected in place. Freezing a snippet here guarantees rot. Instead, read, in
+order, and re-verify against source:
+
+1. **`docs/canonical-api.md`** — the source of truth: the §2 decision table
+   ("I want to X → use Y → NOT Z"), §3 per-subsystem signatures (each cited
+   `file:line`), §4 the end-to-end recipe, §5 the recursive atom, §6 the
+   two-substrate map. Every signature there was read from source.
+2. **`grep` the export barrel** — `grep -nE 'export (function|const|type)' src/runtime/index.ts`
+   (and `src/agent/index.ts`, `src/improvement/index.ts`, `src/mcp/index.ts`,
+   `src/intelligence/index.ts`) for the live names + subpaths. `./loops` and
+   `./runtime` resolve to the SAME barrel (`package.json` maps both to
+   `src/runtime/index.ts`).
+3. **`bench/HARNESS.md`** — the experiment-harness map: commands, the
+   `rollout → corpus → selector → CI → gate` flow, and the `ADAPTERS` registry
+   (a harness-local export, `bench/src/adapters.ts`, not a package export).
+
+**Code wins.** If a name, subpath, or signature here or in `docs/canonical-api.md`
+disagrees with source, the **source is right** — fix the map in the *same turn*
+(the anti-rediscovery law). Verify with Read/Edit, don't re-read to confirm.
+
+## Decision table — by altitude (each row → ONE source, not a snippet)
+
+Read the cited `docs/canonical-api.md` row before writing; it carries the live
+signature + the exact "do NOT build".
+
+| Altitude — I want to… | Use | Source |
+|---|---|---|
+| **Define a genome** (who the agent is + what it can do, ONE surface) | `AgentProfile` (runnable) / `AgentSurfaces` (the editable-coordinate map) — `/runtime`, `/agent` | canonical-api §3.2 |
+| **Define the personified-run record** (model+prompt+tools+role+seams) | `definePersona(input)` — `/runtime` | canonical-api §3.1 |
+| **Run a genome driver⟷worker, end-to-end** | `runPersonified({ persona, shape, task, budget })` — `/runtime` | canonical-api §3.1 |
+| **Loop a worker over one evolving artifact, K rounds, stop-when-good** | `loopUntil(seed, spec)` as the `shape` — `/runtime` | canonical-api §3.1 |
+| **Best-of-N / parallel-research at equal compute** | `fanout(items, opts)` — `/runtime` | canonical-api §3.1 |
+| **Produce-then-gate / multi-judge quorum / fixed chain** | `verify` / `panel` / `pipeline` — `/runtime` | canonical-api §3.1 |
+| **Run depth-vs-breadth (or a custom strategy) over a stateful tool domain** | `runAgentic({ surface, task, mode\|strategy, budget })` — `/loops` | canonical-api §3.3 |
+| **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 |
+| **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 |
+| **Gate: ship/hold a candidate** (campaign ctx) | `defaultProductionGate` / `heldOutGate` / `composeGate` — `agent-eval/contract` | canonical-api §3.4 |
+| **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 |
+| **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) |
+
+## Do-NOT-reinvent — the traps this skill exists to stop
+
+Each of these gets hand-rolled every session; the canonical primitive already
+holds the load-bearing invariant the parallel breaks:
+
+- `runConversation` / persona-runner / `while(!done)` steering loop **≈**
+  `loopUntil` + `runPersonified` (threads executor seams; equal-k; selector≠judge
+  firewall; journal/replay — a parallel runner silently fails to wire the seams).
+- "skill optimizer" / "topology mutator" that opens branches + applies patches
+  **≈** `improvementDriver` (code surface) or `selfImprove`/`gepaDriver` (prompt
+  surface) — both gated on a frozen holdout.
+- "profile-seam" / agent-config wrapper carrying model+prompt+tools+role **≈**
+  `AgentProfile` (it IS that bundle) + `definePersona` (the run record);
+  `sandboxAgentRun({ profile })` is the box seam — never pass a router key into
+  the box.
+- `new Sandbox()` + acquire + stream + `box.fs.read` + delete **≈**
+  `openSandboxRun` (persistent + resume) or `runLoop` (fresh box/round).
+- `Promise.all` over N calls + manual argmax/merge **≈** `fanout` (bypassing the
+  budget pool breaks equal-compute claims).
+- a per-step cost/token tally over events **≈** `createWaterfallCollector` (the
+  sum of spans IS the billed run cost; a parallel tally drifts).
+- your own bootstrap loop / PRNG per gate **≈** `pairedLift` / `promotionGate`
+  (seeded, identical run-to-run; never report a point lift without `low/high/pairs`).
+
+## End-to-end recipe
+
+`docs/canonical-api.md` §4 is the real composition — copy it from there, don't
+re-derive: **define a genome → run driver⟷worker via the reactive substrate over
+a multi-turn `AgenticSurface` → measure with `runBenchmark` → optimize a prompt
+surface with `selfImprove` → certify on a frozen holdout with the gate.** For the
+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.
+
+## 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.
+
+## Observe / ship with the Intelligence SDK
+
+One line wraps any agent with trace + billing boundary:
+`withTangleIntelligence(agent, { project, effort })`, `effort ∈
+off|eco|standard|thorough|max` (`'off'` is the provable passthrough floor —
+intelligence spend clamped to 0). It builds on `createOtelExporter` +
+`loopEventToOtelSpan` — don't hand-roll a trace-wrapper or effort/tier config.
+Verify the live subpath against `src/intelligence/index.ts` (canonical-api §7's
+"branch-only" note is stale — it landed on main).
+
+## Final check
+
+- Picked a primitive from the decision table, not a hand-rolled parallel?
+- Genome is ONE `AgentProfile`/`AgentSurfaces` surface, not split skill/tool/prompt knobs?
+- Equal compute preserved (budget pool, or `arms[0]` control) — no `Promise.all` zoo?
+- Selector ≠ judge: no judge score feeding a driver/another judge; holdout score write-only?
+- Any win certified on a FROZEN holdout via a gate, never on the training composite?
+- Map fixed in the same turn if source disagreed with `docs/canonical-api.md`?
+
+See `_common.md` for shared conventions (frontmatter, fail-loud, no AI attribution).
+
+Next: build the genome/loop/optimizer against `docs/canonical-api.md` §3–§4; if a
+strategy beats incumbent on the holdout gate, `/ship` it.

package/skills/loop-writer/SKILL.md

@@ -24,7 +24,7 @@ The driver owns strategy.
 
 | Objective | Use |
 |---|---|
-| Try N attempts, pick best | `fanout` or `createFanoutVoteDriver` |
+| Try N attempts, pick best | `fanout` (or the `sample` strategy) |
 | Ordered stages | `pipeline` |
 | Improve until executable check passes | `loopUntil` + verifier |
 | Review from several lenses | `panel` |
@@ -138,16 +138,15 @@ Git is the durable workspace seam:
 - resume derives completion from git state, not only a side journal
 - conflicts become blockers/questions, not silent overwrite
 
-Proof command for the local substrate join:
+Proof command (real sandbox, real observe→steer join):
 
 ```bash
-pnpm exec tsx bench/src/observe-steer-workspace-loop.mts
+TANGLE_API_KEY=... pnpm exec tsx bench/src/cloud-loop.mts
 ```
 
-It proves `Scope.spawn -> coordination tools -> gitWorkspace -> observe ->
-Scope.send -> corrective worker -> integration pass`. Until the same proof runs
-with `openSandboxRun` and a remote branch, claim local substrate closure and
-serial git accumulation, not full cloud migration safety.
+It proves `openSandboxRun -> observe -> steer -> corrective worker` over a live
+sandbox. The old `observe-steer-workspace-loop.mts` used mock executors and is
+deleted — the live proof is the only valid one.
 
 ## Final Check