@xenosystem/agent-interface-host 0.1.3

package/dist/acp/AcpSessionService.js

@@ -0,0 +1,931 @@
+import { createHash, randomUUID } from 'crypto';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+import { RuntimeEventStore } from '../runtime/RuntimeEventStore.js';
+import { defaultRunIdOf } from '@xenosystem/agent-interface-contract';
+import { HostCoordinationLaneBridge } from '../coordination/laneBridge.js';
+import { AcpProcessSupervisor, XENO_ACP_CONTEXT_META_KEY } from './AcpProcessSupervisor.js';
+import { FailClosedAcpPermissionBridge } from './AcpPermissionBridge.js';
+import { FailClosedAcpHostBridge, } from './AcpHostBridge.js';
+import { acpErrorCode, acpSafeErrorMessage } from './acpErrors.js';
+import { redactAcpText } from './acpRedaction.js';
+import { XENO_ACP_SESSION_RESUME_META_KEY } from './acpSessionResume.js';
+import { mapAcpAgentExitedToRuntimeEvent, mapAcpAgentFailedToRuntimeEvent, mapAcpAgentReadyToRuntimeEvent, mapAcpAgentStartedToRuntimeEvent, mapAcpAgentStderrToRuntimeEvent, mapAcpChooseDirectoryResultToRuntimeEvent, mapAcpChooseWorkspacePlacementResultToRuntimeEvent, mapAcpPermissionDecidedToRuntimeEvent, mapAcpPermissionRequestedToRuntimeEvent, mapAcpPromptResultToRuntimeEvent, mapAcpSessionFailedToRuntimeEvent, mapAcpSessionStartedToRuntimeEvent, mapAcpSessionUpdateToRuntimeEvent, } from './AcpRuntimeEventMapper.js';
+/**
+ * How long a cancelled prompt waits for its transport to finish dying before concluding it did
+ * not die.
+ *
+ * Generous enough that a process which exits on cancel — the normal case, and the one the
+ * lifecycle event exists to report — is reliably observed. Short enough to be invisible on a path
+ * a human just triggered, and it is only ever paid when the agent survives the cancel, since the
+ * wait returns the moment the exit lands.
+ */
+const CANCELLED_TRANSPORT_SETTLE_MS = 500;
+export class AcpSessionService {
+    rootDir;
+    runtimeStore;
+    onRuntimeEvent;
+    permissionBridge;
+    hostBridge;
+    coordinationPort;
+    onRunActivity;
+    requestTimeoutMs;
+    conversationSessions = new Map();
+    conversationPromptTails = new Map();
+    constructor(options = {}) {
+        this.rootDir = options.rootDir;
+        this.runtimeStore = options.runtimeStore || new RuntimeEventStore(options.rootDir ? join(options.rootDir, 'runtime-events') : undefined);
+        this.onRuntimeEvent = options.onRuntimeEvent;
+        this.permissionBridge = options.permissionBridge || new FailClosedAcpPermissionBridge();
+        this.hostBridge = options.hostBridge || new FailClosedAcpHostBridge();
+        this.coordinationPort = options.coordinationPort;
+        this.onRunActivity = options.onRunActivity;
+        this.requestTimeoutMs = options.requestTimeoutMs || 30_000;
+    }
+    async runPrompt(request) {
+        const [result] = await this.runPromptBatch({
+            config: request.config,
+            prompts: [{
+                    conversationId: request.conversationId,
+                    requestId: request.requestId,
+                    subagentRunId: request.subagentRunId,
+                    prompt: request.prompt,
+                    history: request.history,
+                    systemPrompt: request.systemPrompt,
+                    cwd: request.cwd,
+                    additionalDirectories: request.additionalDirectories,
+                    execution: request.execution,
+                    providerModel: request.providerModel,
+                    resumeSessionId: request.resumeSessionId,
+                    resumeState: request.resumeState,
+                    resumeAgentConfigId: request.resumeAgentConfigId,
+                    resumeAgentConfigFingerprint: request.resumeAgentConfigFingerprint,
+                    resumeWorkspaceFingerprint: request.resumeWorkspaceFingerprint,
+                    timeoutMs: request.timeoutMs,
+                    cancelAfterMs: request.cancelAfterMs,
+                    abortSignal: request.abortSignal,
+                }],
+        });
+        if (!result)
+            throw new Error('ACP prompt batch returned no result for its requested prompt.');
+        return result;
+    }
+    async runConversationPrompt(request) {
+        const key = `${request.config.id}:${request.conversationId}`;
+        const previous = this.conversationPromptTails.get(key) || Promise.resolve();
+        let releaseCurrent;
+        const current = new Promise((resolve) => {
+            releaseCurrent = resolve;
+        });
+        const tail = previous.catch(() => undefined).then(() => current);
+        this.conversationPromptTails.set(key, tail);
+        await previous.catch(() => undefined);
+        try {
+            return await this.runConversationPromptExclusive(request, key);
+        }
+        finally {
+            releaseCurrent();
+            if (this.conversationPromptTails.get(key) === tail) {
+                this.conversationPromptTails.delete(key);
+            }
+        }
+    }
+    async runConversationPromptExclusive(request, key) {
+        if (!request.config.enabled) {
+            return {
+                success: false,
+                status: 'failed',
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                acpProcessId: `acp-process-${Date.now()}-${randomUUID().slice(0, 8)}`,
+                acpAgentConfigId: request.config.id,
+                eventCount: 0,
+                error: 'ACP agent config must be enabled before launch.',
+            };
+        }
+        const cwd = this.resolveConversationCwd(request);
+        const additionalDirectories = request.additionalDirectories || [];
+        const workspaceKey = this.workspaceKeyFor(cwd, additionalDirectories, request.execution);
+        const workspaceFingerprint = this.workspaceFingerprintFor(workspaceKey);
+        const configFingerprint = this.agentConfigFingerprintFor(request.config);
+        let replayHistoryOnFreshSession = false;
+        let active = this.conversationSessions.get(key);
+        if (active && (active.supervisor.getStatus() !== 'ready' || active.workspaceKey !== workspaceKey)) {
+            await this.closeConversationSession(active).catch(() => undefined);
+            active = undefined;
+        }
+        if (!active) {
+            const acpProcessId = `acp-process-${Date.now()}-${randomUUID().slice(0, 8)}`;
+            const recorder = new RuntimeRecordingAcpPermissionBridge(this.permissionBridge, (mapping, context) => {
+                this.appendRuntimeEvent(context, mapping);
+            }, this.onRunActivity);
+            const hostRecorder = new RuntimeRecordingAcpHostBridge(this.hostBridge, (mapping, context) => {
+                this.appendRuntimeEvent(context, mapping);
+            });
+            const supervisor = new AcpProcessSupervisor(request.config, {
+                permissionBridge: recorder,
+                hostBridge: hostRecorder,
+                /**
+                 * \u{1F534} The caller's run id is bound HERE, from the host's own request —
+                 * never read from a parameter the agent supplies. An agent that could
+                 * name its own `fromRunId` could message as another run, read a peer's
+                 * summary through someone else's visibility, and claim a file in a
+                 * third run's name. Coordination is host-mediated exactly so a
+                 * participant cannot assert who it is.
+                 *
+                 * `defaultRunIdOf` rather than `conversationId`, because a subagent run
+                 * is its own run and coordinates under its own identity.
+                 */
+                ...(this.coordinationPort
+                    ? {
+                        coordinationBridge: new HostCoordinationLaneBridge({
+                            callerRunId: defaultRunIdOf({
+                                conversationId: request.conversationId,
+                                ...(request.subagentRunId === undefined ? {} : { subagentRunId: request.subagentRunId }),
+                            }),
+                            port: this.coordinationPort,
+                        }),
+                    }
+                    : {}),
+                requestTimeoutMs: this.requestTimeoutMs,
+            });
+            const context = {
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                subagentRunId: request.subagentRunId,
+                acpProcessId,
+                acpAgentConfigId: request.config.id,
+                providerKind: 'acp-provider',
+                providerId: request.config.id,
+                providerModel: request.providerModel,
+                schemaVersion: 1,
+                redactionState: 'redacted',
+            };
+            this.appendRuntimeEvent(context, mapAcpAgentStartedToRuntimeEvent(context, supervisor.diagnostics()));
+            try {
+                await supervisor.initialize();
+                this.appendRuntimeEvent(context, mapAcpAgentReadyToRuntimeEvent(context, supervisor.diagnostics()));
+                let session;
+                let resumeSkipReason;
+                if (request.resumeSessionId) {
+                    if (request.resumeAgentConfigId !== request.config.id) {
+                        resumeSkipReason = 'provider_mismatch';
+                    }
+                    else if (!request.resumeAgentConfigFingerprint
+                        || request.resumeAgentConfigFingerprint !== configFingerprint) {
+                        resumeSkipReason = 'provider_config_changed';
+                    }
+                    else if (!request.resumeWorkspaceFingerprint
+                        || request.resumeWorkspaceFingerprint !== workspaceFingerprint) {
+                        resumeSkipReason = 'workspace_mismatch';
+                    }
+                    else if (!request.resumeState) {
+                        resumeSkipReason = 'missing_resume_state';
+                    }
+                    else if (!supervisor.supportsResumeSession()
+                        && !supervisor.supportsSessionNewResumeState()) {
+                        resumeSkipReason = 'unsupported';
+                    }
+                    else {
+                        try {
+                            const transport = supervisor.supportsResumeSession()
+                                ? 'session_resume'
+                                : 'session_new_meta';
+                            session = transport === 'session_resume'
+                                ? await supervisor.resumeSession(request.resumeSessionId, {
+                                    cwd,
+                                    additionalDirectories,
+                                    mcpServers: [],
+                                    ...this.sessionExecutionMeta(request, true),
+                                })
+                                : await supervisor.createSession({
+                                    cwd,
+                                    additionalDirectories,
+                                    mcpServers: [],
+                                    ...this.sessionExecutionMeta(request, true),
+                                });
+                            context.acpSessionId = session.sessionId;
+                            this.appendLifecycleEvent(context, 'acp.session.resumed', {
+                                status: 'ready',
+                                transport,
+                                configFingerprint,
+                                workspaceFingerprint,
+                            });
+                        }
+                        catch (error) {
+                            resumeSkipReason = 'resume_failed';
+                            this.appendLifecycleEvent(context, 'acp.session.resume_failed', {
+                                status: 'failed',
+                                configFingerprint,
+                                workspaceFingerprint,
+                                error: redactAcpText(acpSafeErrorMessage(error)),
+                            });
+                        }
+                    }
+                    if (resumeSkipReason && resumeSkipReason !== 'resume_failed') {
+                        this.appendLifecycleEvent(context, 'acp.session.resume_skipped', {
+                            status: 'skipped',
+                            reason: resumeSkipReason,
+                            configFingerprint,
+                            workspaceFingerprint,
+                        });
+                    }
+                }
+                if (!session) {
+                    session = await supervisor.createSession({
+                        cwd,
+                        additionalDirectories,
+                        mcpServers: [],
+                        ...this.sessionExecutionMeta(request),
+                    });
+                    replayHistoryOnFreshSession = (request.history?.length || 0) > 0;
+                }
+                context.acpSessionId = session.sessionId;
+                const started = mapAcpSessionStartedToRuntimeEvent(context, session.sessionId);
+                started.event.configFingerprint = configFingerprint;
+                started.event.workspaceFingerprint = workspaceFingerprint;
+                this.appendRuntimeEvent(context, started);
+                active = {
+                    key,
+                    conversationId: request.conversationId,
+                    configId: request.config.id,
+                    configFingerprint,
+                    workspaceKey,
+                    workspaceFingerprint,
+                    acpProcessId,
+                    acpSessionId: session.sessionId,
+                    supervisor,
+                    recorder,
+                    hostRecorder,
+                };
+                this.conversationSessions.set(key, active);
+            }
+            catch (error) {
+                const diagnostics = supervisor.diagnostics();
+                this.appendRuntimeEvent(context, mapAcpAgentFailedToRuntimeEvent(context, redactAcpText(acpSafeErrorMessage(error)), diagnostics));
+                this.emitStderrIfPresent(context, diagnostics);
+                this.appendRuntimeEvent(context, mapAcpAgentExitedToRuntimeEvent(context, diagnostics));
+                await supervisor.stop().catch(() => undefined);
+                return {
+                    success: false,
+                    status: statusForError(error),
+                    conversationId: request.conversationId,
+                    requestId: request.requestId,
+                    acpProcessId,
+                    acpAgentConfigId: request.config.id,
+                    eventCount: 0,
+                    error: redactAcpText(acpSafeErrorMessage(error)),
+                    diagnostics,
+                };
+            }
+        }
+        const promptRequest = replayHistoryOnFreshSession
+            ? {
+                ...request,
+                prompt: buildAcpConversationReplayPrompt(request.history || [], request.prompt),
+            }
+            : request;
+        if (replayHistoryOnFreshSession) {
+            this.appendLifecycleEvent({
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                subagentRunId: request.subagentRunId,
+                acpProcessId: active.acpProcessId,
+                acpAgentConfigId: request.config.id,
+                acpSessionId: active.acpSessionId,
+                providerKind: 'acp-provider',
+                providerId: request.config.id,
+                providerModel: request.providerModel,
+                schemaVersion: 1,
+                redactionState: 'redacted',
+            }, 'acp.session.context_replayed', {
+                status: 'ready',
+                messageCount: request.history?.length || 0,
+                characterCount: (request.history || []).reduce((sum, message) => sum + message.content.length, 0),
+                configFingerprint: active.configFingerprint,
+                workspaceFingerprint: active.workspaceFingerprint,
+            });
+        }
+        const result = await this.runExistingSessionPrompt(active.supervisor, {
+            ...promptRequest,
+            timeoutMs: request.timeoutMs || this.requestTimeoutMs,
+        }, active.acpProcessId, active.acpSessionId, active.recorder, active.hostRecorder);
+        if (!result.success) {
+            if (result.status === 'timed_out') {
+                await this.closeConversationSession(active).catch(() => undefined);
+            }
+            else if (result.status === 'process_exited') {
+                this.conversationSessions.delete(active.key);
+                await active.supervisor.stop().catch(() => undefined);
+            }
+            else if (result.status === 'cancelled' && active.supervisor.getStatus() !== 'ready') {
+                // Deliberately still a plain read, and it is now sufficient: the exit was already
+                // established above (with a bounded wait) before this result was returned, so by the time
+                // control reaches here a transport that died has had its chance to say so. A second
+                // independent wait would double the cancel latency to re-answer a settled question.
+                this.conversationSessions.delete(active.key);
+                await active.supervisor.stop().catch(() => undefined);
+            }
+        }
+        return result;
+    }
+    async closeConversationSessions() {
+        const sessions = [...this.conversationSessions.values()];
+        await Promise.all(sessions.map((session) => this.closeConversationSession(session).catch(() => undefined)));
+    }
+    async closeConversation(conversationId, configId) {
+        const sessions = [...this.conversationSessions.values()]
+            .filter((session) => (session.conversationId === conversationId
+            && (!configId || session.configId === configId)));
+        await Promise.all(sessions.map((session) => this.closeConversationSession(session).catch(() => undefined)));
+        return sessions.length;
+    }
+    async runPromptBatch(request) {
+        const acpProcessId = `acp-process-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        if (!request.config.enabled) {
+            return request.prompts.map((prompt) => ({
+                success: false,
+                status: 'failed',
+                conversationId: prompt.conversationId,
+                requestId: prompt.requestId,
+                acpProcessId,
+                acpAgentConfigId: request.config.id,
+                eventCount: 0,
+                error: 'ACP agent config must be enabled before launch.',
+            }));
+        }
+        const recorder = new RuntimeRecordingAcpPermissionBridge(this.permissionBridge, (mapping, context) => {
+            this.appendRuntimeEvent(context, mapping);
+        }, this.onRunActivity);
+        const hostRecorder = new RuntimeRecordingAcpHostBridge(this.hostBridge, (mapping, context) => {
+            this.appendRuntimeEvent(context, mapping);
+        });
+        const supervisor = new AcpProcessSupervisor(request.config, {
+            permissionBridge: recorder,
+            hostBridge: hostRecorder,
+            requestTimeoutMs: this.requestTimeoutMs,
+        });
+        const results = [];
+        const firstPrompt = request.prompts[0];
+        const baseContext = {
+            conversationId: firstPrompt?.conversationId || 'acp-conversation-unknown',
+            requestId: firstPrompt?.requestId || 'acp-request-unknown',
+            subagentRunId: firstPrompt?.subagentRunId,
+            acpProcessId,
+            acpAgentConfigId: request.config.id,
+            providerKind: 'acp-provider',
+            providerId: request.config.id,
+            providerModel: firstPrompt?.providerModel,
+            schemaVersion: 1,
+            redactionState: 'redacted',
+        };
+        this.appendRuntimeEvent(baseContext, mapAcpAgentStartedToRuntimeEvent(baseContext, supervisor.diagnostics()));
+        try {
+            await supervisor.initialize();
+            this.appendRuntimeEvent(baseContext, mapAcpAgentReadyToRuntimeEvent(baseContext, supervisor.diagnostics()));
+            for (const prompt of request.prompts) {
+                results.push(await this.runSinglePrompt(supervisor, {
+                    ...prompt,
+                    config: request.config,
+                    timeoutMs: prompt.timeoutMs || request.timeoutMs || this.requestTimeoutMs,
+                }, acpProcessId, recorder, hostRecorder));
+            }
+            return results;
+        }
+        catch (error) {
+            const diagnostics = supervisor.diagnostics();
+            this.appendRuntimeEvent(baseContext, mapAcpAgentFailedToRuntimeEvent(baseContext, redactAcpText(acpSafeErrorMessage(error)), diagnostics));
+            const fallback = {
+                success: false,
+                status: statusForError(error),
+                conversationId: baseContext.conversationId,
+                requestId: baseContext.requestId,
+                acpProcessId,
+                acpAgentConfigId: request.config.id,
+                eventCount: 0,
+                error: redactAcpText(acpSafeErrorMessage(error)),
+                diagnostics,
+            };
+            return results.length ? results : [fallback];
+        }
+        finally {
+            const diagnosticsBeforeStop = supervisor.diagnostics();
+            this.emitStderrIfPresent(baseContext, diagnosticsBeforeStop);
+            this.appendRuntimeEvent(baseContext, mapAcpAgentExitedToRuntimeEvent(baseContext, diagnosticsBeforeStop));
+            await supervisor.stop().catch(() => undefined);
+        }
+    }
+    async runSinglePrompt(supervisor, request, acpProcessId, recorder, hostRecorder) {
+        let acpSessionId;
+        const context = {
+            conversationId: request.conversationId,
+            requestId: request.requestId,
+            subagentRunId: request.subagentRunId,
+            acpProcessId,
+            acpAgentConfigId: request.config.id,
+            providerKind: 'acp-provider',
+            providerId: request.config.id,
+            providerModel: request.providerModel,
+            schemaVersion: 1,
+            redactionState: 'redacted',
+        };
+        let status = 'starting';
+        const eventCountBefore = this.listEventCount(request.conversationId);
+        try {
+            const session = await supervisor.createSession({
+                cwd: request.cwd || request.config.cwd,
+                additionalDirectories: request.additionalDirectories,
+                mcpServers: [],
+                ...this.sessionExecutionMeta(request),
+            });
+            acpSessionId = session.sessionId;
+            context.acpSessionId = acpSessionId;
+            this.appendRuntimeEvent(context, mapAcpSessionStartedToRuntimeEvent(context, acpSessionId));
+            return await this.runExistingSessionPrompt(supervisor, request, acpProcessId, acpSessionId, recorder, hostRecorder, eventCountBefore);
+        }
+        catch (error) {
+            status = statusForError(error);
+            const diagnostics = supervisor.diagnostics();
+            diagnostics.runtimeEventCount = this.listEventCount(request.conversationId) - eventCountBefore;
+            this.appendRuntimeEvent(context, mapAcpSessionFailedToRuntimeEvent(context, status, redactAcpText(acpSafeErrorMessage(error)), diagnostics));
+            if (status === 'process_exited') {
+                this.appendRuntimeEvent(context, mapAcpAgentExitedToRuntimeEvent(context, diagnostics));
+            }
+            return {
+                success: false,
+                status,
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                acpProcessId,
+                acpAgentConfigId: request.config.id,
+                acpSessionId,
+                eventCount: diagnostics.runtimeEventCount || 0,
+                error: redactAcpText(acpSafeErrorMessage(error)),
+                diagnostics,
+            };
+        }
+        finally {
+            recorder.setActiveContext(undefined);
+            hostRecorder.setActiveContext(undefined);
+        }
+    }
+    async runExistingSessionPrompt(supervisor, request, acpProcessId, acpSessionId, recorder, hostRecorder, eventCountBefore = this.listEventCount(request.conversationId)) {
+        const context = {
+            conversationId: request.conversationId,
+            requestId: request.requestId,
+            subagentRunId: request.subagentRunId,
+            acpProcessId,
+            acpAgentConfigId: request.config.id,
+            acpSessionId,
+            providerKind: 'acp-provider',
+            providerId: request.config.id,
+            providerModel: request.providerModel,
+            schemaVersion: 1,
+            redactionState: 'redacted',
+        };
+        recorder.setActiveContext(context);
+        hostRecorder.setActiveContext(context);
+        let cancelTimer;
+        let cancellationRequested = request.abortSignal?.aborted === true;
+        const cancelActiveSession = () => {
+            cancellationRequested = true;
+            void supervisor.cancelSession(acpSessionId).catch(() => undefined);
+        };
+        if (request.cancelAfterMs !== undefined) {
+            cancelTimer = setTimeout(cancelActiveSession, Math.max(0, request.cancelAfterMs));
+        }
+        try {
+            const promptResult = await supervisor.prompt(acpSessionId, request.prompt, {
+                timeoutMs: request.timeoutMs,
+                signal: request.abortSignal,
+                model: request.providerModel,
+                systemPrompt: request.systemPrompt,
+                execution: request.execution,
+                onUpdate: (update) => {
+                    this.appendRuntimeEvent(context, mapAcpSessionUpdateToRuntimeEvent(update, context));
+                },
+            });
+            this.appendRuntimeEvent(context, mapAcpPromptResultToRuntimeEvent(acpSessionId, context, promptResult.result));
+            const status = promptResult.result.stopReason === 'cancelled' ? 'cancelled' : 'completed';
+            const diagnostics = supervisor.diagnostics();
+            diagnostics.lastStopReason = promptResult.result.stopReason;
+            diagnostics.runtimeEventCount = this.listEventCount(request.conversationId) - eventCountBefore;
+            return {
+                success: status === 'completed',
+                status,
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                acpProcessId,
+                acpAgentConfigId: request.config.id,
+                acpSessionId,
+                eventCount: diagnostics.runtimeEventCount,
+                stopReason: promptResult.result.stopReason,
+                diagnostics,
+            };
+        }
+        catch (error) {
+            const status = cancellationRequested || request.abortSignal?.aborted === true
+                ? 'cancelled'
+                : statusForError(error);
+            const diagnostics = supervisor.diagnostics();
+            if (status === 'cancelled')
+                diagnostics.lastStopReason = 'cancelled';
+            diagnostics.runtimeEventCount = this.listEventCount(request.conversationId) - eventCountBefore;
+            if (status === 'cancelled') {
+                this.appendRuntimeEvent(context, mapAcpPromptResultToRuntimeEvent(acpSessionId, context, { stopReason: 'cancelled' }));
+            }
+            else {
+                this.appendRuntimeEvent(context, mapAcpSessionFailedToRuntimeEvent(context, status, redactAcpText(acpSafeErrorMessage(error)), diagnostics));
+            }
+            /**
+             * ESTABLISH the exit; do not sample it.
+             *
+             * This read `supervisor.getStatus() === 'exited'` at the instant the prompt rejected —
+             * which, for a cancellation, is the one moment the connection state is guaranteed to still
+             * be settling, because cancelling is what aborted it.
+             *
+             * ⚠️ Stated carefully, because a stronger version of this comment was written first and the
+             * evidence did not support it. Losing that race does NOT lose the event:
+             * `closeConversationSession` emits `acp.agent.exited` later under the synthetic request id
+             * `acp-session-close`. What raced was ATTRIBUTION — whether the exit is reported against
+             * the request that caused it, or deferred and attributed to a close — plus the matching
+             * decision about discarding the session.
+             *
+             * ⚠️ And it is a race removed BY CONSTRUCTION, not a diagnosed cause. An intermittent
+             * failure was observed in the cancel-recovery test under full parallel load; reading the
+             * code showed three separate decisions sampling this one settling value. But no
+             * deterministic reproduction of the sampled answer being WRONG was achieved — with the
+             * fixtures available the exit is always already visible by the time the prompt settles. So
+             * this is "a class of race made unrepresentable", which is worth having, and it is not
+             * evidence that it was the cause of that failure.
+             *
+             * `process_exited` needs no wait — that status IS the observation, and `prompt()` has
+             * already transitioned the supervisor to `exited` on `AcpProcessExitedError`.
+             */
+            const transportGone = status === 'process_exited'
+                || (status === 'cancelled' && await supervisor.waitForExit(CANCELLED_TRANSPORT_SETTLE_MS));
+            if (transportGone) {
+                this.appendRuntimeEvent(context, mapAcpAgentExitedToRuntimeEvent(context, diagnostics));
+            }
+            return {
+                success: false,
+                status,
+                conversationId: request.conversationId,
+                requestId: request.requestId,
+                acpProcessId,
+                acpAgentConfigId: request.config.id,
+                acpSessionId,
+                eventCount: diagnostics.runtimeEventCount || 0,
+                ...(status === 'cancelled'
+                    ? { stopReason: 'cancelled' }
+                    : { error: redactAcpText(acpSafeErrorMessage(error)) }),
+                diagnostics,
+            };
+        }
+        finally {
+            if (cancelTimer)
+                clearTimeout(cancelTimer);
+            recorder.setActiveContext(undefined);
+            hostRecorder.setActiveContext(undefined);
+        }
+    }
+    async closeConversationSession(active) {
+        this.conversationSessions.delete(active.key);
+        const context = {
+            conversationId: active.conversationId,
+            requestId: 'acp-session-close',
+            acpProcessId: active.acpProcessId,
+            acpAgentConfigId: active.configId,
+            acpSessionId: active.acpSessionId,
+            providerKind: 'acp-provider',
+            providerId: active.configId,
+            schemaVersion: 1,
+            redactionState: 'redacted',
+        };
+        const diagnostics = active.supervisor.diagnostics();
+        this.emitStderrIfPresent(context, diagnostics);
+        this.appendRuntimeEvent(context, mapAcpAgentExitedToRuntimeEvent(context, diagnostics));
+        await active.supervisor.stop().catch(() => undefined);
+    }
+    appendRuntimeEvent(context, mapping) {
+        const result = this.runtimeStore.append({
+            conversationId: context.conversationId,
+            requestId: context.requestId,
+            subagentRunId: context.subagentRunId,
+            source: 'acp',
+            event: {
+                ...mapping.event,
+                conversationId: context.conversationId,
+                requestId: context.requestId,
+                source: 'acp',
+            },
+        });
+        if (result.event && !result.duplicate)
+            this.onRuntimeEvent?.(result.event);
+    }
+    appendLifecycleEvent(context, type, payload) {
+        this.appendRuntimeEvent(context, {
+            type,
+            event: {
+                type,
+                timestamp: new Date().toISOString(),
+                ...context,
+                ...payload,
+            },
+        });
+    }
+    emitStderrIfPresent(context, diagnostics) {
+        if (diagnostics.stderrTail.length === 0)
+            return;
+        this.appendRuntimeEvent(context, mapAcpAgentStderrToRuntimeEvent(context, diagnostics.stderrTail));
+    }
+    listEventCount(conversationId) {
+        return this.runtimeStore.list({ conversationId, limit: 5000 }).events.length;
+    }
+    workspaceKeyFor(cwd, additionalDirectories, execution) {
+        return JSON.stringify({
+            cwd: normalizeWorkspacePath(cwd || ''),
+            additionalDirectories: additionalDirectories.map(normalizeWorkspacePath).sort(),
+            execution: execution || {
+                schemaVersion: 1,
+                permissionProfile: 'unspecified',
+                filesystem: 'read-only',
+            },
+        });
+    }
+    sessionExecutionMeta(request, includeResumeState = false) {
+        const meta = {};
+        if (request.execution) {
+            meta[XENO_ACP_CONTEXT_META_KEY] = {
+                execution: request.execution,
+            };
+        }
+        if (includeResumeState && request.resumeState) {
+            meta[XENO_ACP_SESSION_RESUME_META_KEY] = request.resumeState;
+        }
+        return Object.keys(meta).length > 0 ? { _meta: meta } : {};
+    }
+    workspaceFingerprintFor(workspaceKey) {
+        return createHash('sha256').update(workspaceKey).digest('hex');
+    }
+    agentConfigFingerprintFor(config) {
+        return createHash('sha256').update(JSON.stringify({
+            id: config.id,
+            command: config.command,
+            args: config.args,
+            cwd: config.cwd || '',
+            envKeys: Object.keys(config.env || {}).sort(),
+            trustLevel: config.trustLevel,
+            updatedAt: config.updatedAt,
+        })).digest('hex');
+    }
+    resolveConversationCwd(request) {
+        if (request.cwd)
+            return request.cwd;
+        if (!this.rootDir)
+            return undefined;
+        const safeConversationId = request.conversationId
+            .replace(/[^A-Za-z0-9._-]/g, '_')
+            .slice(0, 120) || 'conversation';
+        const cwd = join(this.rootDir, 'acp-chat-workspaces', safeConversationId);
+        mkdirSync(cwd, { recursive: true });
+        return cwd;
+    }
+}
+function normalizeWorkspacePath(path) {
+    const normalized = path.trim().replace(/\//g, '\\').replace(/\\+$/, '');
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+class RuntimeRecordingAcpPermissionBridge {
+    delegate;
+    append;
+    onRunActivity;
+    activeContext;
+    constructor(delegate, append, 
+    /**
+     * 🔴 This layer is the ONLY one that knows both facts at once: that a
+     * human is being waited on, and which run is waiting. The delegate knows
+     * the prompt and not the run; the host knows the run and not that the
+     * prompt is outstanding.
+     */
+    onRunActivity) {
+        this.delegate = delegate;
+        this.append = append;
+        this.onRunActivity = onRunActivity;
+    }
+    setActiveContext(context) {
+        this.activeContext = context;
+    }
+    async requestPermission(request) {
+        const context = {
+            ...this.activeContext,
+            conversationId: this.activeContext?.conversationId || 'acp-conversation-unknown',
+            requestId: this.activeContext?.requestId || 'acp-request-unknown',
+            acpProcessId: this.activeContext?.acpProcessId || 'acp-process-unknown',
+            acpAgentConfigId: this.activeContext?.acpAgentConfigId || 'acp-agent-unknown',
+            providerKind: this.activeContext?.providerKind || 'acp-provider',
+            providerId: this.activeContext?.providerId || this.activeContext?.acpAgentConfigId || 'acp-agent-unknown',
+            subagentRunId: this.activeContext?.subagentRunId,
+            acpSessionId: request.sessionId || this.activeContext?.acpSessionId,
+            schemaVersion: 1,
+            redactionState: 'redacted',
+        };
+        const permissionId = `acp-permission-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        this.append(mapAcpPermissionRequestedToRuntimeEvent(context, permissionId, request), context);
+        // The delegate may need to raise this to a surface, and a surface routes a
+        // prompt onto a conversation by the HOST request id. Only this layer knows
+        // it, so it is attached here rather than plumbed through every bridge.
+        const runId = defaultRunIdOf({
+            conversationId: context.conversationId,
+            ...(context.subagentRunId === undefined ? {} : { subagentRunId: context.subagentRunId }),
+        });
+        this.onRunActivity?.({ runId, state: 'awaiting-approval' });
+        try {
+            const outcome = await this.delegate.requestPermission({
+                ...request,
+                hostRequestId: context.requestId,
+                hostConversationId: context.conversationId,
+                // The SAME id the journal event above carries, so a prompt rendered from
+                // either source is answerable by the same key.
+                hostPermissionId: permissionId,
+            });
+            this.append(mapAcpPermissionDecidedToRuntimeEvent(context, permissionId, outcome, request.sessionId), context);
+            this.onRunActivity?.({
+                runId,
+                state: 'running',
+                // §7's "last decision", in the run's own terms. The OUTCOME, not the
+                // prompt: a peer needs to know what this run was allowed to do, and the
+                // prompt text is the request rather than the answer.
+                lastDecision: describePermissionOutcome(outcome),
+            });
+            return outcome;
+        }
+        catch (error) {
+            // A failed prompt still ENDS the wait. Left in `awaiting-approval` the run
+            // would look blocked on a human forever, and a peer would keep deferring
+            // to something that is not going to answer.
+            this.onRunActivity?.({ runId, state: 'running' });
+            throw error;
+        }
+    }
+    cancelOutstanding(reason) {
+        this.delegate.cancelOutstanding?.(reason);
+    }
+}
+/**
+ * One line a peer can act on, from a permission outcome.
+ *
+ * Deliberately terse and structural rather than the prompt text: §9 is explicit
+ * that a summary is never a transcript, and a permission prompt can quote a
+ * command, a path or a diff. What another run needs is what this one was
+ * allowed to do, not what it was asked.
+ */
+function describePermissionOutcome(outcome) {
+    return outcome.outcome === 'selected'
+        ? `permission selected (${outcome.selectedOptionId})`
+        : 'permission cancelled';
+}
+class RuntimeRecordingAcpHostBridge {
+    delegate;
+    append;
+    activeContext;
+    constructor(delegate, append) {
+        this.delegate = delegate;
+        this.append = append;
+    }
+    setActiveContext(context) {
+        this.activeContext = context;
+    }
+    async chooseDirectory(request) {
+        const context = {
+            ...this.activeContext,
+            conversationId: this.activeContext?.conversationId || 'acp-conversation-unknown',
+            requestId: this.activeContext?.requestId || request.requestId || 'acp-request-unknown',
+            acpProcessId: this.activeContext?.acpProcessId || 'acp-process-unknown',
+            acpAgentConfigId: this.activeContext?.acpAgentConfigId || 'acp-agent-unknown',
+            providerKind: this.activeContext?.providerKind || 'acp-provider',
+            providerId: this.activeContext?.providerId || this.activeContext?.acpAgentConfigId || 'acp-agent-unknown',
+            subagentRunId: this.activeContext?.subagentRunId,
+            acpSessionId: request.sessionId || this.activeContext?.acpSessionId,
+            schemaVersion: 1,
+            redactionState: 'redacted',
+        };
+        let chooseDirectoryId;
+        const delegatedRequest = {
+            ...request,
+            requestId: context.requestId,
+            sessionId: context.acpSessionId,
+            emitRuntimeEvent: (event) => {
+                const type = typeof event.type === 'string' && event.type.trim()
+                    ? event.type.trim()
+                    : 'choose_directory.requested';
+                if (typeof event.chooseDirectoryId === 'string' && event.chooseDirectoryId.trim()) {
+                    chooseDirectoryId = event.chooseDirectoryId.trim();
+                }
+                this.append({
+                    type,
+                    event: {
+                        ...event,
+                        type,
+                        source: 'acp',
+                        ...context,
+                        toolCallId: request.toolCallId,
+                        toolName: 'ChooseDirectory',
+                    },
+                }, context);
+            },
+        };
+        let result;
+        try {
+            result = await this.delegate.chooseDirectory(delegatedRequest);
+        }
+        catch (error) {
+            result = { error: acpSafeErrorMessage(error) };
+        }
+        this.append(mapAcpChooseDirectoryResultToRuntimeEvent(context, delegatedRequest, result, chooseDirectoryId), context);
+        return result;
+    }
+    async chooseWorkspacePlacement(request) {
+        const context = {
+            ...this.activeContext,
+            conversationId: this.activeContext?.conversationId || 'acp-conversation-unknown',
+            requestId: this.activeContext?.requestId || request.requestId || 'acp-request-unknown',
+            acpProcessId: this.activeContext?.acpProcessId || 'acp-process-unknown',
+            acpAgentConfigId: this.activeContext?.acpAgentConfigId || 'acp-agent-unknown',
+            providerKind: this.activeContext?.providerKind || 'acp-provider',
+            providerId: this.activeContext?.providerId || this.activeContext?.acpAgentConfigId || 'acp-agent-unknown',
+            subagentRunId: this.activeContext?.subagentRunId,
+            acpSessionId: request.sessionId || this.activeContext?.acpSessionId,
+            schemaVersion: 1,
+            redactionState: 'redacted',
+        };
+        let workspacePlacementId;
+        const delegatedRequest = {
+            ...request,
+            requestId: context.requestId,
+            sessionId: context.acpSessionId,
+            emitRuntimeEvent: (event) => {
+                const type = typeof event.type === 'string' && event.type.trim()
+                    ? event.type.trim()
+                    : 'workspace_placement.requested';
+                if (typeof event.workspacePlacementId === 'string' && event.workspacePlacementId.trim()) {
+                    workspacePlacementId = event.workspacePlacementId.trim();
+                }
+                this.append({
+                    type,
+                    event: {
+                        ...event,
+                        type,
+                        source: 'acp',
+                        ...context,
+                        toolCallId: request.toolCallId,
+                        toolName: 'ChooseWorkspacePlacement',
+                    },
+                }, context);
+            },
+        };
+        let result;
+        try {
+            result = await this.delegate.chooseWorkspacePlacement(delegatedRequest);
+        }
+        catch (error) {
+            result = { error: acpSafeErrorMessage(error) };
+        }
+        this.append(mapAcpChooseWorkspacePlacementResultToRuntimeEvent(context, delegatedRequest, result, workspacePlacementId), context);
+        return result;
+    }
+    cancelOutstanding(reason) {
+        this.delegate.cancelOutstanding?.(reason);
+    }
+}
+export function buildAcpConversationReplayPrompt(history, currentPrompt) {
+    const priorMessages = history.map((message) => ({ ...message }));
+    const last = priorMessages.at(-1);
+    if (last?.role === 'user' && last.content.trim() === currentPrompt.trim()) {
+        priorMessages.pop();
+    }
+    if (priorMessages.length === 0)
+        return currentPrompt;
+    return [
+        'XENO Agent restored this conversation into a fresh ACP session.',
+        'Use the JSON transcript as prior conversational context. Do not repeat or answer prior turns again.',
+        'Answer only the current user message that follows the transcript.',
+        JSON.stringify({
+            schema: 'xeno.agent.acp-conversation-replay.v1',
+            messages: priorMessages,
+        }),
+        'Current user message:',
+        currentPrompt,
+    ].join('\n\n');
+}
+function statusForError(error) {
+    const code = acpErrorCode(error);
+    if (code === 'ACP_TIMEOUT')
+        return 'timed_out';
+    if (code === 'ACP_CANCELLED')
+        return 'cancelled';
+    if (code === 'ACP_PROCESS_EXITED')
+        return 'process_exited';
+    return 'failed';
+}
+//# sourceMappingURL=AcpSessionService.js.map