@jini-ai/daemon 0.3.8 → 0.5.0

package/dist/agent-executor/handoff.d.ts

@@ -0,0 +1,18 @@
+import { type RuntimeAgentDef, type RuntimeLockHold } from '@jini-ai/agent-runtime';
+/**
+ * Phase 7: acquires a `runtimeLock` def's process-global mutex before `buildArgs` runs — see
+ * `RuntimeLock`'s own doc for the concrete race. A no-op (`undefined`) for the 23 of 24 defs with no
+ * `runtimeLock` declared.
+ */
+export declare function acquireRuntimeLockIfConfigured(def: RuntimeAgentDef, model: string | undefined): Promise<RuntimeLockHold | undefined>;
+/** 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;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/agent-executor/handoff.js

@@ -0,0 +1,16 @@
+import {} from '@jini-ai/agent-runtime';
+/**
+ * Phase 7: acquires a `runtimeLock` def's process-global mutex before `buildArgs` runs — see
+ * `RuntimeLock`'s own doc for the concrete race. A no-op (`undefined`) for the 23 of 24 defs with no
+ * `runtimeLock` declared.
+ */
+export async function acquireRuntimeLockIfConfigured(def, model) {
+    return def.runtimeLock?.acquire({ model });
+}
+/** 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 function armHandoffWatcher({ runtimeLockHold, handoffInput, release }) {
+    if (!runtimeLockHold?.waitForHandoff)
+        return;
+    void runtimeLockHold.waitForHandoff(handoffInput).then(release, release);
+}
+//# sourceMappingURL=handoff.js.map

package/dist/agent-executor/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `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 folder 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.
+ */
+export { type SupportedStreamFormat, type AgentExecutorCompatibility, type AgentRuntimeEventTranslation, type AgentExecutorErrorCode, AgentExecutorError, type AgentExecutorRunInput, type AgentExecutor, type CollectProcessTreePidsPort, type StopProcessesPort, type AgentCleanupFailurePhase, type AgentCleanupFailureContext, type ContinuationOptions, type McpJsonInjectionOptions, type McpBridgeDelivery, type PreparedCodexHome, type PreparedClaudeConfigDir, type ClaudeConfigDirSeams, type ClaudeConfigDirIsolationOptions, type FailureClassificationContext, type ClassifyFailure, type CreateAgentExecutorOptions, type SystemPromptOverlayDelivery, type PreparedSystemPromptOverlayFile, type SpawnAgentChildProcessResult, } from './contracts.js';
+export { isSupportedStreamFormat, assessAgentExecutorCompatibility, isAgentExecutorSupported, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, resolveLaunch, stagePromptFile, stageLogFile, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, resolveSystemPromptOverlayDelivery, buildRunArgs, prepareSystemPromptOverlayFileIfNeeded, guardWindowsCommandLineBudget, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, createAgentExecutor, } from './launch.js';
+export { extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, applyAgentTranslationSideEffects, } from './event-translation.js';
+export { MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, buildMcpBridgeDelivery, resolveSourceClaudeConfigDir, resolveMcpBridgeForRun, writeMcpJsonIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, } from './mcp-bridge.js';
+export { DEFAULT_BUFFERED_STDOUT_MAX_BYTES, runAcpDispatch, runPiRpcDispatch, } from './events.js';
+export { armHandoffWatcher, } from './handoff.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent-executor/index.js

@@ -0,0 +1,98 @@
+/**
+ * `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 folder 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.
+ */
+export { AgentExecutorError, } from './contracts.js';
+export { isSupportedStreamFormat, assessAgentExecutorCompatibility, isAgentExecutorSupported, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, resolveLaunch, stagePromptFile, stageLogFile, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, resolveSystemPromptOverlayDelivery, buildRunArgs, prepareSystemPromptOverlayFileIfNeeded, guardWindowsCommandLineBudget, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, createAgentExecutor, } from './launch.js';
+export { extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, applyAgentTranslationSideEffects, } from './event-translation.js';
+export { MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, buildMcpBridgeDelivery, resolveSourceClaudeConfigDir, resolveMcpBridgeForRun, writeMcpJsonIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, } from './mcp-bridge.js';
+export { DEFAULT_BUFFERED_STDOUT_MAX_BYTES, runAcpDispatch, runPiRpcDispatch, } from './events.js';
+export { armHandoffWatcher, } from './handoff.js';
+//# sourceMappingURL=index.js.map

package/dist/agent-executor/launch.d.ts

@@ -0,0 +1,375 @@
+import { spawn as nodeSpawn, type ChildProcess } from 'node:child_process';
+import { getAgentDef, resolveAgentLaunch, prepareAgentLogFile, preparePromptFileForAgent, type AgentLaunchResolution, type PreparedAgentLogFile, type PreparedPromptFile, type RuntimeAgentDef, type RuntimeBuildOptions, type RuntimeContext } from '@jini-ai/agent-runtime';
+import { createCommandInvocation } from '@jini-ai/platform';
+import { type ImagePromptDelivery } from '../image-prompt-delivery.js';
+import { type SupportedStreamFormat, type ChildDrivenStreamFormat, type AgentExecutorCompatibility, type AgentExecutorRunInput, type AgentExecutor, type McpBridgeDelivery, type CreateAgentExecutorOptions, type FailBeforeSpawn, type SystemPromptOverlayDelivery, type PreparedSystemPromptOverlayFile, type SpawnAgentChildProcessResult } from './contracts.js';
+/**
+ * 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;
+};
+/**
+ * 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;
+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 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;
+/**
+ * **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 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 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>;
+/**
+ * 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>;
+/**
+ * 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 index.ts module doc's Invariant).
+ * @complexity `run()`'s own setup is O(1); steady-state cost is the chosen stream parser's.
+ * @overallScore 100/100
+ */
+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 {};
+//# sourceMappingURL=launch.d.ts.map