@tangle-network/agent-runtime 0.126.0 → 0.131.0

package/dist/{types-DnNGJ5Gz.d.ts → types-ebIY0dMG.d.ts}

@@ -1,8 +1,516 @@
-import { u as AgentTaskSpec, x as RuntimeStreamEvent } from "./types-C9j4qg6l.js";
 import { l as RuntimeHooks } from "./runtime-hooks-sbRpjStq.js";
-import { DefaultVerdict } from "@tangle-network/agent-eval";
+import { ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, DefaultVerdict, KnowledgeReadinessReport, KnowledgeRequirement, RunRecord, TraceStore, UserQuestion } from "@tangle-network/agent-eval";
 import { AgentProfile as AgentProfile$1 } from "@tangle-network/agent-interface";
 import { CreateSandboxOptions, SandboxEvent, SandboxInstance } from "@tangle-network/sandbox";
+//#region src/types.d.ts
+/** @stable */
+interface AgentTaskSpec {
+  id: string;
+  intent: string;
+  /** Domain is metadata, not an architectural boundary: tax, legal, gtm, creative, blueprint, redteam, etc. */
+  domain?: string;
+  inputs?: Record<string, unknown>;
+  requiredKnowledge?: KnowledgeRequirement[];
+  budget?: Partial<ControlBudget>;
+  metadata?: Record<string, unknown>;
+}
+/** @stable */
+interface AgentKnowledgeProvider {
+  buildReadiness?(task: AgentTaskSpec): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport;
+  answerQuestions?(questions: UserQuestion[], task: AgentTaskSpec): Promise<Record<string, string>> | Record<string, string>;
+  executeAcquisitionPlans?(plans: DataAcquisitionPlan[], task: AgentTaskSpec): Promise<string[]> | string[];
+  refreshReadiness?(input: {
+    task: AgentTaskSpec;
+    previous: KnowledgeReadinessReport;
+    userAnswers: Record<string, string>;
+    acquiredEvidenceIds: string[];
+  }): Promise<KnowledgeReadinessReport> | KnowledgeReadinessReport;
+}
+/** @stable */
+interface AgentTaskContext<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+  state: TState;
+  evals: TEval[];
+  history: ControlStep<TState, TAction, TActionResult, TEval>[];
+  budget: ControlBudget;
+  stepIndex: number;
+  wallMs: number;
+  spentCostUsd: number;
+  remainingCostUsd?: number;
+  abortSignal: AbortSignal;
+}
+/** @stable */
+interface AgentAdapter<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  observe(ctx: {
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    history: ControlStep<TState, TAction, TActionResult, TEval>[];
+    abortSignal: AbortSignal;
+  }): Promise<TState> | TState;
+  validate(ctx: {
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    state: TState;
+    history: ControlStep<TState, TAction, TActionResult, TEval>[];
+    abortSignal: AbortSignal;
+  }): Promise<TEval[]> | TEval[];
+  decide(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<ControlDecision<TAction>> | ControlDecision<TAction>;
+  act(action: TAction, ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<TActionResult> | TActionResult;
+  shouldStop?(ctx: AgentTaskContext<TState, TAction, TActionResult, TEval>): Promise<{
+    stop: boolean;
+    pass: boolean;
+    reason: string;
+    score?: number;
+  }> | {
+    stop: boolean;
+    pass: boolean;
+    reason: string;
+    score?: number;
+  };
+  onKnowledgeBlocked?(ctx: {
+    task: AgentTaskSpec;
+    knowledge: KnowledgeReadinessReport;
+    questions: UserQuestion[];
+    acquisitionPlans: DataAcquisitionPlan[];
+  }): Promise<ControlDecision<TAction>> | ControlDecision<TAction>;
+  getActionCostUsd?(ctx: {
+    action: TAction;
+    result: TActionResult;
+    task: AgentTaskSpec;
+    state: TState;
+    evals: TEval[];
+    history: ControlStep<TState, TAction, TActionResult, TEval>[];
+  }): number | undefined;
+  projectRunRecords?(result: ControlRunResult<TState, TAction, TActionResult, TEval>, task: AgentTaskSpec): RunRecord[];
+}
+/** @stable */
+type AgentTaskStatus = 'completed' | 'blocked' | 'failed' | 'aborted';
+/** @stable */
+type AgentRuntimeEvent<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> = {
+  type: 'task_start';
+  task: AgentTaskSpec;
+} | {
+  type: 'readiness_start';
+  task: AgentTaskSpec;
+} | {
+  type: 'readiness_end';
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+} | {
+  type: 'questions_start';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+} | {
+  type: 'questions_end';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+  userAnswers: Record<string, string>;
+} | {
+  type: 'acquisition_start';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+} | {
+  type: 'acquisition_end';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+  acquiredEvidenceIds: string[];
+} | {
+  type: 'control_start';
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+} | {
+  type: 'control_step';
+  task: AgentTaskSpec;
+  step: ControlStep<TState, TAction, TActionResult, TEval>;
+} | {
+  type: 'control_end';
+  task: AgentTaskSpec;
+  control: ControlRunResult<TState, TAction, TActionResult, TEval>;
+} | {
+  type: 'task_end';
+  task: AgentTaskSpec;
+  status: AgentTaskStatus;
+  reason: string;
+};
+/** @stable */
+type AgentRuntimeEventSink<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> = (event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>) => Promise<void> | void;
+/**
+ *
+ * Typed transport / backend failure detail. Carried on `backend_error` and
+ * `final` events when the backend's stream throws or the upstream HTTP call
+ * returns a non-success status. Lets consumers (a) distinguish "stream
+ * completed with no text" from "stream never reached the model" and
+ * (b) reconstruct the precise upstream signal (status + truncated body) when
+ * building a `RunRecord.error`.
+ *
+ * `body` is truncated to 2 KiB by the backend so an HTML error page from a
+ * misconfigured proxy never bloats event payloads or logs. Consumers needing
+ * the full body should inspect the underlying `BackendTransportError.body`
+ * via a custom `mapEvent` or backend wrapper.
+ *
+ * @stable
+ */
+interface BackendErrorDetail {
+  /**
+   * `'transport'` — upstream HTTP / network failure with optional status code.
+   * `'backend'` — the backend's `stream()` generator threw for a non-transport
+   * reason (e.g. a custom adapter error, sandbox crash).
+   */
+  kind: 'transport' | 'backend';
+  message: string;
+  /** Upstream HTTP status when known. `0` for connection / abort errors. */
+  status?: number;
+  /** Truncated response body (≤2 KiB). Diagnostic only — never machine-parsed. */
+  body?: string;
+}
+/**
+ *
+ * OpenAI Chat Completions tool descriptor. The shape mirrors the
+ * `/v1/chat/completions` `tools[]` parameter so caller-owned compatible
+ * transports can pass tool definitions without translation. A router can
+ * proxy this shape to Anthropic
+ * (translated server-side), DeepSeek, Groq, OpenAI, and Gemini — every model
+ * that the eval surface targets.
+ *
+ * Callers that build their tool list from MCP servers should run a one-shot
+ * MCP `tools/list` at config time and project the result into this shape. The
+ * runtime intentionally does NOT depend on `@modelcontextprotocol/sdk` —
+ * keeping the backend transport thin lets domain repos own MCP plumbing.
+ *
+ * @stable
+ */
+interface OpenAIChatTool {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+}
+/**
+ *
+ * `tool_choice` parameter for OpenAI-compat chat. Same shape as the OpenAI
+ * spec: `'auto'` (default — model decides), `'none'` (disable tool calling
+ * for this turn), `'required'` (force a tool call), or a specific function
+ * pin `{ type: 'function', function: { name } }`.
+ *
+ * @stable
+ */
+type OpenAIChatToolChoice = 'auto' | 'none' | 'required' | {
+  type: 'function';
+  function: {
+    name: string;
+  };
+};
+/**
+ *
+ * `response_format` parameter for OpenAI-compatible chat endpoints. Use
+ * `json_object` when the caller needs syntactically valid JSON, or
+ * `json_schema` when the upstream provider supports schema-constrained JSON.
+ *
+ * @stable
+ */
+type OpenAIChatResponseFormat = {
+  type: 'text';
+} | {
+  type: 'json_object';
+} | {
+  type: 'json_schema';
+  json_schema: Record<string, unknown>;
+};
+/** @stable */
+type RuntimeStreamEvent = {
+  type: 'task_start';
+  task: AgentTaskSpec;
+  timestamp: string;
+} | {
+  type: 'readiness_start';
+  task: AgentTaskSpec;
+  timestamp: string;
+} | {
+  type: 'readiness_end';
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+  decision: KnowledgeReadinessDecision;
+  timestamp: string;
+} | {
+  type: 'questions_start';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+  timestamp: string;
+} | {
+  type: 'questions_end';
+  task: AgentTaskSpec;
+  questions: UserQuestion[];
+  userAnswers: Record<string, string>;
+  timestamp: string;
+} | {
+  type: 'acquisition_start';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+  timestamp: string;
+} | {
+  type: 'acquisition_end';
+  task: AgentTaskSpec;
+  acquisitionPlans: DataAcquisitionPlan[];
+  acquiredEvidenceIds: string[];
+  timestamp: string;
+} | {
+  type: 'session_created';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  timestamp: string;
+} | {
+  type: 'session_resumed';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  timestamp: string;
+} | {
+  type: 'backend_start';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  backend: string;
+  /** Canonical execution identity and materialization evidence for this turn, when Runtime
+   *  owns the selected executor. Generic metadata keeps the event vocabulary open while the
+   *  values use Runtime's existing identity/materialization receipt shapes. */
+  metadata?: Record<string, unknown>;
+  timestamp: string;
+} | {
+  type: 'text_delta';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  text: string;
+  timestamp?: string;
+} | {
+  type: 'reasoning_delta';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  text: string;
+  timestamp?: string;
+} | {
+  type: 'tool_call';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  toolName: string;
+  toolCallId?: string;
+  args?: unknown;
+  timestamp?: string;
+} | {
+  type: 'tool_result';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  toolName: string;
+  toolCallId?: string;
+  result?: unknown;
+  timestamp?: string;
+} | {
+  type: 'llm_call';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  model: string;
+  tokensIn?: number;
+  tokensOut?: number;
+  /** False when the numeric token subtotal is incomplete or absent. */
+  tokensKnown?: false;
+  costUsd?: number;
+  /** False when `costUsd` is only an observed floor, estimate, or absent. */
+  usdKnown?: false;
+  /** Separately-labelled local/catalog estimate; never billed spend. */
+  estimatedCostUsd?: number;
+  /** Provider-reported prompt-cache fields; absent fields remain unknown. */
+  promptCache?: Readonly<Record<string, number | string>>;
+  latencyMs?: number;
+  finishReason?: string;
+  timestamp?: string;
+} | {
+  type: 'artifact';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  artifactId: string;
+  name?: string;
+  mimeType?: string;
+  uri?: string;
+  content?: string;
+  metadata?: Record<string, unknown>;
+  timestamp?: string;
+} | {
+  type: 'proposal_created';
+  task?: AgentTaskSpec;
+  session?: RuntimeSession;
+  proposalId: string;
+  title: string;
+  status?: 'pending' | 'approved' | 'rejected';
+  content?: string;
+  timestamp?: string;
+} | {
+  type: 'backend_error';
+  task: AgentTaskSpec;
+  session?: RuntimeSession;
+  backend: string;
+  message: string;
+  recoverable: boolean;
+  /**
+   * Typed transport diagnostic. Present when the upstream returned a
+   * non-success HTTP status or every retry attempt threw. Consumers MUST
+   * surface this onto their `RunRecord.error` — silently treating a
+   * `backend_error` as "no output" hides credit exhaustion, auth failure,
+   * and upstream outages from operators.
+   *  - `kind: 'transport'` — HTTP / network failure with optional `status`
+   *    + truncated response `body`.
+   *  - `kind: 'backend'` — the backend's `stream()` generator threw for a
+   *    reason that isn't a recognized transport failure.
+   */
+  error?: BackendErrorDetail;
+  timestamp: string;
+} | {
+  type: 'backend_end';
+  task: AgentTaskSpec;
+  session: RuntimeSession;
+  backend: string;
+  timestamp: string;
+} | {
+  type: 'task_end';
+  task: AgentTaskSpec;
+  status: AgentTaskStatus;
+  reason: string;
+  timestamp: string;
+} | {
+  type: 'final';
+  task: AgentTaskSpec;
+  session?: RuntimeSession;
+  status: AgentTaskStatus;
+  reason: string;
+  text?: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * Typed terminal-error diagnostic. Mirrors the `backend_error.error`
+   * shape so a consumer that only listens for `final` still receives a
+   * loud, structured failure when the backend never produced output. Only
+   * set when `status !== 'completed'`. Consumers building a `RunRecord`
+   * MUST map this to `RunRecord.error` rather than recording silent
+   * `error: null` with empty `finalText`.
+   */
+  error?: BackendErrorDetail;
+  timestamp: string;
+};
+/** @stable */
+interface RuntimeSession {
+  id: string;
+  backend: string;
+  status: 'active' | 'completed' | 'failed' | 'aborted';
+  resumeToken?: string;
+  createdAt: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+/** @stable */
+interface RuntimeSessionStore {
+  get(sessionId: string): Promise<RuntimeSession | undefined> | RuntimeSession | undefined;
+  put(session: RuntimeSession): Promise<void> | void;
+  appendEvent?(sessionId: string, event: RuntimeStreamEvent): Promise<void> | void;
+  listEvents?(sessionId: string): Promise<RuntimeStreamEvent[]> | RuntimeStreamEvent[];
+}
+/** @stable */
+interface AgentBackendInput {
+  task: AgentTaskSpec;
+  message?: string;
+  messages?: Array<{
+    role: string;
+    content: string;
+  }>;
+  inputs?: Record<string, unknown>;
+}
+/** @stable */
+interface AgentBackendContext {
+  task: AgentTaskSpec;
+  knowledge: KnowledgeReadinessReport;
+  session: RuntimeSession;
+  signal?: AbortSignal;
+  /**
+   * Conversation/run identifier when this call is part of a multi-agent run.
+   * Backends should stamp it into any trace/log emission so cross-participant
+   * events correlate. Absent when the call is a stand-alone `runAgentTask`.
+   */
+  runId?: string;
+  /**
+   * Deterministic turn id for this single call. Stable across retries of the
+   * same logical turn so a caching gateway / idempotent backend can dedupe.
+   */
+  turnId?: string;
+  /**
+   * If this call is itself nested inside a higher-order conversation
+   * (recursion via `createConversationBackend`), the enclosing turn's id.
+   * Used for trace stitching across nested orchestration.
+   */
+  parentTurnId?: string;
+  /**
+   * Headers to forward verbatim to any outbound HTTP the backend issues:
+   * `X-Tangle-Forwarded-Authorization`, `X-Tangle-Forwarded-Depth`,
+   * run/turn correlation. Backends that issue HTTP MUST merge these into
+   * the outbound request; backends that don't issue HTTP may ignore them.
+   */
+  propagatedHeaders?: Readonly<Record<string, string>>;
+}
+/** @stable */
+interface AgentExecutionBackend<TInput extends AgentBackendInput = AgentBackendInput> {
+  kind: string;
+  start?(input: TInput, context: Omit<AgentBackendContext, 'session'> & {
+    requestedSessionId?: string;
+  }): Promise<RuntimeSession> | RuntimeSession;
+  resume?(session: RuntimeSession, input: TInput, context: Omit<AgentBackendContext, 'session'>): Promise<RuntimeSession> | RuntimeSession;
+  stream(input: TInput, context: AgentBackendContext): AsyncIterable<RuntimeStreamEvent>;
+  stop?(session: RuntimeSession, reason: string): Promise<void> | void;
+}
+/** @stable */
+interface RunAgentTaskStreamOptions<TInput extends AgentBackendInput = AgentBackendInput> {
+  task: AgentTaskSpec;
+  backend: AgentExecutionBackend<TInput>;
+  input?: Omit<TInput, 'task'>;
+  knowledge?: AgentKnowledgeProvider;
+  sessionStore?: RuntimeSessionStore;
+  sessionId?: string;
+  resume?: boolean;
+  signal?: AbortSignal;
+  minimumReadinessScore?: number;
+}
+/** @stable */
+interface RunAgentTaskOptions<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  task: AgentTaskSpec;
+  adapter: AgentAdapter<TState, TAction, TActionResult, TEval>;
+  knowledge?: AgentKnowledgeProvider;
+  onEvent?: AgentRuntimeEventSink<TState, TAction, TActionResult, TEval>;
+  store?: TraceStore;
+  signal?: AbortSignal;
+  scenarioId?: string;
+  projectId?: string;
+  variantId?: string;
+  minimumReadinessScore?: number;
+}
+/** @stable */
+interface AgentTaskRunResult<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult> {
+  task: AgentTaskSpec;
+  status: AgentTaskStatus;
+  knowledge: KnowledgeReadinessReport;
+  questions: UserQuestion[];
+  acquisitionPlans: DataAcquisitionPlan[];
+  userAnswers: Record<string, string>;
+  acquiredEvidenceIds: string[];
+  control: ControlRunResult<TState, TAction, TActionResult, TEval>;
+  runRecords: RunRecord[];
+}
+/** @stable */
+interface KnowledgeReadinessDecision {
+  passed: boolean;
+  status: 'ready' | 'blocked' | 'caveat';
+  reason: string;
+  readinessScore: number;
+  recommendedAction: KnowledgeReadinessReport['recommendedAction'];
+  severity: KnowledgeReadinessReport['severity'];
+  blockingGapIds: string[];
+  nonBlockingGapIds: string[];
+}
+//#endregion
 //#region src/runtime-run.d.ts
 /** @stable */
 type RuntimeRunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
@@ -114,7 +622,7 @@ interface RuntimeRunHandle {
 declare function startRuntimeRun(options: RuntimeRunOptions): RuntimeRunHandle;
 //#endregion
 //#region src/runtime/types.d.ts
-/** @experimental */
+/** @stable */
 interface ValidationCtx {
   /** Iteration index this output came from (0-based). */
   iteration: number;
@@ -133,7 +641,7 @@ interface ValidationCtx {
    */
   traceEmitter?: LoopTraceEmitter;
 }
-/** @experimental */
+/** @stable */
 interface Validator<Output, Verdict = DefaultVerdict> {
   validate(output: Output, ctx: ValidationCtx): Promise<Verdict>;
 }
@@ -146,7 +654,7 @@ interface Validator<Output, Verdict = DefaultVerdict> {
  * fanout supplies multiple `AgentRunSpec`s and the kernel round-robins
  * through them when the driver plans N tasks.
  *
- * @experimental
+ * @stable
  */
 interface AgentRunSpec<Task> {
   /** Sandbox SDK profile — what kind of agent runs the task. */
@@ -191,7 +699,7 @@ interface AgentRunSpec<Task> {
  * do not receive the live AsyncIterable so they can be replayed against
  * persisted streams during tests / replays.
  *
- * @experimental
+ * @stable
  */
 interface OutputAdapter<Output> {
   parse(events: SandboxEvent[]): Output;
@@ -201,6 +709,8 @@ interface OutputAdapter<Output> {
 interface LoopTokenUsage {
   input: number;
   output: number;
+  /** False when the subtotal is incomplete. */
+  tokensKnown?: false;
 }
 /**
  * One mounted resource recorded during box preparation — a pure provenance
@@ -211,7 +721,7 @@ interface LoopTokenUsage {
  * its content fingerprint, its size, and where it came from — so a run is
  * auditable after the fact ("what exactly was this agent given?").
  *
- * @experimental
+ * @stable
  */
 interface MountManifestEntry {
   /** Destination path inside the box where the resource was placed. */
@@ -232,7 +742,7 @@ interface MountManifestEntry {
  * human-readable reason, with no domain semantics. The kernel emits one receipt
  * per scored candidate at finalize so a run answers "why did THIS one win?".
  *
- * @experimental
+ * @stable
  */
 interface SelectionReceipt {
   /** Iteration index this receipt is about. */
@@ -255,7 +765,7 @@ interface SelectionReceipt {
  * it. Empty arrays when the caller recorded no mounts and there was no
  * candidate to select.
  *
- * @experimental
+ * @stable
  */
 interface RunProvenance {
   /** Every resource recorded via `prepareBox`'s `recordMount`, in record order. */
@@ -268,10 +778,10 @@ interface RunProvenance {
  * `prepareBox` so the caller — which owns the bytes it writes into the box —
  * declares what it mounted without the kernel having to inspect box contents.
  *
- * @experimental
+ * @stable
  */
 type MountRecorder = (entry: MountManifestEntry) => void;
-/** @experimental */
+/** @stable */
 interface Iteration<Task, Output> {
   /** 0-based iteration index assigned by the kernel. */
   index: number;
@@ -286,10 +796,16 @@ interface Iteration<Task, Output> {
   startedAt: number;
   endedAt: number;
   costUsd: number;
+  /** False when `costUsd` is only the observed subtotal, not a complete bill. */
+  costUsdKnown?: false;
+  /** Local/catalog estimates remain separate from billed spend. */
+  estimatedCostUsd?: number;
+  /** Provider-reported prompt-cache fields; absent fields remain unknown. */
+  promptCache?: Record<string, number | string>;
   /** Summed LLM token usage across every `llm_call` event in this iteration. */
   tokenUsage: LoopTokenUsage;
 }
-/** @experimental */
+/** @stable */
 interface Driver<Task, Output, Decision> {
   /**
    * Stable identifier surfaced in trace events. Default `'driver'`.
@@ -328,7 +844,7 @@ interface Driver<Task, Output, Decision> {
    */
   selectWinner?(history: ReadonlyArray<Iteration<Task, Output>>): LoopWinner<Task, Output> | undefined;
 }
-/** @experimental Driver-supplied description of the just-planned move. */
+/** @stable Driver-supplied description of the just-planned move. */
 interface LoopPlanDescription {
   /** Topology move this round — e.g. `'refine' | 'fanout' | 'verify' | 'stop'`. */
   kind: string;
@@ -342,7 +858,7 @@ interface LoopPlanDescription {
    */
   parentIndex?: number;
 }
-/** @experimental */
+/** @stable */
 interface LoopWinner<Task, Output> {
   task: Task;
   output: Output;
@@ -350,7 +866,7 @@ interface LoopWinner<Task, Output> {
   iterationIndex: number;
   agentRunName: string;
 }
-/** @experimental */
+/** @stable */
 interface LoopResult<Task, Output, Decision> {
   decision: Decision;
   iterations: Iteration<Task, Output>[];
@@ -358,6 +874,12 @@ interface LoopResult<Task, Output, Decision> {
   durationMs: number;
   /** Sum of every iteration's `costUsd`. */
   costUsd: number;
+  /** False when `costUsd` is only the observed subtotal, not a complete bill. */
+  costUsdKnown?: false;
+  /** Sum of separately-labelled local/catalog estimates. */
+  estimatedCostUsd?: number;
+  /** Aggregated provider-reported prompt-cache fields. */
+  promptCache?: Record<string, number | string>;
   /** Sum of every iteration's token usage. `loopDispatch` commits it through
    *  the campaign's paid-call receipt. */
   tokenUsage: LoopTokenUsage;
@@ -377,7 +899,7 @@ interface LoopResult<Task, Output, Decision> {
  * Fleet-aware adapters set this; the raw `Sandbox` SDK class does not, and
  * the kernel falls back to `{ placement: 'sibling', sandboxId: box.id }`.
  *
- * @experimental
+ * @stable
  */
 interface SandboxClient {
   create(options?: CreateSandboxOptions): Promise<SandboxInstance>;
@@ -463,18 +985,18 @@ interface LoopLineageOptions {
    */
   streaming?: 'sse' | 'poll';
 }
-/** @experimental */
+/** @stable */
 interface LoopSandboxPlacement {
   kind: 'sibling' | 'fleet';
   sandboxId?: string;
   fleetId?: string;
   machineId?: string;
 }
-/** @experimental */
+/** @stable */
 interface LoopTraceEmitter {
   emit(event: LoopTraceEvent): void | Promise<void>;
 }
-/** @experimental */
+/** @stable */
 type LoopTraceEvent = {
   kind: 'loop.started';
   runId: string;
@@ -516,7 +1038,7 @@ type LoopTraceEvent = {
   timestamp: number;
   payload: LoopTeardownFailedPayload;
 };
-/** @experimental */
+/** @stable */
 interface LoopStartedPayload {
   driver: string;
   agentRunNames: string[];
@@ -529,7 +1051,7 @@ interface LoopStartedPayload {
  * the inferred fan-width. `moveKind` is the driver's `describePlan().kind` when
  * provided, else inferred from `plannedCount` (0→stop, 1→refine, N→fanout).
  *
- * @experimental
+ * @stable
  */
 interface LoopPlanPayload {
   /** 0-based plan round (one per `plan()` call). */
@@ -549,7 +1071,7 @@ interface LoopPlanPayload {
   /** Iteration indices this round dispatched (the edge targets). */
   childIndices: number[];
 }
-/** @experimental */
+/** @stable */
 interface LoopIterationStartedPayload {
   iterationIndex: number;
   agentRunName: string;
@@ -565,7 +1087,7 @@ interface LoopIterationStartedPayload {
  * a shared-workspace fleet — workers see the caller's filesystem and any diff
  * they write lands on it directly.
  *
- * @experimental
+ * @stable
  */
 interface LoopIterationDispatchPayload {
   iterationIndex: number;
@@ -582,7 +1104,7 @@ interface LoopIterationDispatchPayload {
   /** Iteration this one was planned from; `undefined` ⇒ root. */
   parentIndex?: number;
 }
-/** @experimental */
+/** @stable */
 interface LoopIterationEndedPayload {
   iterationIndex: number;
   agentRunName: string;
@@ -590,6 +1112,8 @@ interface LoopIterationEndedPayload {
   verdict?: DefaultVerdict;
   error?: string;
   costUsd: number;
+  costUsdKnown?: false;
+  estimatedCostUsd?: number;
   durationMs: number;
   /** Summed LLM token usage for this iteration — maps to gen_ai.usage.* on the
    *  branch span. Omitted when no `llm_call` events carried token counts. */
@@ -602,21 +1126,23 @@ interface LoopIterationEndedPayload {
    *  Bounded to ~280 chars; never the full payload. */
   outputPreview?: string;
 }
-/** @experimental */
+/** @stable */
 interface LoopDecisionPayload {
   decision: string;
   historyLength: number;
 }
-/** @experimental */
+/** @stable */
 interface LoopEndedPayload {
   winnerIterationIndex?: number;
   totalCostUsd: number;
+  costUsdKnown?: false;
+  estimatedCostUsd?: number;
   durationMs: number;
   iterations: number;
 }
 /** Emitted when a box's `delete()` throws or times out during teardown — the
  *  loop swallows the failure (platform reaps on expiry) but surfaces it here so
- *  a real leak (e.g. mid-loop auth expiry) is observable. @experimental */
+ *  a real leak (e.g. mid-loop auth expiry) is observable. @stable */
 interface LoopTeardownFailedPayload {
   sandboxId?: string;
   /** `'timeout'` or the delete error message. */
@@ -625,7 +1151,7 @@ interface LoopTeardownFailedPayload {
 /**
  * Execution context for `runAgentRounds`: the sandbox client the kernel creates boxes through, plus optional runtime hooks.
  *
- * @experimental
+ * @stable
  */
 interface ExecCtx {
   /** Sandbox SDK client — the kernel calls `.create()` per iteration. */
@@ -676,5 +1202,5 @@ interface ExecCtx {
   parentSpanId?: string;
 }
 //#endregion
-export { RuntimeRunCompleteInput as A, MountRecorder as C, SelectionReceipt as D, SandboxClient as E, RuntimeRunRow as F, RuntimeRunStatus as I, startRuntimeRun as L, RuntimeRunHandle as M, RuntimeRunOptions as N, ValidationCtx as O, RuntimeRunPersistenceAdapter as P, MountManifestEntry as S, RunProvenance as T, LoopTeardownFailedPayload as _, Iteration as a, LoopTraceEvent as b, LoopIterationDispatchPayload as c, LoopLineageOptions as d, LoopPlanDescription as f, LoopStartedPayload as g, LoopSandboxPlacement as h, ExecCtx as i, RuntimeRunCost as j, Validator as k, LoopIterationEndedPayload as l, LoopResult as m, DefaultVerdict as n, LoopDecisionPayload as o, LoopPlanPayload as p, Driver as r, LoopEndedPayload as s, AgentRunSpec as t, LoopIterationStartedPayload as u, LoopTokenUsage as v, OutputAdapter as w, LoopWinner as x, LoopTraceEmitter as y };
-//# sourceMappingURL=types-DnNGJ5Gz.d.ts.map
+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, LoopTraceEvent as b, LoopIterationDispatchPayload as c, LoopLineageOptions as d, RunAgentTaskOptions as et, LoopPlanDescription as f, LoopStartedPayload as g, LoopSandboxPlacement as h, ExecCtx as i, RuntimeStreamEvent as it, RuntimeRunCost as j, Validator as k, LoopIterationEndedPayload as l, LoopResult as m, DefaultVerdict as n, RuntimeSession as nt, LoopDecisionPayload as o, LoopPlanPayload as p, AgentTaskSpec as q, Driver as r, RuntimeSessionStore 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-ebIY0dMG.d.ts.map