@tangle-network/agent-runtime 0.142.3 → 0.153.1

package/dist/{types-_7w24mMg.d.ts → types-BPQhQRrC.d.ts}

@@ -1,8 +1,310 @@
-import { J as AgentTaskStatus, U as AgentRuntimeEvent, at as RuntimeStreamEvent, v as LoopTokenUsage, y as LoopTraceEmitter } from "./types-DZrBoBpN.js";
+import { J as AgentTaskStatus, U as AgentRuntimeEvent, at as RuntimeStreamEvent, v as LoopTokenUsage, y as LoopTraceEmitter } from "./types-DeX8ibLc.js";
 import { l as RuntimeHooks } from "./runtime-hooks-Bj6wJHlH.js";
-import { AgentProfile, Sha256Digest } from "@tangle-network/agent-interface";
+import { AgentExactRunControlRef, AgentInteractiveSession, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionRef, AgentInteractiveSessionStart, AgentNativeContextContinuationOptions, AgentNativeContextContinuationResult, AgentProfile, AgentSessionStatus, ChildTaskEvent, InteractionAcknowledgement, InteractionRequest, InteractionResponseCommand, NativeContextBoundaryProof, NativeContextContinuationRequest, NativeContextContinuationTurn, RuntimeEventEnvelope, Sha256Digest } from "@tangle-network/agent-interface";
 import { ControlEvalResult, DefaultVerdict, KnowledgeReadinessReport, KnowledgeRequirement, ToolSpan } from "@tangle-network/agent-eval";
 import { BackendType } from "@tangle-network/sandbox";
