@tangle-network/agent-runtime 0.86.0 → 0.88.0

package/dist/mcp/index.js

@@ -6,7 +6,7 @@ import {
 import {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "../chunk-U4TS65XZ.js";
+} from "../chunk-JHULWWQD.js";
 import {
   createKbGate
 } from "../chunk-SGKPNBXE.js";
@@ -14,7 +14,7 @@ import {
   assertTraceDerivedFindings,
   runCoderChecks,
   selectValidWinner
-} from "../chunk-3TZOXS7B.js";
+} from "../chunk-22HPUH77.js";
 import {
   DELEGATE_DESCRIPTION,
   DELEGATE_FEEDBACK_DESCRIPTION,
@@ -64,7 +64,7 @@ import {
   validateDelegateUiAuditArgs,
   validateDelegationHistoryArgs,
   validateDelegationStatusArgs
-} from "../chunk-F7OO2SKB.js";
+} from "../chunk-LRNRPJAV.js";
 import "../chunk-UD4BHQMI.js";
 import {
   deleteBoxSafe,
@@ -72,7 +72,7 @@ import {
   throwAbort,
   throwIfAborted
 } from "../chunk-BZF3KQ6G.js";
-import "../chunk-4J6RBI3K.js";
+import "../chunk-FVJ7M3DA.js";
 import {
   runLocalHarness
 } from "../chunk-7LO5GMAO.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -94,7 +94,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@tangle-network/agent-eval": "^0.103.1",
+    "@tangle-network/agent-eval": "^0.103.2",
     "@tangle-network/agent-interface": ">=0.14.0 <1.0.0",
     "@tangle-network/sandbox": ">=0.8.0 <1.0.0",
     "@types/node": "^25.9.3",

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

@@ -64,8 +64,9 @@ agent-runtime's `AgentSpec { profile, harness }`. To sweep it as an eval axis,
 don't hand-declare a harness list — expand one base profile across
 `CODING_HARNESSES` with `expandProfileAxes` (agent-eval), run with
 `runProfileMatrix`, and pivot results by the stamped `AgentProfileCell`
-(`groupRunsByAgentProfileCell`); incompatible `(harness, model)` pairs drop via
-`harnessSupportsModel`.
+(`groupRunsByAgentProfileCell`); `harnessSupportsModel` filters per harness,
+and a vendor-locked harness that supports none of the requested models SNAPS
+to its native default (`HARNESS_NATIVE_MODEL`) — never silently dropped.
 
 | Altitude — I want to… | Use | Source |
 |---|---|---|
@@ -77,9 +78,15 @@ don't hand-declare a harness list — expand one base profile across
 | **Produce-then-gate / multi-judge quorum / fixed chain** | `verify` / `panel` / `pipeline` — `/loops` | 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 |
+| **Spawn a coded loop as a first-class atom** (bounded/gated/steerable, spawned + steered like a worker — the 3rd shape beside leaf worker + driver child) | `defineLoop(name, { maxRounds, round | agents, check })` + `loopChild`, wired via `createInMemoryRunContext({ withLoop: true })` — `/loops` — multi-agent = `agents: [proposer, verifier]` (declarative chain, not a bespoke `runTwoAgent…` fn); NOT a hand-driver looping in the model's head; the loop-executor owns maxRounds + conserved budget + gate + steer-between-rounds | canonical-api decision table |
+| **Have an LLM AUTHOR a loop at runtime** (codemode: the supervisor writes a `defineLoop` module for a novel goal) | `authorLoop({ chat, goal, maxRounds, outDir })` → a `LoopDef` for `loopChild` — `/loops` — NOT a per-product loop-code generator or a VM around authored code; the sibling of `authorStrategy`, safety is the conserved pool + gate + `assertStrategyContract` lint | `src/runtime/loop-author.ts` |
 | **Add a stateful tool-using domain** | implement `AgenticSurface` (5 hooks) — `/loops` | canonical-api §3.3 |
 | **Drive a team of agents over a graded `AgenticSurface` task** (workers settle on its check, driver self-improves from the failing tests) | `superviseSurface(profile, task, { surface, worker })` — `/loops` | canonical-api §2 |
 | **Benchmark: compare strategies + significance + Pareto on a domain** | `runBenchmark({ environment, tasks, worker, strategies })` — `/loops` | canonical-api §3.3 |
+| **Author a PRODUCT eval leaderboard** (cases + prompt + grader → ranked board, standard flags, fresh run-dir, export, `toBenchmarkAdapter()`) | `defineLeaderboard({ name, cases, prompt, score, axis?, backends?, flags?, setup?/teardown?, onCellEvents?, resolveModel?, export?, dispatch?, judges?, matrix? })` — `/loops` — NOT a hand-assembled flag-parsing + `runProfileMatrix` frame; `runProfileMatrix` is the escape floor, the level-2 `dispatch` override is how in-process products plug in | `src/runtime/define-leaderboard.ts` (verify vs source) |
+| **Resolve a harness-in-box backend** (box / local cli-bridge / router leaf, one `SandboxClient` shape) | `resolveSandboxClient({ backend: 'sandbox' \| 'bridge' \| 'router' })` — `/loops` — NOT a per-product backend factory or a hand-faked box (`inlineSandboxClient` / the bridge executor already exist) | `src/runtime/resolve-sandbox-client.ts` |
+| **Resolve an in-process chat backend** (the one `--backend` branch for `runChatThroughRuntime` / `runAgentTaskStream`) | `resolveAgentBackend({ kind: 'router' \| 'tcloud' \| 'cli-bridge' \| 'sandbox' })` — root `.` | `src/resolve-agent-backend.ts` |
+| **Run ONE agent turn as one normalized event stream** (box, executor, or chat backend; guaranteed terminal result+usage) | `streamAgentTurn(backend, prompt, { signal, timeoutMs })` + `collectAgentTurn(stream)` — `/loops` | canonical-api §2 |
 | **Benchmark report: multi-profile × multi-axis leaderboard** (ranked board + score matrix + SVG/HTML charts, any `RunRecord[]`) | `leaderboard(records)` + `renderLeaderboardMarkdown` / `renderLeaderboardSvg` / `renderLeaderboardHtml` — `/loops` | canonical-api §2 |
 | **Meter one `openSandboxRun` cell's token/cost usage** | `sumSandboxUsage(events)` — `/loops` | canonical-api §2 |
 | **Sweep harness × model as an eval axis** (turn one base profile into the full harness × model set) | `expandProfileAxes({ base, harnesses, models })` over `CODING_HARNESSES` → `runProfileMatrix(...)`, pivot with `groupRunsByAgentProfileCell` — `agent-eval` root — NOT a hand-declared `HARNESSES` list | agent-eval root (verify vs source) |
@@ -125,10 +132,28 @@ holds the load-bearing invariant the parallel breaks:
   (seeded, identical run-to-run; never report a point lift without `low/high/pairs`).
 - a per-product `HARNESSES` / `HarnessBackend` list + a metadata-harness reader
   **≈** `CODING_HARNESSES` + `expandProfileAxes` (the one canonical harness list;
-  incompatible `(harness, model)` pairs drop via `harnessSupportsModel`) and the
+  vendor-locked harnesses SNAP to their native model via `HARNESS_NATIVE_MODEL`,
+  never dropped) and the
   `AgentProfileCell` stamped by `runProfileMatrix`, pivoted via
   `groupRunsByAgentProfileCell` — never bake the harness into the model id so the
   same model can run under multiple harnesses.
