tangle-network · drewstone · Jul 3, 2026 · Jul 3, 2026
diff --git a/docs/api/primitive-catalog.md b/docs/api/primitive-catalog.md
@@ -7,7 +7,7 @@
 
 # Primitive catalog — the never-stale anti-reinvention inventory
 
-> **GENERATED** from `@tangle-network/agent-runtime@0.84.0` and `@tangle-network/agent-eval@0.103.1` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
+> **GENERATED** from `@tangle-network/agent-runtime@0.85.0` and `@tangle-network/agent-eval@0.103.1` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
 
 ## 1. agent-runtime — own public surface
 
@@ -246,7 +246,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 63 exports.
 
 ### Recursive atom + loop kernel (alias of ./runtime)
 
-Import from `@tangle-network/agent-runtime/loops` — 419 exports.
+Import from `@tangle-network/agent-runtime/loops` — 425 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -262,6 +262,7 @@ Import from `@tangle-network/agent-runtime/loops` — 419 exports.
 | `authorStrategy` | function | Author + load a strategy from losses. Throws when the author emits no loadable module; |
 | `breadthStrategy` | function | BREADTH: K independent rollouts (each own artifact), verifier picks the best. |
 | `buildSteerContext` | function | Build the `SteerContext` a combinator reads to steer (its `loopUntil.until`, `widen` gate, any |
+| `collectAgentTurn` | function | Drain a `streamAgentTurn` stream (or any `RuntimeStreamEvent` stream that |
 | `completionAuthorizes` | function | Decide whether a `CompletionVerdict` may end the node under the policy: authority scales with the verdict's determinism, and probabilistic verdicts must clear `minConfidence`. |
 | `computeFindingId` | function | Compute the stable finding_id from the identity-defining fields. |
 | `contentAddress` | function | Mint the content-addressed `outRef` for a result artifact: `sha256:<hex>` over a |
@@ -358,6 +359,7 @@ Import from `@tangle-network/agent-runtime/loops` — 419 exports.
 | `settledToIteration` | function | The step-8 merge-boundary adapter (M4): rehydrate a `Settled.done` into the kernel's |
 | `spendFromUsageEvents` | function | Fold a normalized `UsageEvent` array into a `Spend`. Tokens and usd are separate |
 | `stopSentinel` | function | A unique, attributable stop sentinel for a node (ralph-loop style). Deterministic from the |
+| `streamAgentTurn` | function | Run ONE agent turn on any backend kind and stream its events. Yields the |
 | `sumSandboxUsage` | function | Sum the token usage + USD cost of a sandbox turn's events — the one honest way to meter an |
 | `supervise` | function | One-call supervisor: build + run a supervisor from its profile with sensible defaults; the raw `supervisorAgent` + `createSupervisor().run` seams stay available for power use. |
 | `superviseSurface` | function | Drive a team of agents (spawned + steered by `profile`) to solve a graded `AgenticSurface` task, and |
@@ -394,6 +396,7 @@ Import from `@tangle-network/agent-runtime/loops` — 419 exports.
 | `AgentProfile` | interface | Public provider-neutral agent profile contract. |
 | `AgentRunSpec` | interface | Sandbox-SDK-shaped agent specification. |
 | `AgentSpec` | interface | `AgentProfile` does NOT carry a `harness`/backend field — `harness` lives on the |
+| `AgentTurnUsage` | interface | Metered usage of one turn, summed over every cost-bearing event the backend |
 | `AnalystFinding` | interface | Unified envelope every analyst emits. Schema-versioned so renderers |
 | `AnytimeTaskCurve` | interface | anytimeReport — time-to-satisfactory-output metrics, derived entirely from the |
 | `AuditIntentInput` | interface | auditIntent — the route-rigor analyst: is this trajectory even going the RIGHT WAY? |
@@ -404,6 +407,7 @@ Import from `@tangle-network/agent-runtime/loops` — 419 exports.
 | `BusEvent` | interface | Every bus event is a discriminated union member keyed by `type`. |
 | `BusRecord` | interface | A published event stamped for ordering and observability. `seq` is the monotonic publish index; |
 | `CheckpointCapableBox` | interface | Loop-side widening of the box's optional checkpoint method. The |
+| `CollectedAgentTurn` | interface | A drained turn: the terminal summary plus every event the stream yielded. |
 | `CompletionAnalyst` | interface | Reads a node's trace → a completion verdict. Same input shape as the `analyze` hook, so |
 | `CompletionEvidence` | interface | Trace-derived evidence for a completion claim — an artifact (output) or a verifier metric, |
 | `CompletionPolicy` | interface | When a verdict authorizes the driver to END. Deterministic → trust (ground truth); |
@@ -526,6 +530,7 @@ Import from `@tangle-network/agent-runtime/loops` — 419 exports.
 | `WorktreeCommandResult` | interface | Outcome of one verification command run in the worktree (test or typecheck). |
 | `AgentEnvironmentProviderRef` | type | Provider object or registry name accepted by runtime provider adapters. |
 | `AgentProfileRef` | type | Portable profile reference: inline profile or provider catalog id. |
+| `AgentTurnBackend` | type | The execution substrate one turn runs on — a closed discriminated union over |
 | `ApplyContinuation` | type | Fold a steering string into the caller's Task shape, producing the Task for |
 | `AssertTraceDerivedFindings` | type | The firewall assertion contract, re-stated for the reactive seam (PORT of |
 | `BudgetReadout` | type | Post-reservation pool readout — the shape `Scope.budget` exposes. `tokensLeft`, |
@@ -566,7 +571,7 @@ Import from `@tangle-network/agent-runtime/loops` — 419 exports.
 | `WinnerStrategy` | type | Built-in valid-only winner strategies for `selectValidWinner` (selector≠judge): best gated-valid |
 | `WorktreePatchArtifact` | type | Terminal artifact of one worktree-CLI run — the canonical worktree-harness result (the captured |
 
-**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AgentEnvironment`, `AgentEnvironmentCapabilities`, `AgentEnvironmentEvent`, `AgentEnvironmentProvider`, `AgentEnvironmentQuery`, `AgentEnvironmentSummary`, `AgenticOptions`, `AgenticRunResult`, `AgenticTool`, `AgentSession`, `AgentSessionRef`, `AgentTurnInput`, `AgentTurnResult`, `AnalystRegistry`, `AnytimeReport`, `AnytimeStrategySummary`, `ArtifactHandle`, `AuditIntentOptions`, `AuthoredHarness`, `AuthoredStrategy`, `AuthorStrategyOptions`, `BenchmarkConfig`, `BenchmarkLift`, `BenchmarkStrategySummary`, `BenchmarkTaskRow`, `BudgetPool`, `BusStats`, `ChampionPick`, `CheckpointRef`, `CheckpointRequest`, `CreateAgentEnvironmentInput`, `DefinedLeaderboard`, `Driver`, `EventBus`, `EvolutionArchiveNode`, `EvolutionBandInfo`, `EvolutionCandidate`, `EvolutionGeneration`, `EvolutionReport`, `ExecRequest`, `ExecResult`, `ForkRequest`, `GitWorkspaceOptions`, `HarvestFailure`, `HarvestReport`, `Inbox`, `InProcessSandboxClientOptions`, `IntentAudit`, `Iteration`, `Leaderboard`, `LeaderboardOptions`, `LeaderboardSpec`, `LoopDecisionPayload`, `LoopDispatchOptions`, `LoopEndedPayload`, `LoopIterationEndedPayload`, `LoopIterationStartedPayload`, `LoopPlanDescription`, `LoopResult`, `LoopSandboxPlacement`, `LoopStartedPayload`, `LoopTraceEmitter`, `LoopWinner`, `McpEnvironmentOptions`, `Observation`, `ObserveOptions`, `OpenSandboxRunOptions`, `PairwiseOptions`, `PatchDeliverableOptions`, `PlacementInfo`, `PromotionGateOptions`, `PromotionVerdict`, `PublishOptions`, `ResourceRequest`, `RouterChatResult`, `RouterChatToolsResult`, `RouterToolLoopResult`, `RunAgenticOptions`, `SandboxRun`, `ShotSpec`, `StrategyEvolutionConfig`, `StrategyResult`, `SuperviseOptions`, `SuperviseSurfaceOptions`, `SupervisorAgentDeps`, `SupervisorOpts`, `SurfaceScore`, `ToolSpec`, `TraceSource`, `ValidationCtx`, `Validator`, `WaterfallCollector`, `WaterfallReport`, `Workspace`, `WorkspaceRequest`, `WorkspaceRun`, `WorktreeCliExecutorOptions`, `WorktreeFanoutOptions`, `AgentEnvironmentStatus`, `AgentSessionStatus`, `ChampionPolicy`, `LoopTraceEvent`, `MakeWorkerAgent`, `WorkspaceCommit`.
+**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AgentEnvironment`, `AgentEnvironmentCapabilities`, `AgentEnvironmentEvent`, `AgentEnvironmentProvider`, `AgentEnvironmentQuery`, `AgentEnvironmentSummary`, `AgenticOptions`, `AgenticRunResult`, `AgenticTool`, `AgentSession`, `AgentSessionRef`, `AgentTurnInput`, `AgentTurnResult`, `AnalystRegistry`, `AnytimeReport`, `AnytimeStrategySummary`, `ArtifactHandle`, `AuditIntentOptions`, `AuthoredHarness`, `AuthoredStrategy`, `AuthorStrategyOptions`, `BenchmarkConfig`, `BenchmarkLift`, `BenchmarkStrategySummary`, `BenchmarkTaskRow`, `BudgetPool`, `BusStats`, `ChampionPick`, `CheckpointRef`, `CheckpointRequest`, `CreateAgentEnvironmentInput`, `DefinedLeaderboard`, `Driver`, `EventBus`, `EvolutionArchiveNode`, `EvolutionBandInfo`, `EvolutionCandidate`, `EvolutionGeneration`, `EvolutionReport`, `ExecRequest`, `ExecResult`, `ForkRequest`, `GitWorkspaceOptions`, `HarvestFailure`, `HarvestReport`, `Inbox`, `InProcessSandboxClientOptions`, `IntentAudit`, `Iteration`, `Leaderboard`, `LeaderboardOptions`, `LeaderboardSpec`, `LoopDecisionPayload`, `LoopDispatchOptions`, `LoopEndedPayload`, `LoopIterationEndedPayload`, `LoopIterationStartedPayload`, `LoopPlanDescription`, `LoopResult`, `LoopSandboxPlacement`, `LoopStartedPayload`, `LoopTraceEmitter`, `LoopWinner`, `McpEnvironmentOptions`, `Observation`, `ObserveOptions`, `OpenSandboxRunOptions`, `PairwiseOptions`, `PatchDeliverableOptions`, `PlacementInfo`, `PromotionGateOptions`, `PromotionVerdict`, `PublishOptions`, `ResourceRequest`, `RouterChatResult`, `RouterChatToolsResult`, `RouterToolLoopResult`, `RunAgenticOptions`, `SandboxRun`, `ShotSpec`, `StrategyEvolutionConfig`, `StrategyResult`, `StreamAgentTurnOptions`, `SuperviseOptions`, `SuperviseSurfaceOptions`, `SupervisorAgentDeps`, `SupervisorOpts`, `SurfaceScore`, `ToolSpec`, `TraceSource`, `ValidationCtx`, `Validator`, `WaterfallCollector`, `WaterfallReport`, `Workspace`, `WorkspaceRequest`, `WorkspaceRun`, `WorktreeCliExecutorOptions`, `WorktreeFanoutOptions`, `AgentEnvironmentStatus`, `AgentSessionStatus`, `ChampionPolicy`, `LoopTraceEvent`, `MakeWorkerAgent`, `WorkspaceCommit`.
 
 ### Environment provider adapters — generic sandbox/compute bridge
 

diff --git a/docs/api/runtime.md b/docs/api/runtime.md
@@ -8143,6 +8143,139 @@ Defined in: [runtime/strategy.ts:1028](https://github.com/tangle-network/agent-r
 
 ***
 
+### StreamAgentTurnOptions
+
+Defined in: [runtime/stream-agent-turn.ts:93](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L93)
+
+**`Experimental`**
+
+#### Properties
+
+##### signal?
+
+> `optional` **signal?**: `AbortSignal`
+
+Defined in: [runtime/stream-agent-turn.ts:95](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L95)
+
+**`Experimental`**
+
+Caller-initiated cancellation. Terminates the stream with `final.status: 'aborted'`.
+
+##### timeoutMs?
+
+> `optional` **timeoutMs?**: `number`
+
+Defined in: [runtime/stream-agent-turn.ts:101](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L101)
+
+**`Experimental`**
+
+Wall-clock deadline for the whole turn in ms. An expired deadline aborts
+the backend and terminates the stream with `final.status: 'failed'`
+(a blown deadline is a turn failure, not a caller cancellation).
+
+***
+
+### AgentTurnUsage
+
+Defined in: [runtime/stream-agent-turn.ts:112](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L112)
+
+**`Experimental`**
+
+Metered usage of one turn, summed over every cost-bearing event the backend
+emitted. `input`/`output` are token counts (0 when the backend reported
+none — the honest sum, never a fabricated estimate). `costUsd`/`model` are
+present only when the backend actually reported them.
+
+#### Properties
+
+##### input
+
+> **input**: `number`
+
+Defined in: [runtime/stream-agent-turn.ts:113](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L113)
+
+**`Experimental`**
+
+##### output
+
+> **output**: `number`
+
+Defined in: [runtime/stream-agent-turn.ts:114](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L114)
+
+**`Experimental`**
+
+##### costUsd?
+
+> `optional` **costUsd?**: `number`
+
+Defined in: [runtime/stream-agent-turn.ts:115](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L115)
+
+**`Experimental`**
+
+##### model?
+
+> `optional` **model?**: `string`
+
+Defined in: [runtime/stream-agent-turn.ts:116](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L116)
+
+**`Experimental`**
+
+***
+
+### CollectedAgentTurn
+
+Defined in: [runtime/stream-agent-turn.ts:126](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L126)
+
+**`Experimental`**
+
+A drained turn: the terminal summary plus every event the stream yielded.
+`status`/`error` mirror the terminal `final` event so a failed or aborted
+turn stays inspectable without re-scanning `events`.
+
+#### Properties
+
+##### finalText
+
+> **finalText**: `string`
+
+Defined in: [runtime/stream-agent-turn.ts:127](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L127)
+
+**`Experimental`**
+
+##### usage
+
+> **usage**: [`AgentTurnUsage`](#agentturnusage)
+
+Defined in: [runtime/stream-agent-turn.ts:128](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L128)
+
+**`Experimental`**
+
+##### events
+
+> **events**: [`RuntimeStreamEvent`](index.md#runtimestreamevent)[]
+
+Defined in: [runtime/stream-agent-turn.ts:129](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L129)
+
+**`Experimental`**
+
+##### status
+
+> **status**: [`AgentTaskStatus`](index.md#agenttaskstatus)
+
+Defined in: [runtime/stream-agent-turn.ts:130](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L130)
+
+**`Experimental`**
+
+##### error?
+
+> `optional` **error?**: [`BackendErrorDetail`](index.md#backenderrordetail)
+
+Defined in: [runtime/stream-agent-turn.ts:131](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L131)
+
+**`Experimental`**
+
+***
+
 ### SurfaceWorkerOut
 
 Defined in: [runtime/supervise-surface.ts:34](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise-surface.ts#L34)
@@ -14448,6 +14581,83 @@ Defined in: [runtime/strategy-evolution.ts:55](https://github.com/tangle-network
 
 ***
 
+### AgentTurnBackend
+
+> **AgentTurnBackend** = \{ `kind`: `"box"`; `box`: `SandboxInstance`; `agentRunName?`: `string`; \} \| \{ `kind`: `"executor"`; `factory`: [`ExecutorFactory`](#executorfactory)\<`unknown`\>; `agentRunName?`: `string`; \} \| \{ `kind`: `"chat"`; `backend`: [`AgentExecutionBackend`](index.md#agentexecutionbackend); \}
+
+Defined in: [runtime/stream-agent-turn.ts:63](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L63)
+
+**`Experimental`**
+
+The execution substrate one turn runs on — a closed discriminated union over
+the three stream surfaces the runtime already owns.
+
+#### Union Members
+
+##### Type Literal
+
+\{ `kind`: `"box"`; `box`: `SandboxInstance`; `agentRunName?`: `string`; \}
+
+###### kind
+
+> **kind**: `"box"`
+
+A live sandbox box: the turn is one `box.streamPrompt(prompt)` call.
+
+###### box
+
+> **box**: `SandboxInstance`
+
+###### agentRunName?
+
+> `optional` **agentRunName?**: `string`
+
+Model label stamped on cost-only `llm_call` events. Default `'agent'`.
+
+***
+
+##### Type Literal
+
+\{ `kind`: `"executor"`; `factory`: [`ExecutorFactory`](#executorfactory)\<`unknown`\>; `agentRunName?`: `string`; \}
+
+###### kind
+
+> **kind**: `"executor"`
+
+A one-shot `Executor` (cli-bridge / router / BYO): the factory is
+instantiated fresh for the turn via `inlineSandboxClient`, run once on
+the prompt, and torn down — the same per-spawn lifecycle the supervise
+runtime gives it.
+
+###### factory
+
+> **factory**: [`ExecutorFactory`](#executorfactory)\<`unknown`\>
+
+###### agentRunName?
+
+> `optional` **agentRunName?**: `string`
+
+Model label stamped on cost-only `llm_call` events. Default `'agent'`.
+
+***
+
+##### Type Literal
+
+\{ `kind`: `"chat"`; `backend`: [`AgentExecutionBackend`](index.md#agentexecutionbackend); \}
+
+###### kind
+
+> **kind**: `"chat"`
+
+An in-process `AgentExecutionBackend` (`resolveAgentBackend` output or
+any custom backend): the turn is one `backend.stream()` call.
+
+###### backend
+
+> **backend**: [`AgentExecutionBackend`](index.md#agentexecutionbackend)
+
+***
+
 ### BudgetReadout
 
 > **BudgetReadout** = `Readonly`\<\{ `tokensLeft`: `number`; `usdLeft`: `number`; `usdCapped`: `boolean`; `deadlineMs`: `number`; `reservedTokens`: `number`; \}\>
@@ -17193,6 +17403,66 @@ Run a Strategy through the keystone Supervisor — `Agent.act` over a conserved-
 
 ***
 
+### streamAgentTurn()
+
+> **streamAgentTurn**(`backend`, `prompt`, `opts?`): `AsyncGenerator`\<[`RuntimeStreamEvent`](index.md#runtimestreamevent)\>
+
+Defined in: [runtime/stream-agent-turn.ts:158](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L158)
+
+**`Experimental`**
+
+Run ONE agent turn on any backend kind and stream its events. Yields the
+`RuntimeStreamEvent` vocabulary incrementally and always ends with a `final`
+event carrying the turn's text and usage (`metadata.tokenUsage`,
+`metadata.costUsd?`, `metadata.model?`) — on success, failure, abort, and
+timeout alike. The generator never throws; failures surface in-band as
+`backend_error` + `final` with a typed `error` detail.
+
+#### Parameters
+
+##### backend
+
+[`AgentTurnBackend`](#agentturnbackend)
+
+##### prompt
+
+`string`
+
+##### opts?
+
+[`StreamAgentTurnOptions`](#streamagentturnoptions) = `{}`
+
+#### Returns
+
+`AsyncGenerator`\<[`RuntimeStreamEvent`](index.md#runtimestreamevent)\>
+
+***
+
+### collectAgentTurn()
+
+> **collectAgentTurn**(`stream`): `Promise`\<[`CollectedAgentTurn`](#collectedagentturn)\>
+
+Defined in: [runtime/stream-agent-turn.ts:223](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/stream-agent-turn.ts#L223)
+
+**`Experimental`**
+
+Drain a `streamAgentTurn` stream (or any `RuntimeStreamEvent` stream that
+honors its terminal contract) into the turn summary plus the full event
+list. Fail-loud: throws when the stream ends without a terminal `final`
+event — a stream that violates the contract must not read as an empty turn.
+
+#### Parameters
+
+##### stream
+
+`AsyncIterable`\<[`RuntimeStreamEvent`](index.md#runtimestreamevent)\>
+
+#### Returns
+
+`Promise`\<[`CollectedAgentTurn`](#collectedagentturn)\>
+
+***
+
 ### failuresAnalyst()
 
 > **failuresAnalyst**(): [`AnalystRegistry`](#analystregistry)