@meistrari/agent-core 0.2.0-experimental.1 → 0.2.0-experimental.2

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

@@ -0,0 +1,320 @@
+import type { Server, Socket } from 'node:net'
+import type { CodexAuthTokens } from './codex-auth'
+import type { ClientRequestParamsByMethod } from './codex-protocol'
+import type { CodexRunAuth } from './codex-run-auth'
+import { Buffer } from 'node:buffer'
+import { chmod, mkdtemp, rm } from 'node:fs/promises'
+import { createServer } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { AgentProviderProtocolError } from '../agent-runtime-error'
+import { codexAuthTokensExpireSoon } from './codex-auth'
+import { toAuthRefreshInput, toCodexLoginParams, toCodexRefreshResponse } from './codex-auth-mapper'
+import { projectCodexBrowserAuthStatus } from './codex-browser-auth-status'
+import { CodexJsonRpcClient, CodexJsonRpcResponseError, isCodexServerRequest } from './codex-json-rpc-client'
+
+const MAX_BYTES = 1024 * 1024
+const DEADLINE_MS = 30_000
+const MAX_CONNECTIONS = 8
+
+/**
+ * The credential source a broker serves. Codex runs pass their own `CodexRunAuth`, shared with the
+ * main native process; Claude runs pass a `LazyCodexRunAuth` that binds an account on first use.
+ */
+export type CodexBrowserAuthSource = Pick<CodexRunAuth, 'getCurrentTokens' | 'refreshAuthTokens' | 'close'>
+
+interface BrokerInput {
+    executable: string
+    cwd: string
+    environment: Record<string, string | undefined>
+    auth: CodexBrowserAuthSource
+}
+type BrowserMethod = 'initialize' | 'getAuthStatus' | 'configRequirements/read' | 'config/read' | 'config/value/write' | 'config/batchWrite'
+type BrowserRequest = {
+    [Method in BrowserMethod]: { id: string | number, method: Method, params: ClientRequestParamsByMethod[Method] }
+}[BrowserMethod]
+
+/** Runtime-only capability: never put this socket path into session metadata. */
+export class CodexBrowserAuthBroker {
+    readonly socketPath: string
+    private readonly server: Server
+    private readonly connections = new Set<{ close: () => Promise<void> }>()
+    private closing: Promise<void> | undefined
+
+    private constructor(private readonly directory: string, private readonly input: BrokerInput) {
+        this.socketPath = join(directory, 'rpc.sock')
+        this.server = createServer((socket) => {
+            if (this.closing || this.connections.size >= MAX_CONNECTIONS) {
+                socket.destroy()
+                return
+            }
+            const connection = new BrowserConnection(socket, this.input)
+            this.connections.add(connection)
+            socket.once('close', () => {
+                void connection.close().finally(() => this.connections.delete(connection))
+            })
+        })
+    }
+
+    static async open(input: BrokerInput): Promise<CodexBrowserAuthBroker> {
+        const directory = await mkdtemp(join(tmpdir(), 'codex-browser-'))
+        const broker = new CodexBrowserAuthBroker(directory, input)
+        try {
+            await chmod(directory, 0o700)
+            await new Promise<void>((resolve, reject) => {
+                broker.server.once('error', reject)
+                broker.server.listen(broker.socketPath, resolve)
+            })
+            await chmod(broker.socketPath, 0o600)
+            return broker
+        }
+        catch {
+            await broker.close()
+            throw brokerFailure()
+        }
+    }
+
+    async close(): Promise<void> {
+        this.closing ??= (async () => {
+            this.input.auth.close()
+            const listenerClosed = new Promise<void>(resolve => this.server.close(() => resolve()))
+            await Promise.all([...this.connections].map(async connection => await connection.close()))
+            await listenerClosed
+            await rm(this.directory, { recursive: true, force: true })
+        })()
+        await this.closing
+    }
+}
+
+class BrowserConnection {
+    private readonly client: CodexJsonRpcClient
+    private readonly abort = new AbortController()
+    private tokens: CodexAuthTokens | undefined
+    private initialized = false
+    private buffer = Buffer.alloc(0)
+    private queuedBytes = 0
+    private queuedFrames = 0
+    private queuedRefreshes = 0
+    private queue = Promise.resolve()
+    private refreshQueue = Promise.resolve()
+    private closing: Promise<void> | undefined
+    private readonly startupTimer: ReturnType<typeof setTimeout>
+
+    constructor(private readonly socket: Socket, private readonly input: BrokerInput) {
+        this.client = new CodexJsonRpcClient(input.executable, {
+            cwd: input.cwd,
+            environment: input.environment,
+            maxLineBytes: MAX_BYTES,
+            onStderr: () => undefined,
+            onInvalidLine: () => {
+                void this.close()
+            },
+            onMessage: (message) => {
+                if (!isCodexServerRequest(message))
+                    return
+                if (message.method !== 'account/chatgptAuthTokens/refresh') {
+                    this.client.respondError(message.id, { code: -32601, message: 'Unsupported request.' })
+                    return
+                }
+                this.queuedRefreshes += 1
+                if (this.queuedRefreshes > 8) {
+                    void this.close()
+                    return
+                }
+                this.refreshQueue = this.refreshQueue.then(async () => {
+                    this.abort.signal.throwIfAborted()
+                    if (!this.tokens || message.params.reason !== 'unauthorized')
+                        throw brokerFailure()
+                    const refreshed = await this.deadline(input.auth.refreshAuthTokens(toAuthRefreshInput(message.params, this.tokens)))
+                    if (this.abort.signal.aborted)
+                        return
+                    this.tokens = refreshed
+                    this.client.respond(message.id, toCodexRefreshResponse(refreshed))
+                }).catch(() => {
+                    void this.close()
+                }).finally(() => { this.queuedRefreshes -= 1 })
+            },
+        })
+        this.startupTimer = setTimeout(() => {
+            void this.close()
+        }, DEADLINE_MS)
+        this.client.child.once('close', () => {
+            void this.close()
+        })
+        socket.on('error', () => {
+            void this.close()
+        })
+        socket.on('end', () => {
+            void this.close()
+        })
+        socket.on('data', (chunk: Buffer) => {
+            this.queuedBytes += chunk.length
+            if (this.queuedBytes > MAX_BYTES) {
+                void this.close()
+                return
+            }
+            this.buffer = Buffer.concat([this.buffer, chunk])
+            let newline = this.buffer.indexOf(10)
+            while (newline !== -1) {
+                this.queuedFrames += 1
+                if (this.queuedFrames > 64) {
+                    void this.close()
+                    return
+                }
+                const line = this.buffer.subarray(0, newline)
+                this.buffer = this.buffer.subarray(newline + 1)
+                newline = this.buffer.indexOf(10)
+                this.queue = this.queue.then(async () => {
+                    if (!this.closing)
+                        await this.deadline(this.handleLine(line))
+                }).catch(() => {
+                    void this.close()
+                }).finally(() => {
+                    this.queuedBytes -= line.length + 1
+                    this.queuedFrames -= 1
+                })
+            }
+        })
+    }
+
+    async close(): Promise<void> {
+        this.closing ??= (async () => {
+            clearTimeout(this.startupTimer)
+            this.tokens = undefined
+            this.abort.abort()
+            this.socket.destroy()
+            await this.client.stop()
+            this.buffer = Buffer.alloc(0)
+        })()
+        await this.closing
+    }
+
+    private async handleLine(line: Buffer): Promise<void> {
+        const raw: unknown = JSON.parse(line.toString('utf8'))
+        if (isInitializedNotification(raw))
+            return
+        const request = parseRequest(raw)
+        let result: unknown
+        if (request.method === 'initialize') {
+            if (this.initialized)
+                throw brokerFailure()
+            result = await this.client.request(request.method, request.params)
+            this.abort.signal.throwIfAborted()
+            this.client.notify('initialized', undefined)
+            const tokens = await this.input.auth.getCurrentTokens({ signal: this.abort.signal })
+            await this.installTokens(tokens)
+            this.initialized = true
+            clearTimeout(this.startupTimer)
+        }
+        else {
+            if (!this.initialized)
+                throw brokerFailure()
+            try {
+                if (request.method === 'getAuthStatus') {
+                    await this.prepareAuthStatus(request.params)
+                    const response = await this.client.request(request.method, request.params)
+                    if (!this.tokens)
+                        throw brokerFailure()
+                    result = projectCodexBrowserAuthStatus({ response, params: request.params, installedTokens: this.tokens })
+                }
+                else {
+                    result = await this.client.request(request.method, request.params)
+                }
+            }
+            catch (error) {
+                // Native config errors (including version conflicts) are command results, not
+                // transport failures. Keep only the numeric code; messages/data may hold secrets.
+                if (request.method === 'getAuthStatus' || !(error instanceof CodexJsonRpcResponseError)
+                    || error.responseErrorCode === undefined || !Number.isSafeInteger(error.responseErrorCode)
+                    || error.responseErrorCode < -2147483648 || error.responseErrorCode > 2147483647) {
+                    throw brokerFailure()
+                }
+                await this.writeResponse({ id: request.id, error: { code: error.responseErrorCode, message: 'Codex configuration request failed.' } })
+                return
+            }
+        }
+        await this.writeResponse({ id: request.id, result })
+    }
+
+    private async prepareAuthStatus(params: ClientRequestParamsByMethod['getAuthStatus']): Promise<void> {
+        const current = await this.input.auth.getCurrentTokens({ signal: this.abort.signal })
+        await this.installTokens(current)
+        const installed = this.tokens
+        if (!installed)
+            throw brokerFailure()
+        if (params.refreshToken === true || codexAuthTokensExpireSoon(installed)) {
+            this.abort.signal.throwIfAborted()
+            const refreshed = await this.input.auth.refreshAuthTokens(toAuthRefreshInput({ reason: 'unauthorized' }, installed))
+            await this.installTokens(refreshed)
+        }
+    }
+
+    private async installTokens(tokens: CodexAuthTokens): Promise<void> {
+        this.abort.signal.throwIfAborted()
+        if (this.tokens?.chatgptAccountId === tokens.chatgptAccountId
+            && this.tokens.accessTokenGeneration === tokens.accessTokenGeneration
+            && this.tokens.accessTokenFingerprint === tokens.accessTokenFingerprint
+            && (this.tokens.chatgptPlanType ?? null) === (tokens.chatgptPlanType ?? null)) {
+            return
+        }
+        this.tokens = tokens
+        await this.client.request('account/login/start', toCodexLoginParams(tokens))
+    }
+
+    private async writeResponse(message: object): Promise<void> {
+        this.abort.signal.throwIfAborted()
+        const response = `${JSON.stringify(message)}\n`
+        if (Buffer.byteLength(response) > MAX_BYTES)
+            throw brokerFailure()
+        await new Promise<void>((resolve, reject) => this.socket.write(response, error => error ? reject(brokerFailure()) : resolve()))
+    }
+
+    private async deadline<T>(operation: Promise<T>): Promise<T> {
+        this.abort.signal.throwIfAborted()
+        let timer: ReturnType<typeof setTimeout> | undefined
+        let rejectAbort: (() => void) | undefined
+        try {
+            return await Promise.race([
+                operation,
+                new Promise<never>((_, reject) => {
+                    rejectAbort = () => reject(brokerFailure())
+                    this.abort.signal.addEventListener('abort', rejectAbort, { once: true })
+                }),
+                new Promise<never>((_, reject) => { timer = setTimeout(() => reject(brokerFailure()), DEADLINE_MS) }),
+            ])
+        }
+        finally {
+            clearTimeout(timer)
+            if (rejectAbort)
+                this.abort.signal.removeEventListener('abort', rejectAbort)
+        }
+    }
+}
+
+function isInitializedNotification(raw: unknown): boolean {
+    return typeof raw === 'object' && raw !== null && 'method' in raw && raw.method === 'initialized' && !('id' in raw)
+}
+
+function parseRequest(raw: unknown): BrowserRequest {
+    if (typeof raw !== 'object' || raw === null || !('id' in raw) || !('method' in raw)
+        || !(typeof raw.id === 'string' || (typeof raw.id === 'number' && Number.isSafeInteger(raw.id)))
+        || typeof raw.method !== 'string'
+        || !['initialize', 'getAuthStatus', 'configRequirements/read', 'config/read', 'config/value/write', 'config/batchWrite'].includes(raw.method)) {
+        throw brokerFailure()
+    }
+    if (raw.method === 'configRequirements/read') {
+        if ('params' in raw && raw.params !== null)
+            throw brokerFailure()
+        // Both native wire forms denote no payload; the generated client uses undefined.
+        return { id: raw.id, method: raw.method, params: undefined }
+    }
+    if (!('params' in raw) || typeof raw.params !== 'object' || raw.params === null || Array.isArray(raw.params))
+        throw brokerFailure()
+    // Raw Unix transport boundary only: Codex validates the generated native params;
+    // this broker validates framing, correlation and its narrow method policy.
+    return raw as BrowserRequest
+}
+
+function brokerFailure(): AgentProviderProtocolError {
+    return new AgentProviderProtocolError({ message: 'Browser authentication connection failed.' })
+}

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

