@jini-ai/daemon 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.5.4 — pending release
+
+- Re-export the canonical core surface-exchange contracts and parameter constants. Store and ask/report behavior are unchanged; requires core 0.4.2.
+
 ## 0.5.3 — 2026-10-06
 
 - Message attachments reach every runtime: new `prepareMessageAttachments` / `messageContentWithImages` (+ `MessageAttachmentImage`, `MessageAttachmentSource`, `MessageAttachmentReader`) turn claimed refs into image pixels for providers and a file notice for non-images.

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

@@ -1,13 +1,13 @@
 import type { MessageAttachmentImage } from '../attachment-content.js';
-import { type spawn as nodeSpawn, type ChildProcess } from 'node:child_process';
-import { type Principal } from '@jini-ai/core';
-import { type RunAgentPayload, type RunErrorPayload } from '@jini-ai/protocol';
-import { type applyAgentLaunchEnv, type ensureAgentCapabilities, type getAgentDef, type resolveAgentLaunch, type attachAcpSession, type attachPiRpcSession, type prepareAgentLogFile, type preparePromptFileForAgent, type AcpMcpServerInput, type AcpPermissionHandler, type PromptAugmenter } from '@jini-ai/agent-runtime';
-import { type createCommandInvocation, type listProcessSnapshots, type ProcessSnapshot, type StopProcessesResult } from '@jini-ai/platform';
-import { type RunByteJournal } from '../continuation/journal.js';
-import { type RunRetrySideEffectState } from '../run/core/index.js';
-import { type ToolExecutor } from '../tool-executor.js';
-import { type RunLifecycle } from '../run-lifecycle.js';
+import type { spawn as nodeSpawn, ChildProcess } from 'node:child_process';
+import type { Principal } from '@jini-ai/core';
+import type { RunAgentPayload, RunErrorPayload } from '@jini-ai/protocol';
+import type { applyAgentLaunchEnv, ensureAgentCapabilities, resolveModelForLaunch, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, prepareAgentLogFile, preparePromptFileForAgent, AcpMcpServerInput, AcpPermissionHandler, PromptAugmenter } from '@jini-ai/agent-runtime';
+import type { createCommandInvocation, listProcessSnapshots, ProcessSnapshot, StopProcessesResult } from '@jini-ai/platform';
+import type { RunByteJournal } from '../continuation/journal.js';
+import type { RunRetrySideEffectState } from '../run/core/index.js';
+import type { ToolExecutor } from '../tool-executor.js';
+import type { RunLifecycle } from '../run-lifecycle.js';
 /**
  * A parsed, loosely-typed event as produced by one of `@jini-ai/agent-runtime`'s
  * four stream-parser factories — each parser's `onEvent` callback receives
@@ -90,7 +90,7 @@ export type AgentRuntimeEventTranslation = {
     readonly kind: 'ignored';
 };
 /** Machine-readable failure reasons `run()` can reject with — every one is preceded by a `lifecycle.finish({status:'failed'})` call (see index.ts module doc's Invariant section). */
