@borgee/agents-host 0.2.1 → 0.2.26

package/dist/providers/codex/cli-client.js

@@ -0,0 +1,1133 @@
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { Readable, Writable } from 'node:stream';
+import { createRequire } from 'node:module';
+import spawn from 'cross-spawn';
+import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
+import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
+import { assertCodexProjectDocumentSize, buildCodexProjectDocument } from './project-doc.js';
+const SESSION_TAINTED_ERRORS = new WeakSet();
+const DEFAULT_IDLE_SESSION_TTL_MS = 2 * 24 * 60 * 60 * 1000;
+const DEFAULT_SHUTDOWN_GRACE_PERIOD_MS = 250;
+const DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS = 250;
+const DEFAULT_SESSION_CAPABILITIES = {
+    loadSession: false,
+    resumeSession: false,
+};
+const DEFAULT_CODEX_COMMAND = 'codex-acp';
+const DEFAULT_CODEX_ARGS = [];
+const CODEX_CONTEXT_ROOT_DIRNAME = 'codex-context';
+const PROJECTED_GATEWAY_AUTH_FILENAME = '.localhost-gateway-auth.json';
+const PROJECTED_GATEWAY_AUTH_PREFIX = '.localhost-gateway-auth.';
+const PROJECTION_UNAVAILABLE_PLACEHOLDER = '[codex-projection-unavailable]';
+const QUEUED_TURN_DROPPED_MESSAGE = 'Codex ACP session was reset after a failed turn; queued turns were dropped instead of replaying them on a fresh session';
+const require = createRequire(import.meta.url);
+const DEFAULT_RUNTIME = {
+    spawn,
+    client,
+    ndJsonStream,
+    methods,
+    protocolVersion: PROTOCOL_VERSION,
+    cwd: process.cwd(),
+    idleSessionTtlMs: DEFAULT_IDLE_SESSION_TTL_MS,
+    shutdownGracePeriodMs: DEFAULT_SHUTDOWN_GRACE_PERIOD_MS,
+    shutdownForceKillWaitMs: DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS,
+    readFile: async (path, options) => {
+        return fs.readFile(path, options?.encoding ?? 'utf8');
+    },
+    readdir: async (path) => {
+        return fs.readdir(path);
+    },
+    writeFile: async (path, data, options) => {
+        await fs.writeFile(path, data, options);
+    },
+    mkdir: async (path, options) => {
+        await fs.mkdir(path, options);
+    },
+    unlink: async (path) => {
+        await fs.unlink(path);
+    },
+};
+function hasVisibleText(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function cloneDirectories(directories) {
+    return directories ? [...directories] : undefined;
+}
+function directoriesEqual(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (!left || !right) {
+        return !left && !right;
+    }
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+function parsePersistedSessionRecord(rawValue) {
+    const trimmed = rawValue.trim();
+    if (trimmed.startsWith('{')) {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed.sessionId === 'string' && parsed.sessionId.trim().length > 0) {
+            return {
+                sessionId: parsed.sessionId,
+                visibilityKey: typeof parsed.visibilityKey === 'string' && parsed.visibilityKey.trim().length > 0
+                    ? parsed.visibilityKey
+                    : undefined,
+                cwd: typeof parsed.cwd === 'string' && parsed.cwd.trim().length > 0
+                    ? parsed.cwd
+                    : undefined,
+            };
+        }
+    }
+    return { sessionId: rawValue };
+}
+function serializePersistedSessionRecord(record) {
+    return JSON.stringify({
+        sessionId: record.sessionId,
+        ...(record.visibilityKey ? { visibilityKey: record.visibilityKey } : {}),
+        ...(record.cwd ? { cwd: record.cwd } : {}),
+    });
+}
+function formatToolProgress(title, status) {
+    const normalizedTitle = hasVisibleText(title) ? title.trim() : null;
+    switch (status) {
+        case 'completed':
+            return normalizedTitle ? `Completed ${normalizedTitle}` : 'Completed tool call';
+        case 'failed':
+            return normalizedTitle ? `Failed ${normalizedTitle}` : 'Tool call failed';
+        case 'pending':
+        case 'in_progress':
+        case undefined:
+        case null:
+            return normalizedTitle ? `Running ${normalizedTitle}…` : 'Running tool…';
+        default:
+            return normalizedTitle ? `${status} ${normalizedTitle}` : status;
+    }
+}
+function formatPlanProgress(entries) {
+    const current = entries.find((entry) => entry.status === 'in_progress') ??
+        entries.find((entry) => entry.status === 'pending') ??
+        entries[0];
+    return hasVisibleText(current?.content) ? `Plan: ${current.content.trim()}` : null;
+}
+class CodexProgressCollector {
+    onProgress;
+    publicText = '';
+    lastPublished = null;
+    toolTitles = new Map();
+    constructor(onProgress) {
+        this.onProgress = onProgress;
+    }
+    consume(update) {
+        switch (update.update.sessionUpdate) {
+            case 'agent_message_chunk':
+                if (update.update.content.type !== 'text') {
+                    return;
+                }
+                this.publicText += update.update.content.text;
+                this.publish(this.publicText);
+                return;
+            case 'tool_call':
+                this.toolTitles.set(update.update.toolCallId, update.update.title);
+                this.publishFallback(formatToolProgress(update.update.title, update.update.status));
+                return;
+            case 'tool_call_update': {
+                const nextTitle = update.update.title ?? this.toolTitles.get(update.update.toolCallId);
+                if (hasVisibleText(nextTitle)) {
+                    this.toolTitles.set(update.update.toolCallId, nextTitle);
+                }
+                this.publishFallback(formatToolProgress(nextTitle, update.update.status));
+                return;
+            }
+            case 'plan':
+                this.publishFallback(formatPlanProgress(update.update.entries.map((entry) => ({
+                    content: entry.content,
+                    status: entry.status,
+                }))));
+                return;
+            default:
+                return;
+        }
+    }
+    getFinalText() {
+        return this.publicText.trim();
+    }
+    publishFallback(text) {
+        if (hasVisibleText(this.publicText)) {
+            return;
+        }
+        this.publish(text);
+    }
+    publish(text) {
+        if (!this.onProgress || !hasVisibleText(text) || text === this.lastPublished) {
+            return;
+        }
+        this.lastPublished = text;
+        this.onProgress({ text });
+    }
+}
+function createDeferredTurn(channelId, prompt, promptContext, sessionPersistence, options) {
+    let settled = false;
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+    });
+    return {
+        channelId,
+        prompt,
+        promptContext,
+        sessionPersistence,
+        options,
+        promise,
+        resolve(value) {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(value);
+        },
+        reject(error) {
+            if (settled)
+                return;
+            settled = true;
+            rejectPromise(normalizeError(error));
+        },
+    };
+}
+function normalizeError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function resolveSessionRouting(turn) {
+    return {
+        channelId: turn.channelId,
+        key: turn.providerSessionRouting?.key ?? turn.channelId,
+        persistence: turn.providerSessionRouting?.persistence ?? 'persistent',
+    };
+}
+function asObject(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+function readSessionCapabilities(response) {
+    const agentCapabilities = asObject(asObject(response)?.agentCapabilities);
+    const sessionCapabilities = asObject(agentCapabilities?.sessionCapabilities ?? agentCapabilities?.session);
+    return {
+        loadSession: agentCapabilities?.loadSession === true,
+        resumeSession: asObject(sessionCapabilities?.resume) !== null,
+    };
+}
+function isStaleRestoreFailure(error) {
+    const normalized = normalizeError(error);
+    const code = asObject(error)?.code;
+    const dataCode = asObject(asObject(error)?.data)?.code;
+    if (code === 'session_not_found' || dataCode === 'session_not_found') {
+        return true;
+    }
+    const message = normalized.message.toLowerCase();
+    return message.includes('session not found')
+        || message.includes('unknown session')
+        || message.includes('cannot resume')
+        || message.includes('not found');
+}
+function markSessionTainted(error) {
+    const normalized = normalizeError(error);
+    SESSION_TAINTED_ERRORS.add(normalized);
+    return normalized;
+}
+function isSessionTainted(error) {
+    return error instanceof Error && SESSION_TAINTED_ERRORS.has(error);
+}
+function createPermissionResponse(params) {
+    const options = Array.isArray(params.options) ? params.options : [];
+    const preferredKinds = ['allow_once', 'allow_always', 'reject_once', 'reject_always'];
+    for (const kind of preferredKinds) {
+        const match = options.find((option) => option.kind === kind);
+        if (match) {
+            return {
+                outcome: {
+                    outcome: 'selected',
+                    optionId: match.optionId,
+                },
+            };
+        }
+    }
+    return {
+        outcome: {
+            outcome: 'cancelled',
+        },
+    };
+}
+function resolveBundledCodexAdapterPath() {
+    return require.resolve('@agentclientprotocol/codex-acp');
+}
+function useBundledCodexAdapter(command, args) {
+    return command === DEFAULT_CODEX_COMMAND && args.length === DEFAULT_CODEX_ARGS.length;
+}
+function resolveAdapterLaunch(command, args) {
+    if (useBundledCodexAdapter(command, args)) {
+        return {
+            command: process.execPath,
+            args: [resolveBundledCodexAdapterPath()],
+        };
+    }
+    return {
+        command,
+        args: [...args],
+    };
+}
+export class CodexCliClient {
+    command;
+    args;
+    sessionStore;
+    resolveSessionStoreAgentId;
+    logger;
+    runtime;
+    channels = new Map();
+    persistedSessions = new Map();
+    closingSessions = new WeakSet();
+    pendingSessionStarts = new Set();
+    pendingSessionCloses = new Set();
+    pendingSessionStoreOperations = new Set();
+    fatalPromise;
+    rejectFatalPromise;
+    child;
+    connection;
+    startPromise;
+    shutdownPromise;
+    childExitPromise;
+    resolveChildExit;
+    fatalError = null;
+    disposing = false;
+    backendClosed = false;
+    loadedSessionStoreAgentId = null;
+    sessionStoreLoadPromise = null;
+    sessionStoreWriteQueue = Promise.resolve();
+    sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
+    constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger()) {
+        this.command = command;
+        this.args = args;
+        this.sessionStore = sessionStore;
+        this.resolveSessionStoreAgentId = resolveSessionStoreAgentId;
+        this.logger = logger;
+        this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
+        this.fatalPromise = new Promise((_, reject) => {
+            this.rejectFatalPromise = reject;
+        });
+        void this.fatalPromise.catch(() => { });
+    }
+    async generateReply(channelIdOrTurn, promptOrOptions, maybeOptions) {
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        const preparedTurn = typeof channelIdOrTurn === 'string'
+            ? {
+                channelId: channelIdOrTurn,
+                prompt: typeof promptOrOptions === 'string' ? promptOrOptions : '',
+            }
+            : channelIdOrTurn;
+        const options = typeof channelIdOrTurn === 'string'
+            ? maybeOptions
+            : promptOrOptions;
+        const sessionRouting = resolveSessionRouting(preparedTurn);
+        const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
+        this.clearIdleTimer(state);
+        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, preparedTurn.promptContext, sessionRouting.persistence, options);
+        state.queue.push(turn);
+        this.processChannelQueue(sessionRouting.key, state);
+        return turn.promise;
+    }
+    async dispose() {
+        const error = new Error('Codex ACP backend stopped');
+        this.disposing = true;
+        this.logger?.debug('stopping Codex ACP backend');
+        const closed = this.connection?.closed ?? Promise.resolve();
+        this.failAll(error);
+        let thrown;
+        try {
+            await Promise.all([closed, this.shutdownPromise ?? Promise.resolve()]);
+        }
+        catch (disposeError) {
+            thrown = disposeError;
+        }
+        try {
+            await Promise.allSettled(this.pendingSessionStoreOperations);
+            await this.sessionStoreWriteQueue;
+            await this.sessionStore?.close?.();
+        }
+        catch (closeError) {
+            thrown ??= closeError;
+        }
+        if (thrown) {
+            throw thrown;
+        }
+    }
+    async ensureStarted() {
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        if (!this.startPromise) {
+            this.startPromise = this.startBackend();
+        }
+        await this.startPromise;
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        if (!this.connection) {
+            throw new Error('Codex ACP connection is not available');
+        }
+    }
+    async startBackend() {
+        const launch = resolveAdapterLaunch(this.command, this.args);
+        this.logger?.debug('starting Codex ACP process', {
+            command: launch.command,
+            args: launch.args,
+            cwd: this.runtime.cwd,
+        });
+        const child = this.runtime.spawn(launch.command, launch.args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child = child;
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            this.logger?.childStderr('codex stderr', summarizeChildStderr(chunk));
+        });
+        child.stderr.resume();
+        this.logger?.debug('spawned Codex ACP process', { pid: child.pid });
+        child.once('error', (error) => {
+            this.logger?.debugError('Codex ACP process error', error);
+            this.failAll(new Error(`Codex ACP process error: ${normalizeError(error).message}`));
+        });
+        child.once('exit', (code, signal) => {
+            this.resolveChildExit?.();
+            if (this.disposing) {
+                this.logger?.debug('Codex ACP process exited during shutdown', { code, signal });
+                return;
+            }
+            this.logger?.debugError('Codex ACP process exited unexpectedly', { code, signal });
+            const suffix = signal ? `signal ${signal}` : `code ${String(code ?? 'unknown')}`;
+            this.failAll(new Error(`Codex ACP process exited unexpectedly (${suffix})`));
+        });
+        this.childExitPromise = new Promise((resolveChildExit) => {
+            this.resolveChildExit = resolveChildExit;
+        });
+        const output = Writable.toWeb(child.stdin);
+        const input = Readable.toWeb(child.stdout);
+        const stream = this.runtime.ndJsonStream(output, input);
+        const app = this.runtime
+            .client({ name: 'borgee-agents-host' })
+            .onRequest(this.runtime.methods.client.session.requestPermission, ({ params }) => (createPermissionResponse(params)));
+        const connection = app.connect(stream);
+        this.connection = connection;
+        void connection.closed.then(() => {
+            if (!this.disposing) {
+                this.logger?.debugError('Codex ACP connection closed unexpectedly');
+                this.failAll(new Error('Codex ACP connection closed unexpectedly'));
+            }
+        });
+        try {
+            const initializeResponse = await connection.agent.request(this.runtime.methods.agent.initialize, {
+                protocolVersion: this.runtime.protocolVersion,
+                clientCapabilities: {},
+                clientInfo: {
+                    name: '@borgee/agents-host',
+                    version: '0.2.24',
+                },
+            });
+            this.sessionCapabilities = readSessionCapabilities(initializeResponse);
+            this.logger?.debug('initialized Codex ACP connection', {
+                loadSession: this.sessionCapabilities.loadSession,
+                resumeSession: this.sessionCapabilities.resumeSession,
+            });
+        }
+        catch (error) {
+            const normalized = new Error(`Codex ACP initialize failed: ${normalizeError(error).message}`);
+            this.logger?.debugError('Codex ACP initialize failed', normalized);
+            this.failAll(normalized);
+            throw normalized;
+        }
+    }
+    getOrCreateChannelState(channelId, resolvedChannelId, sessionPersistence) {
+        let state = this.channels.get(channelId);
+        if (!state) {
+            state = {
+                channelId: resolvedChannelId,
+                sessionPersistence,
+                idleTimerGeneration: 0,
+                processing: false,
+                queue: [],
+            };
+            this.channels.set(channelId, state);
+        }
+        else if (state.channelId !== resolvedChannelId
+            || state.sessionPersistence !== sessionPersistence) {
+            throw new Error(`Codex session routing changed for key "${channelId}"`);
+        }
+        return state;
+    }
+    processChannelQueue(channelId, state) {
+        if (state.processing) {
+            return;
+        }
+        state.processing = true;
+        void (async () => {
+            try {
+                while (!this.fatalError) {
+                    const turn = state.queue.shift();
+                    if (!turn) {
+                        return;
+                    }
+                    state.activeTurn = turn;
+                    try {
+                        state.cwd = await this.resolveSessionCwd(turn.promptContext);
+                        const projectedPromptContext = await this.refreshProjectedPromptContextBestEffort(turn.channelId, turn.promptContext);
+                        state.additionalDirectories = this.resolveSessionAdditionalDirectories(projectedPromptContext);
+                        state.visibilityKey = this.resolveSessionVisibilityKey(projectedPromptContext);
+                        await this.ensureStarted();
+                        await this.recycleSessionIfInjectionScopeChanged(channelId, state);
+                        const session = await this.getOrCreateSession(channelId, state);
+                        let reply;
+                        try {
+                            reply = await this.runTurn(session, this.rewritePromptContextPaths(turn.prompt, turn.promptContext, projectedPromptContext?.promptContext), turn.options);
+                        }
+                        catch (error) {
+                            if (isSessionTainted(error)) {
+                                this.invalidateSession(channelId, state, session);
+                                this.rejectQueuedTurnsAfterSessionTaint(state, error);
+                            }
+                            throw error;
+                        }
+                        turn.resolve(reply);
+                    }
+                    catch (error) {
+                        turn.reject(error);
+                    }
+                    finally {
+                        state.activeTurn = undefined;
+                    }
+                }
+            }
+            finally {
+                state.processing = false;
+                this.reconcileIdleChannelState(channelId, state);
+            }
+        })();
+    }
+    async getOrCreateSession(channelId, state) {
+        if (state.session) {
+            return state.session;
+        }
+        if (state.sessionPromise) {
+            return state.sessionPromise;
+        }
+        if (!this.connection) {
+            throw new Error('Codex ACP connection is not available');
+        }
+        const cwd = state.cwd ?? this.runtime.cwd;
+        const persistedSessionId = state.sessionPersistence === 'persistent'
+            ? await this.readPersistedSessionId(channelId, state.visibilityKey, cwd)
+            : undefined;
+        const additionalDirectories = state.additionalDirectories;
+        const sessionPromise = persistedSessionId
+            ? this.restoreOrCreateSession(channelId, persistedSessionId, cwd, additionalDirectories)
+            : this.startFreshSession(channelId, cwd, additionalDirectories);
+        this.pendingSessionStarts.add(sessionPromise);
+        state.sessionPromise = sessionPromise;
+        let sessionAdopted = false;
+        void sessionPromise
+            .then((session) => {
+            if (!sessionAdopted &&
+                (this.fatalError !== null || this.disposing || state.sessionPromise !== sessionPromise)) {
+                this.closeSession(session);
+            }
+        })
+            .finally(() => {
+            this.pendingSessionStarts.delete(sessionPromise);
+        })
+            .catch(() => { });
+        try {
+            const session = await this.raceWithFatal(sessionPromise);
+            if (this.fatalError) {
+                this.closeSession(session);
+                throw this.fatalError;
+            }
+            sessionAdopted = true;
+            state.session = session;
+            state.sessionCwd = cwd;
+            state.sessionAdditionalDirectories = cloneDirectories(state.additionalDirectories);
+            state.sessionVisibilityKey = state.visibilityKey;
+            return session;
+        }
+        catch (error) {
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionAdditionalDirectories = undefined;
+            state.sessionVisibilityKey = undefined;
+            throw error;
+        }
+        finally {
+            if (state.sessionPromise === sessionPromise) {
+                state.sessionPromise = undefined;
+            }
+        }
+    }
+    async startFreshSession(channelId, cwd, additionalDirectories) {
+        if (!this.connection) {
+            throw new Error('Codex ACP connection is not available');
+        }
+        const sessionBuilder = this.connection.agent.buildSession(cwd);
+        if (additionalDirectories && additionalDirectories.length > 0) {
+            sessionBuilder.withAdditionalDirectories(additionalDirectories);
+        }
+        const session = await sessionBuilder.start();
+        this.logger?.debug('started fresh Codex ACP session', { channelId, cwd });
+        const state = this.channels.get(channelId);
+        if (state?.sessionPersistence === 'persistent') {
+            await this.persistSessionBestEffort(channelId, session.sessionId, state.visibilityKey, cwd);
+        }
+        return session;
+    }
+    async restoreOrCreateSession(channelId, sessionId, cwd, additionalDirectories) {
+        if (!this.sessionCapabilities.resumeSession && !this.sessionCapabilities.loadSession) {
+            this.logger?.debug('Codex ACP restore unsupported; starting fresh session', { channelId });
+            return this.startFreshSession(channelId, cwd, additionalDirectories);
+        }
+        try {
+            const session = await this.restoreSession(sessionId, cwd, additionalDirectories);
+            this.logger?.debug('restored Codex ACP session', {
+                channelId,
+                restoreMethod: this.sessionCapabilities.resumeSession ? 'session/resume' : 'session/load',
+            });
+            return session;
+        }
+        catch (error) {
+            if (!isStaleRestoreFailure(error)) {
+                throw normalizeError(error);
+            }
+            this.logger?.debug('discarded stale Codex ACP session and started fresh', { channelId });
+            await this.clearPersistedSessionBestEffort(channelId);
+            return this.startFreshSession(channelId, cwd, additionalDirectories);
+        }
+    }
+    async restoreSession(sessionId, cwd, additionalDirectories) {
+        if (!this.connection) {
+            throw new Error('Codex ACP connection is not available');
+        }
+        const agent = this.connection.agent;
+        if (typeof agent.attachSession !== 'function') {
+            throw new Error('Codex ACP SDK does not expose session attachment helpers');
+        }
+        const session = agent.attachSession({ sessionId });
+        const sessionRequest = additionalDirectories && additionalDirectories.length > 0
+            ? { sessionId, cwd, additionalDirectories, mcpServers: [] }
+            : { sessionId, cwd, mcpServers: [] };
+        try {
+            if (this.sessionCapabilities.resumeSession) {
+                await this.connection.agent.request(this.runtime.methods.agent.session.resume, sessionRequest);
+                return session;
+            }
+            if (this.sessionCapabilities.loadSession) {
+                await this.connection.agent.request(this.runtime.methods.agent.session.load, sessionRequest);
+                this.clearBufferedSessionReplay(session);
+                return session;
+            }
+            throw new Error('Codex ACP agent does not advertise session restore capabilities');
+        }
+        catch (error) {
+            session.dispose();
+            throw normalizeError(error);
+        }
+    }
+    clearBufferedSessionReplay(session) {
+        const updates = session.updates;
+        if (updates && Array.isArray(updates.values)) {
+            updates.values = [];
+        }
+    }
+    async resolveSessionCwd(promptContext) {
+        return promptContext?.taskWorkspace?.rootPath ?? this.runtime.cwd;
+    }
+    async recycleSessionIfInjectionScopeChanged(channelId, state) {
+        const session = state.session;
+        if (!session) {
+            return;
+        }
+        if (state.sessionCwd === (state.cwd ?? this.runtime.cwd)
+            && directoriesEqual(state.sessionAdditionalDirectories, state.additionalDirectories)
+            && state.sessionVisibilityKey === state.visibilityKey) {
+            return;
+        }
+        this.logger?.debug('recycling Codex ACP session after session scope changed', {
+            channelId,
+            previousCwd: state.sessionCwd,
+            nextCwd: state.cwd ?? this.runtime.cwd,
+        });
+        state.session = undefined;
+        state.sessionCwd = undefined;
+        state.sessionAdditionalDirectories = undefined;
+        state.sessionVisibilityKey = undefined;
+        this.clearIdleTimer(state);
+        if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
+            await this.clearPersistedSessionBestEffort(channelId);
+        }
+        this.closeSession(session);
+    }
+    resolveSessionAdditionalDirectories(projectedPromptContext) {
+        return projectedPromptContext ? [projectedPromptContext.directoryPath] : undefined;
+    }
+    resolveSessionVisibilityKey(projectedPromptContext) {
+        if (!projectedPromptContext) {
+            return undefined;
+        }
+        return JSON.stringify({
+            directoryPath: projectedPromptContext.directoryPath,
+            channelContextPayloadPath: projectedPromptContext.promptContext.channelContextPayloadPath,
+            gatewayAuthPath: projectedPromptContext.promptContext.gatewayAuthPath ?? null,
+        });
+    }
+    resolveProjectedContextDirectory(payloadPath) {
+        const channelContextDirectory = resolve(dirname(payloadPath));
+        return join(dirname(dirname(channelContextDirectory)), CODEX_CONTEXT_ROOT_DIRNAME, basename(channelContextDirectory));
+    }
+    buildProjectedPromptContext(promptContext, projectedDirectoryPath) {
+        const payloadPath = promptContext.channelContextPayloadPath?.trim();
+        if (!payloadPath) {
+            return null;
+        }
+        return {
+            ...promptContext,
+            channelContextPayloadPath: join(projectedDirectoryPath, basename(payloadPath)),
+            gatewayAuthPath: promptContext.gatewayAuthPath
+                ? join(projectedDirectoryPath, basename(promptContext.gatewayAuthPath))
+                : undefined,
+        };
+    }
+    async copyProjectedFile(sourcePath, targetPath) {
+        const content = await this.runtime.readFile(sourcePath, { encoding: 'utf8' });
+        await this.runtime.writeFile(targetPath, content, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+    }
+    async pruneProjectedGatewayAuthFiles(directoryPath, keepPath) {
+        const keepFilename = keepPath ? basename(keepPath) : null;
+        const entries = await this.runtime.readdir(directoryPath);
+        await Promise.all(entries
+            .filter((entry) => entry === PROJECTED_GATEWAY_AUTH_FILENAME
+            || (entry.startsWith(PROJECTED_GATEWAY_AUTH_PREFIX) && entry.endsWith('.json')))
+            .filter((entry) => entry !== keepFilename)
+            .map(async (entry) => {
+            await this.runtime.unlink(join(directoryPath, entry)).catch((error) => {
+                if (error.code !== 'ENOENT') {
+                    throw error;
+                }
+            });
+        }));
+    }
+    async refreshProjectedPromptContextBestEffort(channelId, promptContext) {
+        const resolvedPromptContext = promptContext;
+        const payloadPath = resolvedPromptContext?.channelContextPayloadPath?.trim();
+        if (!resolvedPromptContext || !payloadPath) {
+            return undefined;
+        }
+        const projectedDirectoryPath = this.resolveProjectedContextDirectory(payloadPath);
+        const projectedPromptContext = this.buildProjectedPromptContext(resolvedPromptContext, projectedDirectoryPath);
+        if (!projectedPromptContext?.channelContextPayloadPath) {
+            return undefined;
+        }
+        try {
+            await this.runtime.mkdir(projectedDirectoryPath, { recursive: true, mode: 0o700 });
+            await this.pruneProjectedGatewayAuthFiles(projectedDirectoryPath, projectedPromptContext.gatewayAuthPath);
+            await this.copyProjectedFile(payloadPath, projectedPromptContext.channelContextPayloadPath);
+            if (resolvedPromptContext.gatewayAuthPath && projectedPromptContext.gatewayAuthPath) {
+                await this.copyProjectedFile(resolvedPromptContext.gatewayAuthPath, projectedPromptContext.gatewayAuthPath);
+            }
+            const content = buildCodexProjectDocument(projectedPromptContext);
+            assertCodexProjectDocumentSize(content);
+            await this.runtime.writeFile(join(projectedDirectoryPath, 'AGENTS.md'), content, {
+                encoding: 'utf8',
+                mode: 0o600,
+            });
+            return {
+                directoryPath: projectedDirectoryPath,
+                promptContext: projectedPromptContext,
+            };
+        }
+        catch (error) {
+            this.logger.error('failed to refresh Codex visible context projection; keeping prompt delivery', {
+                channelId,
+                cwd: projectedDirectoryPath,
+                error: summarizeError(error),
+            });
+            return undefined;
+        }
+    }
+    rewritePromptContextPaths(prompt, sourceContext, targetContext) {
+        if (!sourceContext) {
+            return prompt;
+        }
+        let rewritten = prompt;
+        const replacements = [
+            [sourceContext.channelContextPayloadPath, targetContext?.channelContextPayloadPath],
+            [sourceContext.gatewayAuthPath, targetContext?.gatewayAuthPath],
+        ];
+        for (const [sourcePath, targetPath] of replacements) {
+            if (!sourcePath || sourcePath === targetPath) {
+                continue;
+            }
+            rewritten = rewritten.split(sourcePath).join(targetPath ?? PROJECTION_UNAVAILABLE_PLACEHOLDER);
+        }
+        return rewritten;
+    }
+    async runTurn(session, prompt, options) {
+        const promptPromise = this.raceWithFatal(session.prompt(prompt));
+        const promptFailure = new Promise((_, reject) => {
+            void promptPromise.catch((error) => reject(markSessionTainted(error)));
+        });
+        const collector = new CodexProgressCollector(options?.onProgress);
+        for (;;) {
+            let update;
+            try {
+                update = await this.raceWithFatal(Promise.race([session.nextUpdate(), promptFailure]));
+            }
+            catch (error) {
+                if (this.fatalError && error === this.fatalError) {
+                    throw error;
+                }
+                throw markSessionTainted(error);
+            }
+            if (update.kind === 'stop') {
+                let response;
+                try {
+                    response = await promptPromise;
+                }
+                catch (error) {
+                    throw markSessionTainted(error);
+                }
+                if (response.stopReason !== 'end_turn') {
+                    throw new Error(`Codex ACP turn stopped with stopReason "${response.stopReason}"`);
+                }
+                const output = collector.getFinalText();
+                if (!output) {
+                    throw new Error('Codex ACP returned empty output');
+                }
+                return output;
+            }
+            collector.consume(update);
+        }
+    }
+    async raceWithFatal(promise) {
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        return Promise.race([promise, this.fatalPromise]);
+    }
+    invalidateSession(channelId, state, session) {
+        this.clearIdleTimer(state);
+        if (state.session === session) {
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionAdditionalDirectories = undefined;
+            state.sessionVisibilityKey = undefined;
+        }
+        this.logger?.debug('discarding tainted Codex ACP session', { channelId });
+        this.closeSession(session);
+        if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
+            void this.clearPersistedSessionBestEffort(channelId);
+        }
+    }
+    rejectQueuedTurnsAfterSessionTaint(state, error) {
+        if (state.queue.length === 0) {
+            return;
+        }
+        const rejection = new Error(QUEUED_TURN_DROPPED_MESSAGE, {
+            cause: normalizeError(error),
+        });
+        for (const turn of state.queue) {
+            turn.reject(rejection);
+        }
+        state.queue.length = 0;
+    }
+    failAll(error) {
+        if (this.fatalError) {
+            return;
+        }
+        this.fatalError = error;
+        this.rejectFatalPromise(error);
+        for (const [channelId, state] of this.channels.entries()) {
+            this.clearIdleTimer(state);
+            state.activeTurn?.reject(error);
+            for (const turn of state.queue) {
+                turn.reject(error);
+            }
+            state.queue.length = 0;
+            if (state.session) {
+                this.closeSession(state.session);
+            }
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionAdditionalDirectories = undefined;
+            state.sessionVisibilityKey = undefined;
+            state.sessionPromise = undefined;
+            state.activeTurn = undefined;
+            if (!state.processing) {
+                this.channels.delete(channelId);
+            }
+        }
+        this.channels.clear();
+        this.shutdownPromise = this.shutdownBackend(error);
+    }
+    closeSession(session) {
+        if (this.closingSessions.has(session)) {
+            return;
+        }
+        this.closingSessions.add(session);
+        const agent = this.connection?.agent;
+        const closeMethod = this.runtime.methods.agent.session?.close;
+        const closePromise = typeof agent?.closeSession === 'function'
+            ? agent.closeSession({ sessionId: session.sessionId })
+            : closeMethod
+                ? this.connection?.agent.request(closeMethod, { sessionId: session.sessionId })
+                : undefined;
+        session.dispose();
+        if (!closePromise) {
+            return;
+        }
+        let trackedClosePromise;
+        trackedClosePromise = Promise.resolve(closePromise)
+            .then(() => undefined)
+            .catch(() => { })
+            .finally(() => {
+            this.pendingSessionCloses.delete(trackedClosePromise);
+        });
+        this.pendingSessionCloses.add(trackedClosePromise);
+    }
+    clearIdleTimer(state) {
+        state.idleTimerGeneration += 1;
+        if (!state.idleTimer) {
+            return;
+        }
+        clearTimeout(state.idleTimer);
+        state.idleTimer = undefined;
+    }
+    reconcileIdleChannelState(channelId, state) {
+        if (this.channels.get(channelId) !== state) {
+            return;
+        }
+        if (this.disposing || this.fatalError || this.backendClosed) {
+            this.clearIdleTimer(state);
+            return;
+        }
+        if (state.activeTurn || state.queue.length > 0 || state.sessionPromise || state.processing) {
+            this.clearIdleTimer(state);
+            return;
+        }
+        if (!state.session) {
+            this.clearIdleTimer(state);
+            this.channels.delete(channelId);
+            return;
+        }
+        if (state.sessionPersistence === 'ephemeral') {
+            this.clearIdleTimer(state);
+            const session = state.session;
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionAdditionalDirectories = undefined;
+            state.sessionVisibilityKey = undefined;
+            this.closeSession(session);
+            this.channels.delete(channelId);
+            return;
+        }
+        this.clearIdleTimer(state);
+        const generation = state.idleTimerGeneration;
+        state.idleTimer = setTimeout(() => {
+            this.evictIdleChannel(channelId, state, generation);
+        }, this.runtime.idleSessionTtlMs);
+    }
+    async ensureSessionStoreLoaded() {
+        if (!this.sessionStore) {
+            return;
+        }
+        const agentId = this.resolveSessionStoreAgentId()?.trim();
+        if (!agentId) {
+            return;
+        }
+        if (this.loadedSessionStoreAgentId === agentId) {
+            return;
+        }
+        if (!this.sessionStoreLoadPromise) {
+            this.sessionStoreLoadPromise = (async () => {
+                const loaded = await this.sessionStore.load(agentId);
+                this.persistedSessions.clear();
+                for (const [channelId, sessionValue] of Object.entries(loaded)) {
+                    this.persistedSessions.set(channelId, parsePersistedSessionRecord(sessionValue));
+                }
+                this.loadedSessionStoreAgentId = agentId;
+            })().finally(() => {
+                this.sessionStoreLoadPromise = null;
+            });
+        }
+        await this.sessionStoreLoadPromise;
+    }
+    async readPersistedSessionId(channelId, visibilityKey, cwd) {
+        await this.ensureSessionStoreLoaded();
+        const record = this.persistedSessions.get(channelId);
+        if (!record) {
+            return undefined;
+        }
+        if (record.visibilityKey !== visibilityKey
+            || !record.cwd
+            || record.cwd !== cwd) {
+            await this.clearPersistedSessionBestEffort(channelId);
+            return undefined;
+        }
+        return record.sessionId;
+    }
+    async persistSession(channelId, sessionId, visibilityKey, cwd) {
+        await this.ensureSessionStoreLoaded();
+        this.persistedSessions.set(channelId, { sessionId, visibilityKey, cwd });
+        await this.flushSessionStore();
+    }
+    async persistSessionBestEffort(channelId, sessionId, visibilityKey, cwd) {
+        await this.trackSessionStoreOperation((async () => {
+            try {
+                await this.persistSession(channelId, sessionId, visibilityKey, cwd);
+            }
+            catch (error) {
+                this.logger.error('failed to persist Codex session map; keeping reply delivery', {
+                    agentId: this.loadedSessionStoreAgentId,
+                    channelId,
+                    sessionId,
+                    error: summarizeError(error),
+                });
+            }
+        })());
+    }
+    async clearPersistedSession(channelId) {
+        await this.ensureSessionStoreLoaded();
+        if (!this.persistedSessions.delete(channelId)) {
+            return;
+        }
+        await this.flushSessionStore();
+    }
+    async clearPersistedSessionBestEffort(channelId) {
+        await this.trackSessionStoreOperation((async () => {
+            try {
+                await this.clearPersistedSession(channelId);
+            }
+            catch (error) {
+                this.logger.error('failed to clear Codex session map; retrying in-memory only', {
+                    agentId: this.loadedSessionStoreAgentId,
+                    channelId,
+                    error: summarizeError(error),
+                });
+            }
+        })());
+    }
+    async flushSessionStore() {
+        if (!this.sessionStore || !this.loadedSessionStoreAgentId) {
+            return;
+        }
+        const agentId = this.loadedSessionStoreAgentId;
+        const snapshot = Object.fromEntries([...this.persistedSessions.entries()].map(([channelId, record]) => [
+            channelId,
+            serializePersistedSessionRecord(record),
+        ]));
+        const write = this.sessionStoreWriteQueue.then(() => this.sessionStore.save(agentId, snapshot));
+        this.sessionStoreWriteQueue = write.catch(() => { });
+        await write;
+    }
+    async trackSessionStoreOperation(operation) {
+        const tracked = operation.finally(() => {
+            this.pendingSessionStoreOperations.delete(tracked);
+        });
+        this.pendingSessionStoreOperations.add(tracked);
+        return tracked;
+    }
+    evictIdleChannel(channelId, state, generation) {
+        if (this.disposing || this.fatalError || this.backendClosed) {
+            return;
+        }
+        if (this.channels.get(channelId) !== state || state.idleTimerGeneration !== generation) {
+            return;
+        }
+        state.idleTimer = undefined;
+        if (state.activeTurn || state.queue.length > 0 || state.sessionPromise || state.processing) {
+            return;
+        }
+        const session = state.session;
+        state.session = undefined;
+        state.sessionCwd = undefined;
+        state.sessionAdditionalDirectories = undefined;
+        state.sessionVisibilityKey = undefined;
+        if (session) {
+            this.logger?.debug('evicting idle Codex ACP session', { channelId });
+            this.closeSession(session);
+        }
+        this.channels.delete(channelId);
+    }
+    async shutdownBackend(error) {
+        if (this.backendClosed) {
+            return;
+        }
+        this.backendClosed = true;
+        const connection = this.connection;
+        const child = this.child;
+        await this.waitForPendingSessionStarts();
+        await this.waitForPendingSessionCloses();
+        connection?.close(error);
+        this.connection = undefined;
+        if (!child) {
+            this.child = undefined;
+            return;
+        }
+        const childExitPromise = this.childExitPromise ?? Promise.resolve();
+        this.logger?.debug('sending SIGTERM to Codex ACP process');
+        child.kill('SIGTERM');
+        const exitedAfterTerm = await this.waitForChildExit(childExitPromise, this.runtime.shutdownGracePeriodMs);
+        if (exitedAfterTerm) {
+            this.logger?.debug('Codex ACP process exited after SIGTERM');
+            this.child = undefined;
+            return;
+        }
+        this.logger?.debug('sending SIGKILL to Codex ACP process after SIGTERM grace timeout');
+        child.kill('SIGKILL');
+        await this.waitForChildExit(childExitPromise, this.runtime.shutdownForceKillWaitMs);
+        this.child = undefined;
+    }
+    async waitForPendingSessionStarts() {
+        if (this.pendingSessionStarts.size === 0) {
+            return;
+        }
+        await Promise.race([
+            Promise.allSettled([...this.pendingSessionStarts]).then(() => undefined),
+            new Promise((resolveDelay) => {
+                setTimeout(resolveDelay, this.runtime.shutdownGracePeriodMs);
+            }),
+        ]);
+    }
+    async waitForPendingSessionCloses() {
+        if (this.pendingSessionCloses.size === 0) {
+            return;
+        }
+        await Promise.race([
+            Promise.allSettled([...this.pendingSessionCloses]).then(() => undefined),
+            new Promise((resolveDelay) => {
+                setTimeout(resolveDelay, this.runtime.shutdownGracePeriodMs);
+            }),
+        ]);
+    }
+    async waitForChildExit(childExitPromise, timeoutMs) {
+        if (timeoutMs <= 0) {
+            return false;
+        }
+        return Promise.race([
+            childExitPromise.then(() => true),
+            new Promise((resolveDelay) => {
+                setTimeout(() => resolveDelay(false), timeoutMs);
+            }),
+        ]);
+    }
+}