@@ -0,0 +1,55 @@
+import type { CodexAuthTokens } from './codex-auth'
+import type { ClientRequestParamsByMethod, ClientRequestResponsesByMethod } from './codex-protocol'
+import { Buffer } from 'node:buffer'
+import { z } from 'zod'
+import { AgentProviderProtocolError } from '../agent-runtime-error'
+
+const externalAuthStatusSchema = z.object({
+    authMethod: z.literal('chatgptAuthTokens'),
+    authToken: z.string().nullable(),
+    requiresOpenaiAuth: z.boolean().nullable(),
+}).passthrough() satisfies z.ZodType<ClientRequestResponsesByMethod['getAuthStatus']>
+
+const accountClaimsNamespace = 'https://api.openai.com/auth'
+const browserAccountClaimsSchema = z.object({
+    [accountClaimsNamespace]: z.object({
+        chatgpt_account_id: z.string().refine(value => value.trim().length > 0),
+    }),
+})
+
+/** Pinned Browser Use accepts the legacy label only; native auth and refresh stay external. */
+export function projectCodexBrowserAuthStatus(input: {
+    response: ClientRequestResponsesByMethod['getAuthStatus']
+    params: ClientRequestParamsByMethod['getAuthStatus']
+    installedTokens: CodexAuthTokens
+}): ClientRequestResponsesByMethod['getAuthStatus'] {
+    // The generated client types the RPC result; validate the actual native wire value here.
+    const validated = externalAuthStatusSchema.safeParse(input.response)
+    if (!validated.success)
+        throw invalidBrowserAuthStatus()
+    const expectedToken = input.params.includeToken === true ? input.installedTokens.accessToken : null
+    if (validated.data.authToken !== expectedToken || !installedAccountMatchesToken(input.installedTokens))
+        throw invalidBrowserAuthStatus()
+    // Preserve the exact native token, auth requirement, and extension fields. This is not
+    // a claim that Codex owns refresh, nor a change to JWT claims or remote authorization.
+    return { ...input.response, authMethod: 'chatgpt' }
+}
+
+function installedAccountMatchesToken(tokens: CodexAuthTokens): boolean {
+    const parts = tokens.accessToken.split('.')
+    if (parts.length !== 3 || parts.some(part => part.length === 0 || /[^\w-]/.test(part)))
+        return false
+    try {
+        // Account consistency only, not signature verification. The native consumer uses
+        // this original claim for its account header; never supply a fallback or rewrite it.
+        const claims = browserAccountClaimsSchema.safeParse(JSON.parse(Buffer.from(parts[1]!, 'base64url').toString('utf8')))
+        return claims.success && claims.data[accountClaimsNamespace].chatgpt_account_id === tokens.chatgptAccountId
+    }
+    catch {
+        return false
+    }
+}
+
+function invalidBrowserAuthStatus(): AgentProviderProtocolError {
+    return new AgentProviderProtocolError({ message: 'Browser authentication status is invalid.' })
+}

