fix(runtime): adopt the Sandbox run result

.github/workflows/ci.yml

@@ -81,7 +81,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: tangle-network/agent-sdk
-          ref: 7864c1803eb299d136682bcc782f4718c7e69bc6 # @tangle-network/agent-interface@1.1.0
+          ref: a3c31b986809689892ec34617df58b007992ef0c # @tangle-network/agent-interface@1.3.0
           path: .cohort/agent-sdk
           persist-credentials: false
 

.github/workflows/publish.yml

@@ -135,7 +135,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: tangle-network/agent-sdk
-          ref: 7864c1803eb299d136682bcc782f4718c7e69bc6 # @tangle-network/agent-interface@1.1.0
+          ref: a3c31b986809689892ec34617df58b007992ef0c # @tangle-network/agent-interface@1.3.0
           path: .cohort/agent-sdk
           persist-credentials: false
 

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.143.0
+
+### Sandbox moves to 0.31.0, and its run outcome is the one terminal result
+
+The Sandbox peer range becomes `>=0.31.0 <0.32.0`, and the catalog requires Sandbox `0.31.0`.
+Sandbox 0.31.0 publishes `createAgentRunOutcomeTracker` and `AgentRunOutcome` on its `runtime` subpath, and this package now requires them.
+The Interface peer range becomes `^1.3.0` because Sandbox 0.31.0 requires Interface `^1.3.0`, so one consumer install resolves one Interface copy.
+Bench moves to 0.8.19 with the same dependency cohort.
+
+The round-synchronous leaf (`runAgentRounds`), `openSandboxRun`, the steerable sandbox session, and `streamAgentTurn` observe the complete Sandbox event stream with the public outcome tracker and read the terminal result from it.
+A `failed` outcome fails the iteration or turn with the Sandbox error.
+A `blocked_on_approval` or `awaiting_*` outcome settles as `blocked`.
+A `success` outcome completes, so a recovered tool error no longer fails a completed turn.
+The outcome rides `Iteration.sandboxOutcome`, `CollectedAgentTurn.sandboxOutcome`, and the final stream event's `metadata.sandboxOutcome`.
+A failed or blocked turn keeps its measured token usage and cost.
+`SandboxLeafOut` carries `content`, `toolCalls`, and `outcome` beside the raw `events`, so a consumer does not parse raw Sandbox events a second time; `SandboxExecutorToolCall` names one retained tool call.
+
+`./kernel` drops `assertSandboxEventSucceeded` and `sandboxEventFailure`; the public Sandbox outcome tracker replaces that event-level failure parser.
+This is a minor release because two public exports are removed.
+
 ## 0.142.3
 
 ### Sandbox 0.29 and 0.30 compatibility

api-surface.json

@@ -1313,6 +1313,7 @@
       "SandboxClientProviderOptions": "type",
       "SandboxControlClient": "type",
       "SandboxEvent": "type",
+      "SandboxExecutorToolCall": "type",
       "SandboxInstance": "type",
       "SandboxLeafOut": "type",
       "SandboxLineage": "type",
@@ -1489,7 +1490,6 @@
       "assertCoordinationBinding": "value",
       "assertModelAllowed": "value",
       "assertProfileModelsAllowed": "value",
-      "assertSandboxEventSucceeded": "value",
       "assertSandboxServedModel": "value",
       "assertStrategyContract": "value",
       "assertTraceDerivedFindings": "value",
@@ -1684,7 +1684,6 @@
       "sampleThenRefine": "value",
       "sandboxCheckRunner": "value",
       "sandboxClientAsProvider": "value",
-      "sandboxEventFailure": "value",
       "sandboxEventServedBackend": "value",
       "sandboxSessionTraceSource": "value",
       "sanitizeMcpToolSchema": "value",

bench/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.8.19
+
+- Align the Bench package with Runtime 0.143.0, Interface 1.3.0, and Sandbox 0.31.0.
+
 ## 0.8.18
 
 - Align the Bench package with Runtime 0.142.3 and the Sandbox 0.29.0–0.30.0 compatibility range.

