@tangle-network/agent-runtime 0.128.0 → 0.131.1

package/dist/runtime-D-QfLbSd.d.ts

@@ -0,0 +1,893 @@
+import { E as SandboxClient, i as ExecCtx } from "./types-ebIY0dMG.js";
+import { B as Spend, d as ExecutorFactory, m as ExecutorRegistry, q as UsageEvent, rn as TraceSource, un as ExecutorProgress } from "./types-C6Q-J0Dt.js";
+import { i as AgentEnvironmentProvider, o as AgentEnvironmentProviderRegistry, w as ProviderExecutorOptions } from "./environment-provider-CxvSd1W6.js";
+import { AgentProfile, HarnessType, ReasoningEffort } from "@tangle-network/agent-interface";
+import { WorkspacePlanReceipt } from "@tangle-network/agent-profile-materialize";
+import { ChildProcess } from "node:child_process";
+import { BackendType } from "@tangle-network/sandbox";
+//#region src/runtime/router-retry-policy.d.ts
+/** Exact retry controls accepted at `AgentProfile.model.metadata.retry`. */
+interface RouterRetryPolicy {
+  /** Total attempts, including the first request. */
+  readonly maxAttempts?: number;
+  /** Delay before the second attempt. Later delays grow exponentially. */
+  readonly initialBackoffMs?: number;
+  /** Maximum delay between attempts. */
+  readonly maxBackoffMs?: number;
+  /** Symmetric random variation around each delay, from 0 through 1. */
+  readonly jitter?: number;
+  /** HTTP statuses that may be retried. */
+  readonly retryStatuses?: ReadonlyArray<number>;
+  /** Deadline for receiving one attempt's response headers. Zero disables it. */
+  readonly requestTimeoutMs?: number;
+}
+//#endregion
+//#region src/runtime/tool-loop.d.ts
+/** Provider-neutral conversation record accepted by a tool-loop brain. */
+type ToolLoopMessageRecord = Record<string, unknown>;
+/** One provider-neutral tool request emitted by a tool-loop model. */
+interface ToolLoopToolCall {
+  id: string;
+  name: string;
+  /** Raw JSON arguments emitted by the model. */
+  arguments: string;
+}
+/** Runtime-owned identity and cancellation for one logical inference call. The wrapper is frozen
+ * before dispatch; a transport may observe the signal but cannot replace the authority it names. */
+interface ToolLoopCallContext {
+  readonly signal: AbortSignal;
+  readonly callId: string;
+  readonly correlationId: string;
+}
+/** One inference turn over the running conversation + the tool specs → the model's text, any
+ *  tool calls, and token usage. The seam every brain satisfies. */
+type ToolLoopChat = (messages: ReadonlyArray<ToolLoopMessageRecord>, tools: ReadonlyArray<ToolSpec>, context?: ToolLoopCallContext) => Promise<{
+  content?: string | null;
+  toolCalls: ToolLoopToolCall[];
+  usage?: {
+    input: number;
+    output: number;
+    reasoning?: number;
+  };
+  /** Dollar value reported for the turn. It is not billed spend unless provenance says so. */
+  costUsd?: number;
+  costProvenance?: 'provider-receipt' | 'billing-receipt' | 'catalog-estimate';
+  /** The turn ran but its usage was not reported when the transport EXPECTED one (the streamed
+   *  router transport asks for usage and this says it never arrived). A metering caller records an
+   *  unknown turn on it; `runBrainLoop` itself ignores it. */
+  usageUnknown?: true;
+  /** Provider-observed model identity. Profile-bound callers validate it before accepting output. */
+  model?: string;
+  /** Provider-reported prompt-cache evidence; missing fields remain missing. */
+  promptCache?: Readonly<Record<string, number | string>>;
+  /** Physical HTTP/injected-transport attempts spent by this one logical call. */
+  transportAttempts?: number;
+}>;
+/** Self-compaction — bound the loop's OWN context window the way a fresh-respawn (dumb-Ralph) loop
+ *  does, but in place. A stateless chat API re-sends the WHOLE running conversation every turn, so an
+ *  agent that accumulates dozens of turns of tool results re-bills its entire transcript on every
+ *  inference — the context-overflow-one-level-up that the conserved budget pool cannot fix. With
+ *  compaction set, once the conversation exceeds `thresholdTokens` the accumulated middle (every prior
+ *  assistant turn + tool result) is distilled into ONE compact progress note and the conversation is
+ *  reset to `[...head, digest]`: the preserved head (system + the original task) survives, the stale
+ *  turn-by-turn history does not. The model keeps deciding; it stops re-billing the whole transcript.
+ *  Fires at a CLEAN turn boundary (after a turn's tool results are folded in, before the next
+ *  inference) so it never orphans an assistant `tool_calls` from its `tool` replies. */
+interface ToolLoopCompaction {
+  /** Compact once the estimated token count of the conversation exceeds this. */
+  readonly thresholdTokens: number;
+  /** Distill the conversation into a compact progress note that REPLACES the middle. Receives the
+   *  full conversation (so it can summarize everything done so far); returns the digest string. */
+  readonly distill: (messages: ReadonlyArray<ToolLoopMessageRecord>) => Promise<string> | string;
+  /** Leading messages preserved verbatim (system + the original task). Default 2. */
+  readonly preserveHead?: number;
+  /** Token estimator over the conversation. Default ≈ chars/4 (incl. tool-call arguments). */
+  readonly estimateTokens?: (messages: ReadonlyArray<ToolLoopMessageRecord>) => number;
+  /** Notified each time a compaction fires — for observability/metering. */
+  readonly onCompact?: (info: {
+    turn: number;
+    beforeTokens: number;
+    afterTokens: number;
+  }) => void;
+}
+/** Public supervisor-facing compaction config: same knobs as the primitive, but `distill` is optional
+ *  because the supervisor has a default digest that combines a brain note with live worker state. */
+type ToolLoopCompactionOptions = Omit<ToolLoopCompaction, 'distill'> & {
+  readonly distill?: ToolLoopCompaction['distill'];
+};
+//#endregion
+//#region src/runtime/router-client.d.ts
+/**
+ * Connection details for Runtime's Router-backed executors.
+ *
+ * This is deliberately transport-only: model, prompt, tools, generation settings, and retry
+ * policy belong to the exact executable `AgentProfile` consumed by `streamAgentTurn`.
+ */
+interface RouterTransportConfig {
+  routerBaseUrl: string;
+  routerKey: string;
+  /** Injectable OpenAI-compatible transport for offline execution. */
+  complete?: (body: Record<string, unknown>, request?: {
+    readonly headers: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+  }) => Promise<unknown>;
+}
+/**
+ * Private request configuration used by Runtime's Router adapter.
+ *
+ * Do not export this through a package entry point. Public callers execute a concrete
+ * `AgentProfile` through `createExecutor` + `streamAgentTurn`; only Runtime may lower that profile
+ * into these provider request fields.
+ */
+interface RouterConfig extends RouterTransportConfig {
+  model: string;
+  /** Exact retry controls lowered from `AgentProfile.model.metadata.retry`. */
+  retry?: RouterRetryPolicy;
+  /**
+   * Optional ceiling for one completion, forwarded as `max_tokens`.
+   *
+   * A REASONING model spends this budget on hidden thinking BEFORE it emits a visible token, so
+   * the default can truncate one mid-thought and return no content at all — observed live with a
+   * model that spent 8,188 of the 8,192 on reasoning and answered with nothing. Raise it for a
+   * thinking model; the ceiling belongs to the router and model a caller chose, which is why it
+   * lives here rather than on one call site.
+   */
+  maxTokens?: number;
+  /**
+   * Take the tool-calling completion over SSE instead of one buffered POST. Off by default —
+   * `routerChatWithTools` never streams, and every existing caller keeps the buffered transport
+   * byte for byte.
+   *
+   * Why it exists: a buffered POST holds one connection idle for the WHOLE completion, and a
+   * supervisor turn is the longest completion in the system. An intermediary gateway with an
+   * idle-read timeout kills that connection mid-completion (the 524/503 family). A streamed
+   * response puts bytes on the wire from the first generated token on, so the connection is only
+   * idle through prefill. It does NOT shorten prefill, so a gateway whose deadline is
+   * time-to-FIRST-byte is unaffected; only an idle-timeout gateway is.
+   *
+   * Mutually exclusive with `complete`: the injected transport returns one parsed JSON body and has
+   * no stream to read, so setting both throws rather than silently taking the buffered path.
+   *
+   * WHICH PATHS CAN OPT IN. This flag is read in exactly one place (the private `chatWithTools` transport switch), so
+   * every entry point that takes a caller-supplied `RouterConfig` honors it: `routerBrain`,
+   * `routerToolLoop`, and `supervisorAgent` (which spreads `deps.router` into the brain's config —
+   * the supervisor turn this exists for). Two production call sites build a `RouterConfig` literal
+   * from their own options and therefore CANNOT express it today: the bench strategy's
+   * `routerToolLoop` config in `strategy.ts` and the local sandbox client's `routerBrain` config in
+   * `local-sandbox-client.ts`. Neither drives a supervisor-length turn; setting `stream` on a
+   * config handed to either has no path to reach them, and they stay buffered.
+   */
+  stream?: boolean;
+}
+interface ToolSpec {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters: unknown;
+  };
+}
+//#endregion
+//#region src/mcp/worktree.d.ts
+/**
+ *
+ * Git worktree helpers for the in-process delegation executor. Each
+ * delegation runs in its own worktree so multiple parallel harness
+ * subprocesses (claude / codex / opencode in a 3-way fanout) don't clobber
+ * each other's edits on the shared workspace.
+ *
+ * Worktrees live under `<repoRoot>/.agent-worktrees/<runId>/`. After the
+ * harness exits + the diff is captured, the worktree is removed.
+ *
+ * All operations spawn `git` via `child_process.spawn` synchronously
+ * (via a `runGit` helper). Stays narrow on purpose: no commits, no rebases.
+ * Diff capture stages all changes (`git add -A`) into the ephemeral worktree's
+ * index so created (untracked) files appear in the `--cached` diff.
+ *
+ * @experimental
+ */
+/** @experimental */
+interface WorktreeHandle {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** SHA the worktree was created at. */
+  baseSha: string;
+  /** Branch name created for this worktree (typically `delegate/<runId>`). */
+  branch: string;
+}
+/** @experimental */
+interface CreateWorktreeOptions {
+  /** Absolute path to the main git checkout. */
+  repoRoot: string;
+  /** Unique id for the worktree path + branch. Use the delegation run id. */
+  runId: string;
+  /** Parent directory the worktree lives under. Defaults to `.agent-worktrees`. */
+  variantsDir?: string;
+  /** Override the base ref (default `HEAD`). */
+  baseRef?: string;
+  /** Test seam — inject a custom git runner. */
+  runGit?: GitRunner;
+}
+/** @experimental */
+interface DiffOptions {
+  /** Worktree to diff. */
+  worktree: WorktreeHandle;
+  /** What to compare against. Default `worktree.baseSha`. */
+  baseRef?: string;
+  /**
+   * Repository-relative input paths to omit from the captured worker patch.
+   * Paths are passed to Git with literal exclusion magic, so profile-provided
+   * `*`, `?`, `[` and `:` characters can never expand into broader pathspecs.
+   */
+  excludePaths?: ReadonlyArray<string>;
+  /** Test seam. */
+  runGit?: GitRunner;
+}
+/** @experimental */
+interface DiffResult {
+  patch: string;
+  stats: {
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+  };
+}
+/** @experimental */
+interface RemoveWorktreeOptions {
+  worktree: WorktreeHandle;
+  repoRoot: string;
+  /** Force removal even if dirty (default true; the loser of a fanout has uncommitted changes). */
+  force?: boolean;
+  /** Test seam. */
+  runGit?: GitRunner;
+}
+/** Pluggable git runner (sync) — replaceable in tests. */
+type GitRunner = (args: ReadonlyArray<string>, opts: {
+  cwd: string;
+}) => {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+/** Checkout a fresh git worktree for a delegation run on a new branch under `variantsDir`. @experimental */
+declare function createWorktree(options: CreateWorktreeOptions): Promise<WorktreeHandle>;
+/** Stage worker changes and return the diff + shortstat, excluding declared input paths. @experimental */
+declare function captureWorktreeDiff(options: DiffOptions): Promise<DiffResult>;
+/**
+ * Remove a git worktree and delete its branch. Already-removed paths are harmless; every other
+ * Git failure rejects so callers cannot report a worktree as destroyed when cleanup failed.
+ * @experimental
+ */
+declare function removeWorktree(options: RemoveWorktreeOptions): Promise<void>;
+//#endregion
+//#region src/mcp/local-harness.d.ts
+/**
+ * Local coding harness available inside the sandbox — a narrowing of the shared `HarnessType`
+ * vocabulary, NOT a private spelling of it. The harness id is `claude-code`; `claude` is the
+ * EXECUTABLE name and lives only in the `command` field below. Keeping one vocabulary is what
+ * lets a `LocalHarness` be handed straight to the profile materializer and the capability table
+ * with no translation step.
+ */
+type LocalHarness = Extract<HarnessType, 'claude-code' | 'codex' | 'opencode'>;
+/** Every local harness, in table order — the one list `AGENT_RUNTIME_LOCAL_HARNESSES` and any
+ *  other harness enumeration reads, so adding a row above is the only edit a new harness needs. */
+declare const LOCAL_HARNESSES: ReadonlyArray<LocalHarness>;
+/** The harness a caller gets when it expresses no preference. A composition-root default, not a
+ *  capability claim: one constant so the several entry points cannot drift apart. */
+declare const DEFAULT_LOCAL_HARNESS: LocalHarness;
+/** The CLI binary a harness id runs. The two are NOT the same string (`claude-code` runs `claude`),
+ *  so anything spawning a harness — a version probe, a login check — reads it from here rather than
+ *  passing the harness id as a command. */
+declare function localHarnessExecutable(harness: LocalHarness): string;
+/**
+ * Whether the harness's native control can express this reasoning effort. Admission checks read
+ * this so a profile the invocation would later refuse is rejected BEFORE any workspace state is
+ * created, against the same table that emits the argv.
+ */
+declare function harnessSupportsReasoningEffort(harness: LocalHarness, reasoningEffort: ReasoningEffort): boolean;
+/** @experimental */
+interface RunLocalHarnessOptions {
+  harness: LocalHarness;
+  /** Working directory for the subprocess (typically a worktree path). */
+  cwd: string;
+  /** Prompt forwarded as the harness CLI's task argument. */
+  taskPrompt: string;
+  /**
+   * Pre-built command + args (e.g. from `harnessInvocation` so the full authored
+   * `AgentProfile` — systemPrompt + model — reaches the harness). When set it OVERRIDES the
+   * default prompt-only `buildArgs(taskPrompt)` path; `command` defaults to the harness's
+   * default binary when only `args` is supplied. When absent the legacy prompt-only shape
+   * is used unchanged.
+   */
+  invocation?: {
+    command?: string;
+    args: ReadonlyArray<string>;
+  };
+  /** Allow autonomous edits without an interactive approval gate, using whichever bypass argv the
+   *  harness declares. Use only when `cwd` is an isolated candidate worktree. */
+  dangerouslySkipPermissions?: boolean;
+  /** Isolate Codex from ambient configuration/instructions and require JSONL token usage.
+   *  The invocation should come from `harnessInvocation(..., { codexReproducible: true })`. */
+  codexReproducible?: boolean;
+  /** Absolute host paths that reproducible Codex must not read. The normalized set is compiled
+   *  into the controlled permission profile and its digest is returned in execution evidence. */
+  codexReadDeniedPaths?: ReadonlyArray<string>;
+  /** Wall-clock kill deadline (ms). Default 5 min. Subprocess SIGTERMed on expiry. */
+  timeoutMs?: number;
+  /** Newest stdout/stderr bytes retained per stream. Default 64 MiB. */
+  maxOutputBytes?: number;
+  /** Caller cancellation. SIGTERM is sent on abort. */
+  signal?: AbortSignal;
+  /** Override env (defaults to inheriting from the parent). */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Test seam — inject a custom spawner so unit tests can mock the
+   * subprocess without touching the OS. Defaults to node's `child_process.spawn`.
+   */
+  spawn?: (command: string, args: ReadonlyArray<string>, opts: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio: 'pipe';
+    detached: boolean;
+  }) => ChildProcess;
+  /** Test seam for locating the native Codex executable before it is staged in the worktree. */
+  resolveCodexExecutable?: (command: string, env: NodeJS.ProcessEnv) => Promise<string>;
+}
+/** Exact aggregate usage emitted by Codex's terminal `turn.completed` JSONL event. */
+interface CodexTokenUsage {
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+  reasoningOutputTokens: number;
+}
+/** Isolation settings asserted before a reproducible Codex run is allowed to start. */
+interface CodexExecutionPolicy {
+  sessionPersistence: 'ephemeral';
+  userConfig: false;
+  rules: false;
+  projectInstructions: false;
+  skillInstructions: false;
+  appInstructions: false;
+  toolSuggestions: false;
+  multiAgentInstructions: false;
+  sandbox: 'workspace-write';
+  permissionProfile: 'agent_runtime_reproducible';
+  approvalPolicy: 'never';
+  shellNetwork: false;
+  webSearch: false;
+  serviceTier: 'default';
+  shellEnvironment: 'core-filtered';
+  loginShell: false;
+  credentialsReadable: false;
+  hostHomeReadable: false;
+  procEnvironment: 'private-sanitized';
+  sensitiveEnvironmentNamesVisible: false;
+  parentRepoRead: false;
+  gitMetadata: false;
+  temporaryDirectory: 'workspace-private';
+  stagedExecutable: 'static-elf-read-only';
+  callerReadDeniedPaths: 'enforced';
+  containerSockets: false;
+}
+/** Zero-model-call evidence for the exact Codex process about to run. */
+interface CodexExecutionEvidence {
+  cliVersion: string;
+  executableSha256: string;
+  /** SHA-256 of the exact composed prompt argument proved present in the rendered prompt. */
+  requestedPromptSha256: string;
+  effectivePromptSha256: string;
+  nonPromptArgsSha256: string;
+  controlledConfigSha256: string;
+  /** Sorted normalized paths compiled into the permission profile. */
+  readDeniedPaths: string[];
+  readDeniedPathsSha256: string;
+  readDeniedPathCount: number;
+  policy: CodexExecutionPolicy;
+}
+/** @experimental */
+interface LocalHarnessResult {
+  /** OS exit code. `null` when killed before exit. */
+  exitCode: number | null;
+  /** Concatenated stdout. */
+  stdout: string;
+  /** Concatenated stderr. */
+  stderr: string;
+  /** Set when the process exited via signal (timeout / abort). */
+  killedBySignal: NodeJS.Signals | null;
+  /** Wall-clock duration ms (spawn → exit). */
+  durationMs: number;
+  /** Set when timeoutMs elapsed before exit. */
+  timedOut: boolean;
+  /**
+   * Set when the caller's AbortSignal fired before this result settled.
+   * Optional so injected runners and stored results from older releases remain valid.
+   */
+  aborted?: boolean;
+  /** Present for a reproducible Codex run; parsed from the real terminal JSONL event. */
+  usage?: CodexTokenUsage;
+  /** Present for reproducible Codex runs; generated and checked before model execution. */
+  evidence?: CodexExecutionEvidence;
+}
+/**
+ * Spawn a local coding harness CLI as a subprocess + collect its output.
+ *
+ * NOT responsible for parsing the harness's output or extracting a diff —
+ * the in-process executor's `streamPrompt` orchestrates `git diff` against
+ * the worktree after this resolves. This function is intentionally narrow:
+ * spawn, wait, capture, return.
+ *
+ * Fails loud — throws when:
+ *   - `cwd` doesn't exist (subprocess emits ENOENT; surfaced as Error)
+ *   - the harness binary is not on PATH (ENOENT)
+ *   - the caller signal was already aborted before process launch
+ *
+ * Does NOT throw when:
+ *   - the subprocess exits non-zero (`result.exitCode` carries the code)
+ *   - a non-reproducible subprocess is aborted / timed out (`result.aborted` /
+ *     `result.timedOut` carries the reason even when a TERM-aware child exits zero)
+ *
+ * Reproducible Codex additionally requires a terminal usage event. If cancellation
+ * prevents that event, this rejects with `CodexExecutionDiagnosticError` instead of
+ * returning an incomplete reproducibility receipt.
+ *
+ * @experimental
+ */
+declare function runLocalHarness(options: RunLocalHarnessOptions): Promise<LocalHarnessResult>;
+/** Parse and validate the one terminal usage event emitted by `codex exec --json`. */
+declare function parseCodexTokenUsage(stdout: string): CodexTokenUsage;
+//#endregion
+//#region src/mcp/worktree-harness.d.ts
+/** Outcome of one verification command run in the worktree (test or typecheck). */
+interface WorktreeCommandResult {
+  /** The shell command line that was run. */
+  command: string;
+  /** Did the command exit 0? The PASS signal a deliverable gate / coder output reads. */
+  passed: boolean;
+  /** OS exit code, or `null` when killed before exit. */
+  exitCode: number | null;
+  /** Combined stdout+stderr (capped) — surfaced in traces for diagnosis. */
+  output: string;
+}
+/** Proof of the profile inputs delivered before the worker process started. */
+interface WorktreeProfileMaterializationReceipt {
+  /** Digest of the exact materializer plan: files, modes, environment, flags, and unsupported rows. */
+  workspacePlanDigest: string;
+  /** Repository-relative profile input files written into the worker worktree. */
+  writtenPaths: string[];
+  /** Must be empty on a successful run because this path fails closed. */
+  unsupported: WorkspacePlanReceipt['unsupported'];
+  /** Environment variable names added to the worker process. Values remain out of telemetry. */
+  environmentNames: string[];
+  /** Exact additional CLI arguments emitted by the materializer. */
+  flags: string[];
+  /** `resources.instructions` bypasses native project files so reproducible Codex cannot drop it. */
+  resourceInstructions: {
+    delivery: 'none' | 'invocation-prompt';
+    sha256: string | null;
+    byteLength: number;
+  };
+}
+/** The canonical result of one worktree-harness run, projected by each port to its own shape. */
+interface WorktreeHarnessResult {
+  /** The branch the worktree was cut on (`delegate/<runId>`). */
+  branch: string;
+  /** `git diff` of the worktree against its base — the unified patch the harness produced. */
+  patch: string;
+  /** Shortstat-derived change counts. */
+  stats: {
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+  };
+  /**
+   * Exact profile materialization applied before the harness launched.
+   * Absent on transports that cannot return a materializer receipt; never fabricated.
+   */
+  profileMaterialization?: WorktreeProfileMaterializationReceipt;
+  /** The harness subprocess outcome. */
+  harness: {
+    name: LocalHarness | 'bridge';
+    exitCode: number | null;
+    timedOut: boolean;
+    killedBySignal: NodeJS.Signals | null;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+    /** Exact Codex JSONL usage when reproducible mode is enabled. */
+    usage?: CodexTokenUsage;
+    /** Installed CLI version captured immediately before execution. */
+    cliVersion?: string;
+    /** SHA-256 of the native Codex executable staged read-only in the candidate worktree. */
+    executableSha256?: string;
+    /** SHA-256 of the exact composed prompt argument proved present in Codex's rendered prompt. */
+    requestedPromptSha256?: string;
+    /** SHA-256 of `codex debug prompt-input` output for the exact isolated prompt. */
+    effectivePromptSha256?: string;
+    /** SHA-256 of the exact executable + argv with prompt content replaced by `<PROMPT>`. */
+    nonPromptArgsSha256?: string;
+    /** SHA-256 of the isolated config that fixes permissions and shell environment. */
+    controlledConfigSha256?: string;
+    /** SHA-256 of the normalized caller-supplied host read-denial paths. */
+    readDeniedPathsSha256?: string;
+    /** Sorted normalized caller-supplied host read-denial paths. */
+    readDeniedPaths?: string[];
+    /** Number of normalized caller-supplied host read-denial paths. */
+    readDeniedPathCount?: number;
+    /** Explicit isolation claims checked before model execution. */
+    executionPolicy?: CodexExecutionPolicy;
+  };
+  /** Verification signals derived in the live worktree (present only when commands were given). */
+  checks?: {
+    tests?: WorktreeCommandResult;
+    typecheck?: WorktreeCommandResult;
+  };
+}
+/** The single shell-command-in-worktree runner seam (replaces the per-executor copies). */
+type WorktreeCheckRunner = (opts: {
+  command: string;
+  cwd: string;
+  timeoutMs: number;
+  signal?: AbortSignal;
+}) => Promise<{
+  exitCode: number | null;
+  output: string;
+}>;
+//#endregion
+//#region src/runtime/supervise/inbox.d.ts
+/**
+ *
+ * The worker-side receive end of the down-leg: a per-worker inbox an executor exposes as
+ * `Executor.deliver`. The driver's `steer_agent` / `answer_question` land here,
+ * and the worker's agent loop drains them at two points (Drew's two delivery modes):
+ *
+ *   - QUEUED (default): the message accumulates and is FLUSHED at the next step boundary — folded
+ *     into the conversation before the next think. A worker is also forced to flush BEFORE it may
+ *     settle, so it can never finish while a steer/answer it never read is still pending.
+ *   - FORCEFUL (`interrupt: true`): trips `freshInterrupt()`'s signal so the loop can abort its
+ *     in-flight turn immediately, then re-plan with the message folded in — breaking the worker out
+ *     of a wrong path mid-task instead of waiting for it to finish the step.
+ *
+ * `deliver` never throws — a malformed message is ignored and returns `false`, so no caller can
+ * report delivery for bytes this inbox discarded.
+ *
+ * @experimental
+ */
+interface InboxMessage {
+  readonly kind: 'steer' | 'answer';
+  readonly text: string;
+  /** Forceful messages abort the in-flight turn; queued ones wait for the boundary flush. */
+  readonly interrupt: boolean;
+  /** Present for an `answer` — the question id it resolves. */
+  readonly questionId?: string;
+}
+interface Inbox {
+  /** The `Executor.deliver` implementation. Returns false when the raw message is malformed and
+   * therefore was not queued; callers must not acknowledge a message this inbox discarded. */
+  deliver(msg: unknown): boolean;
+  /** Remove and return all pending messages (the flush). */
+  drain(): InboxMessage[];
+  pending(): number;
+  /** Open a fresh per-turn interrupt signal; a later forceful `deliver` aborts it. The loop links
+   *  this into the signal it passes to its inference call, then re-plans when it fires. */
+  freshInterrupt(): AbortSignal;
+  /** Render drained messages as ONE operator turn to fold into the worker's conversation. */
+  fold(messages: ReadonlyArray<InboxMessage>): string;
+}
+/** Create the worker-side inbox for the down-leg: the driver's `steer_agent` / `answer_question` messages queue here and the worker's loop drains them at step boundaries and before settle. */
+declare function createInbox(): Inbox;
+//#endregion
+//#region src/runtime/supervise/sandbox-session.d.ts
+/** Ceiling on continuation turns. Turn 0 is the task; every later turn is a folded steer, so
+ *  this bounds how many times a supervisor may redirect ONE worker before it must respawn. */
+declare const DEFAULT_SANDBOX_STEERING_MAX_TURNS = 24;
+/** Opt-in configuration for the steerable sandbox worker (`SandboxSeam.steering`). Absent, the
+ *  sandbox executor keeps its historical single-shot `runAgentRounds` composition verbatim. */
+interface SandboxSteeringOptions {
+  /** Max turns for one worker (turn 0 + folded steers). Default {@link DEFAULT_SANDBOX_STEERING_MAX_TURNS}. */
+  readonly maxTurns?: number;
+  /** How many recent tool/turn notes `progress()` reports. Default 12. */
+  readonly activityWindow?: number;
+  /** Per-turn wall-clock ceiling; the turn's stream is aborted when it elapses. */
+  readonly turnTimeoutMs?: number;
+}
+/** What the steerable session exposes to its executor: the usage stream plus the live reads. */
+interface SteerableSandboxSession {
+  /** Drive the worker to settlement. `signal` is the spawn-scoped abort handed to `execute`. */
+  stream(task: unknown, signal: AbortSignal): AsyncIterable<UsageEvent>;
+  progress(): ExecutorProgress;
+  traceSource(): TraceSource;
+  artifact(): {
+    outRef: string;
+    out: unknown;
+    spent: Spend;
+  } | undefined;
+  teardown(): Promise<void>;
+}
+interface SteerableSandboxArgs {
+  readonly controller: AbortController;
+  readonly profile: AgentProfile;
+  readonly harness: BackendType;
+  readonly sandboxClient: SandboxClient;
+  readonly inbox: Inbox;
+  readonly taskToPrompt: (task: unknown) => string;
+  readonly options?: SandboxSteeringOptions;
+  readonly loopCtx?: Partial<Omit<ExecCtx, 'sandboxClient' | 'signal'>>;
+  /**
+   * Inherited `TRACE_ID` / `PARENT_SPAN_ID` for the box, merged into `CreateSandboxOptions.env` so
+   * the remote worker's own spans join the supervisor's trace under the spawning node's span.
+   * Absent when the run records no spans — the create options are then untouched.
+   */
+  readonly traceEnv?: Record<string, string>;
+  readonly contentRef: (prefix: string, value: unknown) => string;
+  readonly now?: () => number;
+}
+/** One steerable sandbox worker. The returned session is inert until `stream()` is drained. */
+declare function createSteerableSandboxSession(args: SteerableSandboxArgs): SteerableSandboxSession;
+//#endregion
+//#region src/runtime/supervise/runtime.d.ts
+/**
+ * Router/inline transport seam. The profile owns model, prompt, and generation behavior.
+ */
+interface RouterSeam {
+  routerBaseUrl: string;
+  routerKey: string;
+  /** Injectable transport for offline/local execution; still passes through Runtime metering. */
+  complete?: RouterConfig['complete'];
+  /** When present, return one turn's requested tool calls without executing them. */
+  tools?: ReadonlyArray<ToolSpec>;
+}
+/**
+ * Sandbox executor seam. The `sandboxClient` the composed `runAgentRounds` creates
+ * boxes through, plus the optional trace/run/lineage wiring forwarded into the
+ * loop. `lineage` is opaque here (PR #150's `RunAgentRoundsOptions.lineage`): forwarded
+ * forward-compatibly, never inspected — this executor does NOT reinvent
+ * checkpoint/fork.
+ */
+interface SandboxSeam {
+  sandboxClient: SandboxClient;
+  /** Forwarded into the composed `runAgentRounds`'s `ctx` (trace emitter, run handle, etc.). */
+  loopCtx?: Partial<Omit<ExecCtx, 'sandboxClient' | 'signal'>>;
+  /** PR #150 `RunAgentRoundsOptions.lineage` passthrough — opaque; forwarded, not parsed. */
+  lineage?: unknown;
+  /** Hard cap on the composed loop's iterations. The budget pool reserves against
+   *  the spawn `Budget.maxIterations`; this is the leaf's own ceiling. Default 1. */
+  maxIterations?: number;
+  /**
+   * OPT-IN: run this worker as a multi-turn, STEERABLE session instead of the historical
+   * single-shot `runAgentRounds` composition. Setting it gives the sandbox worker an `Executor.deliver`
+   * inbox (so `Scope.send` / `steer_agent` actually reach it), a live tool-activity trace, and a
+   * `progress()` read — turning the default cloud worker from something a supervisor can only
+   * wait on into something it can watch and correct.
+   *
+   * Absent, nothing changes: the same `runAgentRounds` leaf, no inbox, `steer_agent` still reports
+   * `delivered:false`. Opt-in because a steerable worker holds ONE box across several turns,
+   * which is a different resource profile from a fire-and-forget shot.
+   */
+  steering?: SandboxSteeringOptions;
+}
+/**
+ * UNMETERED CLI subprocess seam. `bin` + `args` describe the process to spawn.
+ *
+ * READ THIS BEFORE CHOOSING `backend: 'cli'`. This backend pipes a prompt to a subprocess's stdin
+ * and reads its stdout. It has no usage receipt of any kind, so it reports its spend with
+ * `Spend.tokensKnown: false`: the work is recorded, its `{0,0}` tokens and `$0` are a FLOOR rather
+ * than a measurement, and a ceiling priced from either is a ceiling that cannot fire. The executor
+ * is also `budgetExempt: true`, which is why `driveHarnessFromBackend` refuses it outright rather
+ * than pretending to budget it.
+ *
+ * If you need a metered harness worker, use `backend: 'bridge'` (a cli-bridge session, which
+ * reports the harness's real per-turn tokens and cost) or `backend: 'cli-worktree'` with
+ * `codexReproducible`. Reach for this seam only when the subprocess genuinely is not an inference
+ * agent, or when you have accepted that its cost is invisible.
+ *
+ * `args` is argv for a LOCAL, in-process spawn under this process's own privileges. It is not a
+ * remote channel and nothing forwards it over a wire.
+ */
+interface CliSeam {
+  bin: string;
+  args?: string[];
+  /** Extra environment for the subprocess (merged over `process.env`). */
+  env?: Record<string, string>;
+  /** Working directory for the subprocess. */
+  cwd?: string;
+}
+/**
+ * cli-worktree seam. A supervisor-authored `AgentProfile` driving a local coding-harness CLI
+ * (claude / codex / opencode) on its own git worktree — the leaf `createWorktreeCliExecutor`
+ * named as data. `repoRoot` is transport data; `AgentProfile.harness` selects the CLI.
+ * `taskPrompt` remains an optional direct-call fallback for callers that execute with `undefined`.
+ * The authored
+ * `profile.prompt.systemPrompt` + `profile.model.default` reach the harness via the §1.5
+ * `harnessInvocation` mapper. Everything else mirrors `WorktreeCliExecutorOptions`.
+ */
+interface CliWorktreeSeam {
+  repoRoot: string;
+  taskPrompt?: string;
+  runId?: string;
+  baseRef?: string;
+  harnessTimeoutMs?: number;
+  /** Isolated, network-off Codex execution with terminal JSONL usage capture. */
+  codexReproducible?: boolean;
+  /** Absolute host paths denied to reproducible Codex. */
+  codexReadDeniedPaths?: ReadonlyArray<string>;
+  testCmd?: string;
+  typecheckCmd?: string;
+  checkTimeoutMs?: number;
+  checkOutputCap?: number;
+  budgetExempt?: boolean;
+  /** Live cli-bridge transport inside the worktree. When set, the worktree leaf accepts
+   *  `deliver()` messages and resumes the same bridge session in this worktree cwd. */
+  bridge?: CliWorktreeBridgeSeam;
+  /** Test seam — forwarded to worktree helpers. */
+  runGit?: GitRunner;
+  /** Test seam — forwarded to verification checks. */
+  runCommand?: WorktreeCheckRunner;
+}
+interface CliWorktreeBridgeSeam {
+  bridgeUrl: string;
+  bridgeBearer: string;
+  /** Caller-owned deadline for each bridge turn. Runtime enforces it locally and sends the
+   *  same value in `execution.timeoutMs` so cli-bridge cannot substitute its own cutoff. */
+  timeoutMs?: number;
+  /** Stable cli-bridge session id. Defaults to `bridge-worktree-${runId}`. */
+  sessionId?: string;
+  /** Transport reconnects allowed after the first POST. Default 3; set 0 to disable. */
+  maxReconnects?: number;
+}
+/**
+ * cli-bridge seam. A local OpenAI-compatible bridge that fronts harness CLIs
+ * (claude-code / opencode / kimi / pi) behind one HTTP surface. The spawned
+ * `AgentProfile` is the sole harness/provider/model and behavioral authority and
+ * is forwarded verbatim per request; this seam carries transport data only.
+ *
+ * The executor opens a resumable cli-bridge session. `sessionId` identifies the
+ * harness conversation across turns; each turn also receives its own durable run id.
+ * A dropped HTTP reader reattaches to that exact run and explicit cancel is the only
+ * operation allowed to stop it. Omit `sessionId` and the executor mints one per spawn.
+ *
+ * ── HOW TO CONTROL WHAT THE HARNESS LOADS (there is no argv field, by design) ──
+ *
+ * A worker often needs the harness started in a KNOWN state — no ambient extensions, skills,
+ * context files, or prompt templates — because ambient state is how a paired experiment silently
+ * loses its pairing: an installed extension that persists memory across runs carries arm A's state
+ * into arm B, and nothing reports it.
+ *
+ * That is what the spawned `AgentProfile` is FOR. `agent_profile`
+ * rides every request verbatim, and cli-bridge maps it onto each harness's own native controls:
+ *
+ *   - Materializing any profile at all already starts the harness isolated from ambient
+ *     workspace state — for pi that is `--no-context-files --no-skills --no-prompt-templates`,
+ *     applied to every request that carries an `agent_profile`.
+ *   - `AgentProfile.extensions.<harness>` is the named, per-harness control channel. An explicit
+ *     `extensions: { pi: { load: [] } }` disables ambient extension discovery outright
+ *     (pi's `--no-extensions`); listing package names loads exactly those and nothing else.
+ *   - `permissions` / `tools` / `mcp` map onto the harness's native tool and server controls.
+ *
+ * A caller therefore does NOT need to hand-roll an `Executor` to isolate a harness run, and the
+ * profile expressing it stays portable: the same declaration means the same thing on a different
+ * harness, whereas an argv string means nothing anywhere else.
+ *
+ * WHY NOT A GENERAL ARGV PASSTHROUGH. `bridgeUrl` addresses a process-spawning server. Forwarding
+ * an arbitrary argv array to it would let any caller holding a bearer token choose the flags of a
+ * process on the bridge host — which for real harness CLIs includes flags that load code from a
+ * path, read a file into the prompt, redirect the working directory, or turn off the isolation the
+ * bridge applies. cli-bridge deliberately confines workers (a filesystem jail and deny-by-default
+ * network egress), and every one of those confinements is expressed as spawn configuration, so an
+ * argv channel is a channel for unwinding them. It would also break this executor's own contract:
+ * the durable-run replay protocol, session pinning, and streaming mode are all argv the bridge
+ * owns, and a caller-supplied duplicate silently wins or corrupts the parse. The structured profile
+ * channel is validated, per-harness, portable, and refuses controls it does not understand — keep
+ * new harness capability there.
+ */
+interface BridgeSeam {
+  bridgeUrl: string;
+  bridgeBearer: string;
+  /** Optional working directory forwarded to cli-bridge and persisted with the session. */
+  cwd?: string;
+  /** Caller-owned deadline for each bridge turn. Runtime enforces it locally and sends the
+   *  same value in `execution.timeoutMs` so the bridge-owned process follows the same policy. */
+  timeoutMs?: number;
+  /** Stable, caller-owned cli-bridge session id for harness-side resume. Defaults
+   *  to a freshly minted per-spawn id so each worker is its own resumable session. */
+  sessionId?: string;
+  /** Transport reconnects allowed after the first POST. Default 3; set 0 to disable. */
+  maxReconnects?: number;
+  /** Newest-last activity window `progress()` reports. Default 12. */
+  activityWindow?: number;
+}
+/** Generic environment provider executor config. External packages implement
+ *  `AgentEnvironmentProvider`; this built-in wrapper lets `createExecutor`
+ *  consume them as backend data while preserving the existing usage channel. */
+interface ProviderSeam extends ProviderExecutorOptions {
+  provider: AgentEnvironmentProvider | string;
+  registry?: AgentEnvironmentProviderRegistry;
+  /**
+   * Compose the provider through the existing steerable sandbox session.
+   * The exact profile must name its harness, and the provider must expose live
+   * continuation plus session controls. The provider still owns environment
+   * creation and session semantics.
+   */
+  steering?: SandboxSteeringOptions;
+}
+/**
+ * Router seam WITH tool use — the tool-using router backend. Same direct
+ * OpenAI-compatible endpoint as `RouterSeam`, but each turn passes `tools`; when
+ * the model emits tool_calls they run via `executeToolCall` ON THIS HOST and the
+ * results fold back as `tool` messages, repeating until the model answers without
+ * a tool or `maxTurns` is hit. A real agentic loop, OFF-BOX — no sandbox, so it
+ * is unaffected by a box's egress allowlist. One turn = one completion = the
+ * equal-compute unit. `executeToolCall` receives the task so per-task tool
+ * surfaces (e.g. a gym keyed by task) can dispatch correctly.
+ */
+interface RouterToolsSeam {
+  routerBaseUrl: string;
+  routerKey: string;
+  complete?: RouterConfig['complete'];
+  tools: ReadonlyArray<ToolSpec>;
+  executeToolCall: (name: string, args: Record<string, unknown>, task: unknown) => Promise<string>;
+  /** Exact conversation to continue. Runtime validates its system message against the profile. */
+  initialMessages?: ReadonlyArray<Readonly<Record<string, unknown>>>;
+  /** Observe the detached final conversation for session persistence. */
+  onMessages?: (messages: ReadonlyArray<Readonly<Record<string, unknown>>>) => void | Promise<void>;
+  /** Online observer of each tool step — the seam a `DetectorMonitor` taps to watch the live pipe
+   *  (raise a `finding` when the worker loops/errors). Called after every tool call resolves, with
+   *  real per-call wall-clock (`startedAt`/`endedAt`/`durationMs`) so a push `TraceSource` can carry
+   *  non-zero span durations onto the unified timeline. */
+  onToolStep?: (step: {
+    toolName: string;
+    args: Record<string, unknown>;
+    status: 'ok' | 'error';
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+  }) => void;
+}
+/**
+ * The leaf `createWorktreeCliExecutor` as a backend-as-data factory: a supervisor-authored
+ * `AgentProfile` driving claude / codex / opencode on its own worktree. `budgetExempt` like
+ * the other CLI leaves; the authored systemPrompt + model reach the harness via §1.5.
+ */
+declare const cliWorktreeExecutor: ExecutorFactory<unknown>;
+/**
+ * Config for {@link createExecutor}: the backend is DATA — the cost dial a profile,
+ * an experiment config, or a replay journal can name — not an import choice. Each
+ * variant carries its backend's seam (router/router-tools/bridge/cli/cli-worktree/sandbox).
+ */
+type ExecutorConfig = ({
+  backend: 'router';
+} & RouterSeam) | ({
+  backend: 'router-tools';
+} & RouterToolsSeam) | ({
+  backend: 'bridge';
+} & BridgeSeam) | ({
+  backend: 'cli';
+} & CliSeam) | ({
+  backend: 'cli-worktree';
+} & CliWorktreeSeam) | ({
+  backend: 'provider';
+} & ProviderSeam) | ({
+  backend: 'sandbox';
+} & SandboxSeam);
+/**
+ * The single built-in executor factory. Picks a leaf backend by data (`config.backend`),
+ * injects the matching seam, and delegates to that backend's built-in implementation.
+ * The `Executor` port stays OPEN: bring-your-own agents implement `Executor` directly, while Scope
+ * or `createExecutorRegistry` still parses and seals their exact profile before use. Use this instead of a
+ * per-vendor adapter or a closed `inline|sandbox|cli` switch — those bypass the
+ * `UsageEvent` reporting channel.
+ */
+declare function createExecutor(config: ExecutorConfig): ExecutorFactory<unknown>;
+/**
+ * The open resolver/registry. Pre-registers the three built-ins under their
+ * runtime tags (`'router'`, `'sandbox'`, `'cli'`) and accepts `register(name,
+ * factory)` for any additional runtime. A BYO `AgentSpec.executor` has highest routing precedence
+ * after the same exact-profile intake validation. Registration + BYO remain open extension points.
+ *
+ * `resolve` precedence (frozen in `ExecutorRegistry`): a BYO `spec.executorFactory` →
+ * `spec.executor` → `harness === null` → the `'router'` factory; else a registered factory for the
+ * harness-derived runtime (`'sandbox'` for any `BackendType`); else fail loud.
+ */
+declare function createExecutorRegistry(): ExecutorRegistry;
+//#endregion
+export { ToolLoopToolCall as $, LocalHarness as A, GitRunner as B, WorktreeHarnessResult as C, CodexTokenUsage as D, CodexExecutionPolicy as E, parseCodexTokenUsage as F, removeWorktree as G, WorktreeHandle as H, runLocalHarness as I, ToolLoopCallContext as J, RouterTransportConfig as K, CreateWorktreeOptions as L, RunLocalHarnessOptions as M, harnessSupportsReasoningEffort as N, DEFAULT_LOCAL_HARNESS as O, localHarnessExecutable as P, ToolLoopMessageRecord as Q, DiffOptions as R, WorktreeCommandResult as S, CodexExecutionEvidence as T, captureWorktreeDiff as U, RemoveWorktreeOptions as V, createWorktree as W, ToolLoopCompaction as X, ToolLoopChat as Y, ToolLoopCompactionOptions as Z, createSteerableSandboxSession as _, ExecutorConfig as a, createInbox as b, RouterToolsSeam as c, createExecutor as d, createExecutorRegistry as f, SteerableSandboxSession as g, SteerableSandboxArgs as h, CliWorktreeSeam as i, LocalHarnessResult as j, LOCAL_HARNESSES as k, SandboxSeam as l, SandboxSteeringOptions as m, CliSeam as n, ProviderSeam as o, DEFAULT_SANDBOX_STEERING_MAX_TURNS as p, ToolSpec as q, CliWorktreeBridgeSeam as r, RouterSeam as s, BridgeSeam as t, cliWorktreeExecutor as u, Inbox as v, WorktreeProfileMaterializationReceipt as w, WorktreeCheckRunner as x, InboxMessage as y, DiffResult as z };
+//# sourceMappingURL=runtime-D-QfLbSd.d.ts.map