@jini-ai/daemon 0.2.1 → 0.3.1

package/dist/agent-executor.d.ts

@@ -9,7 +9,7 @@
  * a real `node:child_process` spawn, feeding both `RunLifecycle.emit()` and
  * this package's own `@jini-ai/protocol` event envelope.
  *
- * ## v1 scope: 23 of 24 registered agent defs
+ * ## 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
@@ -25,14 +25,14 @@
  * `mapPiRpcEvent` `send()` call site — no new translation code was needed),
  * so only the driver wiring (spawn → attach → cancel → finish) was new for it.
  *
- * 4 of the 5 `streamFormat: 'plain'` defs — grok-build, aider, deepseek,
- * qwen — are also driven, per
+ * 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. Every raw
- * `child.stdout` chunk is forwarded verbatim as a `text_delta` `'agent'`
- * event, live, as it arrives — never buffered until close (see
- * `wireChildLifecycle`'s `streamFormat === 'plain'` branch). Prompt delivery
- * across the 4 is not uniform: qwen already fit the pre-existing stdin-only
+ * 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,
@@ -41,16 +41,27 @@
  * Windows CreateProcess command-line-expansion guards
  * (`checkWindowsCmdShimCommandLineBudget`/`checkWindowsDirectExeCommandLineBudget`).
  *
- * The 5th plain def, **antigravity, is deliberately still rejected.** It
- * needs two concerns unrelated to `streamFormat: 'plain'` itself — buffering
- * stdout until close so a leaked OAuth URL can be suppressed before it
- * reaches the client, and a cross-run lock serializing writes to its shared
- * `settings.json` model-selection file — that the proposal doc explicitly
- * scoped out to its own follow-up (see that doc's §2c/§3). `run()` guards it
- * with its own `def.id === 'antigravity'` check, ahead of (and independent
- * of) the generic plain-format prompt-delivery/dispatch logic. `run()`
- * rejects cleanly (never a bare throw) with an `AgentExecutorError` for any
- * def outside the supported 23 — see `isSupportedStreamFormat`.
+ * ## 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
  *
@@ -72,24 +83,37 @@
  * deliberately never ported (see `run/core/failure-taxonomy.ts`'s own doc and
  * `source-map.md`). The real zero-config classifier lives in `@jini-ai/daemon`'s
  * `run/core/retry.ts` (`resumableFromProcessExit`/`classifyProcessExitFailure`)
- * and is wired in by `@jini-ai/node-host`'s `createLocalNodeDaemon` — see that
+ * and is wired in by `@jini-ai/server`'s `createLocalNodeDaemon` — see that
  * package's own source-map.md, 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 } from 'node:child_process';
+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, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, preparePromptFileForAgent, type AcpPermissionHandler } from '@jini-ai/agent-runtime';
-import { collectProcessTreePids, createCommandInvocation, listProcessSnapshots, stopProcesses } from '@jini-ai/platform';
+import { applyAgentLaunchEnv, 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 { collectProcessTreePids, createCommandInvocation, listProcessSnapshots, stopProcesses, 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.
@@ -99,6 +123,52 @@ export type SupportedStreamFormat = (typeof SUPPORTED_STREAM_FORMATS)[number];
  * @overallScore 100/100
  */
 export declare function isSupportedStreamFormat(value: string): value is 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: 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: RuntimeAgentDef): boolean;
 /**
  * Result of translating one parsed stream event into this engine's
  * vocabulary. `'agent'` is the common case (forward as a `RunAgentPayload`
@@ -143,6 +213,23 @@ export type AgentRuntimeEventTranslation = {
 } | {
     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: Record<string, unknown> | undefined): {
+    input_tokens?: number;
+    output_tokens?: number;
+} | undefined;
+export declare function translateStatusEvent(rawEvent: Record<string, unknown>): AgentRuntimeEventTranslation;
+export declare function translateToolResultEvent(rawEvent: Record<string, unknown>): AgentRuntimeEventTranslation;
+export declare function translateErrorEvent(rawEvent: Record<string, unknown>): AgentRuntimeEventTranslation;
+export declare function translateTurnEndEvent(rawEvent: Record<string, unknown>): AgentRuntimeEventTranslation;
 /**
  * Narrows one parser-emitted `{type, ...}` record into this engine's
  * `RunAgentPayload` union (or the `error`/`turn-end`/`ignored` routing
@@ -162,7 +249,7 @@ export type AgentRuntimeEventTranslation = {
  *
  * @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 discriminant switch, no iteration.
+ * @complexity O(1) — one table lookup, no iteration.
  * @overallScore 100/100
  */
 export declare function translateAgentRuntimeEvent(rawEvent: unknown): AgentRuntimeEventTranslation;
@@ -190,7 +277,16 @@ export interface AgentExecutorRunInput {
      * A host that wants a run to NOT auto-approve every action passes `'restricted'` here.
      */
     readonly permissionMode?: 'bypass' | 'restricted';
-    /** Host-validated image files forwarded through argv, ACP, or pi-rpc. */
+    /**
+     * 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[];
@@ -210,9 +306,27 @@ export interface AgentExecutorRunInput {
      * 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 (`foundry/docs/jini-port/extraction-plan.md`).
+     * 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;
 }
 export interface AgentExecutor {
     /**
@@ -226,12 +340,30 @@ export interface AgentExecutor {
      */
     run(input: AgentExecutorRunInput): Promise<void>;
 }
-/** Which caller invoked {@link terminateChildTreeBestEffort} — carried through to `onCleanupFailure` (SEC-007) for diagnosis. */
-export type AgentCleanupFailurePhase = 'cancel' | 'acp-attach-failure' | 'pi-rpc-attach-failure';
+interface TerminateChildTreeDeps {
+    readonly listProcessSnapshots: () => Promise<ProcessSnapshot[]>;
+    readonly collectProcessTreePids: typeof collectProcessTreePids;
+    readonly stopProcesses: (pids: Array<number | null | undefined>) => Promise<StopProcessesResult>;
+}
+/**
+ * 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;
-    readonly pid: number;
+    /**
+     * 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;
 }
 /**
@@ -270,15 +402,14 @@ export interface ContinuationOptions {
  * 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, and the only
- * `externalMcpInjection` strategy that mechanism is wired for here is `'claude-mcp-json'`
- * (`claude`/`codebuddy` — see `@jini-ai/agent-runtime`'s `types.ts` doc on the other three
- * strategies: `'acp-merge'` delivers `mcpServers` through the ACP `session/new` params
- * `wireAcpLifecycle`/`attachAcpSession` already carry, and `'opencode-env-content'`/
- * `'mimo-env-content'` deliver through spawn-env content, neither of which needs or wants a
- * written file — a future task wiring those two would extend `wireAcpLifecycle`'s existing
- * `envFormat`/`mcpServers` passthrough or `applyAgentLaunchEnv`'s env composition respectively,
- * not this function).
+ * 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
@@ -292,10 +423,64 @@ export interface McpJsonInjectionOptions {
     readonly args?: readonly 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;
-    /** Reads an existing `.mcp.json` at the given absolute path so this driver merges rather than clobbers a project's own file. Rejecting (ENOENT or otherwise) is treated as "no existing file" — see `writeMcpJsonForRun`. @default the real `fs.promises.readFile` (utf8) */
+    /**
+     * 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: 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: string) => Promise<string>;
-    /** Writes the merged `.mcp.json` content back out. @default the real `fs.promises.writeFile` (utf8) */
+    /** 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: string, 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: 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: 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: string) => Promise<void>;
 }
 /** One `.mcp.json` `mcpServers` entry — the shape Claude Code's own config schema expects. */
 interface McpJsonServerEntry {
@@ -304,15 +489,24 @@ interface McpJsonServerEntry {
     readonly env: {
         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, so every field mapping is directly
- * assertable without touching the filesystem.
+ * 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` 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: string, options: Pick<McpJsonInjectionOptions, 'command' | 'args' | 'daemonUrl'>): McpJsonServerEntry;
+export declare function buildMcpJsonServerEntry(runId: string, options: Pick<McpJsonInjectionOptions, 'command' | 'args' | 'daemonUrl'>, 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 ===
@@ -325,6 +519,226 @@ export declare function buildMcpJsonServerEntry(runId: string, options: Pick<Mcp
  * @overallScore 100/100
  */
 export declare function mergeMcpJsonContent(existingRaw: string | undefined, 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: 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: string | undefined, 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: string | undefined, 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 `source-map.md` 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: McpJsonServerEntry): string;
+/**
+ * Builds the full `config.toml` a run's scratch `CODEX_HOME` gets: the real Codex home's own
+ * config, verbatim, with this run's `[mcp_servers.jini]` table appended.
+ *
+ * **Append-only by design, not a parse-and-merge.** `mergeMcpJsonContent`/`mergeEnvContentMcpConfig`
+ * above can safely parse-merge-reserialize because their formats have a JS-native parser
+ * (`JSON.parse`); this driver has no 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. Appending preserves all of it; the one failure mode this trades
+ * away is a PRE-EXISTING `[mcp_servers.jini]` table in the operator's own config, which would
+ * produce a duplicate TOML key Codex rejects at startup. Accepted as vanishingly unlikely — `jini`
+ * is this integration's own reserved server name (see {@link JINI_MCP_SERVER_KEY}), never suggested
+ * to an operator for their own config — rather than solved with a full TOML parser for one
+ * collision case.
+ * @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.
+ * @overallScore 100/100
+ */
+export declare function buildCodexHomeConfigToml(existingRaw: string | undefined, 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: 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>;
+};
 /**
  * Gap 4 of the run/chat orchestration Final Recommendation: what
  * `classifyFailure` (see `CreateAgentExecutorOptions.classifyFailure`) is
@@ -368,6 +782,41 @@ export interface FailureClassificationContext {
  * 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: (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: RunAgentPayload, sessionId: string | undefined, sink: AgentTranslationSideEffectSink): void;
 export interface CreateAgentExecutorOptions {
     readonly lifecycle: RunLifecycle;
     /** @default the real `@jini-ai/agent-runtime` registry lookup */
@@ -399,6 +848,14 @@ export interface CreateAgentExecutorOptions {
      * @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 */
@@ -445,6 +902,23 @@ export interface CreateAgentExecutorOptions {
      * `command`/`daemonUrl` this package could assume on a caller's behalf.
      */
     readonly mcpJsonInjection?: McpJsonInjectionOptions;
+    /**
+     * 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
@@ -461,6 +935,354 @@ export interface CreateAgentExecutorOptions {
  * @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 = (runId: string, code: AgentExecutorErrorCode, message: string) => Promise<never>;
+interface ResolvedDefAndFormat {
+    readonly def: RuntimeAgentDef;
+    readonly streamFormat: SupportedStreamFormat;
+}
+/** Phase 1: registry lookup + `assessAgentExecutorCompatibility` guard. */
+export declare function resolveDefAndStreamFormat(input: Pick<AgentExecutorRunInput, 'runId' | 'agentId'>, 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: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly prompt: string;
+    readonly imagePaths: readonly string[] | undefined;
+    readonly extraAllowedDirs: readonly string[] | undefined;
+}, 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: Pick<AgentExecutorRunInput, 'env' | 'credentialEnv'>, 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: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly resolvedEnv: Record<string, string>;
+}, 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: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly prompt: string;
+}, 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: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly preparedPromptFile: PreparedPromptFile | null;
+}, 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: {
+    readonly runId: string;
+    readonly cwd: string;
+    readonly def: RuntimeAgentDef;
+}, 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: NodeJS.ProcessEnv, mcpBridge: McpBridgeDelivery | null, codexHomeDir?: string, systemPromptEnvOverrides?: Readonly<Record<string, string>>, stagedInstructionsFile?: {
+    readonly varName: string;
+    readonly path: 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: PreparedPromptFile | null, preparedLogFile: PreparedAgentLogFile | null, mcpBridge: McpBridgeDelivery | null, resumeSessionId?: string | null, newSessionId?: string): RuntimeContext | undefined;
+/** Phase 9a: the def's `buildArgs` 4th argument — `undefined` when the run selects no model/reasoning/permissionMode/overlay at all (byte-identical to omitting the argument). Pure. */
+export declare function buildAgentBuildArgsOptions(input: Pick<AgentExecutorRunInput, 'model' | 'reasoning' | 'permissionMode'>, systemPromptOverlay: string | null | undefined): RuntimeBuildOptions | undefined;
+/**
+ * **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 The (possibly prefixed) prompt to hand `buildArgs`, 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'`).
+ * @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;
+}): {
+    readonly prompt: string;
+    readonly extraArgs: readonly string[];
+    readonly envOverrides: Readonly<Record<string, string>>;
+};
+/** Phase 9b: calls the def's `buildArgs`, releasing staged resources and failing the run on a throw. */
+export declare function buildRunArgs(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 runtimeContext: RuntimeContext | undefined;
+}, 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: {
+    readonly runId: string;
+    readonly cwd: string;
+    readonly def: RuntimeAgentDef;
+    readonly mcpBridge: McpBridgeDelivery | null;
+}, 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: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly overlay: string | null | undefined;
+}, 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: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly mcpBridge: McpBridgeDelivery | null;
+}, deps: {
+    readonly mcpJsonInjection: McpJsonInjectionOptions | undefined;
+    readonly hostEnv: NodeJS.ProcessEnv;
+    readonly releaseStagedResources: () => Promise<void>;
+    readonly failBeforeSpawn: FailBeforeSpawn;
+}): Promise<PreparedCodexHome | 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: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly launchPath: string;
+    readonly args: readonly string[];
+}, 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: {
+    readonly cwd: string;
+    readonly childEnv: NodeJS.ProcessEnv;
+    readonly invocation: ReturnType<typeof createCommandInvocation>;
+}, 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(streamFormat: SupportedStreamFormat): streamFormat is ChildDrivenStreamFormat;
+/** Phase 13: awaits spawn confirmation, routing a failure through the same `failBeforeSpawn` shape every earlier guard uses. */
+export declare function confirmChildSpawned(input: {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly child: ChildProcess;
+}, 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: RuntimeLockHold | undefined, handoffInput: {
+    readonly logFilePath: string | undefined;
+    readonly model: string | undefined;
+    readonly processExited: AbortSignal;
+}, 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: RunAcpDispatchInput, 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: RunPiRpcDispatchInput, deps: RunPiRpcDispatchDeps): Promise<void>;
 export declare function createAgentExecutor(options: CreateAgentExecutorOptions): AgentExecutor;
 export {};
 //# sourceMappingURL=agent-executor.d.ts.map