@meistrari/agent-core 0.2.0-experimental.5 → 0.2.0-experimental.7

package/README.md

@@ -122,6 +122,13 @@ stale managed instruction file.
 `resolveInferenceModel`, `pluginsEnabled`, and `browserAuth` (a per-run Browser Use
 credential socket for ChatGPT authentication; off by default).
 
+API-key and Bedrock logins stay in the app-server's memory (`cli_auth_credentials_store="ephemeral"`),
+so no `auth.json` under `CODEX_HOME` holds the key for the agent's tools to read. An API-key login
+may name `baseUrl`, the root of another OpenAI Responses API (a gateway, or a loopback proxy that
+holds the real credential and gets a placeholder): Codex then reaches it as a model provider of its
+own, named by `modelProvider` (`api-key-endpoint` by default, never a built-in id), with the key as
+its bearer. `codex-api-key-endpoint.cli.spec.ts` pins that contract against the real CLI.
+
 `AgentRun.notify` and `AgentRun.compactContext` are optional on the interface; the Claude and
 Codex runs implement both. `sendPrompt` accepts `submissionOrder`, defaulting to `in-order`.
 
@@ -134,7 +141,8 @@ product instructions/tools, and supervisor integration tests. CI type-checks and
 with Remy's Bun 1.3.10 / Claude SDK 0.3.284 and agent-api's Claude SDK 0.3.257 pins.
 
 `bun run test` runs the portable suites. `bun run test:cli` runs the `*.cli.spec.ts` suites
-against the real bundled Claude Code CLI and a fake Messages API. CI runs them on Linux; the
+against the real bundled Claude Code CLI and a fake Messages API, and the Codex endpoint spec
+against the pinned Codex CLI (through `bunx`, or `CODEX_EXECUTABLE`) and a fake Responses API. CI runs them on Linux; the
 process lifecycle spec reads `/proc`, so it fails on macOS. Claude Code rejects its
 bypass-permissions mode as root, so run them as a regular user.
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.2.0-experimental.5",
+    "version": "0.2.0-experimental.7",
     "packageManager": "bun@1.3.12",
     "description": "Shared contracts and runtime modules for Tela coding-agent sandboxes: agent protocol, supervisor wire protocol, resident supervisor, worker runtime client, and Claude/Codex harness adapters.",
     "license": "UNLICENSED",

package/src/agents/claude/claude-code-process.ts