package/src/agents/codex/codex-command-mapper.ts

@@ -11,13 +11,18 @@ interface CodexUserInputMapperInput {
     origin?: 'user' | 'supervisor'
     author?: AgentAuthor
     senderContext?: AgentSenderContext
+    authorContext?: string
+    // The session's one-time context block, carried by its first prompt only.
+    sessionContext?: string
 }
 
 export function toCodexUserInput(input: CodexUserInputMapperInput): CodexUserInput[] {
-    const { prompt, origin = 'user', author, senderContext } = input
-    const blocks = prompt.blocks.map(toCodexInputBlock)
+    const { prompt, origin = 'user', author, senderContext, authorContext, sessionContext } = input
+    const blocks: CodexUserInput[] = prompt.blocks.map(toCodexInputBlock)
+    if (sessionContext)
+        blocks.unshift({ type: 'text', text: sessionContext, text_elements: [] })
     return origin === 'user' && author
-        ? [{ type: 'text', text: renderAuthorContext(author, senderContext), text_elements: [] }, ...blocks]
+        ? [{ type: 'text', text: authorContext ?? renderAuthorContext(author, senderContext), text_elements: [] }, ...blocks]
         : blocks
 }
 
@@ -65,6 +70,36 @@ export function codexEffort(effort: AgentReasoningEffort | undefined): CodexTurn
     return effort
 }
 
