@meistrari/agent-core 0.0.0 → 0.1.0

package/src/agents/codex/codex-provider.ts

@@ -0,0 +1,1050 @@
+import type { AgentReasoningEffort, AgentToolDefinition, CodexModelId } from '../../protocol'
+import type { AgentOperationOptions } from '../agent-operation'
+import type { AgentProvider, AgentSessionOpenInput, AgentSessionResumeInput } from '../agent-provider'
+import type { AgentTool } from '../agent-tool'
+import type { InstructionComposer } from '../instructions'
+import type { CodexAuthentication, CodexAuthProvider, CodexAuthRefreshInput, CodexAuthTokens } from './codex-auth'
+import type { CodexEventMapperState, CodexNotification } from './codex-event-mapper'
+import type { CodexJsonRpcMessage, CodexServerRequest } from './codex-json-rpc-client'
+import type { ClientRequestResponsesByMethod, CodexChatGPTAuthTokensRefreshParams } from './codex-protocol'
+import { randomUUID } from 'node:crypto'
+import { lstat, open, readFile, realpath, rename, unlink } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import { codexModelIdSchema } from '../../protocol'
+import { serializeAgentError } from '../agent-error-serializer'
+import { AgentNotAcceptedError, AgentProviderMetadataError, AgentProviderProtocolError, AgentProviderRuntimeError } from '../agent-runtime-error'
+import { sessionConfiguredEvent } from '../agent-session-events'
+import { selectAgentTools, toolByName } from '../agent-tool'
+import { emptyInstructionComposer } from '../instructions'
+import { UserInputRequestStore, userInputRequestStoreRootFromTranscriptPath } from '../user-input-request'
+import { cacheCodexThreadMetadata, codexNotificationFromMessage, createCodexEventMapperState, mapCodexNotification } from './codex-event-mapper'
+import { CodexJsonRpcClient, isCodexServerRequest } from './codex-json-rpc-client'
+import { CodexRun } from './codex-run'
+import { catalogRepositorySkillRoots, stableRepositoryRoots, workspaceSkillRoots } from './codex-skill-roots'
+import { runCodexDynamicTool, toCodexDynamicTools } from './codex-tool-mapper'
+
+export interface CodexStartupStageFact {
+    event: 'sandbox.startup-stage'
+    stage: 'codex-initialize' | 'auth-acquisition-login' | 'thread-start' | 'thread-resume'
+    outcome: 'success' | 'failure'
+    duration: number
+    sessionId: string
+}
+
+export interface CodexProviderConfig {
+    auth: CodexAuthProvider | CodexAuthentication
+    tools?: readonly AgentTool[]
+    executable?: string
+    environment?: Record<string, string | undefined>
+    onStartupStage?: (fact: CodexStartupStageFact) => void
+    instructions?: InstructionComposer
+}
+
+interface CodexRunHolder {
+    toolsByName: Map<string, AgentTool>
+    run?: CodexRun
+    authTokens?: CodexAuthTokens
+    startupFailure?: Error
+}
+type CodexAuthMaterial
+    = | { kind: 'chatgpt', tokens: CodexAuthTokens }
+        | { kind: 'api-key', apiKey: string }
+interface CodexConnection {
+    client: CodexJsonRpcClient
+    abortController: AbortController
+    state: CodexEventMapperState
+}
+interface StartupTaskResult<Source extends 'connection' | 'auth', Value> {
+    source: Source
+    result: PromiseSettledResult<Value>
+}
+type CodexThreadBootstrapResult
+    = | ClientRequestResponsesByMethod['thread/start']
+        | ClientRequestResponsesByMethod['thread/resume']
+interface CodexSessionBootstrapConfig {
+    sessionId: string
+    cwd: string
+    workspaceRepositoryRoots: readonly string[]
+    model?: string
+    reasoningEffort?: AgentReasoningEffort
+    tools?: AgentToolDefinition[]
+}
+
+export class CodexProvider implements AgentProvider<'codex'> {
+    readonly id = 'codex' as const
+    private readonly tools: readonly AgentTool[]
+    private readonly executable: string
+    private readonly environment: Record<string, string | undefined>
+    private readonly auth: CodexAuthentication
+    private readonly onStartupStage: ((fact: CodexStartupStageFact) => void) | undefined
+    private readonly instructions: InstructionComposer
+
+    private constructor(config: CodexProviderConfig) {
+        this.auth = normalizeCodexAuthentication(config.auth)
+        this.tools = config.tools ?? []
+        this.executable = config.executable ?? 'codex'
+        this.environment = config.environment ?? {}
+        this.onStartupStage = config.onStartupStage
+        this.instructions = config.instructions ?? emptyInstructionComposer
+    }
+
+    static create(config: CodexProviderConfig): CodexProvider {
+        return new CodexProvider(config)
+    }
+
+    async openSession(input: AgentSessionOpenInput<'codex'>, options: AgentOperationOptions = {}): Promise<CodexRun> {
+        return await this.startSession({
+            config: input,
+            options,
+            stage: 'thread-start',
+            requestThread: async ({ client, tools }): Promise<CodexThreadBootstrapResult> => await client.request('thread/start', {
+                cwd: input.cwd,
+                model: input.model,
+                modelProvider: this.auth.kind === 'api-key' ? this.auth.modelProvider : undefined,
+                ephemeral: false,
+                approvalPolicy: 'never',
+                sandbox: 'danger-full-access',
+                developerInstructions: this.instructions({ provider: 'codex', tools }),
+                dynamicTools: toCodexDynamicTools(tools),
+            }),
+        })
+    }
+
+    async resumeSession(input: AgentSessionResumeInput<'codex'>, options: AgentOperationOptions = {}): Promise<CodexRun> {
+        return await this.startSession({
+            config: input,
+            options,
+            stage: 'thread-resume',
+            requestThread: async ({ client, tools }): Promise<CodexThreadBootstrapResult> => await client.request('thread/resume', {
+                threadId: input.providerSessionId,
+                cwd: input.cwd,
+                approvalPolicy: 'never',
+                sandbox: 'danger-full-access',
+                model: input.model,
+                modelProvider: this.auth.kind === 'api-key' ? this.auth.modelProvider : undefined,
+                developerInstructions: this.instructions({ provider: 'codex', tools }),
+            }),
+            validateThread: (result) => {
+                // Resume must rebind the same provider session; adopting a different thread would silently
+                // divorce the durable binding from the transcript the user expects.
+                if (result.thread?.id && result.thread.id !== input.providerSessionId) {
+                    throw new AgentProviderProtocolError({
+                        message: 'Codex thread/resume returned a different thread id than requested.',
+                        details: { expected: input.providerSessionId, actual: result.thread.id },
+                    })
+                }
+            },
+        })
+    }
+
+    private async startSession(input: {
+        config: CodexSessionBootstrapConfig
+        options: AgentOperationOptions
+        stage: 'thread-start' | 'thread-resume'
+        requestThread: (context: {
+            client: CodexJsonRpcClient
+            tools: readonly AgentTool[]
+        }) => Promise<CodexThreadBootstrapResult>
+        validateThread?: (result: CodexThreadBootstrapResult) => void
+    }): Promise<CodexRun> {
+        input.options.signal?.throwIfAborted()
+        const tools = selectAgentTools(this.tools, input.config.tools)
+        const holder: CodexRunHolder = { toolsByName: toolByName(tools) }
+        const authStartedAt = performance.now()
+        let authObserved = false
+        const instructionBridge = this.prepareSessionBootstrap({
+            cwd: input.config.cwd,
+            workspaceRepositoryRoots: input.config.workspaceRepositoryRoots,
+            startupSignal: input.options.signal,
+        })
+        void instructionBridge.catch(() => undefined)
+        const { client, abortController, state, authMaterial } = await this.openConnectionWithAuth({
+            sessionId: input.config.sessionId,
+            cwd: input.config.cwd,
+            options: input.options,
+            holder,
+        }).catch(async (error: unknown) => {
+            await instructionBridge.catch(() => undefined)
+            this.observeStartupStage({
+                stage: 'auth-acquisition-login',
+                outcome: 'failure',
+                startedAt: authStartedAt,
+                sessionId: input.config.sessionId,
+            })
+            authObserved = true
+            throw error
+        })
+        const removeBootstrapAbort = this.bindBootstrapAbort({
+            signal: input.options.signal,
+            client,
+            abortController,
+        })
+        try {
+            input.options.signal?.throwIfAborted()
+            await this.login({ client, holder, authMaterial })
+            this.observeStartupStage({
+                stage: 'auth-acquisition-login',
+                outcome: 'success',
+                startedAt: authStartedAt,
+                sessionId: input.config.sessionId,
+            })
+            authObserved = true
+            const instructionBridgePath = await instructionBridge
+            const result = await this.runStartupStage({
+                stage: input.stage,
+                sessionId: input.config.sessionId,
+                operation: async () => await input.requestThread({ client, tools }),
+            })
+            input.options.signal?.throwIfAborted()
+            input.validateThread?.(result)
+
+            return await this.bootstrapRun({
+                config: input.config,
+                result,
+                client,
+                abortController,
+                state,
+                holder,
+                instructionBridgePath,
+                startupSignal: input.options.signal,
+            })
+        }
+        catch (error) {
+            if (!authObserved) {
+                this.observeStartupStage({
+                    stage: 'auth-acquisition-login',
+                    outcome: 'failure',
+                    startedAt: authStartedAt,
+                    sessionId: input.config.sessionId,
+                })
+            }
+            await stopCodexClientBestEffort(client)
+            input.options.signal?.throwIfAborted()
+            throw holder.startupFailure ?? error
+        }
+        finally {
+            removeBootstrapAbort()
+        }
+    }
+
+    private async prepareSessionBootstrap(input: {
+        cwd: string
+        workspaceRepositoryRoots: readonly string[]
+        startupSignal?: AbortSignal
+    }): Promise<string> {
+        input.startupSignal?.throwIfAborted()
+        const instructionBridgePath = await reconcileSelectedRepositoryInstructionBridge({
+            cwd: input.cwd,
+            repositoryRoots: input.workspaceRepositoryRoots,
+        })
+        input.startupSignal?.throwIfAborted()
+        return instructionBridgePath
+    }
+
+    private async attestSessionBootstrap(input: {
+        holder: CodexRunHolder
+        instructionBridgePath: string
+        instructionSources?: readonly string[]
+        workspaceRepositoryRoots: readonly string[]
+        startupSignal?: AbortSignal
+    }): Promise<void> {
+        throwIfStartupFailed(input.holder)
+        await requireSelectedRepositoryInstructionSource({
+            instructionBridgePath: input.instructionBridgePath,
+            instructionSources: input.instructionSources,
+            repositoryRoots: input.workspaceRepositoryRoots,
+        })
+        input.startupSignal?.throwIfAborted()
+    }
+
+    private async openConnectionWithAuth(input: {
+        sessionId: string
+        cwd: string
+        options: AgentOperationOptions
+        holder: CodexRunHolder
+    }): Promise<CodexConnection & { authMaterial: CodexAuthMaterial }> {
+        const authAbortController = new AbortController()
+        const connectionAbortController = new AbortController()
+        const abortStartup = () => {
+            authAbortController.abort(input.options.signal?.reason)
+            connectionAbortController.abort(input.options.signal?.reason)
+        }
+        if (input.options.signal?.aborted)
+            abortStartup()
+        else
+            input.options.signal?.addEventListener('abort', abortStartup, { once: true })
+
+        const connectionTask = this.openConnection({
+            ...input,
+            startupSignal: connectionAbortController.signal,
+        }).then(
+            (value): StartupTaskResult<'connection', CodexConnection> => ({ source: 'connection', result: { status: 'fulfilled', value } }),
+            (reason): StartupTaskResult<'connection', CodexConnection> => ({ source: 'connection', result: { status: 'rejected', reason } }),
+        )
+        const authTask = this.getAuthMaterial(authAbortController.signal).then(
+            (value): StartupTaskResult<'auth', CodexAuthMaterial> => ({ source: 'auth', result: { status: 'fulfilled', value } }),
+            (reason): StartupTaskResult<'auth', CodexAuthMaterial> => ({ source: 'auth', result: { status: 'rejected', reason } }),
+        )
+
+        try {
+            const first = await Promise.race([connectionTask, authTask])
+            if (first.source === 'connection') {
+                if (first.result.status === 'rejected') {
+                    authAbortController.abort(first.result.reason)
+                    throw first.result.reason
+                }
+                const auth = await authTask
+                if (auth.result.status === 'rejected') {
+                    await stopCodexClientBestEffort(first.result.value.client)
+                    throw auth.result.reason
+                }
+                return { ...first.result.value, authMaterial: auth.result.value }
+            }
+
+            if (first.result.status === 'fulfilled') {
+                const connection = await connectionTask
+                if (connection.result.status === 'rejected')
+                    throw connection.result.reason
+                return { ...connection.result.value, authMaterial: first.result.value }
+            }
+
+            connectionAbortController.abort(first.result.reason)
+            const interruptedConnection = await connectionTask
+            if (interruptedConnection.result.status === 'fulfilled')
+                await stopCodexClientBestEffort(interruptedConnection.result.value.client)
+            throw first.result.reason
+        }
+        finally {
+            input.options.signal?.removeEventListener('abort', abortStartup)
+        }
+    }
+
+    private async getAuthMaterial(signal: AbortSignal): Promise<CodexAuthMaterial> {
+        if (this.auth.kind === 'api-key') {
+            const credentials = await this.auth.provider.getApiKey({ signal })
+            return { kind: 'api-key', apiKey: credentials.apiKey }
+        }
+        const tokens = await this.auth.provider.getAuthTokens({ signal })
+        return { kind: 'chatgpt', tokens }
+    }
+
+    private async openConnection(input: {
+        sessionId: string
+        cwd: string
+        options: AgentOperationOptions
+        holder: CodexRunHolder
+        startupSignal: AbortSignal
+    }): Promise<CodexConnection> {
+        const { cwd, holder, startupSignal } = input
+        const state = createCodexEventMapperState()
+        const abortController = new AbortController()
+        const initializeStartedAt = performance.now()
+        let initializeObserved = false
+        let messageQueue = Promise.resolve()
+        let client: CodexJsonRpcClient
+
+        try {
+            client = new CodexJsonRpcClient(this.executable, {
+                cwd,
+                environment: this.environment,
+                onMessage: (message) => {
+                    messageQueue = this.enqueueMessageHandling(messageQueue, { message, holder, state, client, signal: abortController.signal })
+                },
+                onInvalidLine: (line, error) => holder.run?.pushEvent({ type: 'error', payload: { message: `Invalid Codex JSON-RPC line: ${line.slice(0, 200)}`, fatal: false, source: 'transport', error: serializeAgentError(error) } }),
+                onStderr: line => holder.run?.pushEvent({ type: 'error', payload: { message: line, fatal: false, source: 'provider' } }),
+            })
+        }
+        catch (error) {
+            this.observeStartupStage({
+                stage: 'codex-initialize',
+                outcome: 'failure',
+                startedAt: initializeStartedAt,
+                sessionId: input.sessionId,
+            })
+            throw error
+        }
+        const stopForStartupAbort = () => {
+            abortController.abort(startupSignal.reason)
+            void stopCodexClientBestEffort(client)
+        }
+        if (startupSignal.aborted)
+            stopForStartupAbort()
+        else
+            startupSignal.addEventListener('abort', stopForStartupAbort, { once: true })
+
+        try {
+            await client.request('initialize', {
+                clientInfo: { name: 'coding-agent', title: 'Coding Agent', version: '0.1.0' },
+                capabilities: { experimentalApi: true, requestAttestation: false },
+            })
+            client.notify('initialized', undefined)
+            await yieldToPendingServerRequests()
+            await messageQueue
+            throwIfStartupFailed(holder)
+            this.observeStartupStage({
+                stage: 'codex-initialize',
+                outcome: 'success',
+                startedAt: initializeStartedAt,
+                sessionId: input.sessionId,
+            })
+            initializeObserved = true
+
+            return { client, abortController, state }
+        }
+        catch (error) {
+            if (!initializeObserved) {
+                this.observeStartupStage({
+                    stage: 'codex-initialize',
+                    outcome: 'failure',
+                    startedAt: initializeStartedAt,
+                    sessionId: input.sessionId,
+                })
+            }
+            await stopCodexClientBestEffort(client)
+            startupSignal.throwIfAborted()
+            throw error
+        }
+        finally {
+            startupSignal.removeEventListener('abort', stopForStartupAbort)
+        }
+    }
+
+    private async runStartupStage<T>(input: {
+        stage: CodexStartupStageFact['stage']
+        sessionId: string
+        operation: () => Promise<T>
+    }): Promise<T> {
+        const startedAt = performance.now()
+        try {
+            const result = await input.operation()
+            this.observeStartupStage({ ...input, outcome: 'success', startedAt })
+            return result
+        }
+        catch (error) {
+            this.observeStartupStage({ ...input, outcome: 'failure', startedAt })
+            throw error
+        }
+    }
+
+    private observeStartupStage(input: {
+        stage: CodexStartupStageFact['stage']
+        outcome: CodexStartupStageFact['outcome']
+        startedAt: number
+        sessionId: string
+    }): void {
+        try {
+            this.onStartupStage?.({
+                event: 'sandbox.startup-stage',
+                stage: input.stage,
+                outcome: input.outcome,
+                duration: Math.max(0, Math.round(performance.now() - input.startedAt)),
+                sessionId: input.sessionId,
+            })
+        }
+        catch {
+            // Startup telemetry is best effort and cannot alter provider behavior.
+        }
+    }
+
+    private bindBootstrapAbort(input: {
+        signal?: AbortSignal
+        client: CodexJsonRpcClient
+        abortController: AbortController
+    }): () => void {
+        const abortBootstrap = () => {
+            input.abortController.abort(input.signal?.reason)
+            void stopCodexClientBestEffort(input.client)
+        }
+        if (input.signal?.aborted)
+            abortBootstrap()
+        else
+            input.signal?.addEventListener('abort', abortBootstrap, { once: true })
+
+        return () => input.signal?.removeEventListener('abort', abortBootstrap)
+    }
+
+    private async bootstrapRun(input: {
+        config: CodexSessionBootstrapConfig
+        result: CodexThreadBootstrapResult
+        client: CodexJsonRpcClient
+        abortController: AbortController
+        state: CodexEventMapperState
+        holder: CodexRunHolder
+        instructionBridgePath: string
+        startupSignal?: AbortSignal
+    }): Promise<CodexRun> {
+        const { config, result, client, abortController, state, holder, instructionBridgePath, startupSignal } = input
+        const thread = result.thread
+        const effectiveModel = result.model ?? config.model
+        if (!thread?.id || !thread.path || !effectiveModel) {
+            throw new AgentProviderMetadataError({
+                message: 'Codex did not return required persistent thread metadata.',
+                details: { provider: 'codex' },
+            })
+        }
+
+        const metadata = {
+            provider: 'codex' as const,
+            sessionId: config.sessionId,
+            providerSessionId: thread.id,
+            cwd: thread.cwd ?? config.cwd,
+            model: firstCodexModelId(effectiveModel),
+            transcriptPath: thread.path,
+        }
+        throwIfStartupFailed(holder)
+        const [, userInputRequests] = await Promise.all([
+            this.attestSessionBootstrap({
+                holder,
+                instructionBridgePath,
+                instructionSources: result.instructionSources,
+                workspaceRepositoryRoots: config.workspaceRepositoryRoots,
+                startupSignal,
+            }),
+            UserInputRequestStore.open({
+                sessionId: metadata.sessionId,
+                rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+            }),
+        ])
+        startupSignal?.throwIfAborted()
+        const run = new CodexRun({
+            metadata,
+            reasoningEffort: config.reasoningEffort,
+            client,
+            requestedCwd: config.cwd,
+            workspaceRepositoryRoots: config.workspaceRepositoryRoots,
+            registeredSkillRoots: workspaceSkillRoots(config.workspaceRepositoryRoots),
+            repositorySkillRoots: catalogRepositorySkillRoots({
+                repositoryRoots: config.workspaceRepositoryRoots,
+                requestedCwd: config.cwd,
+                runtimeCwd: metadata.cwd,
+            }),
+            reconcileInstructionBridge: async (repositoryRoots) => {
+                await reconcileSelectedRepositoryInstructionBridge({ cwd: config.cwd, repositoryRoots })
+            },
+            userInputRequests,
+            eventMapperState: state,
+            abortSignal: abortController.signal,
+            onStop: () => abortController.abort(),
+        })
+        holder.run = run
+
+        run.pushEvent({ type: 'session.started', payload: run.metadata })
+        run.pushEvent(sessionConfiguredEvent({ model: effectiveModel, cwd: run.metadata.cwd, reasoningEffort: config.reasoningEffort, tools: config.tools, environment: this.environment }))
+        run.pushEvent({ type: 'session.state.changed', payload: { state: 'ready' } })
+        return run
+    }
+
+    private async enqueueMessageHandling(queue: Promise<void>, input: {
+        message: CodexJsonRpcMessage
+        holder: CodexRunHolder
+        state: CodexEventMapperState
+        client: CodexJsonRpcClient
+        signal: AbortSignal
+    }): Promise<void> {
+        return await queue
+            .then(async () => await this.handleMessage(input))
+            .catch((error: unknown) => {
+                input.holder.run?.pushEvent({ type: 'error', payload: { message: 'Codex app-server message handling failed.', fatal: false, source: 'runtime', error: serializeAgentError(error) } })
+            })
+    }
+
+    private async handleMessage(input: {
+        message: CodexJsonRpcMessage
+        holder: CodexRunHolder
+        state: CodexEventMapperState
+        client: CodexJsonRpcClient
+        signal: AbortSignal
+    }): Promise<void> {
+        const { message, holder, state, client, signal } = input
+        const run = holder.run
+        if (isCodexServerRequest(message)) {
+            const handling = this.handleServerRequest(message, holder, client, signal)
+            // Startup requests must flush their response before start/resume surfaces the failure.
+            if (!run)
+                await handling
+            else
+                void handling
+            return
+        }
+        if (!run)
+            return
+        const notification = codexNotificationFromMessage(message)
+        if (!notification)
+            return
+        if (notification.method === 'skills/changed') {
+            run.requestSkillsRefresh()
+            return
+        }
+        // Child-thread notifications must reach the mapper, which buffers them until spawn correlation.
+        await this.cacheSpawnedSubagentThreadMetadata({ notification, state, client })
+        const drafts = mapCodexNotification(notification, state)
+        for (const draft of drafts) {
+            run.pushEvent(draft)
+        }
+        if (notification.method === 'turn/started' && notification.params.threadId === run.metadata.providerSessionId) {
+            run.setActiveTurn(notification.params.turn.id)
+            run.pushEvent({ type: 'session.state.changed', payload: { state: 'running' } })
+        }
+        if (notification.method === 'turn/completed' && notification.params.threadId === run.metadata.providerSessionId) {
+            run.clearActiveTurn()
+            run.pushEvent({ type: 'session.state.changed', payload: { state: 'idle' } })
+        }
+    }
+
+    private async cacheSpawnedSubagentThreadMetadata(input: { notification: CodexNotification, state: CodexEventMapperState, client: CodexJsonRpcClient }): Promise<void> {
+        const threadId = spawnedSubagentThreadId(input.notification)
+        if (!threadId)
+            return
+
+        let thread: Parameters<typeof cacheCodexThreadMetadata>[0]
+        try {
+            const result = await input.client.request('thread/read', { threadId, includeTurns: false })
+            thread = result.thread
+        }
+        catch {
+            // Metadata improves display labels only; lifecycle mapping can proceed without it.
+            return
+        }
+        cacheCodexThreadMetadata(thread, input.state)
+    }
+
+    private async login(input: {
+        client: CodexJsonRpcClient
+        holder: CodexRunHolder
+        authMaterial: CodexAuthMaterial
+    }): Promise<void> {
+        const { client, holder, authMaterial } = input
+        throwIfStartupFailed(holder)
+        if (authMaterial.kind === 'api-key') {
+            await client.request('account/login/start', { type: 'apiKey', apiKey: authMaterial.apiKey })
+            throwIfStartupFailed(holder)
+            return
+        }
+        await client.request('account/login/start', toCodexLoginParams(authMaterial.tokens))
+        throwIfStartupFailed(holder)
+        holder.authTokens = authMaterial.tokens
+    }
+
+    private async handleAuthRefreshRequest(
+        request: Extract<CodexServerRequest, { method: 'account/chatgptAuthTokens/refresh' }>,
+        holder: CodexRunHolder,
+        client: CodexJsonRpcClient,
+    ): Promise<void> {
+        const current = holder.authTokens
+        if (!current) {
+            const error = new AgentProviderProtocolError({
+                message: 'Codex requested ChatGPT auth refresh before external auth tokens were available.',
+                details: { method: request.method },
+            })
+            holder.startupFailure = error
+            await client.respondErrorAndFlush(request.id, { code: -32000, message: 'Codex auth tokens are not available for refresh.' })
+            await client.closeInputAndStop()
+            return
+        }
+        try {
+            if (this.auth.kind !== 'chatgpt')
+                throw new AgentProviderProtocolError({ message: 'Codex requested ChatGPT token refresh while using API-key authentication.' })
+            const refreshed = await this.auth.provider.refreshAuthTokens(toAuthRefreshInput(request.params, current))
+            holder.authTokens = refreshed
+            client.respond(request.id, toCodexRefreshResponse(refreshed))
+        }
+        catch (error) {
+            const serializedError = redactSerializedError(error, current.accessToken)
+            const run = holder.run
+            if (!run) {
+                holder.startupFailure = new AgentProviderProtocolError({
+                    message: 'Codex ChatGPT auth refresh failed during startup.',
+                    details: { method: request.method },
+                    cause: serializedError,
+                })
+                try {
+                    await client.respondErrorAndFlush(request.id, { code: -32001, message: 'Codex auth refresh failed.' })
+                }
+                finally {
+                    await client.closeInputAndStop()
+                }
+                return
+            }
+            try {
+                await client.respondErrorAndFlush(request.id, { code: -32001, message: 'Codex auth refresh failed.' })
+            }
+            finally {
+                await run.failActiveTurnAndEndRun({ reason: 'codex_auth_refresh_failed', error: serializedError })
+            }
+        }
+    }
+
+    private async handleServerRequest(
+        request: CodexServerRequest,
+        holder: CodexRunHolder,
+        client: CodexJsonRpcClient,
+        signal: AbortSignal,
+    ): Promise<void> {
+        const run = holder.run
+        if (request.method === 'account/chatgptAuthTokens/refresh') {
+            await this.handleAuthRefreshRequest(request, holder, client)
+            return
+        }
+        if (request.method !== 'item/tool/call') {
+            client.respond(request.id, {})
+            return
+        }
+        if (!run) {
+            client.respondError(request.id, { code: -32000, message: 'Codex run is not ready for server requests.' })
+            return
+        }
+
+        const toolParams = request.params
+        const runtimeTool = holder.toolsByName.get(toolParams.tool)
+        if (!runtimeTool) {
+            client.respond(request.id, { success: false, contentItems: [{ type: 'inputText', text: `Unknown tool: ${toolParams.tool}` }] })
+            return
+        }
+
+        const toolCallId = toolParams.callId ?? String(request.id)
+        try {
+            const result = await runCodexDynamicTool({
+                tool: runtimeTool,
+                params: toolParams,
+                context: {
+                    provider: 'codex',
+                    sessionId: run.metadata.sessionId,
+                    providerSessionId: run.metadata.providerSessionId,
+                    turnId: toolParams.turnId,
+                    cwd: run.metadata.cwd,
+                    toolCallId,
+                    signal,
+                    requestUserInput: async request => await run.requestUserInput({
+                        ...request,
+                        turnId: toolParams.turnId,
+                        toolCallId,
+                    }),
+                },
+            })
+            client.respond(request.id, result)
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            client.respond(request.id, { success: false, contentItems: [{ type: 'inputText', text: message }] })
+        }
+    }
+}
+
+function throwIfStartupFailed(holder: CodexRunHolder): void {
+    if (holder.startupFailure)
+        throw holder.startupFailure
+}
+
+const SELECTED_REPOSITORY_INSTRUCTION_BRIDGE_FILENAME = 'AGENTS.override.md'
+const SELECTED_REPOSITORY_INSTRUCTION_BRIDGE_SENTINEL = '<!-- coding-agent-managed-selected-repository-instructions -->'
+
+type InstructionBridgeOwnership = 'missing' | 'managed' | 'unowned'
+
+async function reconcileSelectedRepositoryInstructionBridge(input: { cwd: string, repositoryRoots: readonly string[] }): Promise<string> {
+    const instructionBridgePath = resolve(input.cwd, SELECTED_REPOSITORY_INSTRUCTION_BRIDGE_FILENAME)
+    let ownership: InstructionBridgeOwnership
+    try {
+        ownership = await readInstructionBridgeOwnership(instructionBridgePath)
+    }
+    catch (error) {
+        if (!(error instanceof AgentProviderRuntimeError))
+            throw error
+        throw repositoryInstructionsUnavailable({ recoveryKind: 'retry', cause: error })
+    }
+    const repositoryRoots = stableRepositoryRoots(input.repositoryRoots)
+
+    if (repositoryRoots.length === 0) {
+        if (ownership === 'managed') {
+            try {
+                await removeManagedInstructionBridge(instructionBridgePath)
+            }
+            catch (error) {
+                if (!(error instanceof AgentProviderRuntimeError))
+                    throw error
+                throw repositoryInstructionsUnavailable({ recoveryKind: 'retry', cause: error })
+            }
+        }
+        return instructionBridgePath
+    }
+
+    if (ownership === 'unowned') {
+        const cause = new AgentProviderRuntimeError({
+            message: 'Refusing to overwrite an AGENTS.override.md not owned by the Coding Agent runtime.',
+            details: { instructionBridgePath },
+            retryable: false,
+        })
+        throw repositoryInstructionsUnavailable({ recoveryKind: 'terminal', cause })
+    }
+
+    try {
+        await writeInstructionBridgeAtomically({
+            instructionBridgePath,
+            content: selectedRepositoryInstructionBridge(repositoryRoots),
+        })
+    }
+    catch (error) {
+        if (!(error instanceof AgentProviderRuntimeError))
+            throw error
+        throw repositoryInstructionsUnavailable({ recoveryKind: 'retry', cause: error })
+    }
+    return instructionBridgePath
+}
+
+async function readInstructionBridgeOwnership(instructionBridgePath: string): Promise<InstructionBridgeOwnership> {
+    let entry
+    try {
+        entry = await lstat(instructionBridgePath)
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return 'missing'
+        throw new AgentProviderRuntimeError({
+            message: 'Failed to inspect the selected-repository instruction bridge.',
+            details: { instructionBridgePath },
+            retryable: true,
+            cause: error,
+        })
+    }
+
+    if (!entry.isFile() || entry.isSymbolicLink())
+        return 'unowned'
+
+    let content: string
+    try {
+        content = await readFile(instructionBridgePath, 'utf8')
+    }
+    catch (error) {
+        throw new AgentProviderRuntimeError({
+            message: 'Failed to inspect the selected-repository instruction bridge.',
+            details: { instructionBridgePath },
+            retryable: true,
+            cause: error,
+        })
+    }
+
+    return firstLine(content) === SELECTED_REPOSITORY_INSTRUCTION_BRIDGE_SENTINEL ? 'managed' : 'unowned'
+}
+
+async function writeInstructionBridgeAtomically(input: { instructionBridgePath: string, content: string }): Promise<void> {
+    const tempPath = join(
+        dirname(input.instructionBridgePath),
+        `.${basename(input.instructionBridgePath)}.${process.pid}.${randomUUID()}.tmp`,
+    )
+    let tempFile: Awaited<ReturnType<typeof open>> | undefined
+    try {
+        tempFile = await open(tempPath, 'wx', 0o640)
+        await tempFile.chmod(0o640)
+        await tempFile.writeFile(input.content, 'utf8')
+        await tempFile.close()
+        tempFile = undefined
+        await rename(tempPath, input.instructionBridgePath)
+    }
+    catch (error) {
+        await tempFile?.close().catch(() => undefined)
+        await unlink(tempPath).catch(() => undefined)
+        throw new AgentProviderRuntimeError({
+            message: 'Failed to publish the selected-repository instruction bridge.',
+            details: { instructionBridgePath: input.instructionBridgePath },
+            retryable: true,
+            cause: error,
+        })
+    }
+}
+
+async function removeManagedInstructionBridge(instructionBridgePath: string): Promise<void> {
+    try {
+        await unlink(instructionBridgePath)
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return
+        throw new AgentProviderRuntimeError({
+            message: 'Failed to remove the stale selected-repository instruction bridge.',
+            details: { instructionBridgePath },
+            retryable: true,
+            cause: error,
+        })
+    }
+}
+
+async function requireSelectedRepositoryInstructionSource(input: {
+    instructionBridgePath: string
+    instructionSources?: readonly string[]
+    repositoryRoots: readonly string[]
+}): Promise<void> {
+    if (input.repositoryRoots.length === 0)
+        return
+
+    const instructionSources = input.instructionSources ?? []
+    let expectedInstructionSource: string
+    let attestedInstructionSources: string[]
+    try {
+        expectedInstructionSource = await realpath(input.instructionBridgePath)
+        attestedInstructionSources = await Promise.all(instructionSources.map(async source => await realpath(source)))
+    }
+    catch (error) {
+        if (!isFileSystemErrno(error))
+            throw error
+
+        const details = {
+            expectedInstructionSource: input.instructionBridgePath,
+            instructionSources,
+        }
+        if (isDeterministicRealpathFailure(error)) {
+            const cause = new AgentProviderProtocolError({
+                message: 'Failed to attest Codex selected-repository instruction sources.',
+                details,
+                cause: error,
+            })
+            throw repositoryInstructionsUnavailable({ recoveryKind: 'terminal', cause })
+        }
+
+        const cause = new AgentProviderRuntimeError({
+            message: 'Failed to resolve Codex selected-repository instruction sources.',
+            details,
+            retryable: true,
+            cause: error,
+        })
+        throw repositoryInstructionsUnavailable({ recoveryKind: 'retry', cause })
+    }
+
+    if (attestedInstructionSources.includes(expectedInstructionSource))
+        return
+
+    const cause = new AgentProviderProtocolError({
+        message: 'Codex did not load the selected-repository instruction bridge.',
+        details: {
+            expectedInstructionSource,
+            instructionSources: attestedInstructionSources,
+        },
+    })
+    throw repositoryInstructionsUnavailable({ recoveryKind: 'terminal', cause })
+}
+
+function repositoryInstructionsUnavailable(input: {
+    recoveryKind: 'retry' | 'terminal'
+    cause: AgentProviderRuntimeError
+}): AgentNotAcceptedError {
+    return new AgentNotAcceptedError({
+        message: 'Selected repository instructions are unavailable.',
+        recovery: { kind: input.recoveryKind, reason: 'repository_instructions_unavailable' },
+        cause: input.cause,
+    })
+}
+
+function selectedRepositoryInstructionBridge(repositoryRoots: readonly string[]): string {
+    return [
+        SELECTED_REPOSITORY_INSTRUCTION_BRIDGE_SENTINEL,
+        '# Selected repository instructions',
+        '',
+        'Selected repository roots:',
+        ...repositoryRoots.map(root => `- ${JSON.stringify(root)}`),
+        '',
+        'For each repository root, you must:',
+        '- Inspect `AGENTS.override.md` first; if it does not exist, inspect `AGENTS.md`.',
+        '- Follow every documentation file referenced by the applicable AGENTS file.',
+        '- Before editing nested files, re-check for more-local `AGENTS.override.md` or `AGENTS.md` files.',
+        '',
+        'Runtime and developer instructions take precedence over these repository instructions.',
+        'Repository instructions apply only within their own repository.',
+        'If selected repositories contain irreconcilable instructions, report the conflict instead of resolving it by repository input order.',
+        '',
+    ].join('\n')
+}
+
+function firstLine(content: string): string {
+    const lineEnd = content.indexOf('\n')
+    return lineEnd === -1 ? content : content.slice(0, lineEnd)
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+    return error instanceof Error && 'code' in error
+}
+
+function isFileSystemErrno(error: unknown): error is NodeJS.ErrnoException & { code: string, syscall: string } {
+    return isNodeError(error)
+        && typeof error.code === 'string'
+        && /^E[A-Z0-9]+$/.test(error.code)
+        && typeof error.syscall === 'string'
+}
+
+function isDeterministicRealpathFailure(error: NodeJS.ErrnoException): boolean {
+    return error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'ELOOP'
+}
+
+async function yieldToPendingServerRequests(): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, 0))
+}
+
+async function stopCodexClientBestEffort(client: CodexJsonRpcClient): Promise<void> {
+    await client.stop().catch(() => undefined)
+}
+
+function toCodexLoginParams(tokens: CodexAuthTokens): {
+    type: 'chatgptAuthTokens'
+    accessToken: string
+    chatgptAccountId: string
+    chatgptPlanType?: string | null
+} {
+    return {
+        type: 'chatgptAuthTokens',
+        accessToken: tokens.accessToken,
+        chatgptAccountId: tokens.chatgptAccountId,
+        chatgptPlanType: tokens.chatgptPlanType ?? null,
+    }
+}
+
+function normalizeCodexAuthentication(auth: CodexAuthProvider | CodexAuthentication): CodexAuthentication {
+    return 'kind' in auth ? auth : { kind: 'chatgpt', provider: auth }
+}
+
+function toAuthRefreshInput(params: CodexChatGPTAuthTokensRefreshParams, tokens: CodexAuthTokens): CodexAuthRefreshInput {
+    return {
+        reason: params.reason,
+        rejectedTokenGeneration: tokens.accessTokenGeneration,
+        rejectedTokenFingerprint: tokens.accessTokenFingerprint,
+    }
+}
+
+function toCodexRefreshResponse(tokens: CodexAuthTokens): { accessToken: string, chatgptAccountId: string, chatgptPlanType?: string | null } {
+    return {
+        accessToken: tokens.accessToken,
+        chatgptAccountId: tokens.chatgptAccountId,
+        chatgptPlanType: tokens.chatgptPlanType ?? null,
+    }
+}
+
+function redactSerializedError(error: unknown, accessToken: string): { message: string, code?: string, name?: string, stack?: string } {
+    return redactAgentError(serializeAgentError(error), accessToken)
+}
+
+function redactAgentError<T extends { message: string, stack?: string, cause?: T }>(error: T, secret: string): T {
+    const redacted = '<redacted>'
+    const replaceSecret = (value: string | undefined) => value?.split(secret).join(redacted)
+    return {
+        ...error,
+        message: replaceSecret(error.message) ?? error.message,
+        ...(error.stack === undefined ? {} : { stack: replaceSecret(error.stack) }),
+        ...(error.cause === undefined ? {} : { cause: redactAgentError(error.cause, secret) }),
+    }
+}
+
+function firstCodexModelId(...values: Array<string | null | undefined>): CodexModelId | undefined {
+    for (const value of values) {
+        const parsed = codexModelIdSchema.safeParse(value)
+        if (parsed.success)
+            return parsed.data
+    }
+    return undefined
+}
+
+function spawnedSubagentThreadId(notification: CodexNotification): string | undefined {
+    if (notification.method !== 'item/completed')
+        return undefined
+
+    const item = notification.params.item
+    if (item.type !== 'collabAgentToolCall' || item.tool !== 'spawnAgent' || item.status === 'failed')
+        return undefined
+
+    return item.receiverThreadIds.at(0)
+}