+- a per-product leaderboard CLI (flag parsing + run-dir management + axis
+  expansion + a `runProfileMatrix` call + export/markdown) **≈**
+  `defineLeaderboard` (0.84+; it owns that whole frame — FRESH default run-dir,
+  standard `--backend`/`--harnesses`/`--models`/`--cases`/`--shots`/`--reps`
+  flags, `toBenchmarkAdapter()`; the product writes ~150-250 domain lines).
+- a backend factory / `if (backend === 'router') ... else ...` branch or a
+  hand-faked box around a non-box executor **≈** `resolveSandboxClient`
+  (harness-in-box: `'sandbox' | 'bridge' | 'router'`) or `resolveAgentBackend`
+  (in-process: `'router' | 'tcloud' | 'cli-bridge' | 'sandbox'`) — grep the
+  substrate first; `inlineSandboxClient` and the bridge executor exist.
+- a per-provider stream→event mapper for a single agent turn **≈**
+  `streamAgentTurn` + `collectAgentTurn` (0.85+; one `RuntimeStreamEvent`
+  contract over box / executor / chat, guaranteed terminal result+usage).
+- a supervisor `act` with a `for (round…)` loop that spawns + checks + continues
+  in the model's reasoning **≈** `defineLoop` + `loopChild` (the loop-executor
+  enforces the round ceiling, the conserved pool, the completion gate, and
+  steer-between-rounds; a hand-driver loop enforces none of them).
 
 ## End-to-end recipe
 

package/skills/loop-writer/SKILL.md

@@ -30,6 +30,7 @@ The driver owns strategy.
 | Review from several lenses | `panel` |
 | Simulated user/product eval | `defineConversation` + `runConversation` |
 | Dynamic topology / drivers of drivers | `Scope` or sandbox driver + `createCoordinationTools` |
