@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/flows-actors/utils/acp-session-runner.backend.utils.js

@@ -1,10 +1,17 @@
 /**
  * Agent Client Protocol session runner.
  *
- * Drives one coding turn: spawn the agent, negotiate `initialize`, open a
- * session against a confined working directory, send one `session/prompt`, and
- * settle when the agent reports a stop reason — answering the agent's callbacks
- * along the way.
+ * Two shapes over one transport:
+ *
+ * - {@link startACPAgentSession} opens a LIVE session — spawn the agent,
+ *   negotiate `initialize`, open (or `session/load`-resume) a session against a
+ *   confined working directory — and returns a handle whose `promptTurn` drives
+ *   ONE turn at a time. The caller decides whether to send another prompt on
+ *   the same session, which is what makes the interactive/continuation lane
+ *   possible: a turn that ended with a question is answered by the next
+ *   `promptTurn`, on the same `sessionId`, with the agent's context intact.
+ * - {@link runACPCodingSession} is the single-turn wrapper kept for every
+ *   existing caller: start, one turn, close.
  *
  * # Why the transport is written here rather than taken from a package
  *
@@ -86,19 +93,6 @@ const PERMISSION_DECISION_RECORD_LIMIT = 200;
  * {@link permissionAllowedByCeiling}, where the ceiling means what it says —
  * and where the caller's mutation scope can still refuse a path.
  */
