@jini-ai/daemon 0.3.7 → 0.5.0

package/dist/agent-executor/contracts.js

@@ -0,0 +1,28 @@
+import {} from 'node:child_process';
+import {} from '@jini-ai/core';
+import {} from '@jini-ai/protocol';
+import {} from '@jini-ai/agent-runtime';
+import {} from '@jini-ai/platform';
+import {} from '../continuation/journal.js';
+import {} from '../run/core/index.js';
+import {} from '../tool-executor.js';
+import {} from '../run-lifecycle.js';
+export const SUPPORTED_STREAM_FORMATS = [
+    'claude-stream-json',
+    'json-event-stream',
+    'copilot-stream-json',
+    'qoder-stream-json',
+    'acp-json-rpc',
+    'pi-rpc',
+    'plain',
+];
+/** Thrown by `AgentExecutor.run()` on every failure path — never a bare `Error`, so callers can branch on `.code` instead of parsing `.message`. */
+export class AgentExecutorError extends Error {
+    code;
+    constructor({ code, message }) {
+        super(message);
+        this.name = 'AgentExecutorError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=contracts.js.map

package/dist/agent-executor/event-translation.d.ts

@@ -0,0 +1,87 @@
+import { type RunAgentPayload, type RunErrorPayload } from '@jini-ai/protocol';
+import { type AgentRuntimeEventTranslation } from './contracts.js';
+/**
+ * Narrows a parsed `usage` event's `usage` sub-object (`{input_tokens?, output_tokens?}`) — the one
+ * piece of {@link translateUsagePayload} with real nested branching (an optional container holding
+ * two optional numeric fields), extracted so that function reads as a flat field-by-field mapping.
+ * @param rawUsage - `rawEvent.usage` once already narrowed to a record, or `undefined` when absent/malformed.
+ * @returns `undefined` when neither token count is present — matching `translateUsagePayload`'s
+ * original "omit the whole `usage` field rather than emit an empty object" behavior.
+ * @complexity O(1).
+ */
+export declare function extractUsageTokens({ rawUsage }: {
+    readonly rawUsage: Record<string, unknown> | undefined;
+}): {
+    input_tokens?: number;
+    output_tokens?: number;
+} | undefined;
+export declare function translateStatusEvent({ rawEvent }: {
+    readonly rawEvent: Record<string, unknown>;
+}): AgentRuntimeEventTranslation;
+export declare function translateToolResultEvent({ rawEvent }: {
+    readonly rawEvent: Record<string, unknown>;
+}): AgentRuntimeEventTranslation;
+export declare function translateErrorEvent({ rawEvent }: {
+    readonly rawEvent: Record<string, unknown>;
+}): AgentRuntimeEventTranslation;
+export declare function translateTurnEndEvent({ rawEvent }: {
+    readonly rawEvent: Record<string, unknown>;
+}): AgentRuntimeEventTranslation;
+/**
+ * Narrows one parser-emitted `{type, ...}` record into this engine's
+ * `RunAgentPayload` union (or the `error`/`turn-end`/`ignored` routing
+ * `run()` special-cases). Pure — no I/O, no closure state — so every
+ * variant each of the 4 supported parsers can produce is directly
+ * assertable in isolation.
+ *
+ * Defensive by construction: several real parser emissions carry fields
+ * looser than `RunAgentPayload`'s types promise (e.g. copilot's
+ * `tool.execution_start` emits `id: data.toolCallId ?? null` — a literal
+ * `null`, not the `string` `RunAgentPayload['tool_use']['id']` demands).
+ * Every field read here is defensively coerced (`asString`/
+ * `asOptionalString`/`asOptionalNumber`) rather than trusted, so a
+ * malformed or null field degrades to a safe default instead of
+ * propagating `null`/`undefined` into a field typed as required, or
+ * throwing.
+ *
+ * @param rawEvent - One event as delivered to a stream parser's `onEvent` callback.
+ * @returns The routing + payload this event maps to.
+ * @complexity O(1) — one table lookup, no iteration.
+ * @overallScore 100/100
+ */
+export declare function translateAgentRuntimeEvent({ rawEvent }: {
+    readonly rawEvent: unknown;
+}): AgentRuntimeEventTranslation;
+/**
+ * Maps an ACP session's transport error into the canonical run-error shape.
+ * ACP adapters may add a structured `error` member, but a daemon driver must
+ * never make one vendor's error shape part of the run protocol.
+ */
+export declare function translateAcpError(payload: unknown): RunErrorPayload;
+/** The side-effect signals {@link applyAgentTranslationSideEffects} reports through, one callback per signal so a caller only wires the ones it actually tracks. */
+interface AgentTranslationSideEffectSink {
+    readonly onSessionId: (args: {
+        readonly sessionId: string;
+    }) => void;
+    readonly onToolCall: () => void;
+    readonly onUserVisibleOutput: () => void;
+}
+/**
+ * Applies one already-translated `'agent'`-kind event's side-effect signals — a captured session id
+ * (gap 5), and the `toolCallSeen`/`userVisibleOutputSeen` pair every `wire*Lifecycle` driver tracks
+ * for `FailureClassificationContext.sideEffects` — through `sink`. Extracted from `wireAcpLifecycle`'s
+ * `send()`, where this exact three-level-deep nesting (session-id check, then tool_use/else-if
+ * delta-length check) was that function's largest single cognitive-complexity contributor. Pure
+ * except for calling the injected `sink` callbacks.
+ * @param payload - The translated event's `RunAgentPayload`.
+ * @param sessionId - The translation's optional captured session id, or `undefined`.
+ * @param sink - The driver-specific effects to apply.
+ * @complexity O(1).
+ */
+export declare function applyAgentTranslationSideEffects({ payload, sessionId, sink }: {
+    readonly payload: RunAgentPayload;
+    readonly sessionId: string | undefined;
+    readonly sink: AgentTranslationSideEffectSink;
+}): void;
+export {};
+//# sourceMappingURL=event-translation.d.ts.map

package/dist/agent-executor/event-translation.js

@@ -0,0 +1,230 @@
+import {} from '@jini-ai/protocol';
+import {} from './contracts.js';
+import { isRecord, asString, asOptionalString, } from './values.js';
+function asOptionalNumber(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * 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 function extractUsageTokens({ rawUsage }) {
+    if (!rawUsage)
+        return undefined;
+    const inputTokens = asOptionalNumber(rawUsage.input_tokens);
+    const outputTokens = asOptionalNumber(rawUsage.output_tokens);
+    if (inputTokens === undefined && outputTokens === undefined)
+        return undefined;
+    return {
+        ...(inputTokens !== undefined ? { input_tokens: inputTokens } : {}),
+        ...(outputTokens !== undefined ? { output_tokens: outputTokens } : {}),
+    };
+}
+/**
+ * Narrows one parsed `usage` event's loosely-typed fields into
+ * `RunAgentPayload`'s `usage` variant. The 4 source parsers attach extra
+ * fields this narrow payload has no room for — `thought_tokens`,
+ * `cached_read_tokens`/`cached_write_tokens` (opencode/gemini/codex),
+ * `modelUsage`/`stopReason`/`isError` (qoder), a top-level `stopReason`
+ * (claude/copilot) — all intentionally dropped here, not carried through.
+ * @param rawEvent - The raw `{type:'usage', ...}` record from a stream parser.
+ * @returns The narrowed `RunAgentPayload` `usage` variant.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+function translateUsagePayload(rawEvent) {
+    const rawUsage = isRecord(rawEvent.usage) ? rawEvent.usage : undefined;
+    const usage = extractUsageTokens({ rawUsage: rawUsage });
+    const costUsd = asOptionalNumber(rawEvent.costUsd);
+    const durationMs = asOptionalNumber(rawEvent.durationMs);
+    return {
+        type: 'usage',
+        ...(usage !== undefined ? { usage } : {}),
+        ...(costUsd !== undefined ? { costUsd } : {}),
+        ...(durationMs !== undefined ? { durationMs } : {}),
+    };
+}
+export function translateStatusEvent({ rawEvent }) {
+    const model = asOptionalString(rawEvent.model);
+    const ttftMs = asOptionalNumber(rawEvent.ttftMs);
+    const detail = asOptionalString(rawEvent.detail);
+    const sessionId = asOptionalString(rawEvent.sessionId);
+    return {
+        kind: 'agent',
+        payload: {
+            type: 'status',
+            label: asString(rawEvent.label, 'unknown'),
+            ...(model !== undefined ? { model } : {}),
+            ...(ttftMs !== undefined ? { ttftMs } : {}),
+            ...(detail !== undefined ? { detail } : {}),
+        },
+        ...(sessionId !== undefined ? { sessionId } : {}),
+    };
+}
+function translateTextDeltaEvent(rawEvent) {
+    return { kind: 'agent', payload: { type: 'text_delta', delta: asString(rawEvent.delta) } };
+}
+function translateThinkingStartEvent() {
+    return { kind: 'agent', payload: { type: 'thinking_start' } };
+}
+function translateThinkingDeltaEvent(rawEvent) {
+    return { kind: 'agent', payload: { type: 'thinking_delta', delta: asString(rawEvent.delta) } };
+}
+function translateToolUseEvent(rawEvent) {
+    return {
+        kind: 'agent',
+        payload: {
+            type: 'tool_use',
+            id: asString(rawEvent.id),
+            name: asString(rawEvent.name),
+            input: rawEvent.input ?? null,
+        },
+    };
+}
+function translateToolInputDeltaEvent(rawEvent) {
+    return {
+        kind: 'agent',
+        payload: {
+            type: 'tool_input_delta',
+            id: asString(rawEvent.id),
+            name: asString(rawEvent.name),
+            delta: asString(rawEvent.delta),
+        },
+    };
+}
+export function translateToolResultEvent({ rawEvent }) {
+    const isError = typeof rawEvent.isError === 'boolean' ? rawEvent.isError : undefined;
+    return {
+        kind: 'agent',
+        payload: {
+            type: 'tool_result',
+            toolUseId: asString(rawEvent.toolUseId),
+            content: asString(rawEvent.content),
+            ...(isError !== undefined ? { isError } : {}),
+        },
+    };
+}
+function translateUsageEvent(rawEvent) {
+    return { kind: 'agent', payload: translateUsagePayload(rawEvent) };
+}
+function translateRawEvent(rawEvent) {
+    return { kind: 'agent', payload: { type: 'raw', line: asString(rawEvent.line) } };
+}
+export function translateErrorEvent({ rawEvent }) {
+    const code = asOptionalString(rawEvent.code);
+    const message = asString(rawEvent.message, 'Unknown agent error');
+    return {
+        kind: 'error',
+        payload: { message, ...(code !== undefined ? { error: { code, message } } : {}) },
+    };
+}
+export function translateTurnEndEvent({ rawEvent }) {
+    // Claude-specific per-turn boundary. Not forwarded as an 'agent'
+    // event (no RunAgentPayload variant represents it) — run() reacts to
+    // it directly to close stdin (or, for gap 3, decide whether to inject
+    // a tool result and keep it open instead). See module doc.
+    const stopReason = asOptionalString(rawEvent.stopReason);
+    return { kind: 'turn-end', ...(stopReason !== undefined ? { stopReason } : {}) };
+}
+/**
+ * One entry per `rawEvent.type` this driver understands, each producing the same
+ * {@link AgentRuntimeEventTranslation} `translateAgentRuntimeEvent` used to return from an inline
+ * `switch` — replaced with this table (refactor-patterns' preferred fix for a long switch over an
+ * event-kind discriminant) so each case's own mapping is independently readable and testable, and so
+ * `translateAgentRuntimeEvent` itself is just a lookup plus the two upfront guards.
+ */
+const EVENT_TYPE_TRANSLATORS = {
+    status: rawEvent => translateStatusEvent({ rawEvent }),
+    text_delta: translateTextDeltaEvent,
+    thinking_start: translateThinkingStartEvent,
+    thinking_delta: translateThinkingDeltaEvent,
+    tool_use: translateToolUseEvent,
+    tool_input_delta: translateToolInputDeltaEvent,
+    tool_result: rawEvent => translateToolResultEvent({ rawEvent }),
+    usage: translateUsageEvent,
+    raw: translateRawEvent,
+    error: rawEvent => translateErrorEvent({ rawEvent }),
+    turn_end: rawEvent => translateTurnEndEvent({ rawEvent }),
+};
+/**
+ * Narrows one parser-emitted `{type, ...}` record into this engine's
+ * `RunAgentPayload` union (or the `error`/`turn-end`/`ignored` routing
+ * `run()` special-cases). Pure — no I/O, no closure state — so every
+ * variant each of the 4 supported parsers can produce is directly
+ * assertable in isolation.
+ *
+ * Defensive by construction: several real parser emissions carry fields
+ * looser than `RunAgentPayload`'s types promise (e.g. copilot's
+ * `tool.execution_start` emits `id: data.toolCallId ?? null` — a literal
+ * `null`, not the `string` `RunAgentPayload['tool_use']['id']` demands).
+ * Every field read here is defensively coerced (`asString`/
+ * `asOptionalString`/`asOptionalNumber`) rather than trusted, so a
+ * malformed or null field degrades to a safe default instead of
+ * propagating `null`/`undefined` into a field typed as required, or
+ * throwing.
+ *
+ * @param rawEvent - One event as delivered to a stream parser's `onEvent` callback.
+ * @returns The routing + payload this event maps to.
+ * @complexity O(1) — one table lookup, no iteration.
+ * @overallScore 100/100
+ */
+export function translateAgentRuntimeEvent({ rawEvent }) {
+    if (!isRecord(rawEvent) || typeof rawEvent.type !== 'string') {
+        return { kind: 'ignored' };
+    }
+    const translator = EVENT_TYPE_TRANSLATORS[rawEvent.type];
+    return translator ? translator(rawEvent) : { kind: 'ignored' };
+}
+/**
+ * Maps an ACP session's transport error into the canonical run-error shape.
+ * ACP adapters may add a structured `error` member, but a daemon driver must
+ * never make one vendor's error shape part of the run protocol.
+ */
+export function translateAcpError(payload) {
+    if (!isRecord(payload))
+        return { message: asString(payload, 'ACP agent failed') };
+    const message = asString(payload.message, 'ACP agent failed');
+    const error = isRecord(payload.error) ? payload.error : null;
+    const code = error ? asOptionalString(error.code) : undefined;
+    const retryable = error && typeof error.retryable === 'boolean' ? error.retryable : undefined;
+    return {
+        message,
+        ...(code !== undefined
+            ? {
+                error: {
+                    code,
+                    message: asString(error?.message, message),
+                    ...(retryable !== undefined ? { retryable } : {}),
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * 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 function applyAgentTranslationSideEffects({ payload, sessionId, sink }) {
+    if (sessionId !== undefined)
+        sink.onSessionId({ sessionId });
+    if (payload.type === 'tool_use') {
+        sink.onToolCall();
+    }
+    else if ((payload.type === 'text_delta' || payload.type === 'thinking_delta') && payload.delta.length > 0) {
+        sink.onUserVisibleOutput();
+    }
+}
+//# sourceMappingURL=event-translation.js.map

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

@@ -0,0 +1,190 @@
+import { type ChildProcess } from 'node:child_process';
+import { attachAcpSession, attachPiRpcSession, type AcpPermissionHandler, type RuntimeAgentDef } from '@jini-ai/agent-runtime';
+import { type RunByteJournal } from '../continuation/journal.js';
+import { type RunLifecycle } from '../run-lifecycle.js';
+import { type ChildDrivenStreamFormat, type TerminateChildTreeDeps, type AgentCleanupFailureContext, type StdinCloseHandle, type ContinuationOptions, type McpBridgeDelivery, type ClassifyFailure, type FailBeforeSpawn } from './contracts.js';
+/** Default sink when a host does not supply `onCleanupFailure`: still observable, never silent. Redacted per SEC-007 (a spawn/permission error can embed paths/host detail). */
+export declare function defaultCleanupFailureSink(context: AgentCleanupFailureContext): void;
+/**
+ * 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;
+interface WireChildLifecycleContext extends TerminateChildTreeDeps {
+    readonly runId: string;
+    readonly def: RuntimeAgentDef;
+    readonly streamFormat: ChildDrivenStreamFormat;
+    readonly child: ChildProcess;
+    readonly lifecycle: RunLifecycle;
+    readonly onCleanupFailure: (context: AgentCleanupFailureContext) => void;
+    /**
+     * Removes every temp file `run()` staged for this run — a `promptViaFile`
+     * def's prompt file (grok-build) and a `needsAgentLogFile` def's log file
+     * (antigravity) — after the child exits. Deliberately one composed closure
+     * rather than one field per file: the two are staged at the same point and
+     * must be released on the same set of paths, and a second parallel field
+     * is exactly how one of them ends up forgotten on a path the other covers.
+     * A no-op default when neither was staged — see `run()`'s
+     * `preparePromptFileForAgent`/`prepareAgentLogFile` call sites.
+     */
+    readonly cleanupStagedFiles: () => Promise<void>;
+    /** Gap 1's byte-journal (see `continuation/journal.ts`). `undefined` when a caller configured none — every journal call site below is then a no-op. */
+    readonly journal: RunByteJournal | undefined;
+    /** Gap 3's stdin-tool-result injection config. `undefined` means every `turn_end` closes stdin unconditionally — see `ContinuationOptions`'s own doc. */
+    readonly continuation: ContinuationOptions | undefined;
+    /** Gap 4's failure classifier. `undefined` means every `'failed'` outcome stays `resumable: false` — byte-identical to pre-gap-4 behavior. See `ClassifyFailure`'s own doc. */
+    readonly classifyFailure: ClassifyFailure | undefined;
+    /** Ceiling on the `'until-close'` stdout accumulator — see {@link DEFAULT_BUFFERED_STDOUT_MAX_BYTES}. Always resolved by `run()`, never left to this function to default. */
+    readonly bufferedStdoutMaxBytes: number;
+    /**
+     * True when this run's CLI was handed the `jini` bridge (`'claude-mcp-json'` delivery). The first
+     * init frame's MCP report is then checked, and a bridge that is not connected stops the run with
+     * {@link MCP_BRIDGE_UNAVAILABLE} instead of letting it continue without the host's tools.
+     */
+    readonly expectsJiniBridge: boolean;
+}
+/**
+ * Wires one spawned child's full observable lifecycle: raw stdout/stderr
+ * forwarding, structured stream-parser dispatch (translated via
+ * {@link translateAgentRuntimeEvent}), cancellation (subscribes
+ * `lifecycle.onCancelRequested` and escalates via `stopProcesses` on the
+ * child's full descendant tree), and the terminal `close` → `finish()`
+ * transition. Registered *before* the caller awaits spawn confirmation so
+ * no early `'error'`/`'close'` event is ever missed.
+ *
+ * Every `lifecycle.emit()` call is funneled through a per-run FIFO queue
+ * (`enqueueEmit`) rather than fired independently: a single stdout `data`
+ * chunk can synchronously produce several parsed events (a JSON line's
+ * `feed()` call may invoke `onEvent` more than once), and successive
+ * `data` events must not have their derived `emit()` calls race each
+ * other out of order. The queue also absorbs an individual `emit()`
+ * rejection (e.g. a race against an already-terminal run) without losing
+ * subsequently queued events, and the `close` handler awaits it fully
+ * drained before computing the terminal outcome — so `finish()`'s `'end'`
+ * event is always durably last, never interleaved with a still-in-flight
+ * `'agent'`/`'stdout'`/`'stderr'` append.
+ *
+ * `streamFormat: 'plain'` gets no `createStreamHandlerForDef` parser at
+ * all (Option B — see index.ts module doc and
+ * `ADS-memory/reports/proposals/PROP-plain-format-agent-driving-2026-07-21.md`
+ * §3): every raw stdout chunk is forwarded verbatim as a `text_delta`
+ * `'agent'` event, through the same `enqueueEmit` FIFO queue every other
+ * emit already goes through — no new parser state machine.
+ * **Deliberately un-hygiened for v1**: no ANSI/terminal-control-sequence
+ * stripping is applied (there is no Jini equivalent of OD's
+ * `TerminalControlSequenceStripper` yet) — a documented decision, not an
+ * oversight; see `packages/daemon/archived provenance ledger`'s 2026-07-21 addition for
+ * the reasoning.
+ *
+ * *When* those chunks leave is the def's call, via `def.stdoutPolicy`:
+ *
+ *   - `'live'` (the default, and every def but antigravity) — emit per
+ *     chunk, as it arrives.
+ *   - `'until-close'` — accumulate, and emit the whole thing exactly once
+ *     from the `close` handler, after `def.stdoutPolicy.sanitize`. For an
+ *     adapter that can print a secret to stdout and still exit 0, no
+ *     per-chunk decision is safe: the pattern to redact can straddle two
+ *     `'data'` events.
+ *
+ * The buffered path holds back the raw `'stdout'` echo too, not just the
+ * `'agent'`/`text_delta`, and sanitizes both. Emitting an unsanitized raw
+ * echo while withholding the chat copy would leak the exact string the
+ * sanitizer exists to remove to any client subscribed to the run's events —
+ * the raw channel is a different *purpose*, not a different audience.
+ * `journal` is the one thing still recorded per-chunk and verbatim: it is
+ * the host's own byte record, deliberately kept in a **separate** `EventLog`
+ * instance that is never replayed to run-event subscribers (see
+ * `continuation/journal.ts`'s module doc), and "every byte received" is its
+ * whole contract.
+ *
+ * @param ctx - Run/def/child/lifecycle plus the cancellation-escalation ports.
+ * @returns A handle exposing `closeStdinOnce` for the initial prompt write to share.
+ * @complexity Registration is O(1); steady-state per-chunk cost is the
+ * chosen stream parser's own `feed()` cost plus O(1) queue bookkeeping.
+ * @overallScore 100/100
+ */
+export declare function wireChildLifecycle(ctx: WireChildLifecycleContext): StdinCloseHandle;
+/**
+ * Writes the initial user turn to the child's stdin per `def.promptInputFormat`
+ * (both branches only run for `promptViaStdin: true` defs — the only shape
+ * `run()` supports in v1, see index.ts module doc):
+ * - `'text'` (default): the raw prompt buffer, then stdin is closed —
+ *   matches `RuntimeAgentDef.promptInputFormat`'s own doc.
+ * - `'stream-json'`: one JSONL line wrapping the prompt as an Anthropic
+ *   user message; stdin is deliberately left open (a real multi-turn
+ *   caller would inject further messages) — v1 has no such caller, so
+ *   {@link wireChildLifecycle}'s `turn_end` handling closes it once the
+ *   agent's own stream reports the turn ended.
+ * @param def - The resolved agent def (only `.promptInputFormat` is read).
+ * @param child - The spawned child (no-ops if `.stdin` is unexpectedly absent).
+ * @param prompt - The composed user turn.
+ * @param handle - Shared stdin-close guard so a `'text'` write's immediate close and a later `turn_end` close never race into a double-`end()`; also carries gap 1's byte-journal recorder (see `StdinCloseHandle.recordSentBytes`).
+ * @complexity O(1) plus the underlying stream write's own cost.
+ * @overallScore 100/100
+ */
+export declare function writePromptToStdin(def: RuntimeAgentDef, child: ChildProcess, prompt: string, handle: StdinCloseHandle): void;
+interface RunAcpDispatchInput {
+    readonly runId: string;
+    readonly agentId: string;
+    readonly child: ChildProcess;
+    readonly prompt: string;
+    readonly cwd: string;
+    readonly model: string | undefined;
+    readonly imagePaths: readonly string[];
+    readonly envFormat: 'array' | 'map' | undefined;
+    readonly mcpBridge: McpBridgeDelivery | null;
+}
+interface RunAcpDispatchDeps extends TerminateChildTreeDeps {
+    readonly lifecycle: RunLifecycle;
+    readonly attachAcpSession: typeof attachAcpSession;
+    readonly onPermissionRequest: AcpPermissionHandler | undefined;
+    readonly onCleanupFailure: (context: AgentCleanupFailureContext) => void;
+    readonly cleanupStagedFiles: () => Promise<void>;
+    readonly journal: RunByteJournal | undefined;
+    readonly classifyFailure: ClassifyFailure | undefined;
+    readonly releaseStagedResources: () => Promise<void>;
+    readonly failBeforeSpawn: FailBeforeSpawn;
+}
+/** Phase 15 (ACP branch): attaches the ACP session, escalating process-tree teardown and failing the run through `failBeforeSpawn` on an attach-time throw. */
+export declare function runAcpDispatch({ input, deps }: {
+    readonly input: RunAcpDispatchInput;
+    readonly deps: RunAcpDispatchDeps;
+}): Promise<void>;
+interface RunPiRpcDispatchInput {
+    readonly runId: string;
+    readonly agentId: string;
+    readonly child: ChildProcess;
+    readonly prompt: string;
+    readonly cwd: string;
+    readonly model: string | undefined;
+    readonly imagePaths: readonly string[];
+    readonly uploadRoot: string | undefined;
+}
+interface RunPiRpcDispatchDeps extends TerminateChildTreeDeps {
+    readonly lifecycle: RunLifecycle;
+    readonly attachPiRpcSession: typeof attachPiRpcSession;
+    readonly onCleanupFailure: (context: AgentCleanupFailureContext) => void;
+    readonly cleanupStagedFiles: () => Promise<void>;
+    readonly journal: RunByteJournal | undefined;
+    readonly classifyFailure: ClassifyFailure | undefined;
+    readonly releaseStagedResources: () => Promise<void>;
+    readonly failBeforeSpawn: FailBeforeSpawn;
+}
+/** Phase 15 (pi-rpc branch): same discipline as {@link runAcpDispatch}, for the one `'pi-rpc'` def. */
+export declare function runPiRpcDispatch({ input, deps }: {
+    readonly input: RunPiRpcDispatchInput;
+    readonly deps: RunPiRpcDispatchDeps;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=events.d.ts.map