bench/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-bench",
-  "version": "0.8.18",
+  "version": "0.8.19",
   "type": "module",
   "description": "Benchmark adapters and execution for agent-runtime across coding, tool-use, RAG, memory, browser, and terminal tasks.",
   "repository": {

docs/api/primitive-catalog.md

@@ -7,7 +7,7 @@
 
 # Primitive catalog — the never-stale anti-reinvention inventory
 
-> **GENERATED** from `@tangle-network/agent-runtime@0.142.3` and `@tangle-network/agent-eval@0.149.0` 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.143.0` and `@tangle-network/agent-eval@0.149.0` 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
 
@@ -549,7 +549,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 172 exports.
 
 ### Execution kernel — recursive atom, supervision, executors, round-synchronous loop
 
-Import from `@tangle-network/agent-runtime/kernel` — 815 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 814 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -564,7 +564,6 @@ Import from `@tangle-network/agent-runtime/kernel` — 815 exports.
 | `assertCoordinationBinding` | function | Fail closed on a non-loopback coordination bind. `serveCoordinationMcp` mounts spawn_agent / |
 | `assertModelAllowed` | function | Throw a `ConfigError` when `allowed` is set, `model` is defined, and `model` is not a |
 | `assertProfileModelsAllowed` | function | Check every canonical model-bearing field in a complete profile, including the models a |
-| `assertSandboxEventSucceeded` | function | Fail the live execution instead of allowing an in-band failure to become an empty success. |
 | `assertSandboxServedModel` | function | Fail the execution when the platform reports serving a model other than the exact one asked for. |
 | `assertStrategyContract` | function | Static CONTRACT lint over an authored strategy module — the module-boundary |
 | `assessAuthoredProfile` | function | OBSERVE one authored `AgentProfile` and score its richness (no judge verdict is read). The task |
@@ -739,7 +738,6 @@ Import from `@tangle-network/agent-runtime/kernel` — 815 exports.
 | `sampleFromSettled` | function | Build a `ProgressSample` from a scope settlement. The objective is the verdict score and |
 | `sandboxCheckRunner` | function | Default CheckRunner backend: pipes the check program into `python3` over the sandbox |
 | `sandboxClientAsProvider` | function | Adapt a `SandboxClient` into the shared `AgentEnvironmentProvider` contract. |
-| `sandboxEventFailure` | function | Return the terminal failure carried by one Sandbox event. |
 | `sandboxEventServedBackend` | function | Read the served execution identity off one Sandbox event. |
 | `sandboxSessionTraceSource` | function | The SANDBOX / fleet trace source: read a box session's message parts and decode the harness's tool |
 | `sanitizeMcpToolSchema` | function | Coerce an MCP inputSchema to an OpenAI-tool-valid top-level object schema. |
@@ -1025,7 +1023,8 @@ Import from `@tangle-network/agent-runtime/kernel` — 815 exports.
 | `SandboxClient` | interface | Minimal sandbox client surface the kernel calls. Satisfied structurally by |
 | `SandboxClientProviderOptions` | interface | Options for wrapping the current Tangle sandbox client as an environment provider. |
 | `SandboxEvent` | interface | SSE event from sandbox streaming. |
-| `SandboxLeafOut` | interface | Parsed output of the sandbox leaf: the iteration's raw event stream. What a |
+| `SandboxExecutorToolCall` | interface | One tool call retained in a Sandbox executor artifact. |
+| `SandboxLeafOut` | interface | Parsed output of one Sandbox executor turn. |
 | `SandboxLineage` | interface | Owns box + session handles for one loop run and offers the three |
 | `SandboxLineageHandle` | interface | A live box plus the session that threads its iterations together. Handed back |
 | `SandboxSeam` | interface | Sandbox executor seam. The `sandboxClient` the composed `runAgentRounds` creates |

docs/api/runtime.md

@@ -852,7 +852,7 @@ One flattened node with the journal tree that owns its records.
 
 ###### Inherited from
 
-[`NodeSnapshot`](#nodesnapshot).[`id`](#id-18)
+[`NodeSnapshot`](#nodesnapshot).[`id`](#id-19)
 
 ##### parent?
 
@@ -7610,6 +7610,50 @@ Sequence for synthesized call ids when an event carries none.
 
 ***
 
+### SandboxExecutorToolCall
+
+One tool call retained in a Sandbox executor artifact.
+
+#### Properties
+
+##### id?
+
+> `optional` **id?**: `string`
+
+##### name
+
+> **name**: `string`
+
+##### arguments
+
+> **arguments**: `unknown`
+
+***
+
+### SandboxLeafOut
+
+Parsed output of one Sandbox executor turn.
+
+#### Properties
+
+##### events
+
+> **events**: `SandboxEvent`[]
+
+##### content
+
+> **content**: `string`
+
+##### toolCalls?
+
+> `optional` **toolCalls?**: [`SandboxExecutorToolCall`](#sandboxexecutortoolcall)[]
+
+##### outcome?
+
+> `optional` **outcome?**: `AgentRunOutcome`
+
+***
+
 ### SandboxLineageHandle
 
 **`Experimental`**
@@ -7954,6 +7998,14 @@ nothing" from a transport/FS fault.
 
 **`Experimental`**
 
+##### outcome
+
+> **outcome**: `AgentRunOutcome`
+
+**`Experimental`**
+
+Outcome settled by the public Sandbox tracker after the stream drained.
+
 ##### readError?
 
 > `optional` **readError?**: `string`
@@ -9997,6 +10049,12 @@ Exact underlying transport calls when the Runtime-owned executor reports them.
 
 > `optional` **error?**: [`BackendErrorDetail`](index.md#backenderrordetail)
 
+##### sandboxOutcome?
+
+> `optional` **sandboxOutcome?**: `AgentRunOutcome`
+
+Public Sandbox outcome, when the turn ran through a Sandbox stream or executor.
+
 ***
 
 ### StructuralRolloutPolicy
@@ -14170,19 +14228,6 @@ Online observer of each tool step — the seam a `DetectorMonitor` taps to watch
 
 ***
 
-### SandboxLeafOut
-
-Parsed output of the sandbox leaf: the iteration's raw event stream. What a
- `SandboxSeam.validator` receives as its `output` argument.
-
-#### Properties
-
-##### events
-
-> **events**: `SandboxEvent`[]
-
-***
-
 ### SandboxSteeringOptions
 
 Opt-in configuration for the steerable sandbox worker (`SandboxSeam.steering`). Absent, the
@@ -14254,11 +14299,11 @@ Drive the worker to settlement. `signal` is the spawn-scoped abort handed to `ex
 
 ##### artifact()
 
-> **artifact**(): \{ `outRef`: `string`; `out`: `unknown`; `spent`: [`Spend`](index.md#spend); \} \| `undefined`
+> **artifact**(): \{ `outRef`: `string`; `out`: `unknown`; `verdict?`: `DefaultVerdict`; `spent`: [`Spend`](index.md#spend); \} \| `undefined`
 
 ###### Returns
 
-\{ `outRef`: `string`; `out`: `unknown`; `spent`: [`Spend`](index.md#spend); \} \| `undefined`
+\{ `outRef`: `string`; `out`: `unknown`; `verdict?`: `DefaultVerdict`; `spent`: [`Spend`](index.md#spend); \} \| `undefined`
 
 ##### teardown()
 
@@ -18898,6 +18943,12 @@ Stable name of the `AgentRunSpec` that produced this iteration.
 
 > `optional` **error?**: `Error`
 
+##### sandboxOutcome?
+
+> `optional` **sandboxOutcome?**: `AgentRunOutcome`
+
+Public Sandbox outcome settled after the complete event stream.
+
 ##### events
 
 > **events**: `SandboxEvent`[]
@@ -24679,54 +24730,6 @@ promise is cached so concurrent fanout branches share one round-trip.
 
 ***
 
-### sandboxEventFailure()
-
-> **sandboxEventFailure**(`event`): `string` \| `undefined`
-
-Return the terminal failure carried by one Sandbox event.
-
-Sandbox transports report execution failure in-band: commonly an `error`
-event followed by a synthetic `done`. Treating the iterable as successfully
-drained therefore turns a provider/configuration failure into a completed
-empty artifact.
-
-The decoder reads a failure from exactly two places, so that a mid-stream
-event describing its OWN failure cannot fail the execution: an `error`-typed
-event, and a terminal event (`done`/`result`/`final`) whose `success` is
-`false` or whose status is a failed one. A failing tool part therefore stays
-a tool result, which is what [mapSandboxToolEvent](#mapsandboxtoolevent) already projects it
-to.
-
-#### Parameters
-
-##### event
-
-`SandboxEvent`
-
-#### Returns
-
-`string` \| `undefined`
-
-***
-
-### assertSandboxEventSucceeded()
-
-> **assertSandboxEventSucceeded**(`event`): `void`
-
-Fail the live execution instead of allowing an in-band failure to become an empty success.
-
-#### Parameters
-
-##### event
-
-`SandboxEvent`
-
-#### Returns
-
-`void`
-
-***
-
 ### sandboxEventServedBackend()
 
 > **sandboxEventServedBackend**(`event`): [`SandboxServedBackend`](#sandboxservedbackend) \| `undefined`
@@ -24791,8 +24794,8 @@ the event carries usage/cost data. Returns `undefined` for non-cost events
 so the kernel can iterate the full stream without branching.
 
 Pure by contract: it never throws on a failed run. The terminal truth
-boundary is [assertSandboxEventSucceeded](#assertsandboxeventsucceeded), applied by the two paths
-that SETTLE an execution. Post-hoc readers — [sumSandboxUsage](#sumsandboxusage), the
+boundary is the public Sandbox outcome tracker, applied after the complete
+stream. Post-hoc readers — [sumSandboxUsage](#sumsandboxusage), the
 analyst trace store, the chat projection — must stay able to read a failed
 turn's events, which is when reading them matters most.
 

docs/canonical-api.md

@@ -4,11 +4,11 @@
 Generated signatures and the complete export list live in docs/api/.
 Run pnpm docs:freshness after editing this file. -->
 
-> **Version 0.142.3.**
+> **Version 0.143.0.**
 > [`docs/api/primitive-catalog.md`](./api/primitive-catalog.md) lists every export and import path.
 > `agent-eval` must satisfy `>=0.149.0 <0.150.0`.
-> `sandbox` must satisfy `>=0.29.0 <0.31.0`.
-> Portable profile and tool-part types come from `@tangle-network/agent-interface` `^1.1.0`.
+> `sandbox` must satisfy `>=0.31.0 <0.32.0`.
+> Portable profile and tool-part types come from `@tangle-network/agent-interface` `^1.3.0`.
 >
 > **`./kernel` is the execution kernel**: `package.json` maps it to `src/runtime/index.ts`. Everything below labelled `/kernel` lives there — the recursive atom (`Scope`/`Supervisor`), the executor registry, budget conservation, the finalizer seam, analyst wiring, and the round-synchronous loop.
 >

examples/agentic-data-creation/offline-fixtures.ts

@@ -121,6 +121,7 @@ export function challengerClient(): SandboxClient {
           data: { model: 'offline-challenger', tokensIn: 320, tokensOut: 90, costUsd: 0.0006 },
         },
         { type: 'result', data: { result: example } },
+        { type: 'done', data: { outcome: { type: 'completed' } } },
       ]
     },
   })
@@ -152,6 +153,7 @@ export function solverClient(strength: 'weak' | 'strong'): SandboxClient {
           },
         },
         { type: 'result', data: { result: { answer } } },
+        { type: 'done', data: { outcome: { type: 'completed' } } },
       ]
     },
   })

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.142.3",
+  "version": "0.143.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": {
@@ -174,8 +174,8 @@
   "packageManager": "pnpm@11.17.0",
   "peerDependencies": {
     "@tangle-network/agent-eval": ">=0.149.0 <0.150.0",
-    "@tangle-network/agent-interface": "^1.1.0",
-    "@tangle-network/sandbox": ">=0.29.0 <0.31.0"
+    "@tangle-network/agent-interface": "^1.3.0",
+    "@tangle-network/sandbox": ">=0.31.0 <0.32.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {