@tangle-network/agent-runtime 0.123.1 → 0.128.0

package/dist/testing.js

@@ -4,7 +4,7 @@ import { SANDBOX_SIZE_PRESET_NAMES } from "@tangle-network/agent-interface";
 //#region src/testing/fixtures/agent-improvement-proposal.json
 var agent_improvement_proposal_default = {
 	changedSurfaces: ["prompt"],
-	digest: "sha256:fb18b750e1c943753d05266412a3240b548e47b3a7b049c6b49baf4387d14578",
+	digest: "sha256:5feb51aa14c16c29e4b06a4f344dec42ecc7c13f0a876c17ed743014580dc93a",
 	evaluation: {
 		"decision": {
 			"contributingChecks": [
@@ -4515,7 +4515,7 @@ var agent_improvement_proposal_default = {
 		],
 		"metadata": {
 			"fixture": "agent-improvement-proposal",
-			"runtimeVersion": "0.123.1"
+			"runtimeVersion": "0.128.0"
 		},
 		"objectives": [
 			{
@@ -4626,8 +4626,8 @@ var agent_improvement_proposal_default = {
 			"baselineContentHash": "sha256:5c21ee53e513fc604cb09754e21c392b24a424da0ef37dbf8f1ee4a8a0b08f09",
 			"candidateContentHash": "sha256:60fcbb1c728194bd51d7d19cb732d1c3f1881dce7e0a6266b41c8b98cfd65693",
 			"kind": "agent-eval-loop",
-			"recordDigest": "sha256:9ff787d43525daee437bd6dd1518ef0d119ff0e3d91c5907068b29bac1a31d0a",
-			"runId": "agent-runtime-0.123.1-proposal-fixture",
+			"recordDigest": "sha256:21aec498ac5cf1fec87690d5216cf4edb811e0db19b841f8be84c1bea8a9365e",
+			"runId": "agent-runtime-0.128.0-proposal-fixture",
 			"schema": "agent-candidate-experiment"
 		}
 	},
@@ -4650,13 +4650,13 @@ var agent_improvement_proposal_default = {
 	}],
 	kind: "agent-improvement-proposal",
 	proposedAt: "2026-07-10T01:00:00.000Z",
-	runId: "agent-runtime-0.123.1-proposal-fixture"
+	runId: "agent-runtime-0.128.0-proposal-fixture"
 };
 //#endregion
 //#region src/testing/fixtures/agent-profile-improvement-proposal.json
 var agent_profile_improvement_proposal_default = {
 	changedSurfaces: ["prompt", "skills"],
-	digest: "sha256:af06351a86081b1db9bdd82aa7c01aade535163410bb5d769e0ce5fcf67fabd1",
+	digest: "sha256:481b9db8d4e8e1834114e3b922876eaa0d68ac007c094ce9b2bd9aa7a14d812e",
 	evaluation: {
 		"decision": {
 			"contributingChecks": [
@@ -6290,7 +6290,7 @@ var agent_profile_improvement_proposal_default = {
 		],
 		"metadata": {
 			"fixture": "agent-profile-improvement-proposal",
-			"runtimeVersion": "0.123.1"
+			"runtimeVersion": "0.128.0"
 		},
 		"objectives": [
 			{
@@ -6401,7 +6401,7 @@ var agent_profile_improvement_proposal_default = {
 			"baselineContentHash": "sha256:21c495a37c418c10bde64fbaa188beddeed31f1f051ea60a6a6582a9ee0db704",
 			"candidateContentHash": "sha256:103f77bc8481601eef1ad5fe6ba84a40dffabc3a44f421f8c8559121edab84e9",
 			"kind": "agent-eval-loop",
-			"recordDigest": "sha256:b2cdacb049f574cded93ebeddfe3f90dbce5f8b9c16abd59b6e310d74eb07e08",
+			"recordDigest": "sha256:9c0bf8c61092567c90d1d40e48ba3f44f70433c80dcd6d28cc14b14a80bcd295",
 			"runId": "profile-improvement-1",
 			"schema": "agent-profile-improvement-experiment"
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.123.1",
+  "version": "0.128.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": {
@@ -117,7 +117,7 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
     "@biomejs/biome": "^2.5.5",
-    "@tangle-network/agent-eval": "0.142.2",
+    "@tangle-network/agent-eval": "0.143.0",
     "@tangle-network/agent-interface": "0.43.0",
     "@tangle-network/sandbox": "0.17.2",
     "@types/node": "26.1.1",
@@ -139,7 +139,7 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.142.2 <0.143.0",
+    "@tangle-network/agent-eval": ">=0.143.0 <0.144.0",
     "@tangle-network/agent-interface": ">=0.43.0 <0.44.0",
     "@tangle-network/sandbox": ">=0.17.2 <0.18.0",
     "playwright": "^1.40.0"
@@ -153,7 +153,7 @@
     }
   },
   "dependencies": {
-    "@tangle-network/agent-knowledge": "7.0.7",
+    "@tangle-network/agent-knowledge": "7.0.8",
     "@tangle-network/agent-profile-materialize": "0.10.2",
     "@tangle-network/agent-trace-contract": "^1.0.2",
     "tar-stream": "3.2.0"

package/skills/agent-graphs/IMPROVE.md

@@ -0,0 +1,58 @@
+# Improving the agent-graphs skill: the loop, mapped onto what exists
+
+The improving artifact is `skills/agent-graphs/SKILL.md`'s text.
+Nothing below is a new framework; every step names the existing agent-eval primitive it composes, per the adopt-or-improve rule.
+The only code this loop owns is two closures and a case set — the slots the machinery deliberately leaves to the caller.
+
+## The loop
+
+```
+case (idea brief) ──► author agent + skill-vN ──► graph ──► runGraph OFFLINE ──► score ──► revise skill ──► gate ──► vN+1
+```
+
+| Step | Primitive | What the loop supplies |
+| --- | --- | --- |
+| Skill text as candidate surface | `MutableSurface = string` (`campaign/types.ts:210`); read `skills/agent-graphs/SKILL.md` → string | one line |
+| Generate graph from case | caller-owned `dispatchWithSurface(surface, scenario, ctx)` in `runCampaign` | **closure A**: run an author agent carrying skill-vN + the case brief; return the authored graph module |
+| Execute offline | `runGraph` with scripted `brain`, stub leaf seam, in-memory journal/blobs (the `examples/graphs/` pattern) | part of closure A |
+| Deterministic scoring | a `JudgeConfig` closure (the `golden-matcher`/`completion-verifier` pattern) | **closure B**: score from `GraphResult` — validation passed; expected edges present with >0 traversals; ledger outcomes match the case's expectations; `exhaustedEdges` empty unless expected; deliverable verdict correct on both a passing and a failing scripted run |
+| Semantic scoring (only what mechanics can't see) | `judge-panel.ts` `ensembleJudge` (cross-family, fail-loud) | rubric: role decomposition quality, directive clarity |
+| Revision | `skillOptOptimizationMethod` (requires a **string** surface — skill text is first-class) or `gepa-optimization-method`; trace-conditioned diffs via `reflective-mutation.ts` | config only |
+| Generations + incumbent | `runOptimization` (retains every generation's surfaces and campaigns) | config only |
+| Gated promotion | `runImprovementLoop` — disjoint train/holdout enforced, no-op winner forced to hold, `autoOnPromote: 'pr'` writes the winner back as a PR | config only |
+| Audit trail | `search-ledger.ts` hash-chained JSONL | free |
+
+## Cases
+
+`cases/` seeds eight idea-briefs, each with `expect`: the edges a correct graph must have, ledger outcomes, whether analysts are warranted, and a floor-trap flag (the case is under-budgetable and a correct author must budget above the floor).
+Case briefs are deliberately loose — "loose context in, correct graph out" is the skill's whole claim, so tidy specs would test the wrong thing.
+
+Holdout discipline: at least 3 of the 8 held out, never trained on; `runImprovementLoop` throws on overlap.
+
+## What is deliberately NOT built
+
+- No graph-diff scorer beyond the ledger checks — a graph is correct if it *runs* correctly offline, not if it textually matches a golden.
+- No new optimizer, campaign runner, judge plumbing, or ledger — all named above.
+- No live-backend scoring in the loop. Live runs are pursuit work, not skill-improvement work; the loop stays offline and free.
+
+## Orchestration layering (doctrine, gates gen4)
+
+Two layers, different jobs.
+Foundation harnesses ship trained orchestration — Claude Code subagents, codex goal-mode, pi extensions — and prose is that layer's native API: instructing a claude-code node to "fan out subagents over these files" invokes an in-distribution capability, not vibes.
+The graph/script layer exists for what no single harness provides: cross-harness composition, one conserved budget across the whole tree, durable ledger evidence, resume, and heterogeneous model placement.
+Rule: outer layer coarse, inner layer maximal — one harness-sized node told to use its native fan-out beats N externally-choreographed thin nodes that each pay the harness floor while suppressing the orchestration the model was trained for.
+Which harnesses qualify for native fan-out is a supervisor-lab harness-KB row, not a guess.
+
+## Version history
+
+The live tree carries only the current `SKILL.md`; every prior surface text is recoverable from git history via the pinned sha256s below, and each generation's full measurement record lives in `generations/`.
+
+| gen | date | surface sha256 (short) | holdout mean | verdict |
+| --- | --- | --- | --- | --- |
+| 1 | 2026-08-03 | `582429a1` | 0.444 (k=3 re-measure in `generations/gen2.json`, n=9 holdout cells) | baseline |
+| 2 | 2026-08-03 | `4c6615b6` | 0.611 (k=3, n=9 holdout cells); 0.600 at the gen3 k=5 re-measure | SHIP (#722) |
+| 3 | 2026-08-03 | `54e7b38b` (not promoted; v2 stays live) | 0.900 — invalidated | **HOLD**: verifier found case-design contamination and scorer leniency; reasons + gen4 requirements in `generations/gen3.json` `verifierHold` |
+
+## Known upstream gap this loop will hit
+
+`OptimizationMethodResult` returns `winnerSurface` only — full candidate history is an owed upstream extension (recorded in discovery docs 22/25). Workaround needing no code: `runOptimization` already retains every generation's surfaces.

package/skills/agent-graphs/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: agent-graphs
+description: Author runGraph programs from AgentProfiles and versioned prompt directives.
+---
+
+# Agent graphs
+
+Use this skill when every role is known before execution and the relationship between roles must be reviewable as data.
+The output is an `AgentGraph` executed by `runGraph`, not a new coordinator or workflow framework.
+
+## Choose the existing entry point
+
+| Need | Use |
+| --- | --- |
+| Known roles with versioned work and analysis instructions | `runGraph` |
+| A standard fixed shape such as parallel attempts, a chain, or a review panel | `fanout`, `pipeline`, `verify`, or `panel` |
+| A model decides which workers to create while it works | `supervise` |
+| One profile can complete the task directly | Run that profile without composition |
+
+Do not force a dynamic task into a static graph.
+Do not use a graph when a smaller shipped primitive already expresses the work.
+
+### Strict authoring decisions (Do not under-graph)
+
+- **Cheapness is not the dialect test:** Do not bail to `single-agent` just because a brief sounds trivial (e.g., "write a one-line file"). If the brief implies roles, observers, or a specific tight budget, author the graph.
+- **Budget Floor Traps:** If a brief demands an impossibly "tight" budget (e.g., a few thousand tokens), do not dodge it by dropping to `single-agent`. Author the graph and explicitly set `budget` to the valid measured executor floor.
+- **Identical-Role Parallelism:** If a brief requests N parallel instances of the same role, you MUST create N distinct worker nodes and N `delegates` edges. Do not collapse identical parallel workers into a single node.
+- **Mandatory Analysts:** If a brief requires independent observation, review, or post-settle findings (e.g., "neutral decider", "review by two perspectives", "watch the worker"), you MUST author `analyzes` edges. Do not omit analysts and attempt to merge their logic into the root's prompt.
+- **Caps are not stops:** Do not use an analysis edge `maxTraversals` cap as a global stop condition. To stop after N findings, use `deliverable.check` or `maxTraversals` on a `delegates` edge.
+
+## Author the complete contract
+
+An `AgentGraph` has four required fields: `nodes`, `edges`, `deliverable`, and `budget`.
+`runGraph(graph, options)` validates graph structure and prompt references before it spends compute.
+
+### Nodes
+
+Each node is `{ id, profile }`, where `profile` is a complete canonical `AgentProfile`.
+Set `profile.name` equal to `id` because Runtime uses that value to select and route the node.
+Put the standing role in `profile.prompt.systemPrompt` and capabilities in the profile's tools, MCP, resources, hooks, and subagents.
+Do not rebuild profile materialization in graph code.
+
+### Delegation edges
+
+A delegation edge is `{ kind: 'delegates', from, to, directive, maxTraversals? }`.
+The directive is a registered, versioned `PromptHandle`, such as `promptHandle('delegates/research-brief/v1')`.
+Each spawn and each later steer over the same edge consumes one traversal.
+The default cap is `defaultEdgeTraversalCap`; exhaustion refuses further delegation.
+
+The current graph form has one root and a static set of worker nodes.
+Every delegation edge starts at the root, and each worker has exactly one incoming delegation edge.
+Use a new directive version to change a brief instead of adding a second edge to the same worker.
+
+### Analysis edges
+
+An analysis edge is `{ kind: 'analyzes', analyst, over, to, directive, maxTraversals? }`.
+It runs after a listed worker settles and routes findings to one node.
+
+`analyst` has two supported forms:
+
+- A lens id from `options.analysts` runs a caller-supplied analysis function.
+- A graph node id runs that node's pinned `AgentProfile` as a tool-equipped analyst.
+
+An analyst node has no incoming delegation edge, so the root cannot hand it ordinary work.
+An id cannot be both a registered lens and an analyst node.
+`over` lists delegated worker nodes only; Runtime refuses the root and analyst nodes because neither settles as an ordinary worker.
+An analysis traversal cap records excess findings as `unpropagated`; it does not stop the run.
+
+### Completion and budget
+
+`deliverable.check(output)` is the independent completion test.
+It must accept a genuinely complete result and reject junk.
+Put the concrete mission in `deliverable.describe`; Runtime uses that text as the root's task.
+
+`budget` is one conserved pool for the full graph.
+Set `options.perWorker` explicitly from the actual executor cost.
+For Pi, `WORKER_TOKEN_FLOOR.pi` is 31,211 input tokens before useful work, so a worker allocation below that value is refused. If a brief asks for a budget lower than the floor, do not switch to `single-agent`; output the graph with the floor allocation.
+Treat an unmeasured executor floor as unknown rather than zero.
+Analyst nodes spend from the same pool and need the same honest accounting as ordinary workers.
+
+## Authoring procedure
+
+1. **Classify correctly:** Verify if this needs `single-agent`, `dynamic-workflow`, or a static `runGraph`. If independent review or parallel workers are requested, use `runGraph`.
+2. **Define completion first:** Write the completion test and its description.
+3. **Select entry point:** Choose the smallest shipped entry point from the table above.
+4. **Define Roles:** Give every distinct role one complete `AgentProfile`. If N parallel instances of a role are requested, create N nodes. Merge roles only if their standing prompts and capabilities are identical.
+5. **Register directives:** Register a versioned directive for every edge.
+6. **Delegate work:** Add one delegation edge per ordinary worker from the root.
+7. **Attach analysts:** Add `analyzes` edges only when findings must be produced independently after a worker settles. Do not skip this if the brief asked for a watcher/reviewer.
+8. **Size the pool:** Set budget, per-worker allocation, traversal caps, time, and concurrency from measured executor behavior. Ensure budgets meet the executor floor.
+9. **Prove and inspect:** Run the structure offline, then run the real backend and inspect its result.
+
+## Prove the graph before spending
+
+Use an injected `brain` plus `makeWorkerAgent` to exercise graph structure without a network call.
+Cover invalid profiles, unknown directives, impossible analysis routes, traversal exhaustion, successful completion, and rejected junk.
+Start from the runnable programs in `examples/graphs/` rather than creating a second graph runner.
+
+Offline execution proves control flow only.
+A real task must still use the intended backend, profiles, tools, completion test, and budget before claiming the graph solves that task.
+
+## Read the complete result
+
+| Field | Meaning |
+| --- | --- |
+| `result.result.kind` and `reason` | Whether a result won and why execution ended |
+| `result.result.spentTotal` | Tokens and money, including whether each total is known |
+| `result.ledger` | Every delivered, stripped, empty, or unpropagated edge traversal with byte counts |
+| `result.exhaustedEdges` | Every edge whose cap was reached, including normal lifecycle endings |
+| Journal `edge` events | Durable copies of traversal evidence |
+
+Zero traversals on an expected edge means the graph did not exercise that relationship.
+`usdKnown: false` means cost is missing, not free.
+A passing completion test proves only what that test checks.
+
+## Common mistakes
+
+- Bailing to `single-agent` because a brief sounds trivial, instead of respecting requested roles or applying budget floors.
+- Collapsing N requested parallel identical roles into a single worker node.
+- Skipping `analyzes` edges when an observer or reviewer is explicitly requested.
+- Putting the task only in a spawn prompt instead of `deliverable.describe`.
+- Giving a node a `profile.name` different from its id.
+- Delegating ordinary work to an analyst node.
+- Listing the root or an analyst node in `analyzes.over`.
+- Using an analysis cap as a stop condition.
+- Allowing a driver-authored spawn profile to add capabilities instead of defining them on the pinned node profile.
+- Reading only thrown cap errors and missing `result.exhaustedEdges` on budget or cancellation endings.
+- Treating unknown spend as zero.
+- Claiming recursive or runtime-discovered structure when the current graph is a static root with workers and analysts.
+
+## Improve only after measurement
+
+Runtime already optimizes one inline skill through `improve(profile, { surface: 'skills', skills: { resourceName }, ... })`.
+Put the exact skill bytes in `profile.resources.skills`, set `profile.resources.failOnError: true`, supply disjoint development and final-test tasks, and pass a complete Agent Eval optimization method.
+Do not create a graph-specific optimizer, campaign runner, candidate store, or promotion path.
+
+## Then consider
+
+- `loop-writer` when the required dynamic structure still cannot be expressed by `supervise` or another shipped primitive; pass the exact missing behavior and the completion test.
+- `verify` before publishing a graph consumer; pass the real backend command, expected result fields, and failure cases.

package/skills/agent-graphs/cases/artifact-mission-release-notes.json

@@ -0,0 +1,10 @@
+{
+  "id": "artifact-mission-release-notes",
+  "brief": "Produce a release-notes file for version 2.0 that passes our repo format checker.",
+  "expect": {
+    "correctAnswerIsGraph": true,
+    "nodes": 1,
+    "deliverableDescribeCarriesMission": true,
+    "checkIsMechanical": true
+  }
+}

package/skills/agent-graphs/cases/audited-single-writer.json

@@ -0,0 +1,9 @@
+{
+  "id": "audited-single-writer",
+  "brief": "Have a separate worker write the summary document so I can audit exactly what it did afterwards.",
+  "expect": {
+    "correctAnswerIsGraph": true,
+    "nodes": 1,
+    "reason": "auditability warrants delegation despite a cheap-sounding task"
+  }
+}

package/skills/agent-graphs/cases/cap-as-stop-mistake.json

@@ -0,0 +1,8 @@
+{
+  "id": "cap-as-stop-mistake",
+  "brief": "Have an analyst watch the worker and stop the whole thing after three findings.",
+  "expect": {
+    "trapIsAnalyzesCapAsStop": true,
+    "correctStopIsDelegatesCapOrDeliverable": true
+  }
+}

package/skills/agent-graphs/cases/floor-trap-pi.json

@@ -0,0 +1,11 @@
+{
+  "id": "floor-trap-pi",
+  "brief": "Cheap little task: have a pi agent write a one-line file. Keep the budget tight, like a few thousand tokens.",
+  "expect": {
+    "nodes": 1,
+    "analyzesWarranted": false,
+    "floorTrap": true,
+    "mustBudgetAtLeast": 31211,
+    "correctAuthorOverridesBrief": true
+  }
+}

package/skills/agent-graphs/cases/mission-in-deliverable.json

@@ -0,0 +1,8 @@
+{
+  "id": "mission-in-deliverable",
+  "brief": "Produce a CHANGELOG entry for last week that passes our format check.",
+  "expect": {
+    "deliverableDescribeCarriesMission": true,
+    "checkIsMechanical": true
+  }
+}

package/skills/agent-graphs/cases/review-pipeline.json

@@ -0,0 +1,14 @@
+{
+  "id": "review-pipeline",
+  "brief": "I want code changes reviewed by two different perspectives before anything merges, and someone neutral deciding.",
+  "expect": {
+    "nodes": 3,
+    "analyzesWarranted": true,
+    "floorTrap": false,
+    "edges": [
+      "delegates to each reviewer",
+      "analyzes routing findings to root"
+    ],
+    "wrongIfAnalystIsNode": true
+  }
+}

package/skills/agent-graphs/cases/runtime-discovered-fanout.json

@@ -0,0 +1,8 @@
+{
+  "id": "runtime-discovered-fanout",
+  "brief": "Find every failing test in the repo and fix each one in parallel.",
+  "expect": {
+    "correctAnswerIsDynamicWorkflow": true,
+    "reason": "topology discovered mid-run"
+  }
+}

package/skills/agent-graphs/cases/single-agent-suffices.json

@@ -0,0 +1,7 @@
+{
+  "id": "single-agent-suffices",
+  "brief": "Summarize this document into five bullets.",
+  "expect": {
+    "correctAnswerIsNoGraph": true
+  }
+}

package/skills/agent-graphs/cases/steer-heavy-drafting.json

@@ -0,0 +1,9 @@
+{
+  "id": "steer-heavy-drafting",
+  "brief": "One writer drafts, I want the coordinator to redirect it up to five times based on how the draft evolves.",
+  "expect": {
+    "nodes": 1,
+    "maxTraversalsAtLeast": 6,
+    "reason": "spawns and steers share the traversal count"
+  }
+}

package/skills/agent-graphs/cases/unmeasured-harness.json

@@ -0,0 +1,9 @@
+{
+  "id": "unmeasured-harness",
+  "brief": "Run three probes on claude-code workers and collect what they output.",
+  "expect": {
+    "nodes": 3,
+    "floorTrap": false,
+    "generousBudgetsBecauseFloorUnknown": true
+  }
+}