@jini-ai/agent-runtime 0.3.10 → 0.4.1

package/dist/agent-protocol/acp/session.d.ts

@@ -1,6 +1,6 @@
 import type { ExecutionProfile } from './types.js';
 import { type ArtifactTextSuppressor } from './text-suppression.js';
-import type { JsonRpcId, JsonObject, AcpChildProcess } from './types.js';
+import type { JsonRpcId, UnknownRecord, AcpChildProcess } from './types.js';
 import { type AcpMcpServerInput } from './session-params.js';
 import { type AccountFailureClassifier } from './account-failure.js';
 /** One option offered by an ACP agent for a pending tool permission request. */
@@ -19,10 +19,10 @@ export interface AcpPermissionOption {
 export interface AcpPermissionRequest {
     readonly requestId: JsonRpcId;
     readonly sessionId: string | null;
-    readonly toolCall: JsonObject | null;
+    readonly toolCall: UnknownRecord | null;
     readonly options: readonly AcpPermissionOption[];
     /** Original ACP request parameters for forward-compatible audit storage. */
-    readonly rawParams: JsonObject;
+    readonly rawParams: UnknownRecord;
 }
 /** A host's response to an {@link AcpPermissionRequest}. */
 export type AcpPermissionDecision = {
@@ -55,7 +55,10 @@ export interface AttachAcpSessionOptions {
     imagePaths?: string[];
     mcpServers?: AcpMcpServerInput[];
     envFormat?: 'array' | 'map';
-    send: (event: string, payload: unknown) => void;
+    send: (requiredArgs: {
+        event: string;
+        payload: unknown;
+    }) => void;
     /**
      * Receives every native ACP tool-permission request before the agent can
      * execute it. Omit it only when the host intends the session to fail closed
@@ -113,7 +116,10 @@ export declare function createAcpSessionState(): AcpSessionState;
  * construct a fake one with `vi.fn()` stubs for the callbacks.
  */
 export interface AcpSessionEffects {
-    send: (event: string, payload: unknown) => void;
+    send: (requiredArgs: {
+        event: string;
+        payload: unknown;
+    }) => void;
     fail: (message: string, options?: {
         forceModelUnavailable?: boolean;
         details?: unknown;
@@ -127,7 +133,7 @@ export interface AcpSessionEffects {
     emitVisibleTextDelta: (delta: string) => void;
     noteArtifactTextSuppression: (reason: string) => void;
     noteToolCallTextSuppression: (reason: string) => void;
-    emitAcpRawShapeDiagnostic: (update: JsonObject) => void;
+    emitAcpRawShapeDiagnostic: (update: UnknownRecord) => void;
     toolCallTextSuppressor: ArtifactTextSuppressor;
     runStartedAt: number;
     modelUnavailableErrorCode?: 'AMR_MODEL_UNAVAILABLE' | undefined;
@@ -149,20 +155,20 @@ export interface AcpSessionEffects {
 export declare function handleRpcError({ state, effects, obj, error, rpcErr, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    obj: JsonObject;
-    error: JsonObject | null;
+    obj: UnknownRecord;
+    error: UnknownRecord | null;
     rpcErr: string;
 }): void;
 /** Promotes an AMR retry-status `session/update` into a structured account-failure error, if the classifier matches. Returns `true` when it did (and thus failed the session). */
 export declare function tryPromoteAmrRetryStatus({ effects, update, }: {
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): boolean;
 /** Translates an `agent_thought_chunk` update into `thinking_start` (once) / `thinking_delta` events. */
 export declare function handleThoughtChunkUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 /** Strips tool-call XML from a raw message delta via the session's tool-call text suppressor, noting the suppression reason. */
 export declare function stripToolCallText({ effects, delta }: {
@@ -208,31 +214,31 @@ export declare function applyDsmlArtifactSuppression({ state, effects, suppresso
 export declare function handleMessageChunkUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 export declare function mirrorArtifactWriteToolEvent({ state, effects, update, toolCallId, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
     toolCallId: string | null;
 }): void;
 /** Arms the DSML artifact suppressor when a tool_call/tool_call_update completes an artifact write, or disarms it once its owning write call terminally fails. */
 export declare function updateDsmlSuppressorForToolCall({ state, update, toolCallId, }: {
     state: AcpSessionState;
-    update: JsonObject;
+    update: UnknownRecord;
     toolCallId: string | null;
 }): void;
 /** Translates a `tool_call` / `tool_call_update` update: tracks it as real turn output, mirrors artifact writes, and manages DSML suppressor arming. */
 export declare function handleToolCallUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 /** Top-level `session/update` dispatcher: emits a generic status for non-streaming update kinds, then routes to the matching per-kind handler. */
 export declare function handleSessionUpdate({ state, effects, update, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    update: JsonObject;
+    update: UnknownRecord;
 }): void;
 /** Handles the `initialize` ack: sends `session/load` (resume) or `session/new` (fresh). */
 export declare function handleInitializeAck({ state, effects }: {
@@ -248,33 +254,33 @@ export declare function triggerSetModelIfNeeded({ state, effects, }: {
 export declare function handleSessionNewAck({ state, effects, result, rawLine, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    result: JsonObject;
+    result: UnknownRecord;
     rawLine: string;
 }): void;
 /** Handles the `session/prompt` ack: fails a turn that reported model activity but produced no visible output, otherwise flushes and finishes cleanly. */
 export declare function handlePromptResult({ state, effects, result, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    result: JsonObject;
+    result: UnknownRecord;
 }): void;
 /** Whether an incoming result frame is the ack for an in-flight `session/set_model` (or `set_config_option`) request. */
 export declare function isModelSetAckExpected({ state, effects, obj, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    obj: JsonObject;
+    obj: UnknownRecord;
 }): boolean;
 /** Handles the `session/set_model` (or `set_config_option`) ack: records the confirmed model and sends the prompt. */
 export declare function handleModelSetAck({ state, effects, result, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    result: JsonObject;
+    result: UnknownRecord;
 }): void;
 /** Top-level JSON-RPC result dispatcher, keyed by which request `expectedId`/`promptRequestId` is currently outstanding. */
 export declare function routeResultById({ state, effects, obj, result, rawLine, }: {
     state: AcpSessionState;
     effects: AcpSessionEffects;
-    obj: JsonObject;
-    result: JsonObject | null;
+    obj: UnknownRecord;
+    result: UnknownRecord | null;
     rawLine: string;
 }): void;
 /**
@@ -302,5 +308,5 @@ export declare function routeResultById({ state, effects, obj, result, rawLine,
  * @returns A controller with `hasFatalError`, `getDurableSessionId`,
  *   `completedSuccessfully`, and `abort` methods.
  */
-export declare function attachAcpSession(options: AttachAcpSessionOptions): AcpSessionController;
+export declare function attachAcpSession(requiredArgs: Pick<AttachAcpSessionOptions, "child" | "prompt" | "send">, optionalArgs?: Omit<AttachAcpSessionOptions, "child" | "prompt" | "send">): AcpSessionController;
 //# sourceMappingURL=session.d.ts.map

package/dist/agent-protocol/acp/session.js

@@ -107,9 +107,9 @@ export function handleThoughtChunkUpdate({ state, effects, update, }) {
         return;
     if (!state.emittedThinkingStart) {
         state.emittedThinkingStart = true;
-        effects.send('agent', { type: 'thinking_start' });
+        effects.send({ event: 'agent', payload: { type: 'thinking_start' } });
     }
-    effects.send('agent', { type: 'thinking_delta', delta: text });
+    effects.send({ event: 'agent', payload: { type: 'thinking_delta', delta: text } });
 }
 /** Strips tool-call XML from a raw message delta via the session's tool-call text suppressor, noting the suppression reason. */
 export function stripToolCallText({ effects, delta }) {
@@ -251,13 +251,13 @@ export function mirrorArtifactWriteToolEvent({ state, effects, update, toolCallI
     if (!shouldEmit)
         return;
     st.emitted = true;
-    effects.send('agent', {
-        type: 'tool_use',
-        id: toolCallId,
-        name: 'Write',
-        input: { file_path: st.path ?? toolCallId },
-    });
-    effects.send('agent', { type: 'tool_result', toolUseId: toolCallId, isError: failed });
+    effects.send({ event: 'agent', payload: {
+            type: 'tool_use',
+            id: toolCallId,
+            name: 'Write',
+            input: { file_path: st.path ?? toolCallId },
+        } });
+    effects.send({ event: 'agent', payload: { type: 'tool_result', toolUseId: toolCallId, isError: failed } });
     state.emittedConcreteToolEvent = true;
 }
 /** Arms the DSML artifact suppressor when a tool_call/tool_call_update completes an artifact write, or disarms it once its owning write call terminally fails. */
@@ -302,11 +302,11 @@ export function handleSessionUpdate({ state, effects, update, }) {
     if (effects.modelUnavailableErrorCode && tryPromoteAmrRetryStatus({ effects, update }))
         return;
     if (update.sessionUpdate !== 'agent_message_chunk' && update.sessionUpdate !== 'agent_thought_chunk') {
-        effects.send('agent', {
-            type: 'status',
-            label: String(update.sessionUpdate || 'session_update'),
-            elapsedMs: Date.now() - effects.runStartedAt,
-        });
+        effects.send({ event: 'agent', payload: {
+                type: 'status',
+                label: String(update.sessionUpdate || 'session_update'),
+                elapsedMs: Date.now() - effects.runStartedAt,
+            } });
         effects.emitAcpRawShapeDiagnostic(update);
     }
     if (update.sessionUpdate === 'agent_thought_chunk') {
@@ -329,7 +329,7 @@ export function handleInitializeAck({ state, effects }) {
         effects.writeRpc(state.nextId, 'session/load', { sessionId: effects.resumeSessionId, cwd: effects.effectiveCwd }, 'session/load');
     }
     else {
-        effects.writeRpc(state.nextId, 'session/new', buildAcpSessionNewParams(effects.effectiveCwd, effects.mcpServers ? { mcpServers: effects.mcpServers, envFormat: effects.envFormat } : { envFormat: effects.envFormat }), 'session/new');
+        effects.writeRpc(state.nextId, 'session/new', buildAcpSessionNewParams({ cwd: effects.effectiveCwd }, effects.mcpServers ? { mcpServers: effects.mcpServers, envFormat: effects.envFormat } : { envFormat: effects.envFormat }), 'session/new');
     }
     state.nextId += 1;
 }
@@ -358,7 +358,7 @@ export function handleSessionNewAck({ state, effects, result, rawLine, }) {
     state.modelConfigId = resolveModelConfigId(findModelConfigOption(result.configOptions));
     state.activeModel = currentModelFromSessionResult(result);
     if (state.sessionId && state.activeModel) {
-        effects.send('agent', { type: 'status', label: 'model', model: state.activeModel });
+        effects.send({ event: 'agent', payload: { type: 'status', label: 'model', model: state.activeModel } });
     }
     if (triggerSetModelIfNeeded({ state, effects }))
         return;
@@ -403,7 +403,7 @@ export function handleModelSetAck({ state, effects, result, }) {
     // across the function boundary for the type checker (it doesn't survive
     // the call), not a behavior change.
     state.activeModel = currentModelFromSessionResult(result) ?? effects.model;
-    effects.send('agent', { type: 'status', label: 'model', model: state.activeModel });
+    effects.send({ event: 'agent', payload: { type: 'status', label: 'model', model: state.activeModel } });
     effects.sendPrompt();
 }
 /** Top-level JSON-RPC result dispatcher, keyed by which request `expectedId`/`promptRequestId` is currently outstanding. */
@@ -462,13 +462,19 @@ function resolveAcpSessionOptionDefaults(options) {
  * @returns A controller with `hasFatalError`, `getDurableSessionId`,
  *   `completedSuccessfully`, and `abort` methods.
  */
-export function attachAcpSession(options) {
+export function attachAcpSession(requiredArgs, optionalArgs = {}) {
+    const options = { ...optionalArgs, ...requiredArgs };
     const { child, prompt, cwd, model, mcpServers, send, modelUnavailableErrorCode, resumeSessionId, onPermissionRequest, onCliReady, onSessionInit, } = options;
     const { imagePaths, envFormat, clientName, clientVersion, stageTimeoutMs, executionProfile, accountFailureClassifier, } = resolveAcpSessionOptionDefaults(options);
     const runStartedAt = Date.now();
     const effectiveCwd = path.resolve(cwd || process.cwd());
     if (!child.stdin || !child.stdout) {
-        throw new Error('ACP child process must expose stdin and stdout streams');
+        const error = new Error('ACP child process must expose stdin and stdout streams');
+        if (resumeSessionId)
+            Object.assign(error, {
+                details: { kind: 'resume_failed', sessionId: resumeSessionId },
+            });
+        throw error;
     }
     const stdin = child.stdin;
     const stdout = child.stdout;
@@ -531,6 +537,34 @@ export function attachAcpSession(options) {
             value.includes('unknown model') ||
             value.includes('invalid model'));
     };
+    /** Emits a failure, tagging an unacknowledged resume without losing its cause.
+     * The session id is only set by a valid load acknowledgement, so the same
+     * boundary covers initialize/load RPC errors, watchdogs, and transport loss.
+     * Fresh sessions and errors after load keep their existing payloads.
+     * @complexity O(1), excluding the host's event sink.
+     */
+    const sendFailure = ({ payload }) => {
+        if (!resumeSessionId || state.sessionId) {
+            send({ event: 'error', payload });
+            return;
+        }
+        const original = asObject(payload) ?? {};
+        const originalError = asObject(original.error);
+        send({ event: 'error', payload: {
+                ...original,
+                error: {
+                    code: 'AGENT_EXECUTION_FAILED',
+                    message: original.message,
+                    retryable: false,
+                    ...originalError,
+                    details: {
+                        kind: 'resume_failed',
+                        sessionId: resumeSessionId,
+                        ...(originalError?.details === undefined ? {} : { cause: originalError.details }),
+                    },
+                },
+            } });
+    };
     // Both call sites below (the session/update retry-status promotion and the
     // stderr promotion) are already nested inside a scope gated by `finished`
     // at their own entry point (the parser callback's own `if (aborted ||
@@ -540,12 +574,12 @@ export function attachAcpSession(options) {
     // second time once `finished` is true. The origin file carried its own
     // `if (finished) return;` re-entry guard here anyway; removed per this
     // package's coverage-driven dead-branch discipline (verified unreachable
-    // by tracing every call site — see source-map.md), not suppressed.
+    // by tracing every call site — see archived provenance ledger), not suppressed.
     const failWithPayload = (payload) => {
         finished = true;
         fatal = true;
         clearStageTimer();
-        send('error', payload);
+        sendFailure({ payload });
         if (!child.killed)
             child.kill('SIGTERM');
     };
@@ -557,29 +591,29 @@ export function attachAcpSession(options) {
         clearStageTimer();
         const useModelUnavailable = modelUnavailableErrorCode &&
             (options.forceModelUnavailable || isModelUnavailableError(message));
-        send('error', useModelUnavailable
-            ? amrModelUnavailablePayload(message)
-            : options.details === undefined && options.retryable === undefined
-                ? { message }
-                : {
-                    message,
-                    error: {
-                        code: 'AGENT_EXECUTION_FAILED',
+        sendFailure({ payload: useModelUnavailable
+                ? amrModelUnavailablePayload(message)
+                : options.details === undefined && options.retryable === undefined
+                    ? { message }
+                    : {
                         message,
-                        retryable: options.retryable ?? false,
-                        // Every real call site that reaches this branch (the
-                        // RPC-error path and the no-visible-output path) always
-                        // supplies `details` whenever it supplies `retryable`, and
-                        // `retryable` is itself derived from the same `details`
-                        // source at the RPC-error call site — so `options.details`
-                        // is never actually undefined here. Spreading it
-                        // unconditionally (rather than conditionally omitting the
-                        // key) is behaviorally identical for every real caller;
-                        // simplified per this package's coverage-driven
-                        // dead-branch discipline. See source-map.md.
-                        details: options.details,
-                    },
-                });
+                        error: {
+                            code: 'AGENT_EXECUTION_FAILED',
+                            message,
+                            retryable: options.retryable ?? false,
+                            // Every real call site that reaches this branch (the
+                            // RPC-error path and the no-visible-output path) always
+                            // supplies `details` whenever it supplies `retryable`, and
+                            // `retryable` is itself derived from the same `details`
+                            // source at the RPC-error call site — so `options.details`
+                            // is never actually undefined here. Spreading it
+                            // unconditionally (rather than conditionally omitting the
+                            // key) is behaviorally identical for every real caller;
+                            // simplified per this package's coverage-driven
+                            // dead-branch discipline. See archived provenance ledger.
+                            details: options.details,
+                        },
+                    } });
         if (!child.killed)
             child.kill('SIGTERM');
     };
@@ -598,13 +632,13 @@ export function attachAcpSession(options) {
         if (rawAcpShapeDiagnosticCount >= ACP_RAW_EVENT_SHAPE_DIAGNOSTIC_LIMIT)
             return;
         rawAcpShapeDiagnosticCount += 1;
-        send('agent', {
-            type: 'diagnostic',
-            name: 'acp_raw_event_shape',
-            source: 'acp-json-rpc',
-            elapsedMs: Date.now() - runStartedAt,
-            shape: acpRawEventShape(update),
-        });
+        send({ event: 'agent', payload: {
+                type: 'diagnostic',
+                name: 'acp_raw_event_shape',
+                source: 'acp-json-rpc',
+                elapsedMs: Date.now() - runStartedAt,
+                shape: acpRawEventShape(update),
+            } });
     };
     // All three call sites guard against an empty `delta` before calling this
     // (the finishCleanPrompt flush, the `if (outputDelta)` branch, and the
@@ -613,18 +647,18 @@ export function attachAcpSession(options) {
     // origin file's own `if (!delta) return;` guard here can never actually
     // fire. Removed per this package's coverage-driven dead-branch
     // discipline (verified unreachable by tracing every call site — see
-    // source-map.md), not suppressed.
+    // archived provenance ledger), not suppressed.
     const emitVisibleTextDelta = (delta) => {
         state.emittedVisibleTextChunk = true;
         if (!emittedFirstTokenStatus) {
             emittedFirstTokenStatus = true;
-            send('agent', {
-                type: 'status',
-                label: 'streaming',
-                ttftMs: Date.now() - runStartedAt,
-            });
+            send({ event: 'agent', payload: {
+                    type: 'status',
+                    label: 'streaming',
+                    ttftMs: Date.now() - runStartedAt,
+                } });
         }
-        send('agent', { type: 'text_delta', delta });
+        send({ event: 'agent', payload: { type: 'text_delta', delta } });
     };
     const noteArtifactTextSuppression = (reason) => {
         if (!state.dsmlArtifactSuppressor)
@@ -641,42 +675,42 @@ export function attachAcpSession(options) {
         if (artifactSuppressionDiagnosticCount >= ACP_RAW_EVENT_SHAPE_DIAGNOSTIC_LIMIT)
             return;
         artifactSuppressionDiagnosticCount += 1;
-        send('agent', {
-            type: 'diagnostic',
-            name: 'acp_artifact_text_suppression',
-            source: 'acp-json-rpc',
-            elapsedMs: Date.now() - runStartedAt,
-            reason,
-            suppressedChars: artifactTextSuppressionSummary.suppressedChars,
-            suppressedChunks: artifactTextSuppressionSummary.suppressedChunks,
-            openedBlocks: artifactTextSuppressionSummary.openedBlocks,
-            closedBlocks: artifactTextSuppressionSummary.closedBlocks,
-            pendingCandidateChars: stats.pendingCandidateChars,
-            suppressing: stats.suppressing,
-        });
-    };
-    const emitArtifactTextSuppressionSummary = () => {
-        if (artifactTextSuppressionSummary.suppressedChars <= 0)
-            return;
-        if (executionProfile === 'filesystem') {
-            send('agent', {
+        send({ event: 'agent', payload: {
                 type: 'diagnostic',
-                name: 'unexpected_text_artifact_in_filesystem_run',
+                name: 'acp_artifact_text_suppression',
                 source: 'acp-json-rpc',
                 elapsedMs: Date.now() - runStartedAt,
+                reason,
                 suppressedChars: artifactTextSuppressionSummary.suppressedChars,
                 suppressedChunks: artifactTextSuppressionSummary.suppressedChunks,
                 openedBlocks: artifactTextSuppressionSummary.openedBlocks,
                 closedBlocks: artifactTextSuppressionSummary.closedBlocks,
-            });
+                pendingCandidateChars: stats.pendingCandidateChars,
+                suppressing: stats.suppressing,
+            } });
+    };
+    const emitArtifactTextSuppressionSummary = () => {
+        if (artifactTextSuppressionSummary.suppressedChars <= 0)
+            return;
+        if (executionProfile === 'filesystem') {
+            send({ event: 'agent', payload: {
+                    type: 'diagnostic',
+                    name: 'unexpected_text_artifact_in_filesystem_run',
+                    source: 'acp-json-rpc',
+                    elapsedMs: Date.now() - runStartedAt,
+                    suppressedChars: artifactTextSuppressionSummary.suppressedChars,
+                    suppressedChunks: artifactTextSuppressionSummary.suppressedChunks,
+                    openedBlocks: artifactTextSuppressionSummary.openedBlocks,
+                    closedBlocks: artifactTextSuppressionSummary.closedBlocks,
+                } });
         }
-        send('agent', {
-            type: 'diagnostic',
-            name: 'acp_artifact_text_suppression_summary',
-            source: 'acp-json-rpc',
-            elapsedMs: Date.now() - runStartedAt,
-            ...artifactTextSuppressionSummary,
-        });
+        send({ event: 'agent', payload: {
+                type: 'diagnostic',
+                name: 'acp_artifact_text_suppression_summary',
+                source: 'acp-json-rpc',
+                elapsedMs: Date.now() - runStartedAt,
+                ...artifactTextSuppressionSummary,
+            } });
     };
     const noteToolCallTextSuppression = (reason) => {
         const stats = toolCallTextSuppressor.stats();
@@ -691,30 +725,30 @@ export function attachAcpSession(options) {
         if (artifactSuppressionDiagnosticCount >= ACP_RAW_EVENT_SHAPE_DIAGNOSTIC_LIMIT)
             return;
         artifactSuppressionDiagnosticCount += 1;
-        send('agent', {
-            type: 'diagnostic',
-            name: 'acp_tool_call_text_suppression',
-            source: 'acp-json-rpc',
-            elapsedMs: Date.now() - runStartedAt,
-            reason,
-            suppressedChars: toolCallTextSuppressionSummary.suppressedChars,
-            suppressedChunks: toolCallTextSuppressionSummary.suppressedChunks,
-            openedBlocks: toolCallTextSuppressionSummary.openedBlocks,
-            closedBlocks: toolCallTextSuppressionSummary.closedBlocks,
-            pendingCandidateChars: stats.pendingCandidateChars,
-            suppressing: stats.suppressing,
-        });
+        send({ event: 'agent', payload: {
+                type: 'diagnostic',
+                name: 'acp_tool_call_text_suppression',
+                source: 'acp-json-rpc',
+                elapsedMs: Date.now() - runStartedAt,
+                reason,
+                suppressedChars: toolCallTextSuppressionSummary.suppressedChars,
+                suppressedChunks: toolCallTextSuppressionSummary.suppressedChunks,
+                openedBlocks: toolCallTextSuppressionSummary.openedBlocks,
+                closedBlocks: toolCallTextSuppressionSummary.closedBlocks,
+                pendingCandidateChars: stats.pendingCandidateChars,
+                suppressing: stats.suppressing,
+            } });
     };
     const emitToolCallTextSuppressionSummary = () => {
         if (toolCallTextSuppressionSummary.suppressedChars <= 0)
             return;
-        send('agent', {
-            type: 'diagnostic',
-            name: 'acp_tool_call_text_suppression_summary',
-            source: 'acp-json-rpc',
-            elapsedMs: Date.now() - runStartedAt,
-            ...toolCallTextSuppressionSummary,
-        });
+        send({ event: 'agent', payload: {
+                type: 'diagnostic',
+                name: 'acp_tool_call_text_suppression_summary',
+                source: 'acp-json-rpc',
+                elapsedMs: Date.now() - runStartedAt,
+                ...toolCallTextSuppressionSummary,
+            } });
     };
     const sendPrompt = () => {
         state.promptRequestId = state.nextId;
@@ -723,11 +757,11 @@ export function attachAcpSession(options) {
             sessionId: state.sessionId,
             prompt: buildPromptBlocks(prompt, imagePaths),
         }, 'session/prompt');
-        send('agent', {
-            type: 'status',
-            label: 'waiting_for_first_output',
-            elapsedMs: Date.now() - runStartedAt,
-        });
+        send({ event: 'agent', payload: {
+                type: 'status',
+                label: 'waiting_for_first_output',
+                elapsedMs: Date.now() - runStartedAt,
+            } });
         state.nextId += 1;
     };
     // `finishCleanPrompt` has exactly one call site (`handlePromptResult`,
@@ -736,7 +770,7 @@ export function attachAcpSession(options) {
     // (aborted || finished) return;` guard at entry — so this function can
     // never actually be invoked once `finished` is true. The origin file
     // carried its own re-entry guard here anyway; removed per this package's
-    // coverage-driven dead-branch discipline. See source-map.md.
+    // coverage-driven dead-branch discipline. See archived provenance ledger.
     const finishCleanPrompt = (usageSource) => {
         const flushedToolText = toolCallTextSuppressor.flush();
         noteToolCallTextSuppression('tool_call_xml_flush');
@@ -751,11 +785,11 @@ export function attachAcpSession(options) {
         emitArtifactTextSuppressionSummary();
         const usage = formatUsage(usageSource);
         if (usage) {
-            send('agent', {
-                type: 'usage',
-                usage,
-                durationMs: Date.now() - runStartedAt,
-            });
+            send({ event: 'agent', payload: {
+                    type: 'usage',
+                    usage,
+                    durationMs: Date.now() - runStartedAt,
+                } });
         }
         finished = true;
         clearStageTimer();
@@ -827,7 +861,7 @@ export function attachAcpSession(options) {
     const recoverFromModelSelectionError = () => {
         state.setModelRequestId = null;
         state.activeModel = state.activeModel || 'default';
-        send('agent', { type: 'status', label: 'model', model: state.activeModel });
+        send({ event: 'agent', payload: { type: 'status', label: 'model', model: state.activeModel } });
         sendPrompt();
     };
     const effects = {
@@ -853,36 +887,36 @@ export function attachAcpSession(options) {
         mcpServers,
         envFormat,
     };
-    const parser = createJsonLineStream((raw, rawLine) => {
-        if (aborted || finished)
-            return;
-        resetStageTimer('response');
-        const obj = asObject(raw);
-        if (!obj)
-            return;
-        // First well-formed ACP JSON-RPC message = CLI ready. Caller dedupes, so
-        // re-notifying on later messages is harmless.
-        onCliReady?.();
-        const error = asObject(obj.error);
-        const params = asObject(obj.params);
-        const result = asObject(obj.result);
-        const rpcErr = rpcErrorMessage(obj);
-        if (rpcErr) {
-            handleRpcError({ state, effects, obj, error, rpcErr });
-            return;
-        }
-        if (obj.method === 'session/request_permission') {
-            replyPermission(obj);
-            return;
-        }
-        const update = asObject(params?.update);
-        if (obj.method === 'session/update' && update) {
-            handleSessionUpdate({ state, effects, update });
-            return;
-        }
-        routeResultById({ state, effects, obj, result, rawLine });
-    });
-    stdout.on('data', (chunk) => parser.feed(chunk));
+    const parser = createJsonLineStream({ onMessage: ({ message: raw, rawLine }) => {
+            if (aborted || finished)
+                return;
+            resetStageTimer('response');
+            const obj = asObject(raw);
+            if (!obj)
+                return;
+            // First well-formed ACP JSON-RPC message = CLI ready. Caller dedupes, so
+            // re-notifying on later messages is harmless.
+            onCliReady?.();
+            const error = asObject(obj.error);
+            const params = asObject(obj.params);
+            const result = asObject(obj.result);
+            const rpcErr = rpcErrorMessage(obj);
+            if (rpcErr) {
+                handleRpcError({ state, effects, obj, error, rpcErr });
+                return;
+            }
+            if (obj.method === 'session/request_permission') {
+                replyPermission(obj);
+                return;
+            }
+            const update = asObject(params?.update);
+            if (obj.method === 'session/update' && update) {
+                handleSessionUpdate({ state, effects, update });
+                return;
+            }
+            routeResultById({ state, effects, obj, result, rawLine });
+        } });
+    stdout.on('data', (chunk) => parser.feed({ chunk: chunk }));
     child.stderr?.setEncoding('utf8');
     child.stderr?.on('data', (chunk) => {
         if (!modelUnavailableErrorCode || finished)