@@ -25,7 +25,7 @@ export class ClaudeCodeProcess {
     private termination: Promise<void> | undefined
     private stderr = ''
 
-    constructor(private readonly exitTimeoutMs = CLAUDE_PROCESS_EXIT_TIMEOUT_MS) {}
+    constructor(private readonly exitTimeoutMs = CLAUDE_PROCESS_EXIT_TIMEOUT_MS, private readonly processLauncher?: string) {}
 
     /** The SDK `spawnClaudeCodeProcess` hook. A run spawns at most one process. */
     readonly spawn = (options: SpawnOptions): SpawnedProcess => {
@@ -33,10 +33,10 @@ export class ClaudeCodeProcess {
             throw new Error('Claude Code process already spawned for this run.')
         // `detached` makes the CLI a process-group leader. The forwarded signal aborts only after the
         // SDK's graceful stdin-EOF window, as for the SDK's own spawn.
-        const child = spawn(options.command, options.args, { cwd: options.cwd, env: options.env, signal: options.signal, stdio: ['pipe', 'pipe', 'pipe'], detached: true, windowsHide: true })
+        const child = spawn(this.processLauncher ?? options.command, this.processLauncher ? [options.command, ...options.args] : options.args, { cwd: options.cwd, env: options.env, signal: options.signal, stdio: ['pipe', 'pipe', 'pipe'], detached: true, windowsHide: true })
         this.child = child
         this.exit = new Promise((resolve) => {
-            child.once('exit', () => resolve())
+            child.once(this.processLauncher ? 'close' : 'exit', () => resolve())
             // A failed spawn emits `error` without `exit`; there is no process to wait for.
             child.once('error', () => {
                 if (child.pid === undefined)
@@ -70,15 +70,21 @@ export class ClaudeCodeProcess {
         const exit = this.exit
         if (!child || !exit || child.pid === undefined)
             return
-        if (await settlesWithin(exit, this.exitTimeoutMs))
+        // A fork/wait launcher can exit while its CLI still holds the stdio pipes.
+        // For launchers, await close and clean the group even if the wrapper already exited.
+        if (await settlesWithin(exit, this.exitTimeoutMs) && !this.processLauncher)
             return
         try {
             process.kill(-child.pid, 'SIGKILL')
         }
-        catch {
+        catch (error) {
+            if (this.processLauncher && process.platform !== 'win32' && (error as NodeJS.ErrnoException).code !== 'ESRCH')
+                throw error
             child.kill('SIGKILL')
         }
-        await settlesWithin(exit, killedExitWaitMs)
+        const closed = await settlesWithin(exit, killedExitWaitMs)
+        if (this.processLauncher && !closed)
+            throw new Error('Claude launcher process group did not close after SIGKILL.')
     }
 }
 

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

@@ -71,6 +71,14 @@ export interface ClaudeProviderConfig {
     desktop?: ClaudeDesktopConfig | null
     tools?: readonly AgentTool[]
     executable?: string
+    /**
+     * Trusted launcher invoked as <CLI executable> <CLI args>; owns any privilege drop.
+     * Preserve stdio and the process group: exec the CLI or keep children in that group.
+     * On Windows, the launcher must exec the CLI in place (group signals are unavailable).
+     */
+    processLauncher?: string
+    /** Private provider stores; defaults to the CLI transcript directory when omitted. */
+    runtimeStateRoot?: string
     environment?: Record<string, string | undefined>
     nativeToolActorBridge?: ClaudeNativeToolActorBridge
     startupDeadlineMs?: number
@@ -139,6 +147,8 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
     private readonly desktop: ClaudeDesktopConfig | null
     private readonly tools: readonly AgentTool[]
     private readonly executable: string | undefined
+    private readonly processLauncher: string | undefined
+    private readonly runtimeStateRoot: string | undefined
     private readonly environment: Record<string, string | undefined>
     private readonly nativeToolActorBridge: ClaudeNativeToolActorBridge | undefined
     private readonly startupDeadlineMs: number
@@ -156,6 +166,8 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         this.desktop = config.desktop ?? null
         this.tools = config.tools ?? []
         this.executable = config.executable
+        this.processLauncher = config.processLauncher
+        this.runtimeStateRoot = config.runtimeStateRoot
         this.environment = config.environment ?? {}
         this.nativeToolActorBridge = config.nativeToolActorBridge
         this.startupDeadlineMs = config.startupDeadlineMs ?? CLAUDE_STARTUP_DEADLINE_MS
@@ -202,10 +214,10 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
         const runtime = createClaudeToolRuntimeRef({ turnId: () => state.currentTurnId })
         // The transcript location is a pre-input fact; session-local stores live beside it.
         const transcriptPath = join(configDir, 'projects', encodeClaudeProjectPath(input.cwd), `${expectedSessionId}.jsonl`)
-        const steeredNotifications = ClaudeSteeredNotificationStore.open({ sessionId: input.sessionId, transcriptPath })
+        const steeredNotifications = ClaudeSteeredNotificationStore.open({ sessionId: input.sessionId, transcriptPath, rootDir: this.runtimeStateRoot })
         const resources = await this.openRunResources({ input, expectedSessionId, signal: abortController.signal })
         const { nativeToolActorRun, workspaceSkills, selectedRepositoryInstructions, browserAuthBroker, browserTurnMetadata } = resources
-        const claudeProcess = new ClaudeCodeProcess()
+        const claudeProcess = new ClaudeCodeProcess(undefined, this.processLauncher)
         const declaredSubscriptionType = this.auth ? fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) : undefined
         const runtimeMcpServers = toClaudeMcpServers({
             tools,
@@ -302,7 +314,7 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             const [userInputRequests, initialization, , sessionContext] = await Promise.all([
                 UserInputRequestStore.open({
                     sessionId: metadata.sessionId,
-                    rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+                    rootDir: this.runtimeStateRoot ?? userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
                 }),
                 awaitClaudeInitialization({ query, signal: abortController.signal, deadlineMs: this.startupDeadlineMs }),
                 this.auth?.acquire({ signal: abortController.signal }),
@@ -314,8 +326,12 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             if (this.auth && declaredSubscriptionType !== undefined && declaredSubscriptionType !== fetchFreeSubscriptionType(this.auth.knownSubscriptionType()) && !params.respawnedForSubscriptionType) {
                 query.close()
                 inputQueue.close()
-                await claudeProcess.terminate()
-                await closeRunResources(resources)
+                try {
+                    await claudeProcess.terminate()
+                }
+                finally {
+                    await closeRunResources(resources)
+                }
                 return await this.openRun({ ...params, respawnedForSubscriptionType: true })
             }
 
@@ -372,8 +388,12 @@ export class ClaudeProvider implements AgentProvider<'claude'> {
             query.close()
             inputQueue.close()
             // A failed open (for example a missed initialize deadline) must not leave its CLI behind.
-            await claudeProcess.terminate()
-            await closeRunResources(resources)
+            try {
+                await claudeProcess.terminate()
+            }
+            finally {
+                await closeRunResources(resources)
+            }
             throw error
         }
     }

package/src/agents/claude/claude-run.ts

@@ -879,18 +879,31 @@ export class ClaudeRun implements AgentRun {
             cause: error,
         }))
         this.ended = this.endAfterProcessExit(reason, error)
+        // Autonomous stream failure may finish without a stop caller; keep rejection observed.
+        void this.ended.catch(() => undefined)
     }
 
-    // session.ended means the CLI is gone: the terminal events wait for its exit (bounded by
+    // A successful session.ended means the CLI is gone: the terminal events wait for its exit (bounded by
     // CLAUDE_PROCESS_EXIT_TIMEOUT_MS, then a process-group kill). close() is idempotent and sends
     // the stdin EOF the CLI exits on.
     private async endAfterProcessExit(reason: 'completed' | 'stopped' | 'interrupted' | 'failed', error: AgentError | undefined): Promise<void> {
         this.closeQuery()
-        await this.process.terminate()
-        this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
-        this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
-        this.events.end()
-        void this.onFinished().catch(() => undefined)
+        try {
+            await this.process.terminate()
+            this.events.push({ type: 'session.ended', payload: error ? { reason, error } : { reason } })
+            this.events.push({ type: 'session.state.changed', payload: { state: reason === 'failed' ? 'failed' : 'stopped' } })
+        }
+        catch (cause) {
+            const shutdownError = { ...serializeAgentError(cause), code: 'agents.provider-shutdown-failed' }
+            this.events.push({ type: 'error', payload: { message: 'Claude CLI shutdown could not be confirmed.', fatal: true, source: 'runtime', error: shutdownError } })
+            this.events.push({ type: 'session.ended', payload: { reason: 'failed', error: shutdownError } })
+            this.events.push({ type: 'session.state.changed', payload: { state: 'failed' } })
+            throw cause
+        }
+        finally {
+            this.events.end()
+            await this.onFinished().catch(() => undefined)
+        }
     }
 
     // Reports the request's one result; later calls return the reported one. The caller decides

package/src/agents/claude/claude-steered-notifications.ts

@@ -48,9 +48,9 @@ export interface SteeredNotificationDelivery {
 export class ClaudeSteeredNotificationStore {
     private constructor(private readonly filePath: string, private file: StoreFile) {}
 
-    static open(input: { sessionId: string, transcriptPath: string }): ClaudeSteeredNotificationStore {
+    static open(input: { sessionId: string, transcriptPath: string, rootDir?: string }): ClaudeSteeredNotificationStore {
         const filePath = join(
-            dirname(input.transcriptPath),
+            input.rootDir ?? dirname(input.transcriptPath),
             storeDirectoryName,
             Buffer.from(input.sessionId, 'utf8').toString('base64url'),
             storeFileName,

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

@@ -44,9 +44,23 @@ export interface CodexBedrockAuthProvider {
     getCredentials: (input?: CodexAuthTokenRequest) => Promise<CodexBedrockCredentials>
 }
 
+/**
+ * An API key login, kept in the app-server's memory only. Without `baseUrl` it reaches the API of the model
+ * provider `modelProvider` names (OpenAI's by default). With `baseUrl`, the root of another OpenAI Responses
+ * API (`https://gateway.example/v1`, or a loopback proxy that holds the real credential), Codex reaches it as
+ * a model provider of its own, named by `modelProvider` (`api-key-endpoint` by default) and given the key as
+ * its bearer.
+ */
+export interface CodexApiKeyAuthentication {
+    kind: 'api-key'
+    provider: CodexApiKeyAuthProvider
+    modelProvider?: string
+    baseUrl?: string
+}
+
 export type CodexAuthentication
     = | { kind: 'chatgpt', provider: CodexAuthProvider }
-        | { kind: 'api-key', provider: CodexApiKeyAuthProvider, modelProvider?: string }
+        | CodexApiKeyAuthentication
         | { kind: 'amazon-bedrock', region: string, provider: CodexBedrockAuthProvider }
 /** Expiry scheduling hint only; this neither authenticates nor verifies a JWT signature. */
 export function codexAuthTokensExpireSoon(tokens: CodexAuthTokens): boolean {

package/src/agents/codex/codex-json-rpc-client.ts

@@ -59,7 +59,9 @@ export class CodexJsonRpcClient {
     readonly child: ChildProcessWithoutNullStreams
     private nextId = 0
     private stopped = false
+    private shutdown: Promise<void> | undefined
     private readonly closed: Promise<void>
+    private readonly processGroup: boolean
     private readonly pending = new Map<string, {
         method: ClientRequestMethod
         resolve: (value: unknown) => void
@@ -70,6 +72,7 @@ export class CodexJsonRpcClient {
         executable: string,
         options: {
             cwd: string
+            processLauncher?: string
             environment?: Record<string, string | undefined>
             configOverrides?: readonly string[]
             onMessage: (message: CodexJsonRpcMessage) => void
@@ -78,10 +81,13 @@ export class CodexJsonRpcClient {
             maxLineBytes?: number
         },
     ) {
-        this.child = spawn(executable, ['app-server', '--listen', 'stdio://', ...(options.configOverrides ?? []).flatMap(value => ['-c', value])], {
+        this.processGroup = options.processLauncher !== undefined && process.platform !== 'win32'
+        const args = ['app-server', '--listen', 'stdio://', ...(options.configOverrides ?? []).flatMap(value => ['-c', value])]
+        this.child = spawn(options.processLauncher ?? executable, options.processLauncher ? [executable, ...args] : args, {
             cwd: options.cwd,
             env: options.environment,
             stdio: 'pipe',
+            detached: this.processGroup,
         })
         this.closed = new Promise(resolve => this.child.once('close', () => resolve()))
 
@@ -229,9 +235,16 @@ export class CodexJsonRpcClient {
     }
 
     async closeInputAndStop(): Promise<void> {
+        this.shutdown ??= this.drainAndStop()
+        await this.shutdown
+    }
+
+    private async drainAndStop(): Promise<void> {
         if (this.stopped) {
             if (!await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
-                await terminateChild(this.child, this.closed)
+                await terminateChild(this.child, this.closed, this.processGroup)
+            if (this.processGroup)
+                signalProcessGroup(this.child, 'SIGKILL')
             return
         }
         this.stopped = true
@@ -242,9 +255,10 @@ export class CodexJsonRpcClient {
         // EOF/drain and process exit share one grace window. Never wait separately for a
         // buffered stdin write: a child that stops reading must still reach signal escalation.
         this.child.stdin.end()
-        if (await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
-            return
-        await terminateChild(this.child, this.closed)
+        if (!await waitForClosed(this.closed, PROCESS_SHUTDOWN_GRACE_MS))
+            await terminateChild(this.child, this.closed, this.processGroup)
+        if (this.processGroup)
+            signalProcessGroup(this.child, 'SIGKILL')
     }
 
     async stop(): Promise<void> {
@@ -288,7 +302,17 @@ export class CodexJsonRpcClient {
     }
 }
 
-async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Promise<void>): Promise<void> {
+async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Promise<void>, processGroup: boolean): Promise<void> {
+    if (processGroup) {
+        // The launcher may already be gone while the CLI retains its pipes. Signal the
+        // retained group regardless of the wrapper's exitCode, and bound the close wait.
+        for (const signal of ['SIGINT', 'SIGTERM', 'SIGKILL'] as const) {
+            signalProcessGroup(child, signal)
+            if (await waitForClosed(closed, signal === 'SIGKILL' ? 1_000 : PROCESS_SHUTDOWN_GRACE_MS))
+                return
+        }
+        throw new Error('Codex launcher process group did not close after SIGKILL.')
+    }
     if (child.exitCode !== null || child.signalCode !== null) {
         await closed
         return
@@ -308,6 +332,18 @@ async function terminateChild(child: ChildProcessWithoutNullStreams, closed: Pro
     await closed
 }
 
+function signalProcessGroup(child: ChildProcessWithoutNullStreams, signal: NodeJS.Signals): void {
+    if (child.pid === undefined)
+        return
+    try {
+        process.kill(-child.pid, signal)
+    }
+    catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ESRCH')
+            throw error
+    }
+}
+
 async function waitForClosed(closed: Promise<void>, timeoutMs: number): Promise<boolean> {
     return await new Promise<boolean>((resolve) => {
         const timer = setTimeout(() => resolve(false), timeoutMs)

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

@@ -5,7 +5,7 @@ import type { AgentRun } from '../agent-run'
 import type { AgentTool } from '../agent-tool'
 import type { InstructionComposer } from '../instructions'
 import type { SessionContextComposer } from '../session-context'
-import type { CodexAuthentication, CodexAuthProvider, CodexAuthTokens, CodexBedrockCredentials } from './codex-auth'
+import type { CodexApiKeyAuthentication, CodexAuthentication, CodexAuthProvider, CodexAuthTokens, CodexBedrockCredentials } from './codex-auth'
 import type { CodexEventMapperState, CodexNotification } from './codex-event-mapper'
 import type { CodexJsonRpcMessage, CodexServerRequest } from './codex-json-rpc-client'
 import type { ClientRequestResponsesByMethod } from './codex-protocol'
@@ -13,7 +13,7 @@ import { realpath } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { codexModelIdSchema } from '../../protocol'
 import { serializeAgentError } from '../agent-error-serializer'
-import { AgentProviderMetadataError, AgentProviderProtocolError, AgentProviderRuntimeError } from '../agent-runtime-error'
+import { AgentProviderMetadataError, AgentProviderProtocolError, AgentProviderRuntimeError, AgentRuntimeValidationError } from '../agent-runtime-error'
 import { sessionConfiguredEvent } from '../agent-session-events'
 import { selectAgentTools, toolByName } from '../agent-tool'
 import { emptyInstructionComposer } from '../instructions'
@@ -33,6 +33,15 @@ import { CodexRunAuth, CodexRunAuthClosedError } from './codex-run-auth'
 import { catalogRepositorySkillRoots, workspaceSkillRoots } from './codex-skill-roots'
 import { runCodexDynamicTool, toCodexDynamicTools } from './codex-tool-mapper'
 
+/** The model provider an API key endpoint gets when `modelProvider` names none. */
+const API_KEY_ENDPOINT_PROVIDER = 'api-key-endpoint'
+/** Codex's own provider ids: an endpoint defined under one of these would not be the one Codex uses. */
+const BUILT_IN_MODEL_PROVIDERS = new Set(['openai', 'amazon-bedrock', 'ollama', 'lmstudio', 'oss'])
+/** A bare TOML key, so the id is safe inside the dotted `-c model_providers.<id>.…` overrides. */
+const MODEL_PROVIDER_ID = /^[\w-]+$/
+/** Where plain http keeps the key on the machine. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]'])
+
 export interface CodexStartupStageFact {
     event: 'sandbox.startup-stage'
     stage: 'codex-initialize' | 'auth-acquisition-login' | 'thread-start' | 'thread-resume'
@@ -45,6 +54,14 @@ export interface CodexProviderConfig {
     auth: CodexAuthProvider | CodexAuthentication
     tools?: readonly AgentTool[]
     executable?: string
+    /**
+     * Trusted launcher invoked as <CLI executable> <CLI args>; owns any privilege drop.
+     * Preserve stdio and the process group: exec the CLI or keep children in that group.
+     * On Windows, the launcher must exec the CLI in place (group signals are unavailable).
+     */
+    processLauncher?: string
+    /** Private provider stores; defaults to the CLI transcript directory when omitted. */
+    runtimeStateRoot?: string
     environment?: Record<string, string | undefined>
     onStartupStage?: (fact: CodexStartupStageFact) => void
     instructions?: InstructionComposer
@@ -102,7 +119,11 @@ export class CodexProvider implements AgentProvider<'codex'> {
     private readonly tools: readonly AgentTool[]
     private readonly executable: string
     private readonly environment: Record<string, string | undefined>
+    private readonly processLauncher: string | undefined
+    private readonly runtimeStateRoot: string | undefined
     private readonly auth: CodexAuthentication
+    /** The validated endpoint of an API key login that names one. */
+    private readonly apiKeyEndpoint: string | undefined
     private readonly onStartupStage: ((fact: CodexStartupStageFact) => void) | undefined
     private readonly instructions: InstructionComposer
     private readonly sessionContext: SessionContextComposer | undefined
@@ -115,9 +136,12 @@ export class CodexProvider implements AgentProvider<'codex'> {
 
     private constructor(config: CodexProviderConfig) {
         this.auth = normalizeCodexAuthentication(config.auth)
+        this.apiKeyEndpoint = this.auth.kind === 'api-key' ? apiKeyEndpoint(this.auth) : undefined
         this.tools = config.tools ?? []
         this.executable = config.executable ?? 'codex'
         this.environment = config.environment ?? {}
+        this.processLauncher = config.processLauncher
+        this.runtimeStateRoot = config.runtimeStateRoot
         this.onStartupStage = config.onStartupStage
         this.instructions = config.instructions ?? emptyInstructionComposer
         this.sessionContext = config.sessionContext
@@ -422,7 +446,11 @@ export class CodexProvider implements AgentProvider<'codex'> {
     }
 
     private modelProvider(): string | undefined {
-        return this.auth.kind === 'amazon-bedrock' ? 'amazon-bedrock' : this.auth.kind === 'api-key' ? this.auth.modelProvider : undefined
+        if (this.auth.kind === 'amazon-bedrock')
+            return 'amazon-bedrock'
+        if (this.auth.kind === 'api-key')
+            return this.auth.modelProvider ?? (this.apiKeyEndpoint === undefined ? undefined : API_KEY_ENDPOINT_PROVIDER)
+        return undefined
     }
 
     private async openConnection(input: {
@@ -442,6 +470,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
 
         try {
             client = new CodexJsonRpcClient(this.executable, {
+                processLauncher: this.processLauncher,
                 cwd,
                 environment: holder.browserAuthBroker
                     ? { ...this.environment, CODING_AGENT_BROWSER_AUTH_SOCKET: holder.browserAuthBroker.socketPath }
@@ -450,6 +479,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
                     ...(this.auth.kind === 'amazon-bedrock'
                         ? ['cli_auth_credentials_store="ephemeral"', 'model_provider="amazon-bedrock"', `model_providers.amazon-bedrock.aws.region=${JSON.stringify(this.auth.region)}`, 'model_providers.amazon-bedrock.aws.wire_api="responses"']
                         : []),
+                    ...(this.auth.kind === 'api-key' ? apiKeyConfigOverrides(this.auth.modelProvider, this.apiKeyEndpoint) : []),
                     ...(this.pluginsEnabled === undefined ? [] : [`features.plugins=${this.pluginsEnabled}`]),
                 ],
                 onMessage: (message) => {
@@ -620,7 +650,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
             }),
             UserInputRequestStore.open({
                 sessionId: metadata.sessionId,
-                rootDir: userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
+                rootDir: this.runtimeStateRoot ?? userInputRequestStoreRootFromTranscriptPath(metadata.transcriptPath),
             }),
             pendingSessionContext({
                 compose: this.sessionContext,
@@ -895,6 +925,62 @@ function normalizeCodexAuthentication(auth: CodexAuthProvider | CodexAuthenticat
     return 'kind' in auth ? auth : { kind: 'chatgpt', provider: auth }
 }
 
+/**
+ * The endpoint as Codex is given it, or none: an http(s) URL with no credentials, query or fragment (not even
+ * an empty `?` or `#`), plain http only on loopback, where the key never crosses the network. Without a
+ * trailing slash, so Codex appends `/responses` to the path it names.
+ */
+function apiKeyEndpoint(auth: CodexApiKeyAuthentication): string | undefined {
+    const invalid = (message: string) => new AgentRuntimeValidationError({
+        code: 'agents.codex-api-key-endpoint-invalid',
+        message,
+        publicMessage: 'The Codex API key endpoint is misconfigured.',
+        details: { modelProvider: auth.modelProvider },
+    })
+    // Without an endpoint the provider id only selects a provider configured elsewhere, as it always has.
+    if (auth.baseUrl === undefined)
+        return undefined
+    if (auth.modelProvider !== undefined && !MODEL_PROVIDER_ID.test(auth.modelProvider))
+        throw invalid('Codex model provider ids are letters, digits, underscores and hyphens.')
+    let url: URL
+    try {
+        url = new URL(auth.baseUrl)
+    }
+    catch {
+        throw invalid('The Codex API key endpoint is not a URL.')
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw invalid('The Codex API key endpoint must be an http or https URL.')
+    if (url.protocol === 'http:' && !LOOPBACK_HOSTS.has(url.hostname))
+        throw invalid('The Codex API key endpoint sends the key as its bearer: plain http is accepted on loopback only.')
+    if (url.username || url.password || /[?#]/u.test(auth.baseUrl))
+        throw invalid('The Codex API key endpoint carries no credentials, query or fragment; the key travels as the bearer.')
+    if (BUILT_IN_MODEL_PROVIDERS.has(auth.modelProvider ?? API_KEY_ENDPOINT_PROVIDER))
+        throw invalid('An API key endpoint needs a model provider id of its own, not one of Codex\'s built-in providers.')
+    return `${url.origin}${url.pathname.replace(/\/+$/u, '')}`
+}
+
+/**
+ * An API key login is always kept in memory, never written to `auth.json` under CODEX_HOME, where the agent's
+ * own tools could read it. With an endpoint, Codex reaches it through a Responses provider of its own that
+ * authenticates with that login.
+ */
+function apiKeyConfigOverrides(modelProvider: string | undefined, endpoint: string | undefined): string[] {
+    const ephemeral = ['cli_auth_credentials_store="ephemeral"']
+    if (endpoint === undefined)
+        return ephemeral
+    const id = modelProvider ?? API_KEY_ENDPOINT_PROVIDER
+    const provider = `model_providers.${id}`
+    return [
+        ...ephemeral,
+        `model_provider=${JSON.stringify(id)}`,
+        `${provider}.name=${JSON.stringify(id)}`,
+        `${provider}.base_url=${JSON.stringify(endpoint)}`,
+        `${provider}.wire_api="responses"`,
+        `${provider}.requires_openai_auth=true`,
+    ]
+}
+
 async function requireSelectedRepositoryInstructionSource(input: {
     instructionBridgePath: string
     instructionSources?: readonly string[]

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

@@ -21,6 +21,7 @@ import type { CodexEventMapperState } from './codex-event-mapper'
 import type { CodexJsonRpcClient } from './codex-json-rpc-client'
 import type { ClientRequestResponsesByMethod, CodexUserInput } from './codex-protocol'
 import { serializeAgentNotificationToolOutput } from '../../protocol'
+import { serializeAgentError } from '../agent-error-serializer'
 import { AgentEventStream } from '../agent-event-stream'
 import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentPromptDeferredError, AgentRunStateError } from '../agent-runtime-error'
 import { sessionSettingsChangedEvent } from '../agent-session-events'
@@ -146,7 +147,7 @@ export class CodexRun implements AgentRun {
             sessionId: this.metadata.sessionId,
             providerSessionId: this.metadata.providerSessionId,
             reason: 'aborted',
-        }))
+        }).catch(() => undefined))
     }
 
     pushEvent(draft: AgentEventDraft): void {
@@ -639,8 +640,20 @@ export class CodexRun implements AgentRun {
         const revocation = new Promise<void>((resolve) => {
             resolve(this.onStop())
         })
-        void Promise.all([this.client.stop(), revocation])
-            .then(finalize)
+        void Promise.allSettled([this.client.stop(), revocation])
+            .then((outcomes) => {
+                const failure = outcomes.find(outcome => outcome.status === 'rejected')
+                if (!failure) {
+                    finalize()
+                    return
+                }
+                const error = { ...serializeAgentError(failure.reason), code: 'agents.provider-shutdown-failed' }
+                this.events.push({ type: 'error', payload: { message: 'Codex run shutdown could not be confirmed.', fatal: true, source: 'runtime', error } })
+                this.events.push({ type: 'session.ended', payload: { reason: 'failed', error } })
+                this.events.push({ type: 'session.state.changed', payload: { state: 'failed' } })
+                this.events.end()
+                throw failure.reason
+            })
             .then(stopping.resolve, stopping.reject)
     }
 

package/src/agents/input-attachment-preparation.ts

@@ -1,5 +1,5 @@
-import type { Buffer } from 'node:buffer'
 import type { MaterializedAgentInputAttachment } from './materialized-input-attachment'
+import { Buffer } from 'node:buffer'
 import { readFile } from 'node:fs/promises'
 import { AgentInputAttachmentPreparationFailure } from './input-attachment.errors'
 
@@ -8,7 +8,9 @@ type NativeImageMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/web
 export async function readAttachmentBytes(attachment: MaterializedAgentInputAttachment, signal: AbortSignal): Promise<Buffer> {
     signal.throwIfAborted()
     try {
-        const bytes = await readFile(attachment.localPath, { signal })
+        const bytes = attachment.readBytes
+            ? Buffer.from(await attachment.readBytes(signal))
+            : await readFile(attachment.localPath, { signal })
         signal.throwIfAborted()
         return bytes
     }

package/src/agents/materialized-input-attachment.ts

@@ -6,6 +6,8 @@ export type MaterializedAgentInputAttachment = Readonly<{
     byteSize: number
     sha256: string
     localPath: string
+    /** Read as the file owner when the provider uses a different process identity. */
+    readBytes?: (signal: AbortSignal) => Promise<Uint8Array>
 }>
 
 export type AgentInputAttachmentProjection = Readonly<{

package/src/provenance.gen.ts

@@ -1,6 +1,6 @@
 // Generated by scripts/write-provenance.ts. Do not edit by hand.
 export const generatedProvenance = {
-    version: "0.2.0-experimental.5",
-    sha: "eea347fec63bc912885e3201e6463cfcfead865b",
-    buildTime: "2026-09-29T19:55:41.637Z",
+    version: "0.2.0-experimental.7",
+    sha: "c27666274441cd3c81ffc5934ca115dffbe234ee",
+    buildTime: "2026-10-14T20:20:44.640Z",
 } as const