-export type AgentExecutorErrorCode = 'AGENT_PERMISSION_MODE_INVALID' | 'AGENT_NOT_FOUND' | 'AGENT_RUNTIME_UNSUPPORTED' | 'AGENT_BINARY_NOT_RESOLVED' | 'AGENT_SPAWN_FAILED' | 'AGENT_PROMPT_TOO_LARGE';
+export type AgentExecutorErrorCode = 'AGENT_MODEL_UNRESOLVED' | 'AGENT_PERMISSION_MODE_INVALID' | 'AGENT_NOT_FOUND' | 'AGENT_RUNTIME_UNSUPPORTED' | 'AGENT_BINARY_NOT_RESOLVED' | 'AGENT_SPAWN_FAILED' | 'AGENT_PROMPT_TOO_LARGE';
 /** Thrown by `AgentExecutor.run()` on every failure path — never a bare `Error`, so callers can branch on `.code` instead of parsing `.message`. */
 export declare class AgentExecutorError extends Error {
     readonly code: AgentExecutorErrorCode;
@@ -194,7 +194,27 @@ export interface AgentExecutor {
      * `lifecycle.finish()` before this rejects (see index.ts module doc's Invariant).
      */
     run(requiredArgs: Pick<AgentExecutorRunInput, "runId" | "agentId" | "prompt" | "cwd">, optionalArgs?: Pick<AgentExecutorRunInput, "model" | "reasoning" | "permissionMode" | "imagePaths" | "imageContents" | "extraAllowedDirs" | "uploadRoot" | "credentialEnv" | "env" | "resumeSessionId" | "newSessionId" | "disallowedTools" | "allowedTools" | "settingSources" | "settings">): Promise<void>;
+    /**
+     * Delivers a message the human sent while `runId` is going straight into its live agent process
+     * (see {@link UserMessageDelivery} for each outcome). A stream-json agent is interrupted first and
+     * gets the message once the CLI acknowledges the interrupt, so this settles in milliseconds (at
+     * most `INTERRUPT_ACK_TIMEOUT_MS`); it never waits on the agent's reply.
+     */
+    sendUserMessage(requiredArgs: {
+        readonly runId: string;
+        readonly text: string;
+    }): Promise<UserMessageDelivery>;
 }
+/**
+ * What {@link AgentExecutor.sendUserMessage} did with a mid-run message:
+ * - `'delivered'` — the running turn was interrupted and the message written into the live
+ *   session; the agent answers it next, in the same process and session.
+ * - `'unsupported'` — the run is live, but its agent has no way to take input mid-run (its prompt
+ *   is plain text or an RPC request). The host should interrupt and send it as the next turn.
+ * - `'not-running'` — no live process will accept it: an unknown run, a finished one, or one whose
+ *   last turn already ended and closed stdin. The run is ending; the host should send it next.
+ */
+export type UserMessageDelivery = 'delivered' | 'unsupported' | 'not-running';
 /** Process discovery is a getter; process collection and stopping accept explicit host inputs. */
 export type CollectProcessTreePidsPort = (args: {
     readonly processes: ProcessSnapshot[];
@@ -212,11 +232,11 @@ export interface TerminateChildTreeDeps {
  * Which step reported a contained failure through `onCleanupFailure` (SEC-007).
  *
  * The first three come from {@link terminateChildTreeBestEffort} (process-tree teardown). The last
- * two are the two fallible steps that sit between a child's `'close'` and `finish()` — staged-file
- * removal and the host's own `classifyFailure` — neither of which may prevent the terminal
- * transition, and neither of which may fail silently either. See each close handler.
+ * three cover tool cancellation, staged-file removal and the host's own `classifyFailure`.
+ * These fallible steps between a child's `'close'` and `finish()` must never prevent the terminal
+ * transition, and none may fail silently either. See each close handler.
  */
-export type AgentCleanupFailurePhase = 'cancel' | 'acp-attach-failure' | 'pi-rpc-attach-failure' | 'staged-file-cleanup' | 'failure-classification';
+export type AgentCleanupFailurePhase = 'cancel' | 'acp-attach-failure' | 'pi-rpc-attach-failure' | 'tool-cancellation' | 'staged-file-cleanup' | 'failure-classification';
 export interface AgentCleanupFailureContext {
     readonly runId: string;
     readonly phase: AgentCleanupFailurePhase;
@@ -237,6 +257,8 @@ export interface StdinCloseHandle {
     closeStdinOnce(): void;
     /** Journals a sent-to-stdin byte chunk, queued through the same FIFO {@link wireChildLifecycle} already uses for emitted events. No-op when no journal was configured (see `CreateAgentExecutorOptions.journal`). */
     recordSentBytes(content: string): void;
+    /** Interrupts this child's turn, then writes a mid-run user message into its open stdin — see {@link AgentExecutor.sendUserMessage}. */
+    sendUserMessage(text: string): Promise<UserMessageDelivery>;
 }
 /**
  * Gap 3 (capability-routed continuation transport) — host-owned config for the
@@ -374,6 +396,13 @@ export interface McpJsonInjectionOptions {
     readonly removeDir?: ({ path }: {
         readonly path: string;
     }) => Promise<void>;
+    /** `'codex-toml'` only. Links the run home's sessions/archived_sessions to the operator's
+     * persistent rollout store. Config and auth remain isolated and are removed after the run.
+     * @default Native mkdir (0700) and directory symlinks; errors fail staging before spawn. */
+    readonly linkSessionStore?: (required: {
+        runHome: string;
+        sourceHome: string;
+    }, optional?: {}) => Promise<void>;
 }
 /** One `.mcp.json` `mcpServers` entry — the shape Claude Code's own config schema expects. */
 export interface McpJsonServerEntry {
@@ -543,6 +572,8 @@ export interface FailureClassificationContext {
 export type ClassifyFailure = (context: FailureClassificationContext) => boolean | Promise<boolean>;
 export interface CreateAgentExecutorOptions {
     readonly lifecycle: RunLifecycle;
+    /** Resolves/pins the concrete starting model against the actual launch scope. */
+    readonly resolveModelForLaunch?: typeof resolveModelForLaunch;
     /** @default the real `@jini-ai/agent-runtime` registry lookup */
     readonly getAgentDef?: typeof getAgentDef;
     /** @default the real `@jini-ai/agent-runtime` launch resolver */

package/dist/agent-executor/contracts.js

@@ -1,12 +1,3 @@
-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',

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

@@ -1,5 +1,5 @@
-import { type RunAgentPayload, type RunErrorPayload } from '@jini-ai/protocol';
-import { type AgentRuntimeEventTranslation } from './contracts.js';
+import type { RunAgentPayload, 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

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

@@ -1,5 +1,3 @@
-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;

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

@@ -1,8 +1,9 @@
-import { type ChildProcess } from 'node:child_process';
+import type { ModelCatalogSnapshot } from '@jini-ai/agent-runtime';
+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';
+import type { RunByteJournal } from '../continuation/journal.js';
+import type { RunLifecycle } from '../run-lifecycle.js';
+import type { ChildDrivenStreamFormat, TerminateChildTreeDeps, AgentCleanupFailureContext, StdinCloseHandle, ContinuationOptions, McpBridgeDelivery, ClassifyFailure, 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;
 /**
@@ -22,6 +23,8 @@ export declare function defaultCleanupFailureSink(context: AgentCleanupFailureCo
  */
 export declare const DEFAULT_BUFFERED_STDOUT_MAX_BYTES: number;
 interface WireChildLifecycleContext extends TerminateChildTreeDeps {
+    readonly startingModel?: string;
+    readonly modelCatalog?: ModelCatalogSnapshot;
     readonly runId: string;
     readonly def: RuntimeAgentDef;
     readonly streamFormat: ChildDrivenStreamFormat;
@@ -115,6 +118,21 @@ interface WireChildLifecycleContext extends TerminateChildTreeDeps {
  * @overallScore 100/100
  */
 export declare function wireChildLifecycle(ctx: WireChildLifecycleContext): StdinCloseHandle;
+/**
+ * Whether a def's live process can take another user message mid-run: only a stream-json stdin
+ * transport keeps stdin open for more JSONL user lines (see `RuntimeAgentDef.promptInputFormat`).
+ * Deliberately not `resolveContinuationTransport`: that answers how a tool result gets back, and
+ * reports `'mcp-callback'` for Claude even though its stdin takes user lines all the same.
+ */
+export declare function acceptsMidRunUserMessages({ def }: {
+    readonly def: RuntimeAgentDef;
+}): boolean;
+/**
+ * How long a mid-run message waits for the CLI to acknowledge its interrupt before being written
+ * anyway. Claude Code acks within milliseconds (it answers before the aborted turn's own result);
+ * the ceiling only bounds an agent that ignores control requests.
+ */
+export declare const INTERRUPT_ACK_TIMEOUT_MS = 5000;
 /**
  * Writes the initial user turn to the child's stdin per `def.promptInputFormat`
  * (both branches only run for `promptViaStdin: true` defs — the only shape
@@ -122,8 +140,8 @@ export declare function wireChildLifecycle(ctx: WireChildLifecycleContext): Stdi
  * - `'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
+ *   user message; stdin is deliberately left open so a message the human
+ *   sends mid-run can follow it (`StdinCloseHandle.sendUserMessage`), and
  *   {@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).
@@ -141,6 +159,7 @@ interface RunAcpDispatchInput {
     readonly prompt: string;
     readonly cwd: string;
     readonly model: string | undefined;
+    readonly modelCatalog?: ModelCatalogSnapshot;
     readonly imagePaths: readonly string[];
     readonly envFormat: 'array' | 'map' | undefined;
     readonly mcpBridge: McpBridgeDelivery | null;
@@ -168,6 +187,7 @@ interface RunPiRpcDispatchInput {
     readonly prompt: string;
     readonly cwd: string;
     readonly model: string | undefined;
+    readonly modelCatalog?: ModelCatalogSnapshot;
     readonly imagePaths: readonly string[];
     readonly uploadRoot: string | undefined;
 }

package/dist/agent-executor/events.js

@@ -1,18 +1,15 @@
+import { randomUUID } from 'node:crypto';
+import { createModelReceiptTracker } from './model-receipts.js';
 import { messageContentWithImages } from '../attachment-content.js';
-import {} from 'node:child_process';
 import { redactSecrets, } from '@jini-ai/core';
-import {} from '@jini-ai/protocol';
 import { createClaudeStreamHandler, createCopilotStreamHandler, createJsonEventStreamHandler, createQoderStreamHandler, attachAcpSession, attachPiRpcSession, } from '@jini-ai/agent-runtime';
 import { collectProcessTreePids, listProcessSnapshots, stopProcesses, } from '@jini-ai/platform';
 import { classifyRunCloseStatus, } from '../close-status.js';
 import { resolveContinuationTransport, } from '../continuation/continuation-transport.js';
-import {} from '../continuation/journal.js';
 import { resultContent, } from '../delegated-tool-bridge.js';
 import { extractResultMedia, } from '../tool-result-media.js';
-import {} from '../run-lifecycle.js';
-import {} from './contracts.js';
 import { translateAgentRuntimeEvent, translateAcpError, applyAgentTranslationSideEffects, } from './event-translation.js';
-import { errorMessage, } from './values.js';
+import { errorMessage, isRecord, } from './values.js';
 import { MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, bridgeUnavailableMessage, } from './mcp-bridge.js';
 /** Carry PID only on structured status so the host can record its OS start identity early.
  * A PID alone is never proof of death; hosts verify PID reuse before native continuation. */
@@ -72,7 +69,7 @@ export function defaultCleanupFailureSink(context) {
 /**
  * Reports a contained post-close failure through the host's sink, absorbing a throwing sink.
  *
- * A diagnostic sink is host code too, and the whole point of the two callers below is that nothing
+ * A diagnostic sink is host code too, and the whole point of these callers is that nothing
  * between `'close'` and `finish()` can strand the run — a sink that throws must not reintroduce
  * exactly that. Same reasoning `run-lifecycle.ts`'s `handleInactivityTimeout` already applies to its
  * own `onInternalError`.
@@ -260,6 +257,7 @@ function bufferedStdoutTruncationNotice(droppedBytes, maxBytes) {
  */
 export function wireChildLifecycle(ctx) {
     const { runId, def, streamFormat, child, lifecycle, journal, continuation, classifyFailure } = ctx;
+    const modelReceipt = createModelReceiptTracker(ctx.startingModel, ctx.modelCatalog?.models);
     let stdinClosed = false;
     let cancelRequested = false;
     let emitQueue = Promise.resolve();
@@ -276,6 +274,37 @@ export function wireChildLifecycle(ctx) {
     // consumed by a turn-end injection decision. See `ContinuationOptions`'s doc for why this is
     // only ever acted on when a host has explicitly allowlisted the tool's name.
     let pendingToolUse;
+    // Observe the canonical lifecycle, including delegated calls that bypass the CLI parser.
+    // A single latest tool_use cannot represent parallel tools at an interrupt boundary.
+    const unresolvedToolCalls = new Set();
+    const interruptedToolCalls = new Set();
+    const toolSubscription = lifecycle.stream({ runId, onEvent: (event) => {
+            if (event.kind !== 'agent')
+                return;
+            if (event.payload.type === 'tool_use')
+                unresolvedToolCalls.add(event.payload.id);
+            if (event.payload.type === 'tool_result')
+                unresolvedToolCalls.delete(event.payload.toolUseId);
+        } }).catch(error => {
+        // Observing tools is fallible I/O too: report it, but never strand close/finish on a replay
+        // failure or leave an unhandled rejection while the child is still running.
+        reportPostCloseFailure(ctx.onCleanupFailure, { runId, phase: 'tool-cancellation', pid: child.pid, error });
+        return null;
+    });
+    /** Run on the same FIFO as parsed results, after the aborted segment has drained.
+     * O(t) in unresolved calls; completed results are never replaced with cancellation. */
+    async function cancelUnresolvedToolCalls(ids) {
+        await toolSubscription;
+        for (const toolUseId of ids ?? [...unresolvedToolCalls]) {
+            if (!unresolvedToolCalls.has(toolUseId))
+                continue;
+            await lifecycle.emit({ runId, input: { event: 'agent', data: {
+                        type: 'tool_result', toolUseId, content: 'Tool execution cancelled.', isError: true,
+                    } } }).catch(error => {
+                reportPostCloseFailure(ctx.onCleanupFailure, { runId, phase: 'tool-cancellation', pid: child.pid, error });
+            });
+        }
+    }
     // Bridge guard (see `expectsJiniBridge`): checked on the first init frame only. Once the bridge is
     // found unavailable, the child is being stopped and nothing it still prints is forwarded.
     let bridgeChecked = !ctx.expectsJiniBridge;
@@ -306,12 +335,43 @@ export function wireChildLifecycle(ctx) {
             }
         });
     }
+    if (ctx.startingModel)
+        enqueueEmit(() => lifecycle.emit({ runId, input: { event: 'agent', data: { type: 'status', label: 'starting_model', model: ctx.startingModel } } }));
     function closeStdinOnce() {
         if (stdinClosed)
             return;
         stdinClosed = true;
         child.stdin?.end();
     }
+    // Mid-run interrupts (see `sendUserMessage` below): each sent `interrupt` control request waits
+    // here, by request id, for the CLI's `control_response`. Settled with `true` on the ack, `false`
+    // when the process exits first. Bounded by the mid-run messages in flight on this one run.
+    const pendingInterruptAcks = new Map();
+    // Set once this run has interrupted its agent: from then on a turn the interrupt aborted
+    // (`aborted_*` stop reason) is not the run's last — the message that follows starts a new one.
+    let interruptSent = false;
+    // stdout carry-over for spotting acks; only filled while an interrupt waits for one.
+    let ackScanBuffer = '';
+    /** Resolves every waiting interrupt whose `control_response` is in this stdout chunk. @complexity O(chunk length). */
+    function scanForInterruptAcks(text) {
+        if (pendingInterruptAcks.size === 0)
+            return;
+        ackScanBuffer += text;
+        const lines = ackScanBuffer.split('\n');
+        ackScanBuffer = lines.pop() ?? '';
+        for (const line of lines) {
+            if (!line.includes('"control_response"'))
+                continue;
+            const requestId = controlResponseRequestId({ line: line });
+            const settle = requestId === undefined ? undefined : pendingInterruptAcks.get(requestId);
+            if (!settle)
+                continue;
+            pendingInterruptAcks.delete(requestId);
+            settle(true);
+        }
+        if (pendingInterruptAcks.size === 0)
+            ackScanBuffer = '';
+    }
     /**
      * Writes a structured (never string-concatenated — see `ContinuationOptions`'s doc on the
      * prompt-injection stakes here) tool_result JSONL line, mirroring the shape
@@ -331,6 +391,21 @@ export function wireChildLifecycle(ctx) {
         if (journal)
             enqueueEmit(() => journal.record({ runId: runId, entry: sentJournalEntry(content) }));
     }
+    /**
+     * Whether a `turn_end` leaves stdin open for a live agent that takes mid-run messages, because
+     * the run is not over: a `tool_use` stop (the CLI runs the tool itself and carries on, and a
+     * message sent while the tool runs must still reach it), any end while an interrupt still waits
+     * for its ack (the message is about to be written), and the end of a turn an interrupt aborted
+     * (the message written after it starts the next turn). Every other end closes stdin, so the CLI
+     * exits once it has answered everything written before EOF.
+     */
+    function keepsStdinOpenAfterTurnEnd(stopReason) {
+        if (!acceptsMidRunUserMessages({ def: def }))
+            return false;
+        if (stopReason === 'tool_use' || pendingInterruptAcks.size > 0)
+            return true;
+        return interruptSent && stopReason !== undefined && stopReason.startsWith('aborted');
+    }
     /**
      * Decides, per `turn_end`, whether to auto-resolve a pending tool_use through the injected
      * `ToolExecutor` and keep stdin open (gap 3), or close stdin exactly as every version of this
@@ -338,6 +413,11 @@ export function wireChildLifecycle(ctx) {
      * unconfigured or the pending tool isn't allowlisted).
      */
     function handleTurnEnd(stopReason) {
+        if (stopReason?.startsWith('aborted'))
+            enqueueEmit(async () => {
+                await cancelUnresolvedToolCalls([...interruptedToolCalls]);
+                interruptedToolCalls.clear();
+            });
         const toolUse = pendingToolUse;
         const shouldInject = stopReason === 'tool_use' &&
             toolUse !== undefined &&
@@ -345,7 +425,8 @@ export function wireChildLifecycle(ctx) {
             resolveContinuationTransport({ def: def }) === 'stdin-injection' &&
             continuation.autonomousToolNames.has(toolUse.name);
         if (!shouldInject) {
-            closeStdinOnce();
+            if (!keepsStdinOpenAfterTurnEnd(stopReason))
+                closeStdinOnce();
             return;
         }
         pendingToolUse = undefined;
@@ -399,6 +480,9 @@ export function wireChildLifecycle(ctx) {
                 return;
             const translation = translateAgentRuntimeEvent({ rawEvent: rawEvent });
             if (translation.kind === 'agent') {
+                const receipt = modelReceipt(translation.payload);
+                if (receipt)
+                    enqueueEmit(() => lifecycle.emit({ runId, input: { event: 'agent', data: receipt } }));
                 if (translation.sessionId !== undefined)
                     capturedSessionId = translation.sessionId;
                 if (!bridgeChecked && translation.payload.type === 'status' && translation.payload.label === 'initializing') {
@@ -495,6 +579,9 @@ export function wireChildLifecycle(ctx) {
             return;
         }
         enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
+        // Before the parser: an ack and the aborted turn's end can share a chunk, and the turn end must
+        // see that no interrupt is still waiting (see `keepsStdinOpenAfterTurnEnd`).
+        scanForInterruptAcks(text);
         // Non-null: `streamHandler` is only ever null when `streamFormat === 'plain'` (see its
         // construction above), the branch this statement is provably unreachable from.
         streamHandler.feed({ chunk: text });
@@ -520,6 +607,9 @@ export function wireChildLifecycle(ctx) {
             void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
         } });
     child.on('close', (code, signal) => {
+        for (const settle of pendingInterruptAcks.values())
+            settle(false);
+        pendingInterruptAcks.clear();
         void (async () => {
             // Not wrapped in try/catch: all 4 supported parser factories'
             // flush() implementations already internally guard their own
@@ -534,6 +624,11 @@ export function wireChildLifecycle(ctx) {
             // `finish()`'s `'end'` event, exactly like every live-path emit already is.
             flushBufferedStdout();
             await emitQueue;
+            if (cancelRequested)
+                await cancelUnresolvedToolCalls();
+            const subscribedTools = await toolSubscription;
+            if (subscribedTools?.kind === 'ok')
+                subscribedTools.unsubscribe();
             unsubscribeCancel();
             // Both of the next two steps are guarded: neither a failed cleanup nor a rejecting host
             // classifier may prevent the terminal transition below — see each helper's own doc.
@@ -552,14 +647,92 @@ export function wireChildLifecycle(ctx) {
             await lifecycle.finish({ runId, status, code, signal: signal ?? null, resumable }, { ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}) });
         })();
     });
+    /**
+     * A mid-run message: first an `interrupt` control request on the still-open stdin, so the agent
+     * stops generating (or abandons the tool it is running) at once instead of finishing its whole
+     * reply; then, once the CLI acknowledges, the message as the next user line, which the CLI
+     * answers straight away in the same session; then the run's own `user_message` event through the
+     * same FIFO as the agent's output, so the message sits in the stream where it took effect.
+     * An ack that never comes (an agent that ignores control requests) only delays the write by
+     * {@link INTERRUPT_ACK_TIMEOUT_MS}: the CLI then folds the line in at its next step. Once
+     * `turn_end` has closed stdin, or the process exits before the ack, there is no session left to
+     * reach — `'not-running'`.
+     */
+    async function sendUserMessage(text) {
+        if (!acceptsMidRunUserMessages({ def: def }))
+            return 'unsupported';
+        const stdin = child.stdin;
+        if (stdinClosed || !stdin)
+            return 'not-running';
+        const requestId = `jini-interrupt-${randomUUID()}`;
+        interruptSent = true;
+        // Capture before requesting the interrupt. Its result can precede the acknowledgement, or
+        // arrive after the next segment starts: neither ordering may cancel that segment's new tools.
+        enqueueEmit(async () => {
+            await toolSubscription;
+            for (const id of interruptedToolCalls)
+                if (!unresolvedToolCalls.has(id))
+                    interruptedToolCalls.delete(id);
+            for (const id of unresolvedToolCalls)
+                interruptedToolCalls.add(id);
+        });
+        const acked = new Promise((resolve) => pendingInterruptAcks.set(requestId, resolve));
+        stdin.write(`${JSON.stringify({ type: 'control_request', request_id: requestId, request: { subtype: 'interrupt' } })}\n`, 'utf8');
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(true), INTERRUPT_ACK_TIMEOUT_MS);
+        });
+        const processAlive = await Promise.race([acked, timedOut]);
+        clearTimeout(timer);
+        pendingInterruptAcks.delete(requestId);
+        if (!processAlive || stdinClosed)
+            return 'not-running';
+        stdin.write(`${JSON.stringify(streamJsonUserMessage({ content: [{ type: 'text', text: text }] }))}\n`, 'utf8');
+        if (journal)
+            enqueueEmit(() => journal.record({ runId: runId, entry: sentJournalEntry(text) }));
+        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: { type: 'user_message', id: randomUUID(), text: text } } }));
+        return 'delivered';
+    }
     return {
         closeStdinOnce,
         recordSentBytes(content) {
             if (journal)
                 enqueueEmit(() => journal.record({ runId: runId, entry: sentJournalEntry(content) }));
         },
+        sendUserMessage,
     };
 }
+/**
+ * Whether a def's live process can take another user message mid-run: only a stream-json stdin
+ * transport keeps stdin open for more JSONL user lines (see `RuntimeAgentDef.promptInputFormat`).
+ * Deliberately not `resolveContinuationTransport`: that answers how a tool result gets back, and
+ * reports `'mcp-callback'` for Claude even though its stdin takes user lines all the same.
+ */
+export function acceptsMidRunUserMessages({ def }) {
+    return def.promptViaStdin === true && def.promptInputFormat === 'stream-json';
+}
+/**
+ * How long a mid-run message waits for the CLI to acknowledge its interrupt before being written
+ * anyway. Claude Code acks within milliseconds (it answers before the aborted turn's own result);
+ * the ceiling only bounds an agent that ignores control requests.
+ */
+export const INTERRUPT_ACK_TIMEOUT_MS = 5_000;
+/** The `request_id` of a stream-json `control_response` line, or `undefined` for anything else. */
+function controlResponseRequestId({ line }) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!isRecord(parsed) || parsed.type !== 'control_response' || !isRecord(parsed.response))
+            return undefined;
+        return typeof parsed.response.request_id === 'string' ? parsed.response.request_id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The stream-json stdin envelope for one user message — the initial prompt and every mid-run one. */
+function streamJsonUserMessage({ content }) {
+    return { type: 'user', message: { role: 'user', content: content } };
+}
 /**
  * Wires an ACP child to a run. Unlike the JSON-stream path, ACP owns the
  * prompt protocol and reports its parsed events through `attachAcpSession`'s
@@ -570,6 +743,7 @@ export function wireChildLifecycle(ctx) {
  * success.
  */
 function wireAcpLifecycle(ctx) {
+    const modelReceipt = createModelReceiptTracker(ctx.model, ctx.modelCatalog?.models);
     const { runId, agentId, child, lifecycle, journal, classifyFailure } = ctx;
     let cancelRequested = false;
     let emitQueue = Promise.resolve();
@@ -589,6 +763,8 @@ function wireAcpLifecycle(ctx) {
             }
         });
     }
+    if (ctx.model)
+        enqueueEmit(() => lifecycle.emit({ runId, input: { event: 'agent', data: { type: 'status', label: 'starting_model', model: ctx.model } } }));
     child.stdout?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
@@ -632,6 +808,9 @@ function wireAcpLifecycle(ctx) {
             if (event === 'agent') {
                 const translation = translateAgentRuntimeEvent({ rawEvent: payload });
                 if (translation.kind === 'agent') {
+                    const receipt = modelReceipt(translation.payload);
+                    if (receipt)
+                        enqueueEmit(() => lifecycle.emit({ runId, input: { event: 'agent', data: receipt } }));
                     applyAgentTranslationSideEffects({ payload: translation.payload, sessionId: translation.sessionId, sink: {
                             onSessionId: ({ sessionId }) => { capturedSessionId = sessionId; },
                             onToolCall: () => { toolCallSeen = true; },
@@ -674,6 +853,7 @@ function wireAcpLifecycle(ctx) {
  * multi-turn tool continuation, resumable session ids, etc.).
  */
 function wirePiRpcLifecycle(ctx) {
+    const modelReceipt = createModelReceiptTracker(ctx.model, ctx.modelCatalog?.models);
     const { runId, agentId, child, lifecycle, journal, classifyFailure } = ctx;
     let cancelRequested = false;
     let emitQueue = Promise.resolve();
@@ -693,6 +873,8 @@ function wirePiRpcLifecycle(ctx) {
             }
         });
     }
+    if (ctx.model)
+        enqueueEmit(() => lifecycle.emit({ runId, input: { event: 'agent', data: { type: 'status', label: 'starting_model', model: ctx.model } } }));
     child.stdout?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
@@ -735,6 +917,9 @@ function wirePiRpcLifecycle(ctx) {
     session = ctx.attachPiRpcSession({ child: ctx.child, prompt: ctx.prompt, send({ payload }) {
             const translation = translateAgentRuntimeEvent({ rawEvent: payload });
             if (translation.kind === 'agent') {
+                const receipt = modelReceipt(translation.payload);
+                if (receipt)
+                    enqueueEmit(() => lifecycle.emit({ runId, input: { event: 'agent', data: receipt } }));
                 if (translation.sessionId !== undefined)
                     capturedSessionId = translation.sessionId;
                 if (translation.payload.type === 'tool_use') {
@@ -759,8 +944,8 @@ function wirePiRpcLifecycle(ctx) {
  * - `'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
+ *   user message; stdin is deliberately left open so a message the human
+ *   sends mid-run can follow it (`StdinCloseHandle.sendUserMessage`), and
  *   {@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).
@@ -775,7 +960,7 @@ export function writePromptToStdin(def, child, prompt, handle) {
     if (!stdin)
         return;
     if (def.promptInputFormat === 'stream-json') {
-        const line = JSON.stringify({ type: 'user', message: { role: 'user', content: messageContentWithImages({ prompt, images: handle.imageContents ?? [] }, {}) } });
+        const line = JSON.stringify(streamJsonUserMessage({ content: messageContentWithImages({ prompt, images: handle.imageContents ?? [] }, {}) }));
         stdin.write(`${line}\n`, 'utf8');
         handle.recordSentBytes(prompt);
         return;
@@ -795,6 +980,7 @@ export async function runAcpDispatch({ input, deps }) {
             prompt: input.prompt,
             cwd: input.cwd,
             model: input.model,
+            ...(input.modelCatalog ? { modelCatalog: input.modelCatalog } : {}),
             imagePaths: input.imagePaths,
             envFormat: input.envFormat,
             // Mechanism 2 of 5 — see `WireAcpLifecycleContext.mcpServers`. `undefined` for any def that
@@ -831,6 +1017,7 @@ export async function runPiRpcDispatch({ input, deps }) {
             prompt: input.prompt,
             cwd: input.cwd,
             model: input.model,
+            ...(input.modelCatalog ? { modelCatalog: input.modelCatalog } : {}),
             imagePaths: input.imagePaths,
             uploadRoot: input.uploadRoot,
             attachPiRpcSession: deps.attachPiRpcSession,

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

@@ -1,4 +1,4 @@
-import { type RuntimeAgentDef, type RuntimeLockHold } from '@jini-ai/agent-runtime';
+import type { RuntimeAgentDef, 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

package/dist/agent-executor/handoff.js

@@ -1,4 +1,3 @@
-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

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

@@ -89,7 +89,7 @@
  * 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 { type SupportedStreamFormat, type AgentExecutorCompatibility, type AgentRuntimeEventTranslation, type AgentExecutorErrorCode, AgentExecutorError, type AgentExecutorRunInput, type AgentExecutor, type UserMessageDelivery, 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';

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

@@ -370,6 +370,6 @@ export declare function confirmChildSpawned({ input, deps }: {
  * @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 declare function createAgentExecutor(requiredArgs: Pick<CreateAgentExecutorOptions, "lifecycle">, optionalArgs?: Pick<CreateAgentExecutorOptions, "getAgentDef" | "resolveAgentLaunch" | "resolveModelForLaunch" | "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