@jini-ai/daemon 0.5.2 → 0.5.4

package/dist/agent-executor.d.ts

@@ -1,1665 +1,10 @@
 /**
- * `AgentExecutor` — the driver `RunLifecycle`'s own module doc names as the
- * missing piece: *"It does not spawn or signal a subprocess... A driver...
- * calls `emit()` for agent/stdout/stderr/error events, observes cancellation
- * via `onCancelRequested`, and calls `finish()` once it knows the real
- * outcome."* This module is that driver — it wires `@jini-ai/agent-runtime`'s
- * registry/launch-resolution/stream-parsers (previously a complete but
- * disconnected library, zero callers anywhere outside its own package) into
- * a real `node:child_process` spawn, feeding both `RunLifecycle.emit()` and
- * this package's own `@jini-ai/protocol` event envelope.
- *
- * ## v1 scope: all 24 registered agent defs
- *
- * `@jini-ai/agent-runtime`'s registry ships 24 built-in defs across four
- * `streamFormat` families. The JSON-stream-parser family — the four
- * `createXStreamHandler`-shaped parsers (`claude-stream-json`,
- * `json-event-stream`, `copilot-stream-json`, `qoder-stream-json`), covering
- * 9 defs (amp, codebuddy, claude, codex, cursor-agent, opencode, mimo,
- * copilot, qoder) — plus all 9 `acp-json-rpc` defs, plus the one `pi-rpc`
- * def (`pi`), are wired here. ACP and pi-rpc each own their own JSON-RPC
- * prompt-delivery protocol, so each takes its own lifecycle branch rather
- * than being treated as a stdout-tail parser; pi-rpc's events arrive through
- * the exact same `{type, ...}` vocabulary `translateAgentRuntimeEvent`
- * already handles for ACP/JSON-stream (confirmed by reading every
- * `mapPiRpcEvent` `send()` call site — no new translation code was needed),
- * so only the driver wiring (spawn → attach → cancel → finish) was new for it.
- *
- * All 5 `streamFormat: 'plain'` defs — grok-build, aider, deepseek, qwen,
- * antigravity — are also driven, per
- * `ADS-memory/reports/proposals/PROP-plain-format-agent-driving-2026-07-21.md`'s
- * recommended "Option B": no structured stream parser at all. By default
- * every raw `child.stdout` chunk is forwarded verbatim as a `text_delta`
- * `'agent'` event, live, as it arrives (see `wireChildLifecycle`'s
- * `streamFormat === 'plain'` branch). Prompt delivery across the 5 is not
- * uniform: qwen and antigravity already fit the pre-existing stdin-only
- * guard; grok-build stages the prompt to a temp file via
- * `preparePromptFileForAgent` (its path threaded into `buildArgs` through a
- * `RuntimeContext`, cleaned up after the child exits on every path,
- * including pre-spawn/spawn-failure ones); aider/deepseek carry the prompt
- * on argv and are guarded pre-spawn by `checkPromptArgvBudget` plus the two
- * Windows CreateProcess command-line-expansion guards
- * (`checkWindowsCmdShimCommandLineBudget`/`checkWindowsDirectExeCommandLineBudget`).
- *
- * ## Antigravity's two extra needs, met declaratively
- *
- * Antigravity was the one def this driver rejected outright, for two reasons
- * the proposal doc (§2c) scoped out to a follow-up: `agy` can print an OAuth
- * sign-in URL to stdout and *still exit 0*, so live streaming leaks it; and
- * its model choice is written into one process-global `settings.json` that
- * `agy` reads on its own startup, so two concurrent runs race on it.
- *
- * Both are now met through **declarative `RuntimeAgentDef` fields this driver
- * reads generically** — `needsAgentLogFile`, `stdoutPolicy`, `runtimeLock` —
- * not a `def.id === 'antigravity'` branch. That mirrors how all 14 of the
- * def's other optional behavior flags (`promptViaFile`, `authProbe`,
- * `capturesSessionIdFromStream`, …) already work, and it is a deliberate
- * divergence from OD's own `server.ts`, which hardcodes `def.id ===
- * 'antigravity'` twice. The three fields are no-ops for the other 23 defs,
- * none of which declares any of them — so nothing else's behavior changed.
- *
- * `run()` still rejects cleanly (never a bare throw) with an
- * `AgentExecutorError` for any def whose `streamFormat` or prompt-delivery
- * shape this driver does not implement — see `isSupportedStreamFormat` and
- * `assessAgentExecutorCompatibility`.
- *
- * ## Invariant
- *
- * `RunLifecycle.start()` already transitions a run to `'running'` before
- * `run()` is ever called. Every *pre-spawn* failure path in `run()` — unknown
- * `agentId`, an unsupported `streamFormat`/prompt-delivery shape, an
- * unresolvable binary, or a spawn error — calls `lifecycle.finish({status:
- * 'failed', resumable: false, code: null, signal: null})` itself before
- * rejecting, so a run can never get stuck `'running'` with no watchdog.
- * `resumable` is unconditionally `false` on these paths — there is no spawned
- * child, hence nothing a classifier could examine (see
- * `FailureClassificationContext`'s own doc).
- *
- * For a run that *did* spawn and then failed, `resumable` is decided by
- * `classifyFailure` (gap 4 — see `ClassifyFailure`'s own doc), an injectable
- * port with no default of its own in this module (`undefined` stays
- * byte-identical to pre-gap-4 behavior — every `'failed'` outcome
- * resumable:false). OD's ~20-vendor-CLI text-matching failure classifier was
- * deliberately never ported (see `run/core/failure-taxonomy.ts`'s own doc and
- * `archived provenance ledger`). The real zero-config classifier lives in `@jini-ai/daemon`'s
- * `run/core/retry.ts` (`resumableFromProcessExit`/`classifyProcessExitFailure`)
- * and is wired in by `@jini-ai/server`'s `createLocalNodeDaemon` — see that
- * package's own archived provenance ledger, and `run/core/retry.ts`'s own doc for the
- * classification policy and its 2026-07-22 merge-time reconciliation against
- * a second, independently-built (and rejected) classifier that once lived in
- * this module.
- */
-import { spawn as nodeSpawn, type ChildProcess } from 'node:child_process';
-import type { Principal } from '@jini-ai/core';
-import type { RunAgentPayload, RunErrorPayload } from '@jini-ai/protocol';
-import { applyAgentLaunchEnv, ensureAgentCapabilities, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, prepareAgentLogFile, preparePromptFileForAgent, type AcpMcpServerInput, type AcpPermissionHandler, type AgentLaunchResolution, type PreparedAgentLogFile, type PreparedPromptFile, type PromptAugmenter, type RuntimeAgentDef, type RuntimeBuildOptions, type RuntimeContext, type RuntimeLockHold } from '@jini-ai/agent-runtime';
-import { createCommandInvocation, listProcessSnapshots, type ProcessSnapshot, type StopProcessesResult } from '@jini-ai/platform';
-import type { RunByteJournal } from './continuation/journal.js';
-import { type ImagePromptDelivery } from './image-prompt-delivery.js';
-import type { RunRetrySideEffectState } from './run/core/index.js';
-import type { ToolExecutor } from './tool-executor.js';
-import type { RunLifecycle } from './run-lifecycle.js';
-declare const SUPPORTED_STREAM_FORMATS: readonly ["claude-stream-json", "json-event-stream", "copilot-stream-json", "qoder-stream-json", "acp-json-rpc", "pi-rpc", "plain"];
-/** The families of the registry's stream-format this driver implements — see module doc. */
-export type SupportedStreamFormat = (typeof SUPPORTED_STREAM_FORMATS)[number];
-type JsonStreamFormat = Exclude<SupportedStreamFormat, 'acp-json-rpc' | 'pi-rpc' | 'plain'>;
-/**
- * `streamFormat` values `wireChildLifecycle` drives directly off raw
- * `child.stdout` `'data'` events: the 4 JSON-stream-parser formats (fed
- * through a real `feed()`/`flush()` state machine via
- * {@link createStreamHandlerForDef}) plus `'plain'` (no parser at all —
- * each chunk is forwarded verbatim as a `text_delta`, see that function's
- * doc). Distinct from `'acp-json-rpc'`/`'pi-rpc'`, which own their own
- * JSON-RPC prompt/event protocol and get their own
- * `wireAcpLifecycle`/`wirePiRpcLifecycle` wiring instead.
- */
-type ChildDrivenStreamFormat = JsonStreamFormat | 'plain';
-/**
- * Narrows a `RuntimeAgentDef.streamFormat` string to the supported
- * families.
- * @param value - The def's raw `streamFormat` string.
- * @returns `true` when `value` is one of the JSON-stream-parser, ACP, pi-rpc, or plain formats this driver wires.
- * @complexity O(1) — fixed membership check.
- * @overallScore 100/100
- */
-export declare function isSupportedStreamFormat(args: {
-    readonly value: string;
-}): args is {
-    readonly value: SupportedStreamFormat;
-};
-/**
- * Whether `run()` can drive a given def, and — when it can — its `streamFormat` already narrowed for
- * the dispatch logic that follows. The narrowing rides along deliberately: it is what lets `run()`
- * delegate every compatibility guard here without then re-checking the format to satisfy the type
- * system, which would leave an unreachable branch behind.
- */
-export type AgentExecutorCompatibility = {
-    readonly supported: true;
-    readonly streamFormat: SupportedStreamFormat;
-} | {
-    readonly supported: false;
-    readonly reason: string;
-};
-/**
- * The single source of truth for whether this executor can drive a def.
- *
- * It exists because that knowledge was previously reachable only by *calling* `run()` and inspecting
- * the failure. Anything that lists agents for a user to pick from — a discovery route, an agent
- * picker, a CLI healthcheck — needs the same answer *before* a run exists, and had no way to ask it.
- * The observable symptom was a consumer advertising an agent that its own executor then rejected the
- * instant it was selected.
- *
- * `run()` consumes this rather than re-checking the conditions itself, so the discovery-time answer
- * and the run-time guards cannot disagree. A predicate that merely duplicated the guards would be
- * the same bug in a second location.
- *
- * @param def - The def to assess. Must be the **full** `RuntimeAgentDef`, not a projected
- * `DetectedAgent`: that type omits `maxPromptArgBytes`, one of the three prompt-delivery signals
- * checked here, so the argv-bound defs (`aider`, `deepseek`) would be misjudged as unsupported.
- * @returns A discriminated result — see {@link AgentExecutorCompatibility}. The `reason` text is
- * operator-facing and is what `run()` reports as its `AGENT_RUNTIME_UNSUPPORTED` message.
- * @complexity O(1) — fixed field checks.
- * @overallScore 100/100
- */
-export declare function assessAgentExecutorCompatibility({ def }: {
-    readonly def: RuntimeAgentDef;
-}): AgentExecutorCompatibility;
-/**
- * Whether `run()` can actually drive this def — the discovery-time counterpart to the guards inside
- * `run()`, so a consumer never offers a user an agent that fails the moment it is selected.
- *
- * @param def - The full `RuntimeAgentDef`; see {@link assessAgentExecutorCompatibility} for why a
- * projected `DetectedAgent` is not sufficient.
- * @returns `true` when this executor would attempt the run.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export declare function isAgentExecutorSupported({ def }: {
-    readonly def: RuntimeAgentDef;
-}): boolean;
-/**
- * Result of translating one parsed stream event into this engine's
- * vocabulary. `'agent'` is the common case (forward as a `RunAgentPayload`
- * via the `'agent'` run event); `'error'` and `'turn-end'` are the two
- * type values `run()` handles specially rather than passing through (see
- * module doc); `'ignored'` covers anything the 4 parsers never actually
- * produce plus defensively malformed/non-record input.
- *
- * `'agent'`'s optional `sessionId` (gap 5, session resume — see
- * `RunEndPayload.sessionRef`'s doc in `@jini-ai/protocol`) is a daemon-internal
- * side channel, not part of the `RunAgentPayload` wire payload itself:
- * OpenCode's `sessionID`/Codex's `thread_id`/Qoder's and Claude's
- * `session_id` all arrive on a `'status'` event alongside fields
- * `RunAgentPayload`'s `'status'` variant already models (`label`/`model`/
- * `ttftMs`/`detail`) but has no room for a session id itself — surfacing it
- * here lets a lifecycle-wiring function capture it into a local variable and
- * thread it into its own terminal `finish()` call, without widening the
- * public wire protocol just to carry a value that only this module reads.
- *
- * `'turn-end'`'s optional `stopReason` (gap 3, capability-routed
- * continuation transport) is the same kind of internal side channel: the
- * claude-stream parser deliberately emits `stopReason` *after* every
- * `tool_use` block in the same assistant message has already been
- * translated (so a caller can decide whether to keep stdin open before
- * closing it), but v1 (pre-gap-3) discarded it and closed stdin
- * unconditionally on any `turn-end` — see `packages/daemon/archived provenance ledger`'s
- * "Design decision 2" note. `wireChildLifecycle` now reads it to decide
- * whether `stop_reason: 'tool_use'` means "inject a tool result and keep
- * going" (gap 3, gated — see `ContinuationOptions`) or "close stdin as
- * before" (the unconditional default when no continuation is configured).
- */
-export type AgentRuntimeEventTranslation = {
-    readonly kind: 'agent';
-    readonly payload: RunAgentPayload;
-    readonly sessionId?: string;
-} | {
-    readonly kind: 'error';
-    readonly payload: RunErrorPayload;
-} | {
-    readonly kind: 'turn-end';
-    readonly stopReason?: string;
-} | {
-    readonly kind: 'ignored';
-};
-/**
- * Narrows a parsed `usage` event's `usage` sub-object (`{input_tokens?, output_tokens?}`) — the one
- * piece of {@link translateUsagePayload} with real nested branching (an optional container holding
- * two optional numeric fields), extracted so that function reads as a flat field-by-field mapping.
- * @param rawUsage - `rawEvent.usage` once already narrowed to a record, or `undefined` when absent/malformed.
- * @returns `undefined` when neither token count is present — matching `translateUsagePayload`'s
- * original "omit the whole `usage` field rather than emit an empty object" behavior.
- * @complexity O(1).
- */
-export declare function extractUsageTokens({ rawUsage }: {
-    readonly rawUsage: Record<string, unknown> | undefined;
-}): {
-    input_tokens?: number;
-    output_tokens?: number;
-} | undefined;
-export declare function translateStatusEvent({ rawEvent }: {
-    readonly rawEvent: Record<string, unknown>;
-}): AgentRuntimeEventTranslation;
-export declare function translateToolResultEvent({ rawEvent }: {
-    readonly rawEvent: Record<string, unknown>;
-}): AgentRuntimeEventTranslation;
-export declare function translateErrorEvent({ rawEvent }: {
-    readonly rawEvent: Record<string, unknown>;
-}): AgentRuntimeEventTranslation;
-export declare function translateTurnEndEvent({ rawEvent }: {
-    readonly rawEvent: Record<string, unknown>;
-}): AgentRuntimeEventTranslation;
-/**
- * Narrows one parser-emitted `{type, ...}` record into this engine's
- * `RunAgentPayload` union (or the `error`/`turn-end`/`ignored` routing
- * `run()` special-cases). Pure — no I/O, no closure state — so every
- * variant each of the 4 supported parsers can produce is directly
- * assertable in isolation.
- *
- * Defensive by construction: several real parser emissions carry fields
- * looser than `RunAgentPayload`'s types promise (e.g. copilot's
- * `tool.execution_start` emits `id: data.toolCallId ?? null` — a literal
- * `null`, not the `string` `RunAgentPayload['tool_use']['id']` demands).
- * Every field read here is defensively coerced (`asString`/
- * `asOptionalString`/`asOptionalNumber`) rather than trusted, so a
- * malformed or null field degrades to a safe default instead of
- * propagating `null`/`undefined` into a field typed as required, or
- * throwing.
- *
- * @param rawEvent - One event as delivered to a stream parser's `onEvent` callback.
- * @returns The routing + payload this event maps to.
- * @complexity O(1) — one table lookup, no iteration.
- * @overallScore 100/100
- */
-export declare function translateAgentRuntimeEvent({ rawEvent }: {
-    readonly rawEvent: unknown;
-}): AgentRuntimeEventTranslation;
-/** Machine-readable failure reasons `run()` can reject with — every one is preceded by a `lifecycle.finish({status:'failed'})` call (see module doc's Invariant section). */
-export type AgentExecutorErrorCode = 'AGENT_PERMISSION_MODE_INVALID' | 'AGENT_NOT_FOUND' | 'AGENT_RUNTIME_UNSUPPORTED' | 'AGENT_BINARY_NOT_RESOLVED' | 'AGENT_SPAWN_FAILED' | 'AGENT_PROMPT_TOO_LARGE';
-/** Thrown by `AgentExecutor.run()` on every failure path — never a bare `Error`, so callers can branch on `.code` instead of parsing `.message`. */
-export declare class AgentExecutorError extends Error {
-    readonly code: AgentExecutorErrorCode;
-    constructor({ code, message }: {
-        readonly code: AgentExecutorErrorCode;
-        readonly message: string;
-    });
-}
-export interface AgentExecutorRunInput {
-    readonly runId: string;
-    readonly agentId: string;
-    readonly prompt: string;
-    readonly cwd: string;
-    /** Optional host-selected model id, forwarded to every runtime transport. */
-    readonly model?: string;
-    /** Optional host-selected reasoning effort, forwarded to runtime argv builders. */
-    readonly reasoning?: string;
-    /**
-     * Forwarded verbatim to `RuntimeBuildOptions.permissionMode` (see `@jini-ai/agent-runtime`'s
-     * `types.ts`). Every def that has an auto-approve flag (`bypassPermissions` / `--yolo` /
-     * `--dangerously-skip-permissions`) historically enabled it when omitted because a spawned
-     * subprocess has no TTY for interactive approval. That rationale explains the old behavior;
-     * the daemon now fails closed with 'restricted'. A host must explicitly select 'bypass' to
-     * delegate auto-approval, and any unknown mode is rejected before launching a process.
-     */
-    readonly permissionMode?: 'bypass' | 'restricted';
-    /**
-     * Host-validated image files. How each one actually reaches the model
-     * depends on `def.imageDelivery` (see `@jini-ai/agent-runtime`'s `types.ts`):
-     * a `'native'` def forwards these through its own protocol (argv, ACP
-     * `resource_link` blocks, or pi-rpc's base64 `images` field); a
-     * `'prompt-path'` def (currently just `claude`) instead gets them named in
-     * the prompt text and its allowed directories widened, via
-     * `image-prompt-delivery.ts#applyImagePromptDelivery`, called once near
-     * the top of `run()` below.
-     */
-    readonly imagePaths?: readonly string[];
-    /** Additional host-validated directories the runtime may read. */
-    readonly extraAllowedDirs?: readonly string[];
-    /** Trusted root that must contain pi-rpc image paths after realpath resolution. */
-    readonly uploadRoot?: string;
-    /**
-     * Credential(s) this run's selected agent/provider needs (e.g. `{ ANTHROPIC_API_KEY: '...' }`),
-     * delegated explicitly by the host and merged into the baseline-allowlisted env below. Never
-     * read implicitly from `process.env` — see SEC-001.
-     */
-    readonly credentialEnv?: Record<string, string>;
-    /**
-     * Explicit escape hatch: when supplied, used verbatim as the spawned subprocess's entire
-     * environment (no allowlist filtering) — for tests and hosts that have already done their own
-     * scoping. When omitted (the default), the subprocess gets only `BASELINE_AGENT_ENV_KEYS` from
-     * the host's real env plus `credentialEnv`, never a full `process.env` passthrough. A spawned
-     * coding-agent CLI is prompt-influenced and must be treated as potentially adversarial; it must
-     * not inherit secrets the daemon process happens to hold for unrelated reasons. See SEC-001
-     * (`ADS-memory/reports/proposals/PROP-agent-subprocess-env-allowlist-2026-07-21.md`) and locked
-     * architecture decision C8 (`ADS-memory/reports/jini-port/extraction-plan.md`).
-     */
-    readonly env?: NodeJS.ProcessEnv;
-    /**
-     * Stored session id for this (conversation, agent) pair from a prior run's
-     * `RunEndPayload.sessionRef` (see `@jini-ai/protocol`'s doc on that field) — set when the host
-     * wants this run to continue that CLI session instead of starting cold. Forwarded verbatim into
-     * `RuntimeContext.resumeSessionId`; a `resumesSessionViaCli` def (see
-     * `@jini-ai/agent-runtime`'s `types.ts`) reads it to pass its CLI's own resume flag, in which case
-     * the host should send only the latest user turn as `prompt`, not the full transcript. `null` and
-     * omitted are equivalent: no resume target for this run.
-     */
-    readonly resumeSessionId?: string | null;
-    /**
-     * A fresh id the host mints and persists when starting a session it wants resumable on a later
-     * turn (i.e. no `resumeSessionId` is available yet). Forwarded verbatim into
-     * `RuntimeContext.newSessionId`; a `resumesSessionViaCli` def passes it to its CLI's own
-     * "start with this id" flag so a later turn's `resumeSessionId` can continue the same underlying
-     * CLI session. Ignored by defs that don't declare `resumesSessionViaCli`.
-     */
-    readonly newSessionId?: string;
-    /**
-     * Forwarded verbatim to `RuntimeBuildOptions.disallowedTools` (see `@jini-ai/agent-runtime`'s
-     * `types.ts`) — Finding 2 of SEC-assistant-env-isolation-2026-09-07. A mechanism only: this
-     * package bakes in no opinion about which tools to name; the host decides. `undefined`/empty
-     * means no restriction, byte-identical to today's behavior.
-     */
-    readonly disallowedTools?: readonly string[];
-    /** Same mechanism as {@link disallowedTools}, forwarded to `RuntimeBuildOptions.allowedTools`. */
-    readonly allowedTools?: readonly string[];
-    /** Forwarded verbatim to `RuntimeBuildOptions.settingSources` (an empty list = load none of the CLI's settings layers). */
-    readonly settingSources?: readonly string[];
-    /** Forwarded verbatim to `RuntimeBuildOptions.settings` (extra settings JSON or file path for this run). */
-    readonly settings?: string;
-}
-export interface AgentExecutor {
-    /**
-     * Spawns `agentId`'s CLI for `runId`, wires its stdout/stderr into
-     * `lifecycle.emit()`, and resolves once the child process is confirmed
-     * spawned (fire-and-forget from there — see module doc). Callers await
-     * `lifecycle.waitForTerminal(runId)` separately for completion.
-     * @throws {@link AgentExecutorError} on every failure path — the
-     * underlying run is always already transitioned to `'failed'` via
-     * `lifecycle.finish()` before this rejects (see module doc's Invariant).
-     */
-    run(requiredArgs: Pick<AgentExecutorRunInput, "runId" | "agentId" | "prompt" | "cwd">, optionalArgs?: Pick<AgentExecutorRunInput, "model" | "reasoning" | "permissionMode" | "imagePaths" | "extraAllowedDirs" | "uploadRoot" | "credentialEnv" | "env" | "resumeSessionId" | "newSessionId" | "disallowedTools" | "allowedTools" | "settingSources" | "settings">): Promise<void>;
-}
-/** Process discovery is a getter; process collection and stopping accept explicit host inputs. */
-export type CollectProcessTreePidsPort = (args: {
-    readonly processes: ProcessSnapshot[];
-    readonly rootPids: Array<number | null | undefined>;
-}) => number[];
-export type StopProcessesPort = (args: {
-    readonly pids: Array<number | null | undefined>;
-}) => Promise<StopProcessesResult>;
-interface TerminateChildTreeDeps {
-    readonly listProcessSnapshots: () => Promise<ProcessSnapshot[]>;
-    readonly collectProcessTreePids: CollectProcessTreePidsPort;
-    readonly stopProcesses: StopProcessesPort;
-}
-/**
- * Which step reported a contained failure through `onCleanupFailure` (SEC-007).
- *
- * The first three come from {@link terminateChildTreeBestEffort} (process-tree teardown). The last
- * two are the two fallible steps that sit between a child's `'close'` and `finish()` — staged-file
- * removal and the host's own `classifyFailure` — neither of which may prevent the terminal
- * transition, and neither of which may fail silently either. See each close handler.
- */
-export type AgentCleanupFailurePhase = 'cancel' | 'acp-attach-failure' | 'pi-rpc-attach-failure' | 'staged-file-cleanup' | 'failure-classification';
-export interface AgentCleanupFailureContext {
-    readonly runId: string;
-    readonly phase: AgentCleanupFailurePhase;
-    /**
-     * The child's pid. `undefined` only for the post-close phases on a child that never had one
-     * assigned (a spawn that produced no process): those phases are about this run's own bookkeeping
-     * rather than about signalling a process, so an absent pid is reportable rather than a
-     * contradiction.
-     */
-    readonly pid: number | undefined;
-    readonly error: unknown;
-}
-/**
- * Gap 3 (capability-routed continuation transport) — host-owned config for the
- * `'stdin-injection'` transport (claude/codebuddy only; see
- * `resolveContinuationTransport`'s doc). **Absent by default, and absent means
- * zero behavior change**: with no `ContinuationOptions`, every `turn_end`
- * closes stdin exactly as it always has (v1 behavior, unconditionally).
- *
- * `autonomousToolNames` is this task's answer to the debate's Unresolved
- * Delta (how does the loop distinguish "the agent is continuing
- * autonomously" from "the agent is waiting on a human"): rather than
- * inferring intent from the stream, the *host* pre-declares which tool
- * names are safe to auto-resolve and re-inject without a human in the loop.
- * A `tool_use` whose name is not in this set is left exactly as it was
- * before gap 3 — stdin closes, the run proceeds to its normal terminal
- * state — even though a `stopReason: 'tool_use'` was observed. This sidesteps
- * building unproven intent-detection: nothing auto-continues unless a host
- * has explicitly vetted that specific tool as autonomous-safe. A
- * human-facing "ask the user a question" tool is simply never added to this
- * set; `packages/chat-core/src/question-form.ts`'s existing text-tag
- * mechanism (a new `Run` per turn, not mid-turn injection) already covers
- * that case without needing this transport at all.
- */
-export interface ContinuationOptions {
-    /** Injected tool results are authorized through this — the same deny-by-default gate every other tool execution path in this codebase uses. No parallel authorization path. */
-    readonly toolExecutor: ToolExecutor;
-    /** The principal an injected tool call is authorized as. */
-    readonly principal: Principal;
-    /** Tool names this host has pre-classified as safe to auto-resolve without human involvement. See this interface's own doc for why this — not stream-inferred intent — is gap 3's answer to the human-in-the-loop pause question. */
-    readonly autonomousToolNames: ReadonlySet<string>;
-}
-/**
- * Gap 3, part 2 (MCP-callback continuation transport — the spawn-time half the spike's own
- * commit message named as undone: "Item 4 ... NOT done yet"). `resolveContinuationTransport`
- * already resolves `'mcp-callback'` for every def with `externalMcpInjection !== undefined`, but
- * nothing in this file ever *acted* on that resolution — `execute_delegated_tool`
- * (`@jini-ai/mcp`'s `../server/tools/delegated-tool.ts`) only does anything useful once the spawned
- * CLI's own client actually launches `jini-mcp` as its MCP server subprocess.
- *
- * **All six declared strategies are wired.** These options describe *one* bridge server
- * (`command`/`args`/`daemonUrl`/`credential`); which transport carries it to a given child is that
- * def's own `externalMcpInjection` declaration, and each of the six has exactly one
- * implementation here — see {@link buildMcpBridgeDelivery}, which is the single dispatch point.
- * The interface name predates the other five mechanisms and is kept for API compatibility with
- * `@jini-ai/server`'s `agentExecutor` passthrough; it is no longer `.mcp.json`-specific.
- *
- * **Host-resolved, not this package's to know.** `command`/`daemonUrl` have no default the way
- * `journal`/`continuation`/`classifyFailure` don't either — there is no "real" install layout or
- * loopback URL this package could assume on a caller's behalf (matching every other seam on this
- * interface that defaults to *nothing* rather than a real implementation).
- */
-export interface McpJsonInjectionOptions {
-    /** Absolute path (or PATH-resolvable name) to the `jini-mcp` bin entry (`packages/mcp/src/bin/serve.ts`) this driver tells the spawned CLI to launch as its own MCP server subprocess. */
-    readonly command: string;
-    /** Extra argv for `command`. @default [] */
-    readonly args?: readonly string[];
-    /**
-     * Extra env for the bridge child, for hosts whose `command` is not a plain Node binary. An Electron
-     * host passes `{ ELECTRON_RUN_AS_NODE: '1' }`: its `process.execPath` is the app itself, which boots
-     * as a GUI app without that flag and never speaks MCP. `buildAgentEnv`'s allowlist strips the
-     * host's own copy from the CLI, so it can only reach the bridge through here. `JINI_*` keys are
-     * ignored: the run id, callback URL and token are this driver's to set. @default {}
-     */
-    readonly env?: Readonly<Record<string, string>>;
-    /** The daemon's own loopback base URL the spawned `jini-mcp` process calls back into via `JINI_DAEMON_URL` (see `packages/mcp/src/bin/serve.ts`'s `DAEMON_URL_ENV_VAR`). */
-    readonly daemonUrl: string;
-    /**
-     * Mints the bearer credential this run's `jini-mcp` child presents on its callbacks, delivered to
-     * the child through `JINI_DAEMON_TOKEN`. Omit it and the child is spawned exactly as before, with
-     * no token env var at all — so this is additive for every existing host.
-     *
-     * **A resolver, not a string, and deliberately so.** A host's `McpJsonInjectionOptions` is built
-     * once when it composes its executor — before any run exists. A plain string field could therefore
-     * only ever carry one boot-wide secret shared by every run, which defeats the point: the reason to
-     * hand the child a credential at all is that it can be scoped to the one run it was spawned for and
-     * stop working when that run ends. Taking `runId` here is what makes a per-run credential
-     * expressible.
-     *
-     * May be async so a host can mint through a keystore or signing service. Resolution happens in
-     * `writeMcpJsonForRun`, which is already async and already effectful; `buildMcpJsonServerEntry`
-     * stays pure and synchronous and receives the resolved value.
-     *
-     * Never hand this the host's own inbound API token. The child is the least-trusted participant in
-     * the run — it is reachable by whatever the spawned CLI does — so its credential should authorize
-     * its own callback route and nothing else.
-     *
-     * @throws Anything the host's own minting throws. `run()` turns a rejection into a pre-spawn
-     * `AGENT_SPAWN_FAILED` failure rather than spawning a child that cannot authenticate.
-     */
-    readonly credential?: ({ runId }: {
-        readonly runId: string;
-    }) => string | Promise<string>;
-    /** Reads the project's own `cwd/.mcp.json` so this driver merges its servers in rather than dropping them. Rejecting (ENOENT or otherwise) is treated as "no existing file" — see `writeMcpJsonForRun`. This file is only ever *read*. @default the real `fs.promises.readFile` (utf8) */
-    readonly readFile?: ({ path }: {
-        readonly path: string;
-    }) => Promise<string>;
-    /** Writes the merged content to this run's own config path (see {@link mcpJsonPathForRun}), never to the project's `.mcp.json`. @default the real `fs.promises.writeFile` (utf8) */
-    readonly writeFile?: ({ path, content }: {
-        readonly path: string;
-        readonly content: string;
-    }) => Promise<void>;
-    /**
-     * Removes this run's config file once the run is over — it holds a live per-run bearer token, so
-     * leaving it behind is the same class of confidentiality gap as a leaked prompt file (see
-     * `WireChildLifecycleContext.cleanupStagedFiles`). Called on the close handler and on every
-     * pre-spawn/spawn-failure path, and a rejection is reported rather than allowed to strand the run.
-     * @default `fs.promises.rm(path, { force: true })` — already-gone is success, not an error.
-     */
-    readonly removeFile?: ({ path }: {
-        readonly path: string;
-    }) => Promise<void>;
-    /**
-     * `'codex-toml'` only. Creates a fresh, randomly-named directory `prepareCodexHomeForRun` stages
-     * as a run's scratch `CODEX_HOME`. **Must be non-deterministic (a real `mkdtemp`, not a
-     * caller-computed path)** — unlike `mcpJsonPathForRun`'s deterministic path inside the run's own
-     * `cwd`, this directory holds a copy of the operator's real Codex login credential, and
-     * `os.tmpdir()` is a shared location on a multi-user host: a guessable name there is a real
-     * pre-plant/symlink target for another local user. `fs.mkdtemp`'s random suffix plus its `0700`
-     * directory mode is the actual confidentiality control, matching the same reasoning
-     * `@jini-ai/agent-runtime`'s `log-file.ts`/`prompt-file.ts` already apply to their own staged temp
-     * dirs.
-     * @param prefix - A caller-composed, run-id-derived prefix (already sanitized) for the mkdtemp
-     * template; the real suffix mkdtemp appends is what makes the path unpredictable.
-     * @default `fs.mkdtemp(path.join(os.tmpdir(), prefix))`
-     */
-    readonly mkdtemp?: ({ prefix }: {
-        readonly prefix: string;
-    }) => Promise<string>;
-    /**
-     * `'codex-toml'` only. Recursively removes the scratch `CODEX_HOME` directory `mkdtemp` above
-     * created — the directory-level analogue of `removeFile`, needed because this mechanism stages a
-     * whole directory (`config.toml` plus a copied `auth.json`), not one file.
-     * @default `fs.rm(path, { recursive: true, force: true })` — already-gone is success, not an error.
-     */
-    readonly removeDir?: ({ path }: {
-        readonly path: string;
-    }) => Promise<void>;
-}
-/** The run-error code a run gets when its CLI reports the injected `jini` bridge as anything but connected. */
-export declare const MCP_BRIDGE_UNAVAILABLE = "MCP_BRIDGE_UNAVAILABLE";
-/**
- * Judges a CLI's startup report of the injected bridge. Returns the bridge's status (`'missing'`
- * when the list omits it) when it is not `'connected'`, and `undefined` when it is connected or
- * when `rawEvent` is not an init status carrying an MCP server list (nothing to judge).
- *
- * `'pending'` counts as a failure on purpose: the CLI decides which MCP tools a session has at
- * startup, so a bridge that is not connected by then never joins this run.
- * @param rawEvent - One parsed stream event, as `@jini-ai/agent-runtime`'s parser emits it.
- * @complexity O(n) in the number of reported servers.
- */
-export declare function unavailableJiniBridgeStatus({ rawEvent }: {
-    readonly rawEvent: unknown;
-}): string | undefined;
-/** One `.mcp.json` `mcpServers` entry — the shape Claude Code's own config schema expects. */
-interface McpJsonServerEntry {
-    readonly command: string;
-    readonly args: string[];
-    readonly env: Readonly<Record<string, string>> & {
-        readonly JINI_RUN_ID: string;
-        readonly JINI_DAEMON_URL: string;
-        /** Present only when the host supplied a `credential` resolver — see {@link McpJsonInjectionOptions.credential}. */
-        readonly JINI_DAEMON_TOKEN?: string;
-    };
-}
-/**
- * Builds this run's `mcpServers.jini` entry — pure and synchronous, so every field mapping is
- * directly assertable without touching the filesystem. The credential arrives already resolved:
- * `McpJsonInjectionOptions.credential` is a possibly-async per-run resolver, and awaiting it is
- * `writeMcpJsonForRun`'s job, which keeps the effect out of this function.
- *
- * @param runId - The run this entry scopes its child to.
- * @param options - `command`/`args`/`daemonUrl`/`env` from the host's injection options.
- * @param credential - The already-resolved bearer token, or `undefined` to omit `JINI_DAEMON_TOKEN`
- * entirely. Omitting produces byte-identical output to before this parameter existed.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export declare function buildMcpJsonServerEntry({ runId, options }: {
-    readonly runId: string;
-    readonly options: Pick<McpJsonInjectionOptions, 'command' | 'args' | 'daemonUrl' | 'env'>;
-}, { credential }?: {
-    readonly credential?: string;
-}): McpJsonServerEntry;
-/**
- * Merges {@link JINI_MCP_SERVER_KEY} into an existing `.mcp.json`'s `mcpServers` map, preserving
- * every other key and every other registered server untouched. A missing (`existingRaw ===
- * undefined`), empty, or unparseable-as-a-JSON-object existing file all degrade to "start from an
- * empty document" rather than throwing — an unparseable project `.mcp.json` is a pre-existing
- * problem this driver did not create and cannot safely repair, so it is deliberately overwritten
- * with a fresh, valid file containing just this run's bridge entry rather than left broken or
- * left blocking the run. Pure — no I/O — so every branch is directly assertable.
- * @complexity O(1) plus `JSON.parse`/`JSON.stringify`'s own cost on a small config file.
- * @overallScore 100/100
- */
-export declare function mergeMcpJsonContent({ existingRaw, serverEntry }: {
-    readonly existingRaw: string | undefined;
-    readonly serverEntry: McpJsonServerEntry;
-}): string;
-/**
- * Mechanism 2 of 5 — `'acp-merge'`. Re-shapes the same bridge entry into the `mcpServers` element
- * an ACP `session/new` call carries, for the 9 ACP-native defs declaring this strategy (amr, devin,
- * hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe). Pure.
- *
- * `env` is emitted as a plain object on purpose: `@jini-ai/agent-runtime`'s
- * `buildAcpSessionNewParams` already normalises a plain-object `env` into either the
- * `[{name, value}]` array form or the `{"KEY": "val"}` map form according to each def's own
- * `acpMcpEnvFormat`, so the per-vendor wire-shape difference stays in the one place that already
- * owns it rather than being re-decided here.
- *
- * **The credential travels in `env`, never in `args`.** An ACP agent spawns this server itself and
- * applies `env` to that child's environment; a token in `args` would land in the child's process
- * arguments, readable by any other local user via `ps`. Same rule as the `.mcp.json` path.
- *
- * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
- * @returns A single-element list — this driver contributes exactly its own bridge server and never
- * removes or rewrites servers a def or host added by other means.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export declare function buildAcpMcpBridgeServers({ entry }: {
-    readonly entry: McpJsonServerEntry;
-}): AcpMcpServerInput[];
-/**
- * Serialises the bridge entry into the OpenCode-schema config JSON that `OPENCODE_CONFIG_CONTENT`
- * / `MIMOCODE_CONFIG_CONTENT` carries, merging into whatever the host already put in that variable
- * rather than replacing it — the same "merge, never clobber" discipline
- * {@link mergeMcpJsonContent} applies to `.mcp.json`, and for the same reason: a host may already
- * be handing the CLI the *user's* configured MCP servers through this exact variable, and
- * overwriting it would silently delete them.
- *
- * A missing, empty, or unparseable-as-a-JSON-object existing value degrades to "start from an empty
- * document". Overwriting an unparseable value is deliberate and matches `mergeMcpJsonContent`: this
- * driver did not create it, cannot safely repair it, and must not block the run on it.
- *
- * Emitted per server: `{type: 'local', command: [<command>, ...<args>], environment: {...},
- * enabled: true}` — the shape `@jini-ai/mcp`'s own `buildOpenCodeMcpConfigContent` emits for a
- * stdio server, so both producers stay schema-compatible.
- *
- * **The credential lands in `environment`, i.e. the MCP child's env — never in `command`.** OpenCode
- * spawns the bridge from `command`, so a token placed there would be visible in `ps` output to
- * every other local user. This is the same constraint that keeps `JINI_DAEMON_TOKEN` out of argv on
- * the `.mcp.json` and ACP paths.
- *
- * @param existingRaw - Whatever the spawn env already held for this variable, or `undefined`.
- * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
- * @returns The full JSON string to set as the env var's value.
- * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
- * @overallScore 100/100
- */
-export declare function mergeEnvContentMcpConfig({ existingRaw, entry }: {
-    readonly existingRaw: string | undefined;
-    readonly entry: McpJsonServerEntry;
-}): string;
-/**
- * Merges a staged system-prompt overlay file's path into the `instructions` array of the same
- * OpenCode-schema config document {@link mergeEnvContentMcpConfig} writes `mcp` into — for a
- * `systemPromptDelivery: { strategy: 'config-instructions-file' }` def (`opencode` today).
- *
- * Confirmed live (2026-09-01, opencode-cli 1.17.10), not inferred from docs alone:
- *   1. `instructions` is honored — a run configured with it visibly followed the file's directive
- *      (a required exact-token prefix), while an identical run without it did not.
- *   2. It appends, never replaces: the same run that followed the custom instruction ALSO still
- *      answered correctly using opencode's own baked-in environment-context system prompt (asked
- *      for its cwd, with nothing about cwd anywhere in the custom instructions file) — proof
- *      opencode's own defaults survive alongside a custom `instructions` entry, not just proof the
- *      file was read at all.
- *   3. Adding this key alongside `mcp` in the same `OPENCODE_CONFIG_CONTENT` document disturbs
- *      neither: in one combined run, the MCP bridge still got its connection attempt (logged
- *      `key=jini type=local`) AND the custom instruction was still followed — same as running each
- *      key alone.
- *   4. `instructions` is re-read fresh from the env on every spawn, including a `-s <id>`-resumed
- *      turn (proved by swapping in a second instructions file between two turns of one resumed
- *      session and seeing the second turn immediately reflect it while still recalling
- *      conversation memory from turn one) — so this mechanism is safe to redeliver every turn like
- *      `'append-flag'`/`'env-var'`, exempt from the prompt-prefix fallback's create-only gating
- *      (see {@link resolveSystemPromptOverlayDelivery}'s doc): nothing here is ever baked into
- *      opencode's own persisted session state the way re-injecting fallback prompt text would be.
- *
- * @param existingRaw - Whatever the spawn env already held for this variable (already possibly
- * carrying `mcp`, if `mergeEnvContentMcpConfig` ran first on the same value — order between the two
- * doesn't matter, each only touches its own top-level key), or `undefined`.
- * @param instructionsFilePath - The staged overlay file's absolute path (see
- * {@link prepareSystemPromptOverlayFileIfNeeded}).
- * @returns The full JSON string to set as the env var's value. Appends to, never clobbers, any
- * `instructions` entries already present — the same "merge, never clobber" discipline
- * {@link mergeEnvContentMcpConfig} applies to `mcp`, in case a host is already using this same
- * config-content variable to carry the operator's own instruction files.
- * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
- * @overallScore 100/100
- */
-export declare function mergeEnvContentInstructions({ existingRaw, instructionsFilePath }: {
-    readonly existingRaw: string | undefined;
-    readonly instructionsFilePath: string;
-}): string;
-/**
- * Mechanism 5 of 5 — `'codex-toml'`'s serialization step. Builds the `[mcp_servers.jini]` TOML
- * table (plus, when the entry carries any env vars, a separate `[mcp_servers.jini.env]` table)
- * Codex's own config schema expects.
- *
- * Confirmed against a real installed Codex CLI (0.151.0), not assumed from docs: round-tripping
- * `codex mcp add <name> --env K=V -- <cmd> <args>` against a scratch `CODEX_HOME` and reading back
- * `config.toml` produced exactly this shape (`command`/`args` as TOML strings/array in the main
- * table, env vars in a nested `.env` table) — see `archived provenance ledger` for the transcript.
- * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
- * @returns A TOML fragment with no leading/trailing blank-line padding — {@link buildCodexHomeConfigToml} owns spacing when combining it with existing content.
- * @complexity O(n) in the number of argv/env entries.
- * @overallScore 100/100
- */
-export declare function buildCodexMcpServerToml({ entry }: {
-    readonly entry: McpJsonServerEntry;
-}): string;
-/**
- * Builds the full `config.toml` a run's scratch `CODEX_HOME` gets: the real Codex home's own
- * config, with any pre-existing `[mcp_servers.jini]` table removed (see
- * {@link stripExistingJiniMcpServerTable}), then this run's own table appended.
- *
- * **Append-only by design, not a parse-and-merge, for everything but the jini table itself.**
- * `mergeMcpJsonContent`/`mergeEnvContentMcpConfig` above can safely parse-merge-reserialize because
- * their formats have a JS-native parser (`JSON.parse`); this driver has no general TOML parser in
- * its dependency graph (see `buildCodexMcpServerToml`'s doc), and every other setting a real Codex
- * install carries — model choice, sandbox policy, the trusted-project list, the operator's own
- * other MCP servers — must survive a spawn byte-for-byte. Only the one table this driver itself
- * owns (`jini` is this integration's own reserved server name — see {@link JINI_MCP_SERVER_KEY}) is
- * ever removed, via the narrow line-oriented scan above, never a full TOML parse.
- * @param existingRaw - The real Codex home's `config.toml` content, or `undefined` when it does not
- * exist (a fresh Codex install — degrades to "start from just this run's block", matching
- * {@link mergeMcpJsonContent}'s own "missing file" handling).
- * @param entry - The shared bridge entry.
- * @returns The full text to write to the scratch `CODEX_HOME`'s `config.toml`.
- * @complexity O(n) in the existing config's length.
- */
-export declare function buildCodexHomeConfigToml({ existingRaw, entry }: {
-    readonly existingRaw: string | undefined;
-    readonly entry: McpJsonServerEntry;
-}): string;
-/**
- * Where `'codex-toml'` reads the operator's REAL Codex config from, to seed a run's scratch copy —
- * never where it writes. Resolved against the daemon HOST process's own environment (`hostEnv`,
- * `process.env` at the real call site), not a run's sandboxed spawn env: `CODEX_HOME` is not in
- * `BASELINE_AGENT_ENV_KEYS`, so a spawned child never inherits it anyway, and the whole point here
- * is finding wherever the *operator's actual* Codex install lives, which is a host-machine fact.
- * @param hostEnv - The daemon process's own environment.
- * @returns `hostEnv.CODEX_HOME` when set to a non-blank value (matching Codex's own resolution
- * order), else the CLI's documented default, `~/.codex`.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export declare function resolveSourceCodexHomeDir({ hostEnv }: {
-    readonly hostEnv: NodeJS.ProcessEnv;
-}): string;
-/**
- * What one run's MCP bridge turns into, discriminated by the delivery mechanism its def declared.
- * Exactly one variant is produced per run, and each variant carries only what its own consumer
- * needs — so a consumer cannot accidentally read another mechanism's payload.
- */
-export type McpBridgeDelivery = 
-/** `'claude-mcp-json'` (claude, codebuddy): a `.mcp.json` staged into the run cwd, whose path the def's `buildArgs` passes as `--mcp-config`. */
-{
-    readonly kind: 'claude-mcp-json';
-    readonly mcpJsonPath: string;
-    readonly serverEntry: McpJsonServerEntry;
-}
-/** `'acp-merge'` (the 9 ACP-native defs): `mcpServers` entries for the ACP `session/new` params. */
- | {
-    readonly kind: 'acp-merge';
-    readonly mcpServers: readonly AcpMcpServerInput[];
-}
-/** `'opencode-env-content'` / `'mimo-env-content'` (opencode, mimo): one spawn-env variable carrying the serialised config. */
- | {
-    readonly kind: 'env-content';
-    readonly envVarName: string;
-    readonly serverEntry: McpJsonServerEntry;
-}
-/**
- * `'codex-toml'` (codex): no path yet — unlike `'claude-mcp-json'`'s `mcpJsonPath`, the scratch
- * `CODEX_HOME` directory is created with `fs.mkdtemp` (a real, non-deterministic filesystem
- * effect — see `McpJsonInjectionOptions.mkdtemp`'s own doc for why), so it cannot be computed by
- * this delivery's pure, synchronous dispatch. `prepareCodexHomeIfNeeded` stages it separately and
- * reports the resulting path back into `childEnv.CODEX_HOME` directly, never through this type.
- */
- | {
-    readonly kind: 'codex-toml';
-    readonly serverEntry: McpJsonServerEntry;
-}
-/**
- * `'env-passthrough'` (antigravity): the bridge entry's `env` triple (`JINI_RUN_ID`/
- * `JINI_DAEMON_URL`/`JINI_DAEMON_TOKEN`) is set directly on the spawned CLI's own OS
- * environment — no config document, no file, no CLI-specific schema. Correct only because this
- * strategy's CLI already inherits its own env down to the stdio MCP child it launches for a
- * server registered once, globally, out of band (see `types.ts`'s own doc on this strategy).
- */
- | {
-    readonly kind: 'env-passthrough';
-    readonly serverEntry: McpJsonServerEntry;
-};
-/**
- * **The single dispatch point from an `externalMcpInjection` strategy to its delivery mechanism.**
- * Pure and synchronous — the one effectful input (the per-run bearer credential) arrives already
- * resolved, so every strategy's mapping is directly assertable without touching the filesystem,
- * the environment, or a keystore.
- *
- * Keyed off the declared *strategy*, never off `def.id`: a def gets a working bridge by declaring a
- * mechanism, not by being named in this file. That is what makes the 9 `'acp-merge'` defs work
- * without any of their own files being touched.
- *
- * @param input.cwd - The run's working directory; only `'claude-mcp-json'` uses it, to place this
- * run's own config file (see {@link mcpJsonPathForRun}) — never `cwd/.mcp.json` itself.
- * @param input.runId - Scopes the bridge child to this run.
- * @param input.strategy - The def's declared `externalMcpInjection`, or `undefined` for a def with no native MCP transport.
- * @param input.options - The host's bridge options, or `undefined` when the host never configured injection.
- * @param input.credential - Already-resolved bearer token, or `undefined` to omit `JINI_DAEMON_TOKEN` entirely.
- * @returns `null` when this run delivers nothing — an unconfigured host, or a def declaring no
- * strategy — which is byte-identical to this feature not existing.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export declare function buildMcpBridgeDelivery(input: {
-    readonly cwd: string;
-    readonly runId: string;
-    readonly strategy: RuntimeAgentDef['externalMcpInjection'];
-    readonly options: McpJsonInjectionOptions | undefined;
-    readonly credential: string | undefined;
-}): McpBridgeDelivery | null;
-/** A staged, run-scoped Codex `CODEX_HOME` — the directory-holding analogue of {@link PreparedPromptFile}/{@link PreparedAgentLogFile} from `@jini-ai/agent-runtime`. */
-export type PreparedCodexHome = {
-    /** Absolute path to hand to the spawned child as its `CODEX_HOME` env var. */
-    readonly path: string;
-    /** Recursively removes the staged directory — the live `auth.json` copy it may hold makes this a confidentiality cleanup, not just tidiness. Safe to call more than once. */
-    readonly cleanup: () => Promise<void>;
-};
-/**
- * Finding 1 of SEC-assistant-env-isolation-2026-09-07 — a staged, run-scoped `claude` CLI config
- * directory, the `CLAUDE_CONFIG_DIR`-isolation analogue of {@link PreparedCodexHome} above.
- *
- * **The bug this closes:** `BASELINE_AGENT_ENV_KEYS` forwards `HOME` verbatim and neither this
- * package nor `@jini-ai/agent-runtime` ever set `CLAUDE_CONFIG_DIR`, so a spawned `claude` child
- * resolved its config (skills, plugins, agents, memory-path index, settings) from the OPERATOR's
- * own real `$HOME/.claude` — a personal grant (including `Task`/`Edit`/`Write`/`Cron*`/worktree
- * tools on this host) the host process never intended to hand the model.
- */
-export type PreparedClaudeConfigDir = {
-    /** Absolute path to hand to the spawned child as its `CLAUDE_CONFIG_DIR` env var. */
-    readonly path: string;
-    /** Recursively removes the staged directory — it may hold a copied login credential (see {@link prepareClaudeConfigDirForRun}'s doc), the same confidentiality-cleanup duty as {@link PreparedCodexHome.cleanup}. Safe to call more than once. */
-    readonly cleanup: () => Promise<void>;
-};
-/** The Claude-config-dir mechanism's injectable filesystem seams, real by default — the directory-staging analogue of {@link CodexHomeSeams}, kept as its own small options bag (see {@link CreateAgentExecutorOptions.claudeConfigDirIsolation}) rather than folded into {@link McpJsonInjectionOptions}: isolating the operator's personal config is an env-hygiene concern independent of whether this host configured MCP federation at all, and must not be gated on that unrelated flag. */
-export interface ClaudeConfigDirSeams {
-    readonly mkdtemp: ({ prefix }: {
-        readonly prefix: string;
-    }) => Promise<string>;
-    readonly readFile: ({ path }: {
-        readonly path: string;
-    }) => Promise<string>;
-    readonly writeFile: ({ path, content }: {
-        readonly path: string;
-        readonly content: string;
-    }) => Promise<void>;
-    readonly removeDir: ({ path }: {
-        readonly path: string;
-    }) => Promise<void>;
-}
-/**
- * `CreateAgentExecutorOptions.claudeConfigDirIsolation` — every field optional and real-filesystem
- * by default, matching this file's standing "no real disk I/O by default in tests" convention (see
- * `preparePromptFileForAgent`/`prepareAgentLogFile`'s identical shape). Unlike
- * {@link McpJsonInjectionOptions}, this bag is never itself a gate: {@link
- * prepareClaudeConfigDirIfNeeded} stages a scratch directory for every `claude`-def run regardless
- * of whether a host supplies overrides here — this options bag only lets a test observe/replace the
- * filesystem calls, the same way `preparePromptFileForAgent`'s own default does.
- */
-export interface ClaudeConfigDirIsolationOptions {
-    /** @default the real `fs.promises.mkdtemp(path.join(os.tmpdir(), prefix))` */
-    readonly mkdtemp?: ({ prefix }: {
-        readonly prefix: string;
-    }) => Promise<string>;
-    /** Reads the operator's real `.credentials.json`, if any — see {@link prepareClaudeConfigDirForRun}'s own doc. @default the real `fs.promises.readFile` (utf8) */
-    readonly readFile?: ({ path }: {
-        readonly path: string;
-    }) => Promise<string>;
-    /** Writes the copied `.credentials.json` into the scratch directory. @default the real `fs.promises.writeFile` (utf8) */
-    readonly writeFile?: ({ path, content }: {
-        readonly path: string;
-        readonly content: string;
-    }) => Promise<void>;
-    /** @default `fs.promises.rm(path, { recursive: true, force: true })` — already-gone is success, not an error. */
-    readonly removeDir?: ({ path }: {
-        readonly path: string;
-    }) => Promise<void>;
-}
-/**
- * Where `claude`'s own config resolution reads the operator's REAL config from, to seed a run's
- * scratch copy — never where it writes. Mirrors {@link resolveSourceCodexHomeDir}'s exact reasoning
- * and resolution order: `CLAUDE_CONFIG_DIR` is not in `BASELINE_AGENT_ENV_KEYS`, so a spawned child
- * never inherits it anyway — the whole point is finding wherever the *operator's actual* Claude Code
- * install lives, a host-machine fact resolved against the daemon HOST process's own environment.
- * @param hostEnv - The daemon process's own environment.
- * @returns `hostEnv.CLAUDE_CONFIG_DIR` when set to a non-blank value (matching Claude Code's own
- * resolution order, confirmed against installed Claude Code 2.1.263), else the CLI's documented
- * default, `~/.claude`.
- * @complexity O(1).
- */
-export declare function resolveSourceClaudeConfigDir({ hostEnv }: {
-    readonly hostEnv: NodeJS.ProcessEnv;
-}): string;
-/**
- * Gap 4 of the run/chat orchestration Final Recommendation: what
- * `classifyFailure` (see `CreateAgentExecutorOptions.classifyFailure`) is
- * given to decide whether a `'failed'` run is `resumable`. `code`/`signal`
- * are the only *content-level* signals cheaply available at every one of the
- * three lifecycle-wiring close handlers without new stderr/stdout buffering
- * machinery (a host wanting output-pattern-based classification, the way
- * OD's own ~20-vendor text-matching classifier worked, would need its own
- * listener for that — an honest scope limit, not an oversight).
- *
- * `sideEffects` (2026-07-22) carries the two `RunRetrySideEffectState` fields
- * every `wire*Lifecycle` driver already tracks live from the translated
- * agent-event stream it's processing anyway — `userVisibleOutputSeen` (a
- * non-empty `text_delta`/`thinking_delta`) and `toolCallSeen` (a `tool_use`)
- * — so `decideSafeRunRetry`'s matching suppression guards are genuinely
- * exercised, not permanently dead code. Two related fields are deliberately
- * absent: `cancelRequested` is never included because it's structurally
- * always `false` by the time a classifier runs at all (a cancelled run's
- * status already routes to `'cancelled'` before `classifyFailure` is ever
- * consulted — see each `wire*Lifecycle` close handler); `artifactWriteSeen`/
- * `liveArtifactSeen` have no real signal to derive them from at all —
- * `@jini-ai/protocol`'s `RunAgentEventPayload` union (`events.ts`) has no
- * `'artifact'`/`'live_artifact'` event kind yet (Jini's own generalized
- * GenUI/artifact surface isn't built — see this repo's "A2UI full protocol
- * deferred" scope note), unlike OD, which `RunRetrySideEffectState`'s shape
- * was carried over from.
- */
-export interface FailureClassificationContext {
-    readonly runId: string;
-    readonly agentId: string;
-    readonly code: number | null;
-    readonly signal: string | null;
-    readonly sideEffects: Pick<RunRetrySideEffectState, 'userVisibleOutputSeen' | 'toolCallSeen'>;
-}
-/**
- * Host-owned failure classifier — gap 4. Decides, for one specific
- * `'failed'` run, whether `RunLifecycle.finish()`'s `resumable` flag should
- * be `true`. Never consulted for `'succeeded'`/`'cancelled'` outcomes, and
- * never consulted for a pre-spawn failure (`failBeforeSpawn`'s call sites) —
- * those represent failures where no child process ever ran, so there is
- * nothing a classifier could meaningfully examine.
- */
-export type ClassifyFailure = (context: FailureClassificationContext) => boolean | Promise<boolean>;
-/**
- * Default ceiling on the `'until-close'` stdout accumulator (see `RuntimeStdoutPolicy` in
- * `@jini-ai/agent-runtime`), in bytes of received UTF-8.
- *
- * A buffered def holds its child's entire stdout in one in-memory string until the process closes,
- * which is exactly what makes the accumulator a denial-of-service surface: the child is a
- * prompt-influenced agent CLI this driver already treats as potentially adversarial (SEC-001), and
- * nothing obliges it to ever close or to stop emitting. Without a ceiling one run could exhaust the
- * daemon's heap and take every unrelated run in the process down with it.
- *
- * 8 MiB is chosen to sit far above any real buffered-agent transcript (antigravity's print-mode
- * output — the only `'until-close'` def — is a few KiB of auth prompt and result text) while staying
- * small enough that a hostile child cannot meaningfully pressure the heap. A host that genuinely
- * needs more passes `CreateAgentExecutorOptions.bufferedStdoutMaxBytes`.
- */
-export declare const DEFAULT_BUFFERED_STDOUT_MAX_BYTES: number;
-/** The side-effect signals {@link applyAgentTranslationSideEffects} reports through, one callback per signal so a caller only wires the ones it actually tracks. */
-interface AgentTranslationSideEffectSink {
-    readonly onSessionId: (args: {
-        readonly sessionId: string;
-    }) => void;
-    readonly onToolCall: () => void;
-    readonly onUserVisibleOutput: () => void;
-}
-/**
- * Applies one already-translated `'agent'`-kind event's side-effect signals — a captured session id
- * (gap 5), and the `toolCallSeen`/`userVisibleOutputSeen` pair every `wire*Lifecycle` driver tracks
- * for `FailureClassificationContext.sideEffects` — through `sink`. Extracted from `wireAcpLifecycle`'s
- * `send()`, where this exact three-level-deep nesting (session-id check, then tool_use/else-if
- * delta-length check) was that function's largest single cognitive-complexity contributor. Pure
- * except for calling the injected `sink` callbacks.
- * @param payload - The translated event's `RunAgentPayload`.
- * @param sessionId - The translation's optional captured session id, or `undefined`.
- * @param sink - The driver-specific effects to apply.
- * @complexity O(1).
- */
-export declare function applyAgentTranslationSideEffects({ payload, sessionId, sink }: {
-    readonly payload: RunAgentPayload;
-    readonly sessionId: string | undefined;
-    readonly sink: AgentTranslationSideEffectSink;
-}): void;
-export interface CreateAgentExecutorOptions {
-    readonly lifecycle: RunLifecycle;
-    /** @default the real `@jini-ai/agent-runtime` registry lookup */
-    readonly getAgentDef?: typeof getAgentDef;
-    /** @default the real `@jini-ai/agent-runtime` launch resolver */
-    readonly resolveAgentLaunch?: typeof resolveAgentLaunch;
-    /** @default the real `@jini-ai/agent-runtime` once-per-binary `--help` capability probe */
-    readonly ensureAgentCapabilities?: typeof ensureAgentCapabilities;
-    /** @default the real `@jini-ai/agent-runtime` PATH-env composer */
-    readonly applyAgentLaunchEnv?: typeof applyAgentLaunchEnv;
-    /** @default the real `@jini-ai/platform` cross-platform invocation builder */
-    readonly createCommandInvocation?: typeof createCommandInvocation;
-    /** @default `node:child_process`'s `spawn` */
-    readonly spawn?: typeof nodeSpawn;
-    /** @default the real `@jini-ai/agent-runtime` ACP session transport */
-    readonly attachAcpSession?: typeof attachAcpSession;
-    /**
-     * Host-owned policy for ACP agents' native tool calls. The ACP agent still
-     * executes its own selected option; Jini-registered tool execution belongs
-     * to `createDelegatedToolBridge`, not this permission callback.
-     */
-    readonly acpPermissionHandler?: AcpPermissionHandler;
-    /** @default the real `@jini-ai/agent-runtime` pi-rpc session transport */
-    readonly attachPiRpcSession?: typeof attachPiRpcSession;
-    /**
-     * Stages a `promptViaFile` def's (grok-build) composed prompt to a temp
-     * file before `buildArgs` runs. Touches the real filesystem by default
-     * (`fs.mkdtemp`/`fs.writeFile`/`fs.rm`) — injectable so tests can drive
-     * it without real disk I/O, matching this factory's "no real subprocess,
-     * filesystem, or PATH lookup by default in tests" convention.
-     * @default the real `@jini-ai/agent-runtime` prompt-file stager
-     */
-    readonly preparePromptFileForAgent?: typeof preparePromptFileForAgent;
-    /**
-     * Stages a `needsAgentLogFile` def's (antigravity) diagnostic-log path
-     * before `buildArgs` runs. Same real-filesystem/injectable-for-tests deal
-     * as `preparePromptFileForAgent` above, and a no-op for every def that
-     * did not opt in.
-     * @default the real `@jini-ai/agent-runtime` log-file stager
-     */
-    readonly prepareAgentLogFile?: typeof prepareAgentLogFile;
-    /** @default the real `@jini-ai/platform` process-snapshot enumerator */
-    readonly listProcessSnapshots?: typeof listProcessSnapshots;
-    /** @default the real `@jini-ai/platform` descendant-PID collector */
-    readonly collectProcessTreePids?: CollectProcessTreePidsPort;
-    /** @default the real `@jini-ai/platform` SIGTERM→SIGKILL escalator */
-    readonly stopProcesses?: StopProcessesPort;
-    /** Host-owned sink for a process-tree cleanup failure (SEC-007) — e.g. EPERM stopping descendants. @default logs a redacted diagnostic via `console.error` */
-    readonly onCleanupFailure?: (context: AgentCleanupFailureContext) => void;
-    /**
-     * Gap 1's byte-journal (`packages/daemon/src/continuation/journal.ts`) — records every byte
-     * this driver sends to or receives from a child agent process, independent of and prior to any
-     * parsed/translated event. Covers `writePromptToStdin` (sent) and every `child.stdout`/
-     * `child.stderr` `'data'` handler this driver owns (received); does not cover ACP/pi-rpc's own
-     * prompt delivery, which happens inside their respective attach functions' own transport, out
-     * of this driver's direct view — see `WireAcpLifecycleContext.journal`'s doc.
-     * @default no journal — recording is entirely opt-in, unlike every other seam on this
-     * interface (which default to a real implementation): there is no generic "real" journal
-     * storage this package can default to without a caller-supplied `EventLog` instance.
-     */
-    readonly journal?: RunByteJournal;
-    /**
-     * Gap 3's stdin-tool-result injection config — see `ContinuationOptions`'s own doc, especially
-     * on why `autonomousToolNames` (not stream-inferred intent) is this task's answer to the
-     * human-in-the-loop pause question.
-     * @default undefined — every `turn_end` closes stdin unconditionally, byte-identical to
-     * pre-gap-3 behavior. Opt-in only, like `journal`: there is no safe default allowlist of
-     * "tools okay to auto-continue without a human" this package can supply on a caller's behalf.
-     */
-    readonly continuation?: ContinuationOptions;
-    /**
-     * Gap 4's failure classifier — see `ClassifyFailure`'s own doc.
-     * @default undefined — every `'failed'` run stays `resumable: false`, byte-identical to
-     * pre-gap-4 behavior. No default classifier exists: OD's own ~20-vendor-CLI text-matching
-     * failure classifier was deliberately never ported (see this module's own doc), so there is no
-     * generic "real" classification logic this package could supply on a caller's behalf.
-     */
-    readonly classifyFailure?: ClassifyFailure;
-    /**
-     * Gap 3, part 2's spawn-time `.mcp.json` injection — see {@link McpJsonInjectionOptions}'s own
-     * doc for the full design (why only `'claude-mcp-json'`-injection defs, why host-resolved).
-     * @default undefined — no `.mcp.json` is written and no filesystem access beyond what already
-     * happened (prompt-file staging) occurs on this path, byte-identical to pre-this-task behavior.
-     * Opt-in only, like `journal`/`continuation`/`classifyFailure`: there is no safe default
-     * `command`/`daemonUrl` this package could assume on a caller's behalf.
-     */
-    readonly mcpJsonInjection?: McpJsonInjectionOptions;
-    /**
-     * Finding 1 of SEC-assistant-env-isolation-2026-09-07's injectable filesystem seams — see
-     * {@link ClaudeConfigDirIsolationOptions}'s own doc. This bag itself is still NOT a gate (supplying
-     * it only lets a test observe/replace the real filesystem calls); whether staging happens AT ALL is
-     * now {@link claudeConfigDirIsolationEnabled}'s job — see that field's doc for why the two were
-     * split apart instead of overloading this one's presence as the switch.
-     * @default the real `fs.promises.mkdtemp`/`readFile`/`rm` — no real disk I/O for every def other
-     * than `claude`, matching this factory's "no real filesystem by default in tests" convention.
-     */
-    readonly claudeConfigDirIsolation?: ClaudeConfigDirIsolationOptions;
-    /**
-     * The actual on/off switch for Finding 1's `CLAUDE_CONFIG_DIR` isolation (see
-     * {@link prepareClaudeConfigDirIfNeeded}'s doc for the staging behavior this gates). Split out as
-     * its own boolean rather than reusing {@link claudeConfigDirIsolation}'s presence, because that bag
-     * is a test-seam-injection convention shared with every other `*IsolationOptions`/`*Seams` field in
-     * this file (see `mcpJsonInjection`'s own "NOT a gate" precedent) — overloading it here would mean a
-     * host that only wants to override `mkdtemp` for a test silently also flips production behavior.
-     *
-     * @default `false`. This DEFAULTS OFF, which reopens the leak Finding 1 closed (the spawned
-     * `claude` child again reads the operator's real `~/.claude` — skills, plugins, memory index, and
-     * whatever tool grant that directory carries) — **not a regression discovered later, a deliberate
-     * rollback landed the same day as the isolation fix itself.** Reason: on macOS the Keychain login
-     * `claude auth status` reports is keyed to `CLAUDE_CONFIG_DIR` (see {@link
-     * prepareClaudeConfigDirForRun}'s doc), and no caller of this factory was passing a credential of
-     * its own (`AgentExecutorRunInput.credentialEnv`) when Finding 1 landed unconditionally — so every
-     * isolated child ran unauthenticated and the assistant reported "Not logged in" on its default
-     * runtime. A host that provisions a real `ANTHROPIC_API_KEY`/`CLAUDE_CODE_OAUTH_TOKEN` via
-     * `credentialEnv` (both outrank Keychain login in Claude Code's own auth precedence, so an isolated,
-     * still-logged-in child needs no access to the operator's personal Keychain entry at all) should
-     * flip this back on — the mechanism itself is unchanged and was already proven live
-     * (2026-09-07); only the default changed.
-     */
-    readonly claudeConfigDirIsolationEnabled?: boolean;
-    /**
-     * Ceiling on how many bytes of a `'until-close'` def's stdout this driver will hold in memory
-     * before it stops accumulating and reports the shortfall — see
-     * {@link DEFAULT_BUFFERED_STDOUT_MAX_BYTES} for the threat this closes and why 8 MiB.
-     * @default {@link DEFAULT_BUFFERED_STDOUT_MAX_BYTES}
-     */
-    readonly bufferedStdoutMaxBytes?: number;
-    /**
-     * Host-owned system-prompt overlay — see `prompt-augmenter.ts`'s own doc for why this seam
-     * exists (product-specific discovery/behavior instructions that don't belong in the engine).
-     * When present, `systemOverlay()` is called once per `run()` and its result (if non-null) is
-     * threaded through to `buildArgs` as `RuntimeBuildOptions.systemPromptOverlay` — a def with no
-     * append-system-prompt mechanism ignores it.
-     * @default undefined — no overlay is computed and no def sees `systemPromptOverlay`,
-     * byte-identical to pre-this-option behavior.
-     */
-    readonly promptAugmenter?: PromptAugmenter;
-}
-/**
- * Creates the `AgentExecutor` reference implementation: an in-process
- * `RunLifecycle` driver over real (by default) `@jini-ai/agent-runtime`
- * registry lookup, launch resolution, and stream parsing, plus a real
- * `node:child_process.spawn`. Every collaborator is an injectable seam
- * (matching this package's established convention — see
- * `tool-executor.ts`/`run-lifecycle.ts`) so tests can drive a fake child
- * process and a fake registry without touching the filesystem or spawning
- * a real subprocess.
- *
- * @param options.lifecycle - The `RunLifecycle` this executor drives — its `start()` must already have been called for any `runId` passed to `run()`.
- * @returns An `AgentExecutor` whose `run()` never bare-throws (see module doc's Invariant).
- * @complexity `run()`'s own setup is O(1); steady-state cost is the chosen stream parser's.
- * @overallScore 100/100
- */
-/** `createAgentExecutor`'s internal `failBeforeSpawn` — a nested closure over `lifecycle`, so every extracted `run()` phase below takes it as an explicit injected collaborator rather than reaching for a module-level one. */
-type FailBeforeSpawn = (args: {
-    readonly runId: string;
-    readonly code: AgentExecutorErrorCode;
-    readonly message: string;
-}) => Promise<never>;
-interface ResolvedDefAndFormat {
-    readonly def: RuntimeAgentDef;
-    readonly streamFormat: SupportedStreamFormat;
-}
-/** Phase 1: registry lookup + `assessAgentExecutorCompatibility` guard. */
-export declare function resolveDefAndStreamFormat({ input, deps }: {
-    readonly input: Pick<AgentExecutorRunInput, 'runId' | 'agentId'>;
-    readonly deps: {
-        readonly getAgentDef: typeof getAgentDef;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<ResolvedDefAndFormat>;
-/** Phase 2: image-prompt-delivery augmentation + argv-budget guard for argv-bound defs. */
-export declare function resolveImageDeliveryAndArgvBudget({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly prompt: string;
-        readonly imagePaths: readonly string[] | undefined;
-        readonly extraAllowedDirs: readonly string[] | undefined;
-    };
-    readonly deps: {
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<ImagePromptDelivery>;
-/**
- * Phase 3a: the subprocess environment this run's launch resolution and spawn should use — the
- * caller-supplied escape hatch verbatim, or the deny-by-default `BASELINE_AGENT_ENV_KEYS` allowlist.
- * Pure.
- */
-export declare function resolveRunEnv({ input, hostEnv }: {
-    readonly input: Pick<AgentExecutorRunInput, 'env' | 'credentialEnv'>;
-    readonly hostEnv: NodeJS.ProcessEnv;
-}): Record<string, string>;
-/** A resolved launch whose `launchPath` is confirmed non-null — see {@link resolveLaunch}. */
-type ConfirmedAgentLaunchResolution = AgentLaunchResolution & {
-    readonly launchPath: string;
-};
-/** Phase 3b: launch-path resolution + binary-not-resolved guard. */
-export declare function resolveLaunch({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly resolvedEnv: Record<string, string>;
-    };
-    readonly deps: {
-        readonly resolveAgentLaunch: typeof resolveAgentLaunch;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<ConfirmedAgentLaunchResolution>;
-/** Phase 4a: stage a `promptViaFile` def's prompt to a temp file (a no-op for every other def). */
-export declare function stagePromptFile({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly prompt: string;
-    };
-    readonly deps: {
-        readonly preparePromptFileForAgent: typeof preparePromptFileForAgent;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<PreparedPromptFile | null>;
-/** Phase 4b: stage a `needsAgentLogFile` def's diagnostic-log path (a no-op for every other def). */
-export declare function stageLogFile({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly preparedPromptFile: PreparedPromptFile | null;
-    };
-    readonly deps: {
-        readonly prepareAgentLogFile: typeof prepareAgentLogFile;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<PreparedAgentLogFile | null>;
-/** Phase 5: resolves this run's MCP bridge delivery (credential resolution + {@link buildMcpBridgeDelivery}). */
-export declare function resolveMcpBridgeForRun({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly cwd: string;
-        readonly def: RuntimeAgentDef;
-    };
-    readonly deps: {
-        readonly mcpJsonInjection: McpJsonInjectionOptions | undefined;
-        readonly cleanupStagedFiles: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<McpBridgeDelivery | null>;
-/**
- * Phase 6a/10c: the subprocess environment every env-riding mechanism uses — mechanism 3+4
- * (`'opencode-env-content'`/`'mimo-env-content'`, merged into whatever the host already set there,
- * never a CLI argument: the config embeds `JINI_DAEMON_TOKEN`, and process arguments are readable
- * by any other local user through `ps`), mechanism 5 (`'codex-toml'`, `CODEX_HOME` relocation),
- * mechanism 6 (`'env-passthrough'`, the bridge entry's flat env vars set directly with no carrier
- * document — see {@link McpBridgeDelivery}'s own doc), a
- * `systemPromptDelivery: 'env-var'` def's overlay (`reasonix`'s `REASONIX_ACP_SYSTEM_APPEND` today
- * — see `resolveSystemPromptOverlayDelivery`'s own doc), and a `'config-instructions-file'` def's
- * staged overlay file (`opencode` today — see {@link mergeEnvContentInstructions}'s own doc). Pure
- * — `codexHomeDir` and `stagedInstructionsFile` arrive already staged by
- * {@link prepareCodexHomeIfNeeded} and {@link prepareSystemPromptOverlayFileIfNeeded} respectively,
- * the only parts of this mechanism that are NOT pure (real `mkdtemp`/`writeFile` calls).
- * @param spawnEnv - The env every other spawn-time step (launch-path resolution, `applyAgentLaunchEnv`) already computed.
- * @param mcpBridge - This run's resolved bridge delivery, or `null` for an unconfigured host / no-strategy def.
- * @param codexHomeDir - The staged scratch `CODEX_HOME` path for a `'codex-toml'` def, or `undefined` for every other run (including a `'codex-toml'` def when `mcpJsonInjection` was never configured — see `prepareCodexHomeIfNeeded`'s own gate).
- * @param systemPromptEnvOverrides - `resolveSystemPromptOverlayDelivery`'s `envOverrides` — `{}` (default) for every def but an `'env-var'`-strategy one with an overlay present, in which case it carries that one var. Applied after `codexHomeDir`, so it can never be shadowed by it — the two never share a key (`CODEX_HOME` vs. e.g. `REASONIX_ACP_SYSTEM_APPEND`), so the ordering is a documentation choice, not a correctness one.
- * @param stagedInstructionsFile - `varName` (from the def's own `systemPromptDelivery` declaration) and the staged overlay file's `path`, or `undefined` for every def but a `'config-instructions-file'` one with an overlay present. Merged into `varName`'s value AFTER the `mcp` merge above (reading `envContentApplied`, not the original `spawnEnv`, for that same key) so both a `mcp` entry and an `instructions` entry from the two mechanisms survive together in one document — confirmed live this coexistence is safe (see {@link mergeEnvContentInstructions}'s doc).
- * @complexity O(1) plus `mergeEnvContentMcpConfig`'s and `mergeEnvContentInstructions`'s own `JSON.parse`/`JSON.stringify` cost.
- * @overallScore 100/100
- */
-export declare function computeChildEnv({ spawnEnv, mcpBridge }: {
-    readonly spawnEnv: NodeJS.ProcessEnv;
-    readonly mcpBridge: McpBridgeDelivery | null;
-}, { codexHomeDir, systemPromptEnvOverrides, stagedInstructionsFile, claudeConfigDir }?: {
-    readonly codexHomeDir?: string;
-    readonly systemPromptEnvOverrides?: Readonly<Record<string, string>>;
-    readonly stagedInstructionsFile?: {
-        readonly varName: string;
-        readonly path: string;
-    };
-    readonly claudeConfigDir?: string;
-}): NodeJS.ProcessEnv;
-/**
- * Phase 6b: the `RuntimeContext` `buildArgs` receives — `undefined` unless a file, bridge path, or
- * session id was staged. Pure.
- *
- * `resumeSessionId`/`newSessionId` round-trip a prior run's `RunEndPayload.sessionRef` (see
- * `@jini-ai/protocol`'s doc on that field) back into this run's `RuntimeContext`, letting a
- * `resumesSessionViaCli` def (e.g. claude) continue its own CLI session across turns instead of
- * spawning cold every time. Either one alone must still produce a context — a run supplying ONLY a
- * session id, with no prompt/log file staged and no claude-mcp-json bridge, is exactly the common
- * case for a resumed turn.
- */
-export declare function computeRuntimeContext({ preparedPromptFile, preparedLogFile, mcpBridge }: {
-    readonly preparedPromptFile: PreparedPromptFile | null;
-    readonly preparedLogFile: PreparedAgentLogFile | null;
-    readonly mcpBridge: McpBridgeDelivery | null;
-}, { resumeSessionId, newSessionId }?: {
-    readonly resumeSessionId?: string | null;
-    readonly newSessionId?: string;
-}): RuntimeContext | undefined;
-/** Phase 9a: the def's `buildArgs` 4th argument. Historically omitted when every override was absent;
- * that let defs silently enable auto-approval. Always supply the validated restricted default now. Pure. */
-export declare function buildAgentBuildArgsOptions({ input, systemPromptOverlay }: {
-    readonly input: Pick<AgentExecutorRunInput, 'model' | 'reasoning' | 'permissionMode' | 'disallowedTools' | 'allowedTools' | 'settingSources' | 'settings'>;
-    readonly systemPromptOverlay: string | null | undefined;
-}): RuntimeBuildOptions | undefined;
-/**
- * {@link resolveSystemPromptOverlayDelivery}'s decision, threaded out of that one resolver to every
- * channel that can actually carry the overlay to the CLI.
- *
- * **Why `promptPrefix` exists alongside `prompt`.** `prompt` is the composed prompt with the
- * fallback prefix already applied, and is what `buildArgs`, the staged prompt file, and a
- * `promptViaStdin` def's stdin all receive. But the two RPC transports (`runAcpDispatch`,
- * `runPiRpcDispatch`) deliberately send `run()`'s *raw* `input.prompt`, not the image-delivery
- * rewrite this resolver was handed — those defs deliver images through their own native protocol
- * and must never also get `'prompt-path'`'s appended paths (see `resolveImageDeliveryAndArgvBudget`'s
- * call site in `run()` for that hazard). Handing them `prompt` would silently couple them to the
- * image rewrite; handing them `promptPrefix + input.prompt` applies exactly this resolver's overlay
- * decision to exactly the prompt text they were already sending.
- *
- * **The no-double-delivery invariant.** `promptPrefix` is a non-empty string on exactly one path —
- * the universal fallback, the only strategy that carries the overlay *in the prompt text*. Every
- * declared strategy (`'append-flag'`, `'env-var'`, `'config-instructions-file'`) and every
- * suppressed case (no overlay, continuing a session) returns `''`, so a def that receives the
- * overlay through argv, an env var, or a staged config file never also receives it inline. A
- * transport therefore does not need to know which strategy applies: applying `promptPrefix`
- * unconditionally is correct precisely because the resolver already zeroed it where it must not
- * apply.
- */
-export interface SystemPromptOverlayDelivery {
-    /**
-     * The text to prepend to whatever prompt a transport is about to send — `''` for every def whose
-     * overlay rides another channel, so it is always safe to apply unconditionally. See this
-     * interface's own doc for why callers with their own prompt text use this rather than `prompt`.
-     */
-    readonly promptPrefix: string;
-    /** `promptPrefix` already applied to the prompt this resolver was handed. */
-    readonly prompt: string;
-    /** Extra argv to append to `buildArgs`' own result — non-empty only for `'append-flag'`. */
-    readonly extraArgs: readonly string[];
-    /** Env vars to merge into the spawn env — non-empty only for `'env-var'`. */
-    readonly envOverrides: Readonly<Record<string, string>>;
-}
-/**
- * **The single dispatch point from a computed system-prompt overlay to its delivery mechanism** —
- * see `RuntimeAgentDef.systemPromptDelivery`'s own doc for the declared shape. Pure and
- * synchronous, mirroring {@link buildMcpBridgeDelivery}'s "keyed off the declared strategy, never
- * off the def's id" contract: a def earns overlay delivery by declaring a strategy, not by being
- * named in this file. That is what makes every def with no declaration work via the fallback
- * without any of their own files being touched.
- *
- * The fallback (no declared strategy — every def but `claude` today) prefixes the overlay directly
- * onto the composed prompt text, clearly delimited from the user's own request. It is gated on
- * session state, not merely on whether an overlay exists: a def that carries its own conversation
- * memory across spawns (`resumesSessionViaCli` / `resumesSessionViaAcpLoad`) persists whatever its
- * session-creating turn sends it — see `RuntimeContext.resumeSessionId`'s own doc: its presence on
- * a run means "continue a prior session", not "start one". Prefixing on every later turn of that
- * same session would therefore bake the overlay into the CLI's own stored history again and again,
- * compounding without bound turn over turn. So the fallback prefixes only when there is no resume
- * target yet (the session's own first turn, or a def with no session memory at all, which never
- * replays anything back at the CLI and so gets it on every turn).
- *
- * `'append-flag'` and `'env-var'` defs are the opposite case: the flag/env var is a fresh,
- * un-stored per-spawn directive — never part of what a resumed session replays — so it is set on
- * every turn unconditionally, exactly `claude`'s pre-existing (now-centralized) behavior before
- * this function existed.
- *
- * @param input.defId - Looks up this def's probed capabilities for an `'append-flag'` strategy's
- * `capabilityKey`. Otherwise unused — the dispatch itself is keyed off `systemPromptDelivery`, per
- * this function's own doc above, never off the id.
- * @param input.systemPromptDelivery - The def's declared strategy, or `undefined` for the fallback.
- * @param input.resumesSessionViaCli - The def's own flag (see `RuntimeAgentDef`'s doc).
- * @param input.resumesSessionViaAcpLoad - The def's own flag (see `RuntimeAgentDef`'s doc).
- * @param input.overlay - The computed `PromptAugmenter.systemOverlay()` result. `null`/`undefined`/
- * empty short-circuits to "no delivery" — byte-identical to no `PromptAugmenter` configured at all.
- * @param input.prompt - The composed prompt `buildArgs` would otherwise receive verbatim.
- * @param input.resumeSessionId - This run's `RuntimeContext.resumeSessionId`; presence means an
- * existing session is being continued, not created.
- * @returns A {@link SystemPromptOverlayDelivery}: the prefix this run's prompt text must carry
- * (`''` unless the fallback applies), that prefix already applied to `input.prompt`, any extra argv
- * to append to whatever `buildArgs` itself returns, and any env var overrides to merge into the
- * spawn env (`{}` for every strategy but `'env-var'`). Every one of `run()`'s four prompt
- * transports consumes this same result — see the interface's own no-double-delivery note.
- * @complexity O(n) in the overlay/prompt lengths — string concatenation only, no I/O.
- * @overallScore 100/100
- */
-export declare function resolveSystemPromptOverlayDelivery(input: {
-    readonly defId: string;
-    readonly systemPromptDelivery: RuntimeAgentDef['systemPromptDelivery'];
-    readonly resumesSessionViaCli: boolean | undefined;
-    readonly resumesSessionViaAcpLoad: boolean | undefined;
-    readonly overlay: string | null | undefined;
-    readonly prompt: string;
-    readonly resumeSessionId: string | null | undefined;
-}): SystemPromptOverlayDelivery;
-/**
- * Phase 9b: calls the def's `buildArgs`, releasing staged resources and failing the run on a throw.
- *
- * @param input.overlayDelivery - This run's already-resolved overlay decision, computed once in
- * `run()` rather than here. It is resolved upstream because `buildArgs` is only ONE of the four
- * channels that can carry the prompt: the staged prompt file is written *before* this function
- * runs, and stdin/ACP/pi-rpc send theirs *after* spawn. A decision made inside this function could
- * therefore only ever reach the 7 defs whose `buildArgs` reads its first argument at all — the
- * other 17 declare it `_prompt` and discard it, which is exactly how the overlay used to go missing.
- */
-export declare function buildRunArgs({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly imageDelivery: ImagePromptDelivery;
-        readonly imagePaths: readonly string[] | undefined;
-        readonly runInput: Pick<AgentExecutorRunInput, 'model' | 'reasoning' | 'permissionMode'>;
-        readonly systemPromptOverlay: string | null | undefined;
-        readonly overlayDelivery: SystemPromptOverlayDelivery;
-        readonly runtimeContext: RuntimeContext | undefined;
-    };
-    readonly deps: {
-        readonly releaseStagedResources: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<{
-    readonly args: string[];
-    readonly envOverrides: Readonly<Record<string, string>>;
-}>;
-/** Phase 10: mechanism 1 of 5's one effect — stages this run's own `.mcp.json`, returning the path `cleanupStagedFiles` should later remove (`undefined` for every other mechanism / unconfigured host). */
-export declare function writeMcpJsonIfNeeded({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly cwd: string;
-        readonly def: RuntimeAgentDef;
-        readonly mcpBridge: McpBridgeDelivery | null;
-    };
-    readonly deps: {
-        readonly mcpJsonInjection: McpJsonInjectionOptions | undefined;
-        readonly releaseStagedResources: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<string | undefined>;
-/** {@link prepareSystemPromptOverlayFileIfNeeded}'s result. */
-export type PreparedSystemPromptOverlayFile = {
-    /** Absolute path to the staged file, ready to merge into a `config-instructions-file` def's `instructions` array. */
-    readonly path: string;
-    /** Recursively removes the staged directory. Safe to call more than once. */
-    readonly cleanup: () => Promise<void>;
-};
-/**
- * Phase 10b1: `systemPromptDelivery: { strategy: 'config-instructions-file' }`'s one effect —
- * stages the computed overlay to a fresh, run-scoped temp file, so `computeChildEnv` has a real
- * path to merge into that def's `instructions` config array (see
- * {@link mergeEnvContentInstructions}'s own doc for the live verification this mechanism rests on).
- * `null` for every other strategy, an unset `systemPromptDelivery`, or no overlay present at all —
- * byte-identical to before this mechanism existed, matching {@link writeMcpJsonIfNeeded}'s and
- * {@link prepareCodexHomeIfNeeded}'s identical no-op-when-inapplicable gate.
- *
- * `opencode`'s `instructions` field only accepts a file path or a remote URL — confirmed live
- * (2026-09-01): a literal instruction string in the array is silently ignored (no error, just never
- * honored), so an inline-text shortcut is not available and this staging step is load-bearing, not
- * a defensive extra.
- * @param input.def - Only used for its `id`, in the failure message, and its `systemPromptDelivery` declaration.
- * @param input.overlay - The computed `PromptAugmenter.systemOverlay()` result for this run.
- * @complexity O(1) plus one directory creation and one file write.
- * @overallScore 100/100
- */
-export declare function prepareSystemPromptOverlayFileIfNeeded({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly overlay: string | null | undefined;
-    };
-    readonly deps: {
-        readonly releaseStagedResources: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<PreparedSystemPromptOverlayFile | null>;
-/**
- * Phase 10b: mechanism 5 of 5's one effect — stages this run's scratch `CODEX_HOME` directory,
- * returning the prepared handle `cleanupStagedFiles` should later release (`null` for every other
- * mechanism, or for an unconfigured host — matching {@link writeMcpJsonIfNeeded}'s identical gate).
- * @param input.def - Only used for its `id`, in the failure message.
- * @param input.mcpBridge - This run's resolved bridge delivery — a no-op unless its `kind` is `'codex-toml'`.
- * @param deps.hostEnv - The daemon's own environment, threaded through to {@link resolveSourceCodexHomeDir} rather than read from a module-level `process.env` so this phase stays testable with an injected env.
- * @complexity O(1) plus {@link prepareCodexHomeForRun}'s own cost.
- * @overallScore 100/100
- */
-export declare function prepareCodexHomeIfNeeded({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly mcpBridge: McpBridgeDelivery | null;
-    };
-    readonly deps: {
-        readonly mcpJsonInjection: McpJsonInjectionOptions | undefined;
-        readonly hostEnv: NodeJS.ProcessEnv;
-        readonly releaseStagedResources: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<PreparedCodexHome | null>;
-/**
- * Finding 1 of SEC-assistant-env-isolation-2026-09-07's one effect — stages this run's scratch
- * `CLAUDE_CONFIG_DIR` directory, returning the prepared handle `cleanupStagedFiles` should later
- * release (`null` for every def other than `claude` — see {@link prepareClaudeConfigDirForRun}'s
- * own doc for why this is unconditional for `claude` runs, unlike {@link prepareCodexHomeIfNeeded}'s
- * gate on a host-configured MCP bridge strategy).
- *
- * Gated on `def.id === 'claude'` directly rather than on `externalMcpInjection === 'claude-mcp-json'`
- * (which `codebuddy` also declares): isolating the operator's personal `~/.claude` is specific to
- * the real `claude` CLI's own config resolution, not to every def that happens to share its `.mcp.
- * json` delivery shape. Matches the existing `USER`-for-claude-login special case already singled
- * out by id in `BASELINE_AGENT_ENV_KEYS`'s own doc, a few hundred lines above.
- *
- * ALSO gated on `deps.enabled` (`CreateAgentExecutorOptions.claudeConfigDirIsolationEnabled`, default
- * `false`) since this task's own fix — see that field's doc for why it defaults off (Keychain login
- * is `CLAUDE_CONFIG_DIR`-keyed and no caller was supplying a credential when this was unconditional).
- * `def.id === 'claude'` is still checked first and independently: a host that flips this flag on
- * should not suddenly stage a directory for `codebuddy` or any other def.
- * @param input.def - Used for both the `id` gate and the failure message.
- * @param deps.enabled - The isolation on/off switch — see this function's own doc above.
- * @param deps.hostEnv - The daemon's own environment, threaded through to {@link resolveSourceClaudeConfigDir} rather than read from a module-level `process.env`, matching {@link prepareCodexHomeIfNeeded}'s identical testability reasoning.
- * @complexity O(1) plus {@link prepareClaudeConfigDirForRun}'s own cost.
- */
-export declare function prepareClaudeConfigDirIfNeeded({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-    };
-    readonly deps: {
-        readonly enabled: boolean;
-        readonly claudeConfigDirIsolation: ClaudeConfigDirIsolationOptions | undefined;
-        readonly hostEnv: NodeJS.ProcessEnv;
-        readonly releaseStagedResources: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<PreparedClaudeConfigDir | null>;
-/** Phase 11: post-`buildArgs` guard for argv-bound defs whose resolved binary is a Windows shim/.exe — a no-op off-Windows and for non-argv-bound defs. */
-export declare function guardWindowsCommandLineBudget({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly launchPath: string;
-        readonly args: readonly string[];
-    };
-    readonly deps: {
-        readonly releaseStagedResources: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<void>;
-/** {@link spawnAgentChildProcess}'s result — a discriminated union rather than a thrown/rejected outcome so the call can stay synchronous; see that function's doc for why. */
-export type SpawnAgentChildProcessResult = {
-    readonly kind: 'ok';
-    readonly child: ChildProcess;
-} | {
-    readonly kind: 'error';
-    readonly error: unknown;
-};
-/**
- * Phase 12: the real `node:child_process.spawn` call.
- *
- * **Deliberately synchronous, unlike every other phase in this file.** A spawned child can emit
- * `'error'` on the very next microtask tick (Node schedules it eagerly on some failure modes, and a
- * test harness simulating "the child emits 'error' before 'spawn'" does so explicitly via
- * `queueMicrotask`). `run()` must register its `'error'` listeners (`wireChildLifecycle`'s safety net,
- * then `waitForSpawnOrError`'s `child.once('error', reject)`) in the *same synchronous turn* as this
- * spawn call — Node's `EventEmitter` throws synchronously when `'error'` fires with zero listeners
- * attached. Wrapping this call in an `async function` and `await`ing it (as every other phase here
- * does) would insert a microtask tick between spawn and listener registration, occasionally losing
- * that race — confirmed by a real test failure during this refactor (an uncaught `EventEmitter`
- * `'error'` exception) before this function was changed back to a plain, unawaited call returning a
- * result object instead of throwing/rejecting.
- * @returns `{kind:'ok', child}` on success, `{kind:'error', error}` on a synchronous throw from `spawn`
- * — `run()` itself is responsible for cleanup and `failBeforeSpawn` on the error variant, both of
- * which are safe to make asynchronous since no child (and hence no listener race) exists yet.
- * @complexity O(1) plus `spawn`'s own cost.
- */
-export declare function spawnAgentChildProcess({ input, deps }: {
-    readonly input: {
-        readonly cwd: string;
-        readonly childEnv: NodeJS.ProcessEnv;
-        readonly invocation: ReturnType<typeof createCommandInvocation>;
-    };
-    readonly deps: {
-        readonly spawn: typeof nodeSpawn;
-    };
-}): SpawnAgentChildProcessResult;
-/** Named predicate replacing an inline `streamFormat === 'acp-json-rpc' || streamFormat === 'pi-rpc'` check — the two formats that own their own prompt/event protocol and skip `wireChildLifecycle`. */
-export declare function isStdinDrivenFormat(args: {
-    readonly streamFormat: SupportedStreamFormat;
-}): args is {
-    readonly streamFormat: ChildDrivenStreamFormat;
-};
-/** Phase 13: awaits spawn confirmation, routing a failure through the same `failBeforeSpawn` shape every earlier guard uses. */
-export declare function confirmChildSpawned({ input, deps }: {
-    readonly input: {
-        readonly runId: string;
-        readonly def: RuntimeAgentDef;
-        readonly child: ChildProcess;
-    };
-    readonly deps: {
-        readonly releaseStagedResources: () => Promise<void>;
-        readonly failBeforeSpawn: FailBeforeSpawn;
-    };
-}): Promise<void>;
-/** Phase 14: starts a `runtimeLock` def's handoff watcher once a live process exists to consume the locked side effect — a no-op when the def declared no `waitForHandoff`. Deliberately not awaited; see `RuntimeLockHold.waitForHandoff`'s own doc. */
-export declare function armHandoffWatcher({ runtimeLockHold, handoffInput, release }: {
-    readonly runtimeLockHold: RuntimeLockHold | undefined;
-    readonly handoffInput: {
-        readonly logFilePath: string | undefined;
-        readonly model: string | undefined;
-        readonly processExited: AbortSignal;
-    };
-    readonly release: () => void;
-}): void;
-interface RunAcpDispatchInput {
-    readonly runId: string;
-    readonly agentId: string;
-    readonly child: ChildProcess;
-    readonly prompt: string;
-    readonly cwd: string;
-    readonly model: string | undefined;
-    readonly imagePaths: readonly string[];
-    readonly envFormat: 'array' | 'map' | undefined;
-    readonly mcpBridge: McpBridgeDelivery | null;
-}
-interface RunAcpDispatchDeps extends TerminateChildTreeDeps {
-    readonly lifecycle: RunLifecycle;
-    readonly attachAcpSession: typeof attachAcpSession;
-    readonly onPermissionRequest: AcpPermissionHandler | undefined;
-    readonly onCleanupFailure: (context: AgentCleanupFailureContext) => void;
-    readonly cleanupStagedFiles: () => Promise<void>;
-    readonly journal: RunByteJournal | undefined;
-    readonly classifyFailure: ClassifyFailure | undefined;
-    readonly releaseStagedResources: () => Promise<void>;
-    readonly failBeforeSpawn: FailBeforeSpawn;
-}
-/** Phase 15 (ACP branch): attaches the ACP session, escalating process-tree teardown and failing the run through `failBeforeSpawn` on an attach-time throw. */
-export declare function runAcpDispatch({ input, deps }: {
-    readonly input: RunAcpDispatchInput;
-    readonly deps: RunAcpDispatchDeps;
-}): Promise<void>;
-interface RunPiRpcDispatchInput {
-    readonly runId: string;
-    readonly agentId: string;
-    readonly child: ChildProcess;
-    readonly prompt: string;
-    readonly cwd: string;
-    readonly model: string | undefined;
-    readonly imagePaths: readonly string[];
-    readonly uploadRoot: string | undefined;
-}
-interface RunPiRpcDispatchDeps extends TerminateChildTreeDeps {
-    readonly lifecycle: RunLifecycle;
-    readonly attachPiRpcSession: typeof attachPiRpcSession;
-    readonly onCleanupFailure: (context: AgentCleanupFailureContext) => void;
-    readonly cleanupStagedFiles: () => Promise<void>;
-    readonly journal: RunByteJournal | undefined;
-    readonly classifyFailure: ClassifyFailure | undefined;
-    readonly releaseStagedResources: () => Promise<void>;
-    readonly failBeforeSpawn: FailBeforeSpawn;
-}
-/** Phase 15 (pi-rpc branch): same discipline as {@link runAcpDispatch}, for the one `'pi-rpc'` def. */
-export declare function runPiRpcDispatch({ input, deps }: {
-    readonly input: RunPiRpcDispatchInput;
-    readonly deps: RunPiRpcDispatchDeps;
-}): Promise<void>;
-export declare function createAgentExecutor(requiredArgs: Pick<CreateAgentExecutorOptions, "lifecycle">, optionalArgs?: Pick<CreateAgentExecutorOptions, "getAgentDef" | "resolveAgentLaunch" | "ensureAgentCapabilities" | "applyAgentLaunchEnv" | "createCommandInvocation" | "spawn" | "attachAcpSession" | "acpPermissionHandler" | "attachPiRpcSession" | "preparePromptFileForAgent" | "prepareAgentLogFile" | "listProcessSnapshots" | "collectProcessTreePids" | "stopProcesses" | "onCleanupFailure" | "journal" | "continuation" | "classifyFailure" | "mcpJsonInjection" | "claudeConfigDirIsolation" | "claudeConfigDirIsolationEnabled" | "bufferedStdoutMaxBytes" | "promptAugmenter">): AgentExecutor;
-export {};
+ * Compatibility entry for the agent executor's original module path.
+ * The split implementation owns subprocess launch, credential delivery,
+ * cancellation, and run events. Named re-exports preserve the existing API
+ * and AgentExecutorError identity across this entry and the package barrel;
+ * wrappers or a second implementation would let tested and shipped behavior drift.
+ * See agent-executor/index.ts for the driver contracts and invariants.
+ */
+export { type SupportedStreamFormat, isSupportedStreamFormat, type AgentExecutorCompatibility, assessAgentExecutorCompatibility, isAgentExecutorSupported, type AgentRuntimeEventTranslation, extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, type AgentExecutorErrorCode, AgentExecutorError, type AgentExecutorRunInput, type AgentExecutor, type CollectProcessTreePidsPort, type StopProcessesPort, type AgentCleanupFailurePhase, type AgentCleanupFailureContext, type ContinuationOptions, type McpJsonInjectionOptions, MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, type McpBridgeDelivery, buildMcpBridgeDelivery, type PreparedCodexHome, type PreparedClaudeConfigDir, type ClaudeConfigDirSeams, type ClaudeConfigDirIsolationOptions, resolveSourceClaudeConfigDir, type FailureClassificationContext, type ClassifyFailure, DEFAULT_BUFFERED_STDOUT_MAX_BYTES, applyAgentTranslationSideEffects, type CreateAgentExecutorOptions, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, resolveLaunch, stagePromptFile, stageLogFile, resolveMcpBridgeForRun, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, type SystemPromptOverlayDelivery, resolveSystemPromptOverlayDelivery, buildRunArgs, writeMcpJsonIfNeeded, type PreparedSystemPromptOverlayFile, prepareSystemPromptOverlayFileIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, guardWindowsCommandLineBudget, type SpawnAgentChildProcessResult, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, armHandoffWatcher, runAcpDispatch, runPiRpcDispatch, createAgentExecutor, } from './agent-executor/index.js';
 //# sourceMappingURL=agent-executor.d.ts.map