+import { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentProvider, AgentTurnInput, AgentTurnResult, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+//#region src/runtime/retained-run-types.d.ts
+/** Cursor plus runtime sequence needed to continue one ordered replay. @stable */
+interface RetainedRunReplayPoint {
+  readonly cursor: string;
+  readonly sequence: number;
+}
+/** Options for replaying canonical events strictly after a saved point. @stable */
+interface RetainedRunEventOptions {
+  readonly after?: RetainedRunReplayPoint;
+  readonly signal?: AbortSignal;
+}
+/** Effect recorded for one retained control operation. @stable */
+type RetainedRunEffect = 'cancel_requested' | 'cancelled' | 'not_live' | 'unknown';
+/** Stable status snapshot for a retained run. @stable */
+interface RetainedRunSnapshot {
+  readonly runId: string;
+  readonly controlRef: AgentExactRunControlRef;
+  readonly status: AgentSessionStatus | null;
+  readonly effect: RetainedRunEffect;
+  readonly observedAt: string;
+  readonly reason?: string;
+  readonly signal?: string;
+}
+/** Durable acknowledgement state for one retained control operation. @stable */
+interface RetainedRunCancellation {
+  readonly operationId: string;
+  readonly requestDigest: Sha256Digest;
+  readonly status: 'accepted' | 'replayed' | 'conflict' | 'unknown';
+  readonly effect: RetainedRunEffect;
+  readonly snapshot: RetainedRunSnapshot;
+  readonly reason?: string;
+  readonly signal?: string;
+}
+/** Options for an idempotent retained cancellation. @stable */
+interface RetainedRunCancelOptions {
+  readonly operationId: string;
+  readonly reason?: string;
+  readonly signal?: AbortSignal;
+}
+/** Runtime controls plus the exact user turn bound into a continuation request. @stable */
+type NativeContextContinuationInput = NativeContextContinuationTurn & Omit<AgentNativeContextContinuationOptions, 'turn'>;
+/** Result of one verified same-session continuation. @stable */
+type NativeContextContinuationExecution = AgentNativeContextContinuationResult;
+/** Reconstructable control of one provider-retained run. @stable */
+interface RetainedRunHandle {
+  readonly controlRef: AgentExactRunControlRef;
+  /** Capabilities measured from the exact environment that owns this run. */
+  readonly capabilities: AgentEnvironmentCapabilities;
+  status(options?: {
+    waitMs?: number;
+    signal?: AbortSignal;
+  }): Promise<RetainedRunSnapshot>;
+  events(options?: RetainedRunEventOptions): AsyncIterable<RuntimeEventEnvelope>;
+  result(): Promise<AgentTurnResult>;
+  respondToInteraction(command: InteractionResponseCommand, options?: {
+    signal?: AbortSignal;
+  }): Promise<InteractionAcknowledgement>;
+  contextBoundary(options?: {
+    signal?: AbortSignal;
+  }): Promise<NativeContextBoundaryProof | null>;
+  continueNative(request: NativeContextContinuationRequest, turn: NativeContextContinuationInput): Promise<NativeContextContinuationExecution>;
+  cancel(options: RetainedRunCancelOptions): Promise<RetainedRunCancellation>;
+}
+/**
+ * Sanitized headless intent durable before environment creation.
+ *
+ * The request digest binds the public create and turn material without
+ * retaining secret values. The original start material is required to replay
+ * this record after a process crash.
+ * @stable
+ */
+interface RetainedRunIntentAdmission {
+  readonly phase: 'intent';
+  readonly provider: string;
+  readonly idempotencyKey: string;
+  readonly turnId: string;
+  readonly sessionId: string;
+  readonly executionId: string;
+  readonly runId: string;
+  readonly requestedProfileDigest: Sha256Digest;
+  readonly requestDigest: Sha256Digest;
+}
+/** Recovery coordinates durable after environment creation and before dispatch. @stable */
+interface RetainedRunEnvironmentAdmission {
+  readonly phase: 'environment';
+  readonly provider: string;
+  readonly environmentId: string;
+  readonly idempotencyKey: string;
+  readonly turnId: string;
+  /** Caller-supplied or runtime-minted; always the identity the dispatch will request. */
+  readonly sessionId: string;
+  /** Caller-supplied or runtime-minted; always the identity the dispatch will request. */
+  readonly executionId: string;
+}
+/** The verified exact reference, durable before the start promise resolves. @stable */
+interface RetainedRunDispatchedAdmission {
+  readonly phase: 'dispatched';
+  readonly controlRef: AgentExactRunControlRef;
+  readonly idempotencyKey: string;
+  readonly turnId: string;
+}
+/**
+ * Sanitized intent durable before an interactive environment create begins.
+ *
+ * The digest covers the public start and create material without retaining that
+ * material. It never carries environment variables, secret values, or provider
+ * options. The replay input supplies private values after this check.
+ * @stable
+ */
+interface RetainedInteractiveIntentAdmission {
+  readonly phase: 'interactive_intent';
+  readonly provider: string;
+  readonly idempotencyKey: string;
+  readonly interactiveIdempotencyKey: string;
+  readonly sessionId: string;
+  readonly executionId: string;
+  readonly runId: string;
+  readonly requestedProfileDigest: Sha256Digest;
+  readonly requestDigest: Sha256Digest;
+}
+/** Exact interactive start request durable after environment creation. @stable */
+interface RetainedInteractiveEnvironmentAdmission {
+  readonly phase: 'interactive_environment';
+  readonly provider: string;
+  readonly environmentId: string;
+  readonly idempotencyKey: string;
+  readonly interactiveIdempotencyKey: string;
+  readonly request: AgentInteractiveSessionStart;
+}
+/** Provider-issued interactive process reference durable before start returns. @stable */
+interface RetainedInteractiveStartedAdmission {
+  readonly phase: 'interactive_started';
+  readonly idempotencyKey: string;
+  readonly interactiveIdempotencyKey: string;
+  readonly ref: AgentInteractiveSessionRef;
+}
+/** Durable records for one exact native coding-agent process. @stable */
+type RetainedInteractiveAdmission = RetainedInteractiveIntentAdmission | RetainedInteractiveEnvironmentAdmission | RetainedInteractiveStartedAdmission;
+/** One detached-run admission record the runtime persists before creation or dispatch proceeds. @stable */
+type RetainedRunAdmission = RetainedRunIntentAdmission | RetainedRunEnvironmentAdmission | RetainedRunDispatchedAdmission;
+/**
+ * Awaited durability hook for retained admission records.
+ *
+ * The runtime blocks after the pre-create intent, environment creation, and
+ * provider work until the hook resolves. No retained run becomes caller-visible
+ * before its exact recovery record is durable. A rejection keeps provider state
+ * for recovery when provider work has already started.
+ *
+ * @stable
+ */
+type RetainedRunAdmissionHook = (admission: RetainedRunAdmission) => Promise<void>;
+/** Environment, turn, and optional identity needed to replay one retained start. @stable */
+interface RetainedRunStartMaterial {
+  readonly environment: CreateAgentEnvironmentInput & {
+    idempotencyKey: string;
+  };
+  readonly turn: AgentTurnInput & {
+    turnId: string;
+  };
+  /**
+   * Explicit dispatch coordinates. When omitted, the runtime mints
+   * deterministic coordinates from `(environment.idempotencyKey, turn.turnId)`
+   * so every process derives the same values.
+   */
+  readonly identity?: {
+    readonly sessionId: string;
+    readonly executionId: string;
+  };
+}
+/** A retained start is retry-safe only when environment and turn keys are explicit. @stable */
+interface StartRetainedRunOptions extends RetainedRunStartMaterial {
+  readonly provider: AgentEnvironmentProvider;
+  /** A previously persisted intent used to replay the exact create operation. */
+  readonly intent?: RetainedRunIntentAdmission;
+  readonly onAdmission: RetainedRunAdmissionHook;
+  readonly now?: () => number;
+}
+/** A fresh retained session inside a provider environment that already exists. @stable */
+interface StartRetainedRunInEnvironmentOptions {
+  readonly provider: AgentEnvironmentProvider;
+  readonly environment: {
+    /** Stable provider environment identifier used by `provider.get`. */
+    readonly id: string;
+    /** Original environment key. The provider must return the matching retained metadata. */
+    readonly idempotencyKey: string;
+  };
+  readonly turn: AgentTurnInput & {
+    turnId: string;
+  };
+  /**
+   * Explicit fresh-session coordinates. When omitted, the runtime mints them
+   * from `(environment.idempotencyKey, turn.turnId)`.
+   */
+  readonly identity?: {
+    readonly sessionId: string;
+    readonly executionId: string;
+  };
+  readonly onAdmission: RetainedRunAdmissionHook;
+  readonly now?: () => number;
+}
+/** Inputs sufficient to rebuild a control client in a new process. @stable */
+interface ReconnectRetainedRunOptions {
+  readonly provider: AgentEnvironmentProvider;
+  readonly controlRef: AgentExactRunControlRef;
+  readonly now?: () => number;
+}
+/** Recover a headless start after its pre-create intent was persisted. @stable */
+interface RecoverRetainedRunIntentOptions {
+  readonly provider: AgentEnvironmentProvider;
+  readonly admission: RetainedRunIntentAdmission;
+  /** The exact original environment, turn, and optional identity material. */
+  readonly replay: RetainedRunStartMaterial;
+  readonly onAdmission: RetainedRunAdmissionHook;
+  readonly now?: () => number;
+}
+/**
+ * Pre-dispatch admission coordinates for one recovery attempt.
+ *
+ * A `phase: 'environment'` admission record carries these fields, so a caller
+ * can pass that record after a crash before the dispatched record landed.
+ *
+ * @stable
+ */
+interface RecoverRetainedRunOptions {
+  readonly provider: AgentEnvironmentProvider;
+  readonly environmentId: string;
+  readonly sessionId: string;
+  readonly executionId: string;
+  readonly now?: () => number;
+}
+/**
+ * Outcome of one recovery attempt from pre-dispatch admission coordinates.
+ *
+ * `not_found`: the provider no longer holds the environment; nothing remains
+ * to destroy. `recovered`: the provider self-identified the session with a
+ * strict exact reference matching the recorded coordinates. `unverifiable`:
+ * the environment exists but the provider cannot self-identify the session;
+ * never destroy on this outcome — keep the environment, retry
+ * `reconnectRetainedRun` with a dispatched admission record, or inspect it
+ * with provider-native tools.
+ *
+ * @stable
+ */
+type RecoverRetainedRunResult = {
+  readonly outcome: 'recovered';
+  readonly handle: RetainedRunHandle;
+} | {
+  readonly outcome: 'not_found';
+} | {
+  readonly outcome: 'unverifiable';
+  readonly environment: AgentEnvironment;
+};
+//#endregion
+//#region src/runtime/retained-interactive-types.d.ts
+/** Environment and exact AgentProfile used to start one native coding-agent process. @stable */
+type RetainedInteractiveEnvironmentInput = Omit<CreateAgentEnvironmentInput, 'idempotencyKey' | 'profile' | 'signal'> & {
+  readonly idempotencyKey: string;
+  readonly profile: AgentProfile;
+};
+/** Material used to create and start one native coding-agent TUI. @stable */
+interface RetainedInteractiveStartMaterial {
+  readonly environment: RetainedInteractiveEnvironmentInput;
+  readonly interactiveIdempotencyKey: string;
+  readonly initialPrompt?: string;
+  readonly cwd?: string;
+  readonly cols?: number;
+  readonly rows?: number;
+}
+/** Start one retry-safe native coding-agent TUI in a new environment. @stable */
+interface StartRetainedInteractiveRunOptions extends RetainedInteractiveStartMaterial {
+  readonly provider: AgentEnvironmentProvider;
+  /** A previously persisted intent used to replay the exact create operation. */
+  readonly intent?: RetainedInteractiveIntentAdmission;
+  readonly onAdmission: RetainedInteractiveAdmissionHook;
+  readonly signal?: AbortSignal;
+}
+/** Persist each exact interactive record before the runtime proceeds. @stable */
+type RetainedInteractiveAdmissionHook = (admission: RetainedInteractiveAdmission) => Promise<void>;
+/** Reconstruct one exact provider-owned native coding-agent process. @stable */
+interface ReconnectRetainedInteractiveRunOptions {
+  readonly provider: AgentEnvironmentProvider;
+  readonly ref: AgentInteractiveSessionRef;
+  readonly signal?: AbortSignal;
+}
+/** Recover a start after a pre-create crash or a lost provider response. @stable */
+interface RecoverRetainedInteractiveRunOptions {
+  readonly provider: AgentEnvironmentProvider;
+  readonly admission: RetainedInteractiveIntentAdmission | RetainedInteractiveEnvironmentAdmission;
+  /** Required when recovering from an intent before an environment existed. */
+  readonly replay?: RetainedInteractiveStartMaterial;
+  readonly onAdmission: RetainedInteractiveAdmissionHook;
+  readonly signal?: AbortSignal;
+}
+/** Exact interactive process controls plus measured environment capabilities. @stable */
+interface RetainedInteractiveRunHandle extends AgentInteractiveSession {
+  readonly capabilities: AgentEnvironmentCapabilities;
+  sendPrompt(command: AgentInteractiveSessionPromptCommand, options?: {
+    signal?: AbortSignal;
+  }): Promise<AgentInteractiveSessionPromptAcknowledgement>;
+}
+//#endregion
 //#region src/runtime/supervise/progress.d.ts
 /** How long a worker may produce no metered activity before a `progress()` read calls it stalled.
  *  Deliberately generous: a coding harness routinely spends minutes inside one tool call, and a
@@ -817,6 +1119,23 @@ interface Executor<Out> {
    * this runtime (the settle-time analyzers still work).
    */
   traceSource?(): TraceSource | undefined;
+  /**
+   * The exact interactive process this worker runs in, when its execution was started in an
+   * attachable terminal. Read through `Scope.interactive`; synchronous and side-effect free, and
+   * it must not throw. Omitting it is the honest answer for every headless executor: omission
+   * reads as `executor-exposes-no-interactive-session`, never as an empty handle.
+   */
+  interactive?(): WorkerInteractiveSession;
+  /**
+   * Optional provider-neutral CANCELLATION, distinct from `teardown`: it asks the backend to stop
+   * the work and reports what the backend acknowledged, so a caller never has to read a local
+   * iterator abort as remote acceptance. `teardown` remains the resource verb — it releases what
+   * this process holds and says nothing about remote compute or billing.
+   *
+   * An executor that cannot ask its backend anything omits this method; one whose backend has no
+   * cancel operation implements it and answers `unknown` with the reason in `detail`.
+   */
+  cancel?(request: ExecutorCancellationRequest): Promise<ExecutorCancellation>;
   /**
    * Tear the executor's resources down. `grace` mirrors the OTP shutdown spec
    * (`'brutalKill'` = immediate, a number = ms grace, `'infinity'` = await clean exit).
@@ -865,6 +1184,61 @@ type WorkerTraceEvidence = {
   readonly status: 'unavailable';
   readonly reason: WorkerTraceUnavailableReason;
 };
+/** Why Runtime cannot hand a caller the exact interactive process one worker runs in. */
+type WorkerInteractiveUnavailableReason =
+/** No child of this scope carries that node id. */
+'unknown-node' |
+/** The child settled, was cancelled, or is a wait-state node: there is no process to attach to. */
+'not-live' |
+/** The worker runs headless. Its executor exposes no interactive session, so there is no
+ *  terminal — a headless execution is never converted into an attachment. */
+'executor-exposes-no-interactive-session' |
+/** The executor is backed by a runner whose provider publishes no interactive-session contract
+ *  (the local CLI Bridge today), so no process can be attached to even though one is running. */
+'provider-has-no-interactive-contract' |
+/** The runner supports interactive sessions but this execution was not started in one. */
+'interactive-session-not-started';
+/**
+ * One worker's attachable process, or the named reason there is none.
+ *
+ * `available` carries the exact `RetainedInteractiveRunHandle` bound to THAT child's admitted
+ * execution: input, resize, ordered replay, detach, and an acknowledged close all check every
+ * provider answer against the session reference, so a second process that merely resumes the same
+ * conversation cannot present itself as this one. `unavailable` names why, and is never a handle.
+ */
+type WorkerInteractiveSession = {
+  readonly status: 'available';
+  readonly handle: RetainedInteractiveRunHandle;
+} | {
+  readonly status: 'unavailable';
+  readonly reason: WorkerInteractiveUnavailableReason;
+};
+/** One cancellation ask. `operationId` makes the request idempotent per attempt, exactly as the
+ *  worker and retained layers already key their cancellations. */
+interface ExecutorCancellationRequest {
+  readonly operationId: string;
+  readonly reason?: string;
+  /** Deadline for the acknowledgement itself. Its expiry produces `unknown`, never a claim. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * What a backend acknowledged about one cancellation ask.
+ *
+ * `status` is the backend's answer to the ASK; `effect` is what is now known about the RUN, in the
+ * one cancellation vocabulary the worker and retained layers already use. A local abort with no
+ * provider acknowledgement is `{ status: 'unknown', effect: 'cancel_requested' }` — never
+ * `accepted`.
+ */
+interface ExecutorCancellation {
+  readonly status: 'accepted' | 'rejected' | 'already-terminal' | 'unknown';
+  readonly effect: RetainedRunEffect;
+  /** When the acknowledgement was observed, ISO-8601. */
+  readonly observedAt: string;
+  /** Why the backend answered this way — required reading for `unknown`. */
+  readonly detail?: string;
+  /** Backend-native proof, persisted by digest only. */
+  readonly evidence?: unknown;
+}
 /** Split used by a recursive executor when journaled child work differs from the full amount
  * reconciled against its parent reservation. */
 interface ExecutorAccounting {
@@ -888,6 +1262,52 @@ interface ExecutorResult<Out> {
  * therefore remains unknown through live metering and terminal reconciliation instead of becoming
  * a fabricated zero.
  */
+/**
+ * One tool call retained in an executor artifact. Every Runtime-owned executor reports this exact
+ * shape, so `streamAgentTurn` projects terminal tool activity through one reader instead of a
+ * per-backend parser. `arguments` holds the captured argument value; an empty object means the
+ * source reported the call without its arguments.
+ */
+interface ExecutorToolCall {
+  readonly id?: string;
+  readonly name: string;
+  readonly arguments: unknown;
+}
+/**
+ * Live output observed while an executor runs, in Runtime's own vocabulary. It carries what the
+ * backend produced — text, reasoning, tool activity, an interaction request — and never carries
+ * accounting: tokens and dollars stay on the `tokens`/`cost` channels, so a progress event can
+ * never meter a budget.
+ */
+type ExecutorProgressEvent = {
+  readonly kind: 'text_delta';
+  readonly text: string;
+} | {
+  readonly kind: 'reasoning_delta';
+  readonly text: string;
+} | {
+  readonly kind: 'tool_call';
+  readonly toolName: string;
+  readonly toolCallId?: string;
+  readonly args?: unknown;
+} | {
+  readonly kind: 'tool_result';
+  readonly toolName: string;
+  readonly toolCallId?: string;
+  readonly result?: unknown;
+} | {
+  readonly kind: 'interaction';
+  readonly request: InteractionRequest;
+} | {
+  /**
+   * One update of a provider-native child task — a subagent or delegated task the runner
+   * started inside this run. It is the Interface event verbatim, so a client rebuilds the
+   * child tree from provider identity (`childId`, `parentChildId`, `sourceEventId`) instead
+   * of inferring children from tool names or transcript order.
+   */
+  readonly kind: 'child_task';
+  readonly event: ChildTaskEvent;
+};
 type UsageEvent = {
   kind: 'tokens';
   /** Known token subtotal. When false, these counts are only the observed/estimated floor. */
@@ -909,18 +1329,33 @@ type UsageEvent = {
   cacheBreakdownKnown?: false;
 } | {
   kind: 'cost';
-  /** Known dollar subtotal. When false, `usd` must not be treated as total cost. */
-  usdKnown?: false;
+  /** A provider or billing receipt covers this amount in full. */
+  usdKnown: true;
+  usd: number;
+  /** Which receipt proves it. A number without one of these cannot claim `usdKnown: true`. */
+  provenance: 'provider-receipt' | 'billing-receipt';
+} | {
+  kind: 'cost';
+  /** No receipt covers this work, so `usd` is an observed floor, never the total charge. */
+  usdKnown: false;
   usd: number;
   /**
    * The part of `usd` this runtime priced from a model catalog because no provider receipt
-   * covered the work. Requires `usdKnown: false` — a catalog price approximates what a
-   * provider would bill and never measures what it did.
+   * covered the work. A catalog price approximates what a provider would bill and never
+   * measures what it did.
    *
-   * Absence means this runtime priced nothing here, NOT that `usd` is a receipt. `usdKnown`
-   * is what says whether a dollar figure is measured.
+   * Absence means this runtime priced nothing here, NOT that `usd` is a receipt.
    */
   usdEstimated?: number;
+  /**
+   * Why the amount is not measured: a local catalog price, or nothing captured at all —
+   * including a provider that reported a number with no receipt behind it.
+   */
+  provenance: 'catalog-estimate' | 'uncaptured';
+} | {
+  /** Observed output, not accounting. Meters ignore it; the turn projection publishes it. */
+  kind: 'progress';
+  progress: ExecutorProgressEvent;
 } | {
   kind: 'iteration';
 };
@@ -1351,6 +1786,23 @@ interface Scope<Out> {
   /** The live tool-call trace of one child when its executor exposes one (`Executor.traceSource`),
    *  for running the online detector panel over a RUNNING worker. `undefined` otherwise. */
   traceSource(nodeId: NodeId): TraceSource | undefined;
+  /**
+   * Attach a human terminal to the exact process ONE child is running in.
+   *
+   * Returns that child's `RetainedInteractiveRunHandle` when its executor holds an interactive
+   * session — the caller then types, resizes, detaches, reconnects, and closes against the same
+   * admitted execution, with one ordered output history. Every other worker returns an explicit
+   * `unavailable` reason: a headless run, a runner whose provider publishes no interactive
+   * contract, and an unknown or settled node are each distinguishable, and none of them is ever
+   * converted into a fake attachment.
+   */
+  interactive(nodeId: NodeId): WorkerInteractiveSession;
+  /**
+   * Ask one child's backend to stop, and report what it acknowledged. It delegates to
+   * `Executor.cancel` when the runtime has one; otherwise the child is aborted locally and the
+   * answer is `unknown`, never `accepted`. Resource release still belongs to teardown.
+   */
+  cancel(nodeId: NodeId, request: ExecutorCancellationRequest): Promise<ExecutorCancellation>;
   /** This scope's abort signal — aborted when the run is cancelled, a breaker trips, the pool
    *  is exhausted, or a parent scope cascades. A long-running driver `act` over this scope reads
    *  it to break promptly (the conserved pool + driver-stop are the other bounds). A nested
@@ -1401,12 +1853,23 @@ interface Scope<Out> {
     reservedTokens: number;
   }>;
   /** One tree-wide view of simultaneous spawned work. Every nested scope reads the same counter;
-   *  the root agent itself is not a spawned worker. `freeSlots` is `null` when no limit is set. */
+   *  the root agent itself is not a spawned worker. `freeSlots` is `null` when no limit is set.
+   *  `unconfirmed` NAMES the settled children whose executor teardown was never acknowledged —
+   *  the nodes still holding a capacity slot. Empty on every healthy run. */
   readonly workerCapacity: Readonly<{
     live: number;
     freeSlots: number | null;
+    unconfirmed: ReadonlyArray<UnconfirmedTeardown>;
   }>;
 }
+/** One settled child whose executor teardown was never acknowledged: the run cannot prove the
+ *  resource is gone, so its capacity slot stays charged. Named so an operator can act on it. */
+interface UnconfirmedTeardown {
+  readonly id: NodeId;
+  readonly label: string;
+  readonly runtime: Runtime;
+  readonly status: NodeStatus;
+}
 /**
  * The committed work a resumed run inherits from its journal. `settled` is the replayed
  * `Settled[]` (cursor-ordered, rehydrated from the blob store by `replaySpawnTree`); `view`
@@ -1510,6 +1973,11 @@ type SpawnEvent = {
   ownedTreeRoot?: NodeId;
   /** Exact profile/task digests plus trusted candidate/campaign attribution when available. */
   identity?: NodeExecutionIdentity;
+  /** `ResultBlobStore` key holding the AUTHORED child `AgentProfile` this spawn ran under.
+   *  Distinct from `identity.profileDigest`: that is the canonical AgentProfile digest, which
+   *  names the agent, while this is the blob store's own content address, which retrieves its
+   *  bytes. Absent on records written before the body was persisted. */
+  profileRef?: string;
   seq: number;
   at: string;
 } | {
@@ -1592,6 +2060,20 @@ type SpawnEvent = {
   providerModel?: ProviderModelExecutionEvidence;
   seq: number;
   at: string;
+} | {
+  /** A settled child whose executor teardown was never acknowledged: the run cannot prove the
+   *  resource is gone, so its capacity slot stays charged for the rest of the run. Recorded so
+   *  the leak is durable evidence about the EXECUTOR rather than a cause of run failure.
+   *  Informational: replay, `materializeTreeView`, and cost readers skip it, and its `seq` lives
+   *  outside the cursor-uniqueness namespace. */
+  kind: 'teardown-unconfirmed';
+  id: NodeId;
+  label: string;
+  runtime: Runtime;
+  /** The node's terminal status when the barrier read it. */
+  status: NodeStatus;
+  seq: number;
+  at: string;
 } | {
   /** One GRAPH-EDGE traversal (`runGraph`): what the runtime actually DELIVERED across a
    *  delegates/analyzes edge, with byte counts — the observability that makes an edge's
@@ -1820,6 +2302,11 @@ type SupervisedResult<Out> = {
   readonly rootProviderModel?: RootProviderModelEvidence;
   /** Runtime-owned provider evidence reduced across the complete journal forest. */
   readonly providerModel?: ProviderModelExecutionEvidence;
+  /** Settled children whose executor teardown was never acknowledged — the resources this run
+   *  could not prove destroyed. Their capacity slots stay charged for the rest of the run, and
+   *  each is journaled as a `teardown-unconfirmed` event. Present exactly when non-empty; a
+   *  healthy run never carries it. */
+  teardownUnconfirmed?: ReadonlyArray<UnconfirmedTeardown>;
   /** The journaled nodes whose usage accounting is incomplete — the named gaps behind a
    *  `false` `tokensKnown`/`usdKnown` on `spentTotal`. Present exactly when non-empty. */
   spendGaps?: ReadonlyArray<SpendGap>;
@@ -1853,6 +2340,11 @@ type SupervisedResult<Out> = {
   readonly rootProviderModel?: RootProviderModelEvidence;
   /** Runtime-owned provider evidence reduced across the complete journal forest. */
   readonly providerModel?: ProviderModelExecutionEvidence;
+  /** Settled children whose executor teardown was never acknowledged — the resources this run
+   *  could not prove destroyed. Their capacity slots stay charged for the rest of the run, and
+   *  each is journaled as a `teardown-unconfirmed` event. Present exactly when non-empty; a
+   *  healthy run never carries it. */
+  teardownUnconfirmed?: ReadonlyArray<UnconfirmedTeardown>;
   /** The journaled nodes whose usage accounting is incomplete — the named gaps behind a
    *  `false` `tokensKnown`/`usdKnown` on `spentTotal`. Present exactly when non-empty. */
   spendGaps?: ReadonlyArray<SpendGap>;
@@ -1880,6 +2372,11 @@ type SupervisedResult<Out> = {
   readonly rootProviderModel?: RootProviderModelEvidence;
   /** Runtime-owned provider evidence reduced across the complete journal forest. */
   readonly providerModel?: ProviderModelExecutionEvidence;
+  /** Settled children whose executor teardown was never acknowledged — the resources this run
+   *  could not prove destroyed. Their capacity slots stay charged for the rest of the run, and
+   *  each is journaled as a `teardown-unconfirmed` event. Present exactly when non-empty; a
+   *  healthy run never carries it. */
+  teardownUnconfirmed?: ReadonlyArray<UnconfirmedTeardown>;
   /** The journaled nodes whose usage accounting is incomplete — the named gaps behind a
    *  `false` `tokensKnown`/`usdKnown` on `spentTotal`. Present exactly when non-empty. */
   spendGaps?: ReadonlyArray<SpendGap>;
@@ -1932,5 +2429,5 @@ interface WidenGate<Out> {
   readonly judgeExempt?: boolean;
 }
 //#endregion
-export { WaitOpts as $, WaitSpec as $t, ResumedWork as A, exportEvalRuns as At, SpawnOpts as B, RuntimeTelemetryOptions as Bt, NodeStatus as C, OtelSpan as Ct, Restart as D, buildRuntimeEventOtelSpans as Dt, ProviderModelExecutionEvidence as E, buildLoopSpanNodes as Et, Runtime as F, toOtelAttributes as Ft, SpendGap as G, sanitizeAgentRuntimeEvent as Gt, SpawnRejection as H, SanitizedKnowledgeRequirement as Ht, Scope as I, RuntimeEventCollector as It, Supervisor as J, PendingWait as Jt, SteerableRootHandle as K, sanitizeKnowledgeReadinessReport as Kt, Settled as L, RuntimeStreamEventCollector as Lt, RootMaterialization as M, loopEventToOtelSpan as Mt, RootProviderModelEvidence as N, padSpanId as Nt, ResultBlobStore as O, createOpenInferenceFileExporter as Ot, RootSignal as P, padTraceId as Pt, UsageEvent as Q, WaitRejection as Qt, SpawnEvent as R, RuntimeStreamEventSink as Rt, NodeSnapshot as S, OtelExporter as St, ProviderModelAttemptEvidence as T, buildLoopOtelSpans as Tt, Spend as U, createRuntimeEventCollector as Ut, SpawnPrior as V, SanitizedKnowledgeReadinessReport as Vt, SpendChannel as W, createRuntimeStreamEventCollector as Wt, TreeView as X, WaitProbe as Xt, SupervisorOpts as Y, WaitOutcome as Yt, UnknownMaterializationReason as Z, WaitProbeRegistry as Zt, MaterializedExecutionIdentity as _, ScopeProgressInput as _n, EvalRunsExportResult as _t, DefaultVerdict as a, waitUntil as an, readWorkerTraceContext as at, NodeExecutionIdentity as b, readWorkerProgress as bn, OtelAttribute as bt, ExecutorAccounting as c, ToolStepInput as cn, workerTraceSeamKey as ct, ExecutorFactory as d, decodeToolPart as dn, mergeTraceEnv as dt, createWaitProbes as en, WidenGate as et, ExecutorMaterialization as f, sandboxSessionTraceSource as fn, readTraceContextFromEnv as ft, Handle as g, ExecutorProgress as gn, EvalRunsExportConfig as gt, ExecutorResult as h, DEFAULT_STALL_AFTER_MS as hn, EvalRunGeneration as ht, Budget as i, validateWaitSpec as in, WorkerTraceSeamCarrier as it, RootHandle as j, generateSpanId as jt, ResumedKeyState as k, createOtelExporter as kt, ExecutorContext as l, TraceSource as ln, TraceContext as lt, ExecutorRegistry as m, ActivityNote as mn, EvalRunEvent as mt, AgentExecutionRef as n, pollFor as nn, WorkerTraceUnavailableReason as nt, ExecutionBindingReceipt as o, SessionMessageLike as on, workerTraceEnv as ot, ExecutorNodeContext as p, ActivityLog as pn, traceContextToEnv as pt, SupervisedResult as q, sanitizeRuntimeStreamEvent as qt, AgentSpec as r, timerAt as rn, WorkerTraceResolver as rt, Executor as s, SessionTraceBox as sn, workerTraceHeaders as st, Agent as t, isWaitOutcome as tn, WorkerTraceEvidence as tt, ExecutorExecutionBinding as u, createPushTraceSource as un, createPropagatingTraceEmitter as ut, MaterializedModelIdentity as v, WorkerProgress as vn, INTELLIGENCE_WIRE_VERSION as vt, ProfileMaterializationReceipt as w, RuntimeEventOtelOptions as wt, NodeId as x, OtelExportConfig as xt, NoWinnerError as y, createActivityLog as yn, LoopSpanNode as yt, SpawnJournal as z, RuntimeStreamEventSummary as zt };
-//# sourceMappingURL=types-_7w24mMg.d.ts.map
+export { SupervisorOpts as $, RetainedRunHandle as $n, sanitizeKnowledgeReadinessReport as $t, ProviderModelExecutionEvidence as A, RetainedInteractiveAdmissionHook as An, OtelSpan as At, Scope as B, RecoverRetainedRunResult as Bn, padSpanId as Bt, NoWinnerError as C, ExecutorProgress as Cn, EvalRunsExportConfig as Ct, NodeStatus as D, readWorkerProgress as Dn, OtelAttribute as Dt, NodeSnapshot as E, createActivityLog as En, LoopSpanNode as Et, RootHandle as F, NativeContextContinuationExecution as Fn, createOpenInferenceFileExporter as Ft, SpawnPrior as G, RetainedRunAdmission as Gn, RuntimeStreamEventSink as Gt, SpawnEvent as H, RetainedInteractiveEnvironmentAdmission as Hn, toOtelAttributes as Ht, RootMaterialization as I, NativeContextContinuationInput as In, createOtelExporter as It, SpendChannel as J, RetainedRunCancellation as Jn, SanitizedKnowledgeReadinessReport as Jt, SpawnRejection as K, RetainedRunAdmissionHook as Kn, RuntimeStreamEventSummary as Kt, RootProviderModelEvidence as L, ReconnectRetainedRunOptions as Ln, exportEvalRuns as Lt, ResultBlobStore as M, RetainedInteractiveRunHandle as Mn, buildLoopOtelSpans as Mt, ResumedKeyState as N, RetainedInteractiveStartMaterial as Nn, buildLoopSpanNodes as Nt, ProfileMaterializationReceipt as O, ReconnectRetainedInteractiveRunOptions as On, OtelExportConfig as Ot, ResumedWork as P, StartRetainedInteractiveRunOptions as Pn, buildRuntimeEventOtelSpans as Pt, Supervisor as Q, RetainedRunEventOptions as Qn, sanitizeAgentRuntimeEvent as Qt, RootSignal as R, RecoverRetainedRunIntentOptions as Rn, generateSpanId as Rt, MaterializedModelIdentity as S, DEFAULT_STALL_AFTER_MS as Sn, EvalRunGeneration as St, NodeId as T, WorkerProgress as Tn, INTELLIGENCE_WIRE_VERSION as Tt, SpawnJournal as U, RetainedInteractiveIntentAdmission as Un, RuntimeEventCollector as Ut, Settled as V, RetainedInteractiveAdmission as Vn, padTraceId as Vt, SpawnOpts as W, RetainedInteractiveStartedAdmission as Wn, RuntimeStreamEventCollector as Wt, SteerableRootHandle as X, RetainedRunEffect as Xn, createRuntimeEventCollector as Xt, SpendGap as Y, RetainedRunDispatchedAdmission as Yn, SanitizedKnowledgeRequirement as Yt, SupervisedResult as Z, RetainedRunEnvironmentAdmission as Zn, createRuntimeStreamEventCollector as Zt, ExecutorRegistry as _, createPushTraceSource as _n, createPropagatingTraceEmitter as _t, DefaultVerdict as a, WaitRejection as an, StartRetainedRunOptions as ar, WidenGate as at, Handle as b, ActivityLog as bn, traceContextToEnv as bt, ExecutorAccounting as c, isWaitOutcome as cn, WorkerTraceEvidence as ct, ExecutorContext as d, validateWaitSpec as dn, WorkerTraceSeamCarrier as dt, sanitizeRuntimeStreamEvent as en, RetainedRunIntentAdmission as er, TreeView as et, ExecutorExecutionBinding as f, waitUntil as fn, readWorkerTraceContext as ft, ExecutorProgressEvent as g, TraceSource as gn, TraceContext as gt, ExecutorNodeContext as h, ToolStepInput as hn, workerTraceSeamKey as ht, Budget as i, WaitProbeRegistry as in, StartRetainedRunInEnvironmentOptions as ir, WaitOpts as it, Restart as j, RetainedInteractiveEnvironmentInput as jn, RuntimeEventOtelOptions as jt, ProviderModelAttemptEvidence as k, RecoverRetainedInteractiveRunOptions as kn, OtelExporter as kt, ExecutorCancellation as l, pollFor as ln, WorkerTraceUnavailableReason as lt, ExecutorMaterialization as m, SessionTraceBox as mn, workerTraceHeaders as mt, AgentExecutionRef as n, WaitOutcome as nn, RetainedRunSnapshot as nr, UnknownMaterializationReason as nt, ExecutionBindingReceipt as o, WaitSpec as on, WorkerInteractiveSession as ot, ExecutorFactory as p, SessionMessageLike as pn, workerTraceEnv as pt, Spend as q, RetainedRunCancelOptions as qn, RuntimeTelemetryOptions as qt, AgentSpec as r, WaitProbe as rn, RetainedRunStartMaterial as rr, UsageEvent as rt, Executor as s, createWaitProbes as sn, WorkerInteractiveUnavailableReason as st, Agent as t, PendingWait as tn, RetainedRunReplayPoint as tr, UnconfirmedTeardown as tt, ExecutorCancellationRequest as u, timerAt as un, WorkerTraceResolver as ut, ExecutorResult as v, decodeToolPart as vn, mergeTraceEnv as vt, NodeExecutionIdentity as w, ScopeProgressInput as wn, EvalRunsExportResult as wt, MaterializedExecutionIdentity as x, ActivityNote as xn, EvalRunEvent as xt, ExecutorToolCall as y, sandboxSessionTraceSource as yn, readTraceContextFromEnv as yt, Runtime as z, RecoverRetainedRunOptions as zn, loopEventToOtelSpan as zt };
+//# sourceMappingURL=types-BPQhQRrC.d.ts.map

package/dist/{types-DZrBoBpN.d.ts → types-DeX8ibLc.d.ts}

@@ -1,6 +1,7 @@
 import { l as RuntimeHooks } from "./runtime-hooks-Bj6wJHlH.js";
 import { AgentProfile, InputPart, RequestedInteractions, StreamEvent } from "@tangle-network/agent-interface";
 import { ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, DefaultVerdict, KnowledgeReadinessReport, KnowledgeRequirement, RunRecord, TraceStore, UserQuestion } from "@tangle-network/agent-eval";
+import { AgentRunOutcome } from "@tangle-network/sandbox/runtime";
 import { CreateRequestOptions, CreateSandboxOptions, SandboxEvent, SandboxInstance } from "@tangle-network/sandbox";
 //#region src/types.d.ts
 /** @stable */
@@ -812,6 +813,8 @@ interface Iteration<Task, Output> {
   output?: Output;
   verdict?: DefaultVerdict;
   error?: Error;
+  /** Public Sandbox outcome settled after the complete event stream. */
+  sandboxOutcome?: AgentRunOutcome;
   /** Raw sandbox event stream collected for this iteration. Present on a failed iteration too,
    *  holding the events received before the failure — including the one that reported it. */
   events: SandboxEvent[];
@@ -1228,4 +1231,4 @@ interface ExecCtx {
 }
 //#endregion
 export { OpenAIChatToolChoice as $, RuntimeRunCompleteInput as A, AgentBackendInput as B, MountRecorder as C, SelectionReceipt as D, SandboxClient as E, RuntimeRunRow as F, AgentTaskContext as G, AgentKnowledgeProvider as H, RuntimeRunStatus as I, AgentTaskStatus as J, AgentTaskRunResult as K, startRuntimeRun as L, RuntimeRunHandle as M, RuntimeRunOptions as N, ValidationCtx as O, RuntimeRunPersistenceAdapter as P, OpenAIChatTool as Q, AgentAdapter as R, MountManifestEntry as S, RunProvenance as T, AgentRuntimeEvent as U, AgentExecutionBackend as V, AgentRuntimeEventSink as W, KnowledgeReadinessDecision as X, BackendErrorDetail as Y, OpenAIChatResponseFormat as Z, LoopTeardownFailedPayload as _, Iteration as a, RuntimeStreamEvent as at, LoopTraceEvent as b, LoopIterationDispatchPayload as c, LoopLineageOptions as d, RunAgentTaskOptions as et, LoopPlanDescription as f, LoopStartedPayload as g, LoopSandboxPlacement as h, ExecCtx as i, RuntimeSessionStore as it, RuntimeRunCost as j, Validator as k, LoopIterationEndedPayload as l, LoopResult as m, DefaultVerdict as n, RuntimeCanonicalStreamEvent as nt, LoopDecisionPayload as o, LoopPlanPayload as p, AgentTaskSpec as q, Driver as r, RuntimeSession as rt, LoopEndedPayload as s, AgentRunSpec as t, RunAgentTaskStreamOptions as tt, LoopIterationStartedPayload as u, LoopTokenUsage as v, OutputAdapter as w, LoopWinner as x, LoopTraceEmitter as y, AgentBackendContext as z };
-//# sourceMappingURL=types-DZrBoBpN.d.ts.map
+//# sourceMappingURL=types-DeX8ibLc.d.ts.map