@tangle-network/agent-runtime 0.229.0 → 0.231.1

package/dist/types-Ba5mJkyd.d.ts

@@ -1,1293 +0,0 @@
-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, PromptOptions, 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>;
-};
-/** Agent Interface events that do not belong to Runtime's task vocabulary. */
-type RuntimeCanonicalStreamEvent = StreamEvent & {
-  task?: AgentTaskSpec;
-  session?: RuntimeSession;
-  timestamp?: string;
-};
-/** @stable */
-type RuntimeStreamEvent = RuntimeCanonicalStreamEvent | {
-  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;
-  /** Why `tokensKnown` is false when a harness receipt was present but unreadable. */
-  tokensUnknownReason?: string;
-  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;
-  }>;
-  parts?: InputPart[];
-  interactions?: RequestedInteractions;
-  providerOptions?: Record<string, unknown>;
-  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';
-/** @stable */
-interface RuntimeRunCost {
-  /** Cumulative input tokens across every observed `llm_call` event. */
-  tokensIn: number;
-  /** Cumulative output tokens across every observed `llm_call` event. */
-  tokensOut: number;
-  /** Sum of `costUsd` from every observed `llm_call` event. */
-  costUsd: number;
-  /** Wall time from `startRuntimeRun()` to `complete()` (or `now()` if not yet completed). */
-  wallMs: number;
-  /** Count of `llm_call` events observed during the run. */
-  llmCalls: number;
-}
-/** @stable */
-interface RuntimeRunCompleteInput {
-  status: Exclude<RuntimeRunStatus, 'running'>;
-  resultSummary?: string;
-  /** Optional explicit cost override; if omitted, the accumulated ledger is used. */
-  cost?: Partial<RuntimeRunCost>;
-  /** Stable error message when `status === 'failed'`. */
-  error?: string;
-  /** Additional adapter-specific fields merged into the persisted row. */
-  metadata?: Record<string, unknown>;
-}
-/** @stable */
-interface RuntimeRunRow {
-  /** Stable runtime-side identifier. Adapters may translate to their own primary key. */
-  id: string;
-  workspaceId: string;
-  sessionId?: string;
-  agentId?: string;
-  domain?: string;
-  taskId: string;
-  scenarioId?: string;
-  status: RuntimeRunStatus;
-  resultSummary?: string;
-  error?: string;
-  cost: RuntimeRunCost;
-  startedAt: string;
-  completedAt?: string;
-  metadata?: Record<string, unknown>;
-}
-/** @stable */
-interface RuntimeRunPersistenceAdapter {
-  /**
-   * Called once when `handle.persist()` runs. Implementations write `row` to
-   * their durable store (D1, postgres, KV) and return whatever the consumer
-   * wants the caller to see (often the storage-side row id). Errors thrown
-   * here propagate out of `persist()` so the caller can decide whether to
-   * retry or log-and-continue.
-   */
-  upsert(row: RuntimeRunRow): Promise<void> | void;
-}
-/** @stable */
-interface RuntimeRunOptions {
-  workspaceId: string;
-  sessionId?: string;
-  agentId?: string;
-  taskSpec: AgentTaskSpec;
-  scenarioId?: string;
-  /** Optional persistence adapter; if omitted, `persist()` is a no-op. */
-  adapter?: RuntimeRunPersistenceAdapter;
-  /** Override the row id; default = `${taskSpec.id}:${random suffix}`. */
-  id?: string;
-  /** Override the clock; default = `Date.now()`. Useful for deterministic tests. */
-  now?: () => number;
-}
-/** @stable */
-interface RuntimeRunHandle {
-  /** Stable id assigned at start. */
-  readonly id: string;
-  readonly workspaceId: string;
-  readonly sessionId: string | undefined;
-  readonly taskSpec: AgentTaskSpec;
-  readonly status: RuntimeRunStatus;
-  /**
-   * Observe a single `RuntimeStreamEvent`. The handle ignores non-cost events
-   * (text deltas, tool calls) silently so consumers can pipe the whole stream
-   * through `handle.observe`. `llm_call` events update the ledger.
-   */
-  observe(event: RuntimeStreamEvent): void;
-  /** Snapshot of the current cost ledger. Safe to call at any time. */
-  cost(): RuntimeRunCost;
-  /**
-   * Transition to a terminal state. Idempotent for the same status; throws
-   * `RuntimeRunStateError` for a different terminal status (state machines
-   * don't time-travel).
-   */
-  complete(input: RuntimeRunCompleteInput): void;
-  /** Build the current row without writing it. Useful for tests + dry runs. */
-  toRow(metadata?: Record<string, unknown>): RuntimeRunRow;
-  /**
-   * Persist the current row via the configured adapter. Must be called after
-   * `complete()`. Idempotent for the same terminal state (the adapter sees
-   * the same row on retry).
-   */
-  persist(metadata?: Record<string, unknown>): Promise<void>;
-}
-/**
- *
- * Construct a runtime-run handle. The returned handle is mutable across its
- * lifetime; consumers should not share it across requests.
- *
- * @stable
- */
-declare function startRuntimeRun(options: RuntimeRunOptions): RuntimeRunHandle;
-//#endregion
-//#region src/runtime/types.d.ts
-/** @stable */
-interface ValidationCtx {
-  /** Iteration index this output came from (0-based). */
-  iteration: number;
-  /**
-   * Live sandbox for this iteration. Validators that need execution-grounded
-   * evidence can inspect files or run commands here instead of forcing callers
-   * to bypass the loop kernel with raw Sandbox SDK orchestration.
-   */
-  box?: SandboxInstance;
-  /** Cooperative cancellation channel. */
-  signal: AbortSignal;
-  /**
-   * Optional trace emitter. When set, validator implementations that make
-   * LLM calls (e.g. an LLM-judge reviewer) emit spans into it.
-   * The kernel passes `ctx.traceEmitter` from `ExecCtx` when available.
-   */
-  traceEmitter?: LoopTraceEmitter;
-}
-/** @stable */
-interface Validator<Output, Verdict = DefaultVerdict> {
-  validate(output: Output, ctx: ValidationCtx): Promise<Verdict>;
-}
-/**
- * Sandbox-SDK-shaped agent specification.
- *
- * The kernel uses `profile` to instantiate a sandbox per iteration, formats
- * `task` into a prompt via `taskToPrompt`, and merges `sandboxOverrides` into
- * the `CreateSandboxOptions` it passes to `client.create`. Heterogeneous
- * fanout supplies multiple `AgentRunSpec`s and the kernel round-robins
- * through them when the driver plans N tasks.
- *
- * @stable
- */
-interface AgentRunSpec<Task> {
-  /** Sandbox SDK profile — what kind of agent runs the task. */
-  profile: AgentProfile;
-  /** Task → prompt formatter. Pure and deterministic. */
-  taskToPrompt: (task: Task) => string;
-  /**
-   * Optional pre-prompt sandbox provisioner. Runs after the sandbox is acquired
-   * and before the first prompt is streamed into that box. Use this for
-   * domain-agnostic setup such as repo snapshots, benchmark fixtures, policy
-   * files, or seed datasets. The hook is part of the runtime surface so loop
-   * consumers do not hand-roll Sandbox SDK orchestration just to prepare a
-   * workspace before the agent sees it.
-   *
-   * `ctx.recordMount` records what was placed into the box so the run carries a
-   * provenance manifest (`LoopResult.provenance.mounts`). It is optional and
-   * provenance-only — the kernel never reads box contents and attaches no
-   * meaning to the entries; not calling it simply leaves the manifest empty.
-   */
-  prepareBox?: (box: SandboxInstance, ctx: {
-    signal: AbortSignal;
-    recordMount: MountRecorder;
-  }) => Promise<void> | void;
-  /**
-   * Per-spec stable name. Surfaced in trace events and the default winner
-   * selector tiebreak. Falls back to `profile.name ?? 'agent'`.
-   */
-  name?: string;
-  /**
-   * Optional sandbox-SDK `CreateSandboxOptions` overrides merged on top of
-   * the kernel's defaults. `backend.profile` is set to `profile` by the
-   * kernel and cannot be overridden here — use `profile` itself for that.
-   */
-  sandboxOverrides?: Partial<Omit<CreateSandboxOptions, 'backend'>> & {
-    backend?: Omit<NonNullable<CreateSandboxOptions['backend']>, 'profile'>;
-  };
-}
-/**
- * Stream of `SandboxEvent`s → typed `Output`.
- *
- * Adapters are pure functions over the already-collected event array; they
- * do not receive the live AsyncIterable so they can be replayed against
- * persisted streams during tests / replays.
- *
- * @stable
- */
-interface OutputAdapter<Output> {
-  parse(events: SandboxEvent[]): Output;
-}
-/** LLM token usage. Structurally maps into agent-eval's paid-call receipt so a
- * campaign dispatch settles real usage instead of appearing as a stub. */
-interface LoopTokenUsage {
-  /** Total provider-reported prompt tokens. Budgets always use this total. */
-  input: number;
-  output: number;
-  /** False when the subtotal is incomplete. */
-  tokensKnown?: false;
-  /** Prompt tokens newly processed by the provider, when every prompt class is known. */
-  freshInput?: number;
-  /** Prompt tokens the provider reported serving from its cache. */
-  cacheRead?: number;
-  /** Prompt tokens the provider reported writing to its cache. */
-  cacheWrite?: number;
-  /**
-   * False when any positive-input observation omitted or contradicted the prompt-cache split.
-   * This marker is sticky during aggregation. Missing cache fields must never become zero.
-   */
-  cacheBreakdownKnown?: false;
-}
-/**
- * One mounted resource recorded during box preparation — a pure provenance
- * record of what the caller placed into a box before the agent saw it. The
- * kernel never reads box contents itself (it does not know what was mounted);
- * the caller, which owns the bytes inside `prepareBox`, supplies each entry via
- * `recordMount`. Carries no domain semantics — just where the resource landed,
- * its content fingerprint, its size, and where it came from — so a run is
- * auditable after the fact ("what exactly was this agent given?").
- *
- * @stable
- */
-interface MountManifestEntry {
-  /** Destination path inside the box where the resource was placed. */
-  path: string;
-  /** Hex SHA-256 of the mounted bytes. The caller computes it from the bytes
-   *  it wrote — the kernel does not hash box contents. */
-  sha256: string;
-  /** Size of the mounted resource in bytes. */
-  bytes: number;
-  /** Free-form origin of the resource (e.g. a repo ref, a corpus id, a local
-   *  path, a URL). Provenance only — the kernel attaches no meaning to it. */
-  source: string;
-}
-/**
- * A record of one candidate-selection decision: which iteration the selector
- * picked (or rejected) and why. Pure audit trail of the SELECTOR role — it
- * carries the selector's identity, the candidate's score, and an optional
- * 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?".
- *
- * @stable
- */
-interface SelectionReceipt {
-  /** Iteration index this receipt is about. */
-  candidateIndex: number;
-  /** True for the iteration the selector chose as winner; false otherwise. */
-  selected: boolean;
-  /** The candidate's verdict score, when it has one. */
-  score?: number;
-  /** Why this candidate was (or was not) selected, when the selector states it. */
-  reason?: string;
-  /** Identity of the selector that produced this receipt — `'caller'` (an
-   *  explicit `selectWinner`), `'driver'` (a driver-authored winner), or
-   *  `'default'` (the kernel's best-valid-score argmax). */
-  selector: 'caller' | 'driver' | 'default';
-}
-/**
- * Domain-free run provenance: a manifest of what was mounted into the run's
- * boxes and the receipts for how the winner was selected. Surfaced on
- * `LoopResult` purely for run auditability — nothing in the kernel branches on
- * it. Empty arrays when the caller recorded no mounts and there was no
- * candidate to select.
- *
- * @stable
- */
-interface RunProvenance {
-  /** Every resource recorded via `prepareBox`'s `recordMount`, in record order. */
-  mounts: MountManifestEntry[];
-  /** One receipt per scored candidate at finalize, in iteration order. */
-  selectionReceipts: SelectionReceipt[];
-}
-/**
- * Records a mounted resource into the run's provenance manifest. Passed to
- * `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.
- *
- * @stable
- */
-type MountRecorder = (entry: MountManifestEntry) => void;
-/** @stable */
-interface Iteration<Task, Output> {
-  /** 0-based iteration index assigned by the kernel. */
-  index: number;
-  task: Task;
-  /** Stable name of the `AgentRunSpec` that produced this iteration. */
-  agentRunName: string;
-  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[];
-  startedAt: number;
-  endedAt: number;
-  costUsd: number;
-  /** False when `costUsd` is only the observed subtotal, not a complete bill. */
-  costUsdKnown?: false;
-  /**
-   * The part of `costUsd` that came from calls carrying no billing receipt, summed per call.
-   *
-   * `costUsdKnown` is an AND over the iteration, so it cannot say HOW MUCH of the total is
-   * unproven: one receiptless call marks the whole iteration unknown. This is the amount that
-   * belongs on `Spend.usdEstimated`, which keeps `usd - usdEstimated` reading as billed money on
-   * a settlement that mixed both kinds. Absent when every dollar here carried a receipt.
-   */
-  unprovenCostUsd?: number;
-  /** 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;
-  /**
-   * Wall time this iteration's box was alive, in milliseconds: from the moment the loop acquired
-   * the box to the moment the loop's own teardown returned.
-   *
-   * ABSENT when this iteration did not own the box's terminal. A lineage box and a same-sandbox
-   * box are reaped at loop end, AFTER the loop has already built its result, so no iteration can
-   * pair them. A missing lifetime is never a zero: a box nobody timed is a different fact from a
-   * box that lived no time.
-   */
-  boxLiveMs?: number;
-  /** False when `boxLiveMs` is a floor rather than the full lifetime: the delete was attempted and
-   *  never acknowledged, so the box may have outlived the number. */
-  boxLiveMsKnown?: false;
-}
-/** @stable */
-interface Driver<Task, Output, Decision> {
-  /**
-   * Trace label surfaced in trace events. No behavioral effect: it never
-   * selects a strategy or a decision path. Default `'driver'`.
-   */
-  readonly name?: string;
-  /**
-   * Tasks to issue this iteration. `[task]` → refine; N copies → fanout;
-   * `[]` → no more work this round (kernel proceeds to `decide`).
-   */
-  plan(task: Task, history: ReadonlyArray<Iteration<Task, Output>>): Promise<Task[]>;
-  /**
-   * Inspect history and return the next state. The kernel terminates the
-   * loop when `decide` returns a `TerminalDecision`
-   * (`'stop' | 'pick-winner' | 'fail' | 'done'`, exported as
-   * `TERMINAL_DECISIONS` with the `isTerminalDecision` guard), when
-   * `maxIterations` is hit, or when the abort signal fires. Every other
-   * value is caller vocabulary and continues the loop.
-   */
-  decide(history: ReadonlyArray<Iteration<Task, Output>>): Decision | Promise<Decision>;
-  /**
-   * Optional: describe the move `plan()` just produced, for trace emission.
-   * The kernel calls this immediately after `plan()` and emits the result in
-   * the `loop.plan` event so a topology viewer can render the agent's chosen
-   * move + rationale (not just the inferred fan-width). Drivers whose topology
-   * is a pure function of count (refine/fanout-vote) omit it — the kernel
-   * infers `moveKind` from the planned-task count. A driver that authors its
-   * own topology returns its chosen move's kind + rationale here.
-   */
-  describePlan?(): LoopPlanDescription | undefined;
-  /**
-   * Optional: the driver AUTHORS the winner instead of the kernel's argmax. The
-   * kernel consults this at finalize ONLY when the caller did not pass an explicit
-   * `selectWinner` to runAgentRounds. Return the driver-declared winner (e.g. from a
-   * `select` topology move) or `undefined` to fall through to the default
-   * (best-valid-score, earliest index). This is the SELECTOR role made
-   * agent-authorable — the planner runs the selection, not the kernel.
-   * @experimental
-   */
-  selectWinner?(history: ReadonlyArray<Iteration<Task, Output>>): LoopWinner<Task, Output> | undefined;
-}
-/** @stable Driver-supplied description of the just-planned move. */
-interface LoopPlanDescription {
-  /** Topology move this round — e.g. `'refine' | 'fanout' | 'verify' | 'stop'`. */
-  kind: string;
-  /** Why the driver chose this move (the agent's rationale), when available. */
-  rationale?: string;
-  /**
-   * Iteration index this round branches FROM, when the driver declares it.
-   * Overrides the kernel's inferred branch point — lets a planner that
-   * branches off a specific (non-winner) iteration emit faithful edge lineage.
-   * Omit to keep the inferred (best-valid / latest) branch point.
-   */
-  parentIndex?: number;
-}
-/** @stable */
-interface LoopWinner<Task, Output> {
-  task: Task;
-  output: Output;
-  verdict?: DefaultVerdict;
-  iterationIndex: number;
-  agentRunName: string;
-}
-/** @stable */
-interface LoopResult<Task, Output, Decision> {
-  decision: Decision;
-  iterations: Iteration<Task, Output>[];
-  winner?: LoopWinner<Task, Output>;
-  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 every iteration's `unprovenCostUsd` — the part of `costUsd` no billing receipt
-   *  covers. Absent when every dollar in the loop carried one. */
-  unprovenCostUsd?: number;
-  /** 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;
-  /** Sum of `Iteration.boxLiveMs` over the iterations that could pair a box acquire with its
-   *  teardown. ABSENT when none could — the run's box time went unmeasured, which is not a zero. */
-  boxLiveMs?: number;
-  /** False when at least one iteration ran a box whose lifetime the loop could not fully observe,
-   *  so `boxLiveMs` is a floor over the run rather than its total. */
-  boxLiveMsKnown?: false;
-  /** Domain-free run provenance for auditability: the mount manifest recorded
-   *  during `prepareBox` and the selection receipts for how the winner was
-   *  chosen. Always present; empty arrays when nothing was recorded. */
-  provenance: RunProvenance;
-}
-/**
- * Minimal sandbox client surface the kernel calls. Satisfied structurally by
- * `new Sandbox({ apiKey, baseUrl })` — declared as a structural type so
- * tests can pass a stub without instantiating the SDK.
- *
- * `describePlacement` is optional. When present, the kernel calls it after
- * each `create()` so the `loop.iteration.dispatch` trace event carries fleet
- * coordinates (fleetId + machineId) instead of just the sibling sandboxId.
- * Fleet-aware adapters set this; the raw `Sandbox` SDK class does not, and
- * the kernel falls back to `{ placement: 'sibling', sandboxId: box.id }`.
- *
- * @stable
- */
-interface SandboxClient {
-  create(options?: CreateSandboxOptions, requestOptions?: CreateRequestOptions): Promise<SandboxInstance>;
-  describePlacement?(box: SandboxInstance): LoopSandboxPlacement;
-  /**
-   * Optional legacy CRIU capability probe. When present and it resolves
-   * `{ available: true }`, the loop's `lineage.fork` seam may checkpoint and fork
-   * a parent box when live `branch(count)` is unavailable. Current Sandbox boxes
-   * expose live branching directly. The kernel reads this ONLY through the
-   * capability probe — it never branches on backend kind.
-   * The raw `Sandbox` SDK class satisfies it; the loop's test fakes omit it
-   * (⇒ `canFork = false`).
-   * @experimental
-   */
-  criuStatus?(): Promise<{
-    available: boolean;
-    criuVersion?: string;
-    reason?: string;
-  }>;
-}
-/**
- * Opt-in box-lineage controls for `runAgentRounds`. Default OFF — with both flags
- * unset the kernel's per-iteration behavior is byte-identical to acquiring a
- * fresh box, streaming once, and tearing it down. The independence of N fresh
- * boxes (e.g. `random@k`) is a compute-control invariant; these flags must
- * never apply to it. Enable them ONLY on a steered loop (refine / planner-driven
- * fanout) where reusing the parent's context is intended.
- *
- * Live-box footprint: the lineage keeps every box it starts or forks alive
- * across rounds so a later round can descend from it, and tears them down at
- * loop end. When the driver's branch point is kernel-inferred (no
- * `describePlan` — refine, fanout-vote), the kernel prunes boxes no future
- * round can reach after each round, so the live set tracks the active frontier.
- * When the driver authors its own branch point (`describePlan().parentIndex`),
- * it may descend from any prior
- * iteration, so no box is pruned and the live-box count rises to the total
- * iterations across all rounds. Size `forkFanout` runs accordingly. Live branch
- * children use copy-on-write, but each is still a live box until loop end.
- *
- * @experimental
- */
-interface LoopLineageOptions {
-  /**
-   * When true, a refine round (1 planned task) descending from a prior round
-   * CONTINUES the parent iteration's session on the SAME box
-   * (`streamPrompt({ sessionId })`) instead of acquiring a fresh box and
-   * re-injecting prior context as prompt text. Round 0 (no parent) always
-   * starts fresh. Usable on any single-task path, not just the refine driver.
-   *
-   * Requires a platform that honors a client-supplied `sessionId`. The lineage
-   * mints the id and `continue` asserts the session is still live
-   * (`box.session(id).status()`), failing loud if the platform dropped it — so a
-   * non-honoring platform errors instead of silently running contextless turns.
-   * Verify continuity against the live platform before enabling: the assertion
-   * proves the session EXISTS server-side, not that prior turns replay into it.
-   */
-  sessionContinuity?: boolean;
-  /**
-   * When true, a fanout round (N planned tasks) descending from a prior round
-   * branches the parent's live box so all N branches inherit its context prefix.
-   * If live branching is unavailable, the lineage uses legacy CRIU when its
-   * probe is positive. Otherwise it degrades to N fresh boxes with no prefix.
-   * Round 0 always starts fresh. NEVER set this for a `random@k` control arm —
-   * forking would couple the independent samples.
-   *
-   * A real fork inherits the parent's IMAGE/PROFILE: per-branch `AgentRunSpec`
-   * profiles are honored only on the degraded fresh-box path, so a
-   * heterogeneous-profile fanout silently homogenizes to the parent's profile
-   * when fork is available. Use this for same-profile branching; for
-   * different-per-branch profiles use the unforked fanout path.
-   */
-  forkFanout?: boolean;
-  /**
-   * Per-turn sandbox streaming mode. Default `'sse'` (live `streamPrompt` —
-   * low-latency, full per-token trace; best for interactive chat). `'poll'`
-   * fire-and-detaches via `dispatchPrompt` and awaits the terminal result by
-   * status-polling, so a long, quiet in-box turn (clone + build + test) never
-   * holds a live stream a proxy idle-timeout can drop mid-execution. Lower trace
-   * fidelity (one terminal event), so it is opt-in — intended for BATCH eval
-   * runs, which don't need live streaming and were losing long turns to the
-   * idle-drop. Applies to the default fresh-box path too, not only when
-   * `sessionContinuity`/`forkFanout` are on.
-   */
-  streaming?: 'sse' | 'poll';
-}
-/** @stable */
-interface LoopSandboxPlacement {
-  /** `in-process` is a local harness CLI in the caller's own process tree — no sandbox, no fleet.
-   *  It is a placement in its own right so a cost or latency breakdown split by placement does not
-   *  count local runs in the sandbox bucket. */
-  kind: 'sibling' | 'fleet' | 'in-process';
-  sandboxId?: string;
-  fleetId?: string;
-  machineId?: string;
-}
-/** @stable */
-interface LoopTraceEmitter {
-  emit(event: LoopTraceEvent): void | Promise<void>;
-}
-/** @stable */
-type LoopTraceEvent = {
-  kind: 'loop.started';
-  runId: string;
-  timestamp: number;
-  payload: LoopStartedPayload;
-} | {
-  kind: 'loop.plan';
-  runId: string;
-  timestamp: number;
-  payload: LoopPlanPayload;
-} | {
-  kind: 'loop.iteration.started';
-  runId: string;
-  timestamp: number;
-  payload: LoopIterationStartedPayload;
-} | {
-  kind: 'loop.iteration.dispatch';
-  runId: string;
-  timestamp: number;
-  payload: LoopIterationDispatchPayload;
-} | {
-  kind: 'loop.iteration.ended';
-  runId: string;
-  timestamp: number;
-  payload: LoopIterationEndedPayload;
-} | {
-  kind: 'loop.decision';
-  runId: string;
-  timestamp: number;
-  payload: LoopDecisionPayload;
-} | {
-  kind: 'loop.ended';
-  runId: string;
-  timestamp: number;
-  payload: LoopEndedPayload;
-} | {
-  kind: 'loop.teardown.failed';
-  runId: string;
-  timestamp: number;
-  payload: LoopTeardownFailedPayload;
-};
-/** @stable */
-interface LoopStartedPayload {
-  driver: string;
-  agentRunNames: string[];
-  maxIterations: number;
-  maxConcurrency: number;
-}
-/**
- * Emitted once per `plan()` round, immediately after the driver plans. Carries
- * the topology move so a viewer renders WHAT the agent decided + WHY, not just
- * the inferred fan-width. `moveKind` is the driver's `describePlan().kind` when
- * provided, else inferred from `plannedCount` (0→stop, 1→refine, N→fanout).
- *
- * @stable
- */
-interface LoopPlanPayload {
-  /** 0-based plan round (one per `plan()` call). */
-  roundIndex: number;
-  /** Tasks the driver issued this round. */
-  plannedCount: number;
-  /** Topology move — `'refine' | 'fanout' | 'verify' | 'stop'` etc. */
-  moveKind: string;
-  /** Driver rationale for the move, when available. */
-  rationale?: string;
-  /**
-   * Iteration index this round branched FROM (the edge source). `undefined`
-   * for round 0 (root). Kernel-inferred branch point — the best-valid (else
-   * latest) iteration so far — unless a driver later declares it explicitly.
-   */
-  parentIndex?: number;
-  /** Iteration indices this round dispatched (the edge targets). */
-  childIndices: number[];
-}
-/** @stable */
-interface LoopIterationStartedPayload {
-  iterationIndex: number;
-  agentRunName: string;
-  taskHash: string;
-  /** Plan round (== `LoopPlanPayload.roundIndex`) this iteration belongs to. */
-  groupId?: number;
-  /** Iteration this one was planned from; `undefined` ⇒ root. */
-  parentIndex?: number;
-}
-/**
- * Where the iteration's worker was placed. `sibling` = a fresh sandbox the
- * kernel created via `sandboxClient.create`. `fleet` = an existing machine in
- * a shared-workspace fleet — workers see the caller's filesystem and any diff
- * they write lands on it directly.
- *
- * @stable
- */
-interface LoopIterationDispatchPayload {
-  iterationIndex: number;
-  agentRunName: string;
-  placement: 'sibling' | 'fleet' | 'in-process';
-  /** Set on every placement. Lets analyst loops correlate per-iteration logs. */
-  sandboxId?: string;
-  /** Set only when `placement === 'fleet'`. */
-  fleetId?: string;
-  /** Set only when `placement === 'fleet'`. */
-  machineId?: string;
-  /** Plan round this iteration belongs to. */
-  groupId?: number;
-  /** Iteration this one was planned from; `undefined` ⇒ root. */
-  parentIndex?: number;
-}
-/** @stable */
-interface LoopIterationEndedPayload {
-  iterationIndex: number;
-  agentRunName: string;
-  outputHash?: string;
-  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. */
-  tokenUsage?: LoopTokenUsage;
-  /** Plan round this iteration belongs to. */
-  groupId?: number;
-  /** Iteration this one was planned from; `undefined` ⇒ root. */
-  parentIndex?: number;
-  /** Truncated string preview of the parsed output — for a viewer's drawer.
-   *  Bounded to ~280 chars; never the full payload. */
-  outputPreview?: string;
-}
-/** @stable */
-interface LoopDecisionPayload {
-  decision: string;
-  historyLength: number;
-}
-/** @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. @stable */
-interface LoopTeardownFailedPayload {
-  sandboxId?: string;
-  /** `'timeout'` or the delete error message. */
-  reason: string;
-}
-/**
- * Execution context for `runAgentRounds`: the sandbox client the kernel creates boxes through, plus optional runtime hooks.
- *
- * @stable
- */
-interface ExecCtx {
-  /** Sandbox SDK client — the kernel calls `.create()` per iteration. */
-  sandboxClient: SandboxClient;
-  /**
-   * Per-prompt sandbox SDK options, forwarded verbatim into EVERY `streamPrompt`
-   * of every iteration and every turn of this run. The kernel owns `sessionId`
-   * and `signal`: both are removed from the supplied value and applied last, so
-   * only the kernel's own session id and abort signal reach the SDK. A value
-   * that is present but not an object is a `ValidationError`, raised before any
-   * box is created.
-   *
-   * Typical use: `backend.model` credentials (`authMode` / `authFiles`) so a
-   * session runs on a caller-supplied subscription credential, `timeoutMs` for a
-   * per-turn wall-clock ceiling, and `context` for platform-side metadata.
-   *
-   * The instrument keys — `backend` and `model` — need a real box. The no-box
-   * `SandboxClient` seams (`inlineSandboxClient`, `localSandboxClient`,
-   * `inProcessSandboxClient`, and the in-process MCP executor) run an in-process
-   * executor with nothing to reconfigure, so they refuse a `backend` or `model`
-   * with a `ValidationError` instead of running the turn on an instrument the
-   * caller did not ask for. They accept and ignore every other key. The one
-   * exception is `inProcessSandboxClient`, which surfaces the verbatim options
-   * to its `onPrompt` callback: that callback is the executor, so a per-turn
-   * `model` reaches it and only `backend` is refused.
-   */
-  promptOptions?: Omit<PromptOptions, 'signal' | 'sessionId'>;
-  /** Optional runtime hooks. Execution-scoped; never part of `AgentProfile`. */
-  hooks?: RuntimeHooks;
-  /** Optional trace emitter. When set, the kernel emits `loop.*` events. */
-  traceEmitter?: LoopTraceEmitter;
-  /**
-   * Optional per-event tee. When set, the kernel forwards EVERY raw event from
-   * each iteration's `streamPrompt` stream as it arrives, so a host can stream
-   * the agent's live output (tokens, tool calls) token-by-token. The observer
-   * receives a defensive copy of each event — mutating it cannot affect the
-   * run's own cost accounting or output parsing. Called synchronously in the hot
-   * stream loop and never awaited, so a slow or never-settling observer cannot
-   * stall the stream; keep it cheap. An async observer is fire-and-forget: its
-   * promise is not awaited, so events carry no ordering or backpressure
-   * guarantees (the next event may be observed before a prior async observer
-   * settles) — use it for side-effect telemetry, not sequential processing.
-   * Both a synchronous throw and a rejected returned promise are caught +
-   * ignored so the observer can never break the run — but prefer not to depend
-   * on that.
-   *
-   * @experimental
-   */
-  onSandboxEvent?: (event: SandboxEvent, meta: {
-    iterationIndex: number;
-    agentRunName: string;
-  }) => void | PromiseLike<void>;
-  /**
-   * Optional production-run handle. When set, every synthesized `llm_call`
-   * the kernel infers from a sandbox event stream is forwarded via
-   * `runHandle.observe` so per-run cost aggregates pick up loop spend.
-   */
-  runHandle?: RuntimeRunHandle;
-  /** Cooperative cancellation signal. */
-  signal?: AbortSignal;
-  /**
-   * Trace id for OTEL correlation. When set alongside `traceEmitter`, the
-   * exporter uses this as the parent trace for all emitted spans. Typically
-   * inherited from TRACE_ID env var in MCP subprocess mode.
-   */
-  traceId?: string;
-  /**
-   * Parent span id for OTEL correlation. Loop events become children of
-   * this span. Typically inherited from PARENT_SPAN_ID env var.
-   */
-  parentSpanId?: string;
-}
-//#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-Ba5mJkyd.d.ts.map