-const PREFERRED_MODE_IDS = {
-    [AgentClientProtocol_PermissionCeiling.PROMPT_ALWAYS]: ['default'],
-    // Same reasoning as every other ceiling: the read-only lane is expressed by ANSWERING the
-    // permission requests, never by asking the agent to stop raising them. An agent mode that
-    // pre-approves reads on the agent's side would decide which calls count as reads, which is the
-    // decision this runner exists to keep.
-    [AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS]: ['default'],
-    [AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_EDITS]: ['default'],
-    // Even here: an ungated ceiling is expressed by ANSWERING yes, not by asking
-    // the agent to stop reporting. The event stream stays complete, so a run is
-    // still auditable after the fact.
-    [AgentClientProtocol_PermissionCeiling.UNRESTRICTED]: ['default'],
-};
 /** Tool kinds that count as an EDIT for the AUTO_ACCEPT_EDITS ceiling. */
 const EDIT_TOOL_KINDS = new Set(['edit', 'delete', 'move']);
 /**
@@ -136,11 +130,21 @@ export function permissionAllowedByCeiling(ceiling, toolKind) {
             // URL, an unrecognised kind) still requires a decision this runner cannot
             // make on its own, so it is denied rather than guessed.
             //
-            // This is only true because the runner keeps the agent in its
-            // most-escalating mode — see PREFERRED_MODE_IDS. Delegating to the
-            // agent's own `acceptEdits` mode made `execute` bypass this branch
-            // entirely, measured live.
+            // This is only true because the agent is kept in its most-escalating
+            // mode — `sessionModeIdsByPermissionCeiling` on the provider contract,
+            // passed in as `preferredSessionModeIds`. (The runner-local
+            // `PREFERRED_MODE_IDS` this used to name was deleted on 2026-09-04: mode
+            // ids are agent vocabulary, so a map hardcoded here matched nothing for
+            // every agent but the one it was written for.) Delegating to the agent's
+            // own `acceptEdits` mode made `execute` bypass this branch entirely,
+            // measured live.
             return toolKind !== undefined && EDIT_TOOL_KINDS.has(toolKind);
+        case AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS_AND_EDITS:
+            // The union of the two sets above, refusing exactly what both refuse:
+            // `execute` (a command can mutate anything) and `other` (unclassified,
+            // fail-closed). The evidence-persisting research lane's ceiling — the
+            // location predicate is what keeps its writes inside the store.
+            return toolKind !== undefined && (NON_MUTATING_TOOL_KINDS.has(toolKind) || EDIT_TOOL_KINDS.has(toolKind));
         case AgentClientProtocol_PermissionCeiling.AUTO_ACCEPT_READS:
             /*
              * Non-mutating kinds are pre-approved; everything else is denied rather than guessed — the
@@ -233,14 +237,23 @@ export function isPathWithin(root, candidate) {
         return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
     });
 }
-export async function runACPCodingSession(options) {
+/**
+ * Open a live ACP session and return a handle whose `promptTurn` drives one
+ * turn at a time.
+ *
+ * The caller owns the turn cadence — this is the whole point of the handle. A
+ * turn that ends with a question is not the end of the session; the caller
+ * inspects it and may `promptTurn` again with the answer.
+ */
+export async function startACPAgentSession(options) {
     const maxRecordedEventBytes = options.maxRecordedEventBytes ?? DEFAULT_MAX_RECORDED_EVENT_BYTES;
     const child = spawn(options.command, [...(options.args ?? [])], {
         cwd: options.cwd,
         env: options.env,
         stdio: ['pipe', 'pipe', 'pipe'],
     });
-    const state = {
+    // Cumulative session state. Per-turn slices are taken from these by index.
+    const session = {
         nextId: 1,
         buffer: '',
         stderrTail: '',
@@ -248,12 +261,20 @@ export async function runACPCodingSession(options) {
         events: [],
         recordedBytes: 0,
         eventsTruncated: false,
-        finalMessage: '',
-        reportedFileLocations: new Set(),
-        lastUsageUpdate: undefined,
-        deniedPermissionCount: 0,
+        reportedFileLocations: [],
         permissionDecisions: [],
-        settled: false,
+        deniedPermissionCount: 0,
+        // Reset at the start of each turn.
+        turnFinalMessage: '',
+        turnLastUsageUpdate: undefined,
+        // True while `session/load` replay is streaming: replayed history is
+        // consumed and discarded (it is already on the durable record).
+        replaying: false,
+        // Set once the child exits; a later `promptTurn` refuses rather than hanging.
+        childExited: false,
+        // Set BEFORE a deliberate terminate() so the exit handler does not reject
+        // the exit promise for a shutdown the caller asked for.
+        closed: false,
     };
     const pending = new Map();
     const write = (payload) => {
@@ -261,7 +282,7 @@ export async function runACPCodingSession(options) {
             child.stdin.write(`${JSON.stringify(payload)}\n`);
     };
     const request = (method, params) => {
-        const id = state.nextId++;
+        const id = session.nextId++;
         return new Promise((resolvePromise, rejectPromise) => {
             pending.set(id, { resolve: resolvePromise, reject: rejectPromise });
             write({ jsonrpc: '2.0', id, method, params });
@@ -270,17 +291,22 @@ export async function runACPCodingSession(options) {
     const respond = (id, result) => write({ jsonrpc: '2.0', id, result });
     const respondError = (id, message) => write({ jsonrpc: '2.0', id, error: { code: -32603, message } });
     const recordEvent = (event) => {
-        if (!state.eventsTruncated) {
+        // Replayed `session/load` history is neither persisted nor forwarded: it is
+        // already recorded from the run that produced it, and re-emitting it would
+        // double every earlier frame on the resuming run's record.
+        if (session.replaying)
+            return;
+        if (!session.eventsTruncated) {
             const size = JSON.stringify(event).length;
-            if (state.recordedBytes + size > maxRecordedEventBytes) {
+            if (session.recordedBytes + size > maxRecordedEventBytes) {
                 // Truncate, never reject. Losing the tail of a transcript is a reporting
                 // loss; failing the run here would discard work already written to the
                 // workspace, which is the mistake the transport this replaces made.
-                state.eventsTruncated = true;
+                session.eventsTruncated = true;
             }
             else {
-                state.recordedBytes += size;
-                state.events.push(event);
+                session.recordedBytes += size;
+                session.events.push(event);
             }
         }
         try {
@@ -299,9 +325,9 @@ export async function runACPCodingSession(options) {
         const rawOptions = Array.isArray(params.options) ? params.options : [];
         const offeredOptionKinds = rawOptions.flatMap((entry) => (isRecord(entry) && typeof entry.kind === 'string' ? [entry.kind] : []));
         const record = (allowed, reason) => {
-            if (state.permissionDecisions.length >= PERMISSION_DECISION_RECORD_LIMIT)
+            if (session.permissionDecisions.length >= PERMISSION_DECISION_RECORD_LIMIT)
                 return;
-            state.permissionDecisions.push({
+            session.permissionDecisions.push({
                 allowed,
                 reason,
                 ...(toolKind !== undefined ? { toolKind } : {}),
@@ -339,7 +365,7 @@ export async function runACPCodingSession(options) {
                     respond(id, { outcome: { outcome: 'selected', optionId: decision.optionId } });
                     return;
                 }
-                state.deniedPermissionCount++;
+                session.deniedPermissionCount++;
                 const rawOptions = Array.isArray(params.options) ? params.options : [];
                 const reject = rawOptions.find((entry) => isRecord(entry) && entry.kind === 'reject_once');
                 if (isRecord(reject) && typeof reject.optionId === 'string') {
@@ -412,7 +438,7 @@ export async function runACPCodingSession(options) {
              * frames are excluded by construction: they parse, so they never reach this branch, and the
              * tail cannot fill with the session's own traffic.
              */
-            state.unparsedStdoutTail = `${state.unparsedStdoutTail}${line}\n`.slice(-4_000);
+            session.unparsedStdoutTail = `${session.unparsedStdoutTail}${line}\n`.slice(-4_000);
             return;
         }
         if (!isRecord(message))
@@ -420,18 +446,21 @@ export async function runACPCodingSession(options) {
         if (message.method === 'session/update') {
             const update = isRecord(message.params) && isRecord(message.params.update) ? message.params.update : {};
             const kind = typeof update.sessionUpdate === 'string' ? update.sessionUpdate : 'unknown';
-            if (kind === 'agent_message_chunk') {
-                const content = isRecord(update.content) ? update.content : {};
-                if (typeof content.text === 'string')
-                    state.finalMessage += content.text;
-            }
-            if (kind === 'usage_update')
-                state.lastUsageUpdate = update;
-            if (kind === 'tool_call' || kind === 'tool_call_update') {
-                if (Array.isArray(update.locations)) {
-                    for (const entry of update.locations) {
-                        if (isRecord(entry) && typeof entry.path === 'string')
-                            state.reportedFileLocations.add(entry.path);
+            if (!session.replaying) {
+                if (kind === 'agent_message_chunk') {
+                    const content = isRecord(update.content) ? update.content : {};
+                    if (typeof content.text === 'string')
+                        session.turnFinalMessage += content.text;
+                }
+                if (kind === 'usage_update')
+                    session.turnLastUsageUpdate = update;
+                if (kind === 'tool_call' || kind === 'tool_call_update') {
+                    if (Array.isArray(update.locations)) {
+                        for (const entry of update.locations) {
+                            if (isRecord(entry) && typeof entry.path === 'string' && !session.reportedFileLocations.includes(entry.path)) {
+                                session.reportedFileLocations.push(entry.path);
+                            }
+                        }
                     }
                 }
             }
@@ -445,28 +474,44 @@ export async function runACPCodingSession(options) {
         if (typeof message.id === 'number' && pending.has(message.id)) {
             const waiter = pending.get(message.id);
             pending.delete(message.id);
-            if (message.error !== undefined)
-                waiter.reject(message.error);
+            if (message.error !== undefined) {
+                /*
+                 * A JSON-RPC error is an OBJECT ({code, message, data?}), and rejecting with it raw is how a
+                 * real adapter answer became "[object Object]" at the choreography seam and "Unknown agent
+                 * invocation error" in the trace — three layers each normalizing for Error-or-string and
+                 * discarding everything else. The adapter names its failures; carry the name. (Found
+                 * 2026-09-03: a research turn's session/prompt error cost a full diagnosis cycle because all
+                 * that survived was the coercion.)
+                 */
+                const rpcError = message.error;
+                const detail = typeof rpcError?.message === 'string' ? rpcError.message : JSON.stringify(message.error)?.slice(0, 500);
+                const rejection = new Error(`ACP agent error${typeof rpcError?.code === 'number' ? ` ${rpcError.code}` : ''}: ${detail}`);
+                rejection.acpError = message.error;
+                waiter.reject(rejection);
+            }
             else
                 waiter.resolve(message.result);
         }
     };
     child.stdout.setEncoding('utf8');
     child.stdout.on('data', (chunk) => {
-        state.buffer += chunk;
+        session.buffer += chunk;
         let index;
-        while ((index = state.buffer.indexOf('\n')) >= 0) {
-            const line = state.buffer.slice(0, index).trim();
-            state.buffer = state.buffer.slice(index + 1);
+        while ((index = session.buffer.indexOf('\n')) >= 0) {
+            const line = session.buffer.slice(0, index).trim();
+            session.buffer = session.buffer.slice(index + 1);
             if (line)
                 onLine(line);
         }
     });
     child.stderr.setEncoding('utf8');
     child.stderr.on('data', (chunk) => {
-        state.stderrTail = `${state.stderrTail}${chunk}`.slice(-4_000);
+        session.stderrTail = `${session.stderrTail}${chunk}`.slice(-4_000);
     });
     const terminate = () => {
+        // Mark the shutdown as deliberate BEFORE killing so the exit handler does
+        // not reject the exit promise for a close the caller asked for.
+        session.closed = true;
         if (!child.killed)
             child.kill('SIGTERM');
         setTimeout(() => {
@@ -476,15 +521,24 @@ export async function runACPCodingSession(options) {
     };
     const failed = (message, details) => new ACPSessionRunnerError(message, {
         ...details,
-        stderrTail: state.stderrTail.trim().slice(-1_000),
-        stdoutTail: state.unparsedStdoutTail.trim().slice(-1_000),
+        stderrTail: session.stderrTail.trim().slice(-1_000),
+        stdoutTail: session.unparsedStdoutTail.trim().slice(-1_000),
     });
-    const spawnFailure = new Promise((_, rejectPromise) => {
-        child.on('error', (error) => rejectPromise(failed(`Agent process failed to start: ${error.message}`, {})));
+    // ONE persistent "the child died" promise, raced against every awaited
+    // request. It rejects at most once, only for an UNDELIBERATE exit — a close()
+    // the caller asked for sets `closed` first and leaves it pending. Raced at
+    // `initialize`, so it always carries a rejection handler and a later reject
+    // (e.g. a crash between turns) never surfaces as an unhandled rejection.
+    const exitPromise = new Promise((_, rejectPromise) => {
+        child.on('error', (error) => {
+            session.childExited = true;
+            if (!session.closed)
+                rejectPromise(failed(`Agent process failed to start: ${error.message}`, {}));
+        });
         child.on('exit', (code, signal) => {
-            if (!state.settled) {
+            session.childExited = true;
+            if (!session.closed)
                 rejectPromise(failed('Agent process exited before the turn completed', { exitCode: code, signal }));
-            }
         });
     });
     try {
@@ -502,7 +556,7 @@ export async function runACPCodingSession(options) {
                     terminal: false,
                 },
             }),
-            spawnFailure,
+            exitPromise,
         ]);
         if (!isRecord(initializeResult)) {
             throw failed('Agent returned a malformed initialize result', { initializeResult });
@@ -517,100 +571,211 @@ export async function runACPCodingSession(options) {
             });
         }
         const agentInfo = isRecord(initializeResult.agentInfo) ? initializeResult.agentInfo : {};
-        // --- session/new --------------------------------------------------------
-        const sessionResult = await Promise.race([
-            request('session/new', {
-                cwd: options.cwd,
-                mcpServers: [],
-                ...(options.sessionMetaExtensions ? { _meta: options.sessionMetaExtensions } : {}),
-            }),
-            spawnFailure,
-        ]);
-        if (!isRecord(sessionResult) || typeof sessionResult.sessionId !== 'string') {
-            throw failed('Agent returned a malformed session/new result', { sessionResult });
-        }
-        const sessionId = sessionResult.sessionId;
-        // --- best-effort mode selection (an optimisation, never the guarantee) ---
+        const agentCapabilities = isRecord(initializeResult.agentCapabilities) ? initializeResult.agentCapabilities : {};
+        const loadSessionSupported = agentCapabilities.loadSession === true;
+        let sessionId;
         let sessionModeId;
-        const modes = isRecord(sessionResult.modes) ? sessionResult.modes : undefined;
-        const available = modes && Array.isArray(modes.availableModes) ? modes.availableModes : [];
-        const preferred = PREFERRED_MODE_IDS[options.permissionCeiling] ?? [];
-        const match = available.find((entry) => isRecord(entry) && typeof entry.id === 'string' && preferred.includes(entry.id));
-        if (isRecord(match) && typeof match.id === 'string') {
-            try {
-                // Raced against the death signal: before this, a `session/set_mode` sent
-                // to an agent that then died left a promise nobody would ever settle,
-                // with the turn timeout not yet armed — the run hung forever.
-                await Promise.race([request('session/set_mode', { sessionId, modeId: match.id }), spawnFailure]);
-                sessionModeId = match.id;
+        if (options.resumeSessionId !== undefined) {
+            // --- session/load (resume) -------------------------------------------
+            if (!loadSessionSupported) {
+                // Refused, not degraded. Starting a fresh session here would present a
+                // context-less turn as a continuation of a parked one.
+                throw failed('Agent does not advertise the loadSession capability; cannot resume the session', {
+                    resumeSessionId: options.resumeSessionId,
+                });
             }
-            catch {
-                // The ceiling is still enforced by the permission handler, so a mode we
-                // could not set costs round-trips, not safety.
-                sessionModeId = undefined;
+            session.replaying = true;
+            await Promise.race([
+                request('session/load', {
+                    sessionId: options.resumeSessionId,
+                    cwd: options.cwd,
+                    mcpServers: [],
+                }),
+                exitPromise,
+            ]);
+            session.replaying = false;
+            sessionId = options.resumeSessionId;
+            // Modes are reported by session/new, not session/load. The permission
+            // handler is the guarantee regardless, so a resumed session simply runs
+            // without a reselected mode.
+        }
+        else {
+            // --- session/new ------------------------------------------------------
+            const sessionResult = await Promise.race([
+                request('session/new', {
+                    cwd: options.cwd,
+                    mcpServers: [],
+                    ...(options.sessionMetaExtensions ? { _meta: options.sessionMetaExtensions } : {}),
+                }),
+                exitPromise,
+            ]);
+            if (!isRecord(sessionResult) || typeof sessionResult.sessionId !== 'string') {
+                throw failed('Agent returned a malformed session/new result', { sessionResult });
+            }
+            sessionId = sessionResult.sessionId;
+            // --- best-effort mode selection (an optimisation, never the guarantee) -
+            const modes = isRecord(sessionResult.modes) ? sessionResult.modes : undefined;
+            const available = modes && Array.isArray(modes.availableModes) ? modes.availableModes : [];
+            const preferred = options.preferredSessionModeIds ?? [];
+            const match = available.find((entry) => isRecord(entry) && typeof entry.id === 'string' && preferred.includes(entry.id));
+            if (isRecord(match) && typeof match.id === 'string') {
+                try {
+                    // Raced against the death signal: before this, a `session/set_mode` sent
+                    // to an agent that then died left a promise nobody would ever settle,
+                    // with the turn timeout not yet armed — the run hung forever.
+                    await Promise.race([request('session/set_mode', { sessionId, modeId: match.id }), exitPromise]);
+                    sessionModeId = match.id;
+                }
+                catch {
+                    // The ceiling is still enforced by the permission handler, so a mode we
+                    // could not set costs round-trips, not safety.
+                    sessionModeId = undefined;
+                }
+            }
+            else if (typeof modes?.currentModeId === 'string') {
+                sessionModeId = modes.currentModeId;
             }
         }
-        else if (typeof modes?.currentModeId === 'string') {
-            sessionModeId = modes.currentModeId;
+        // --- model delivery, when the agent takes it over ACP -------------------
+        //
+        // Unlike the mode selection above, this is NOT best-effort. A model that
+        // could not be set means the agent runs its own default while the run
+        // records the model that was requested — a false result rather than a
+        // degraded one, which is precisely the failure the provider-declared
+        // delivery channel exists to end. So a rejection fails the session before
+        // any prompt is sent, i.e. before the agent has touched the workspace.
+        if (options.modelSelection) {
+            const setModelResult = await Promise.race([
+                request('session/set_config_option', {
+                    sessionId,
+                    configId: options.modelSelection.configId,
+                    value: options.modelSelection.model,
+                }),
+                exitPromise,
+            ]).catch((error) => {
+                throw failed(`Agent refused the model selection: ${error instanceof Error ? error.message : String(error)}`, { configId: options.modelSelection?.configId, model: options.modelSelection?.model });
+            });
+            void setModelResult;
         }
-        // --- the turn -----------------------------------------------------------
-        let timedOut = false;
-        let timer;
-        const cancelTurn = () => {
-            write({ jsonrpc: '2.0', method: 'session/cancel', params: { sessionId } });
-            setTimeout(() => {
-                if (!state.settled)
-                    terminate();
-            }, COOPERATIVE_CANCEL_GRACE_MS).unref?.();
+        const promptTurn = async (prompt, turnOptions) => {
+            if (session.childExited) {
+                throw failed('Agent process is no longer running; cannot start a turn', { sessionId });
+            }
+            // Per-turn slices are the cumulative arrays from this point on.
+            const eventStart = session.events.length;
+            const permissionStart = session.permissionDecisions.length;
+            const deniedStart = session.deniedPermissionCount;
+            const fileLocStart = session.reportedFileLocations.length;
+            session.turnFinalMessage = '';
+            session.turnLastUsageUpdate = undefined;
+            let settled = false;
+            let timedOut = false;
+            let timer;
+            const cancelTurn = () => {
+                write({ jsonrpc: '2.0', method: 'session/cancel', params: { sessionId } });
+                setTimeout(() => {
+                    if (!settled)
+                        terminate();
+                }, COOPERATIVE_CANCEL_GRACE_MS).unref?.();
+            };
+            const onAbort = () => cancelTurn();
+            const turnPromise = request('session/prompt', {
+                sessionId,
+                prompt: [{ type: 'text', text: prompt }],
+            });
+            if (turnOptions?.turnTimeoutMs !== undefined) {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    // Cooperative first: ACP requires the agent to answer a cancelled turn
+                    // with stop reason `cancelled`, which lets the caller distinguish an
+                    // interrupted run from a completed one. Kill only if it does not.
+                    cancelTurn();
+                }, turnOptions.turnTimeoutMs);
+                timer.unref?.();
+            }
+            if (turnOptions?.abortSignal) {
+                if (turnOptions.abortSignal.aborted)
+                    cancelTurn();
+                else
+                    turnOptions.abortSignal.addEventListener('abort', onAbort, { once: true });
+            }
+            try {
+                const turnResult = await Promise.race([turnPromise, exitPromise]);
+                settled = true;
+                if (!isRecord(turnResult)) {
+                    throw failed('Agent returned a malformed session/prompt result', { turnResult, timedOut });
+                }
+                const { stopReason, rawStopReason } = parseStopReason(turnResult.stopReason);
+                return {
+                    finalMessage: session.turnFinalMessage,
+                    stopReason,
+                    ...(rawStopReason ? { rawStopReason } : {}),
+                    usage: projectUsage(turnResult.usage, session.turnLastUsageUpdate),
+                    reportedFileLocations: session.reportedFileLocations.slice(fileLocStart),
+                    events: session.events.slice(eventStart),
+                    eventsTruncated: session.eventsTruncated,
+                    deniedPermissionCount: session.deniedPermissionCount - deniedStart,
+                    permissionDecisions: session.permissionDecisions.slice(permissionStart),
+                };
+            }
+            finally {
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                turnOptions?.abortSignal?.removeEventListener('abort', onAbort);
+            }
         };
-        const turnPromise = request('session/prompt', {
-            sessionId,
-            prompt: [{ type: 'text', text: options.prompt }],
-        });
-        if (options.turnTimeoutMs !== undefined) {
-            timer = setTimeout(() => {
-                timedOut = true;
-                // Cooperative first: ACP requires the agent to answer a cancelled turn
-                // with stop reason `cancelled`, which lets the caller distinguish an
-                // interrupted run from a completed one. Kill only if it does not.
-                cancelTurn();
-            }, options.turnTimeoutMs);
-            timer.unref?.();
-        }
-        if (options.abortSignal) {
-            if (options.abortSignal.aborted)
-                cancelTurn();
-            else
-                options.abortSignal.addEventListener('abort', cancelTurn, { once: true });
-        }
-        const turnResult = await Promise.race([turnPromise, spawnFailure]);
-        if (timer)
-            clearTimeout(timer);
-        state.settled = true;
-        if (!isRecord(turnResult)) {
-            throw failed('Agent returned a malformed session/prompt result', { turnResult, timedOut });
-        }
-        const { stopReason, rawStopReason } = parseStopReason(turnResult.stopReason);
         return {
-            finalMessage: state.finalMessage,
-            stopReason,
-            ...(rawStopReason ? { rawStopReason } : {}),
-            usage: projectUsage(turnResult.usage, state.lastUsageUpdate),
-            reportedFileLocations: [...state.reportedFileLocations],
             sessionId,
             negotiatedProtocolVersion,
             ...(typeof agentInfo.name === 'string' ? { agentName: agentInfo.name } : {}),
             ...(typeof agentInfo.version === 'string' ? { agentVersion: agentInfo.version } : {}),
             ...(sessionModeId ? { sessionModeId } : {}),
-            events: state.events,
-            eventsTruncated: state.eventsTruncated,
-            deniedPermissionCount: state.deniedPermissionCount,
-            permissionDecisions: state.permissionDecisions,
+            capabilities: { loadSession: loadSessionSupported },
+            promptTurn,
+            close: terminate,
         };
     }
-    finally {
-        state.settled = true;
+    catch (error) {
+        // Setup failed: the child must not be left running.
         terminate();
+        throw error;
+    }
+}
+/**
+ * Drive exactly one coding turn end to end: open a session, send one prompt,
+ * settle, and close.
+ *
+ * The compatibility surface for every caller that does not need the turn
+ * cadence. It is a thin composition of {@link startACPAgentSession} +
+ * `promptTurn` + `close`, so its behaviour tracks the handle by construction.
+ */
+export async function runACPCodingSession(options) {
+    const agentSession = await startACPAgentSession(options);
+    try {
+        const turn = await agentSession.promptTurn(options.prompt, {
+            ...(options.turnTimeoutMs !== undefined ? { turnTimeoutMs: options.turnTimeoutMs } : {}),
+            ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+        });
+        return {
+            finalMessage: turn.finalMessage,
+            stopReason: turn.stopReason,
+            ...(turn.rawStopReason ? { rawStopReason: turn.rawStopReason } : {}),
+            usage: turn.usage,
+            reportedFileLocations: turn.reportedFileLocations,
+            sessionId: agentSession.sessionId,
+            negotiatedProtocolVersion: agentSession.negotiatedProtocolVersion,
+            ...(agentSession.agentName ? { agentName: agentSession.agentName } : {}),
+            ...(agentSession.agentVersion ? { agentVersion: agentSession.agentVersion } : {}),
+            ...(agentSession.sessionModeId ? { sessionModeId: agentSession.sessionModeId } : {}),
+            events: turn.events,
+            eventsTruncated: turn.eventsTruncated,
+            deniedPermissionCount: turn.deniedPermissionCount,
+            permissionDecisions: turn.permissionDecisions,
+        };
+    }
+    finally {
+        agentSession.close();
     }
 }
 /** Re-exported so callers reason about ceilings through one ordering definition. */