+| **A coded multi-round loop spawned + steered like a worker** | `defineLoop` + `loopChild` (the loop atom) |
 | Mutate a shared repo | git branch/clone loop with typed merge outcomes |
 
 If a fixed combinator solves it, do not use a dynamic driver.
@@ -114,6 +115,78 @@ When the driver lives in a sandbox, expose the same verbs through
 `steer_worker`, `list_questions`, `answer_question`, `ask_parent`, `stop`, and
 optional analyst tools.
 
+## The Loop Atom — a coded loop spawned like a worker
+
+When the loop itself is the reusable unit (a research loop, a verify loop, an
+evolve loop), make it a spawnable atom instead of a hand-driver. `defineLoop`
+authors the body; the runtime owns the round ceiling, the conserved budget, the
+gate, and steer-between-rounds. A supervisor spawns / observes / steers it with
+the SAME coordination verbs as a worker.
+
+Two ways to author the round. **`agents`** — a MULTI-AGENT loop as a declarative
+CHAIN (the common case): an ordered list of named agents piped each round,
+`task -> agents[0] -> agents[1] -> ... -> out`, each agent's return feeding the next
+as `prior`. "Two agents" is self-evident from the list — no bespoke `runTwoAgent...`
+function. **`round`** — freeform code for any other topology (fan-out, dynamic
+routing). Provide exactly one.
+
+```ts
+// A two-agent research loop as a CHAIN: proposer drafts, verifier checks the draft.
+const research = defineLoop('research', {
+  maxRounds: 3,
+  agents: [
+    { name: 'proposer', run: async ({ scope, steer }, _prior) => {
+        const w = scope.spawn(researcher, { steer }, { budget: perRound, label: 'propose' })
+        if (!w.ok) throw new Error(w.reason)
+        return await scope.next()                    // the draft
+    } },
+    { name: 'verifier', run: async ({ scope }, draft) => {
+        const w = scope.spawn(verifier, { draft }, { budget: perRound, label: 'verify' })
+        if (!w.ok) throw new Error(w.reason)
+        return await scope.next()                    // the verified result -> round out
+    } },
+  ],
+  check: (out) => readinessPasses(out),              // the deployable completion oracle
+})
+
+// Spawn it exactly like a worker (role:'loop' resolves to the loop-executor).
+const r = scope.spawn(loopChild(research, journal), task, { budget, label: 'research-loop' })
+// Wire once at the top: createInMemoryRunContext({ withDriver: true, withLoop: true }).
+```
+
+TOPOLOGY: `agents` is a sequential CHAIN only. It is NOT parallel and NOT a graph —
+the loop's nested `scope.next()` is one shared queue, so parallel agents would steal
+each other's settlements. For fan-out (a panel of critics, best-of-N), dynamic
+routing, or any non-linear shape, use the freeform `round`: spawn every handle first,
+then drain N times, or branch on the data yourself. `fanout`/`panel`/`pipeline` cover
+the reactive-layer parallel case.
+
+Rules: the loop is code, not the model's judgment — that is what makes maxRounds,
+the budget, and the gate ENFORCED rather than hoped-for. Give the loop a real
+`check` (an executable oracle, never a self-judged score). Budget nests: the pool
+reserves each spawn's full ceiling until it settles, so pool > loop > per-round.
+
+### Codemode — an LLM authors the loop at runtime
+
+When the supervisor should WRITE the loop for a novel goal (not pick a hand-built
+one), use `authorLoop` — the codemode seam over the atom, the sibling of
+`authorStrategy`. It shows the model `loopAuthorContract` (the exact `defineLoop`
+module shape, exported so a skill/GEPA pass can evolve it), extracts the fenced
+module, lints it with `assertStrategyContract` (only the loops import; no
+require/eval/fetch/process/node builtins), writes it, dynamic-imports it, and
+validates the default export is a `LoopDef` — ready for `loopChild`.
+
+```ts
+const { loop } = await authorLoop({ chat, goal, maxRounds, outDir, fallbackModel })
+const spawned = scope.spawn(loopChild(loop, journal), task, { budget, label: 'authored-loop' })
+```
+
+Safety is structural, same as `authorStrategy`: the authored body can be WRONG
+but cannot overspend (conserved pool), cannot skip the check (the runtime gates
+it), and cannot reach outside the loops surface (the lint). Do not build a
+per-product loop-code generator or a VM sandbox around authored loops — `authorLoop`
+is that seam.
+
 ## Role Boundaries
 
 - **Verifier**: executable shippability gate; controls accept/reject.