+export const codexReasoningSummary: CodexTurnStartParams['summary'] = 'auto'
+
+// A type alias: the generated thread config is an index-signature record, which interfaces don't satisfy.
+// eslint-disable-next-line ts/consistent-type-definitions
+type CodexThreadConfig = {
+    'tools.update_plan.enabled': true
+    'features.step_model_switching'?: true
+    'model_reasoning_effort'?: CodexTurnStartParams['effort']
+    'model_reasoning_summary': CodexTurnStartParams['summary']
+}
+
+// Codex prewarms each thread by sending a baseline request over its WebSocket right after
+// thread/start, using the thread's configured effort and summary. The first turn/start reuses that
+// baseline incrementally (previous_response_id + delta items) only when its reasoning settings match;
+// otherwise Codex logs "incremental request failed, websocket reuse properties didn't match" and
+// resends the whole prompt. Configure the thread with exactly what every turn sends.
+//
+// `features.step_model_switching` enables `turn/settings/update`, which a steer uses to change the
+// running turn's model/effort; without it the app-server answers -32600. The feature is experimental
+// upstream and pinned by the sandbox image's Codex version: re-verify it on every Codex bump.
+export function codexThreadConfig(effort: AgentReasoningEffort | undefined, stepModelSwitching = false): CodexThreadConfig {
+    const reasoningEffort = codexEffort(effort)
+    return {
+        'tools.update_plan.enabled': true,
+        ...(stepModelSwitching ? { 'features.step_model_switching': true as const } : {}),
+        ...(reasoningEffort === undefined ? {} : { model_reasoning_effort: reasoningEffort }),
+        'model_reasoning_summary': codexReasoningSummary,
+    }
+}
+
 function toCodexInputBlock(block: AgentInputBlock): CodexUserInput {
     if (block.type === 'text') {
         return { type: 'text', text: block.text, text_elements: [] }