@wix/pathgrade 1.0.18 → 1.0.20

package/README.md

@@ -35,7 +35,8 @@ By default, Pathgrade tries to reuse the agent CLI's native auth before falling
 - **Codex**
   - forwards `OPENAI_API_KEY` when present
   - or runs `codex login --with-api-key` inside the sandbox when an API key is present
-  - `codex exec` can reuse cached `~/.codex/auth.json` when no key is available; `app-server` may reject cached ChatGPT-token refreshes, so prefer `OPENAI_API_KEY` for the default transport
+  - without API credentials, the default `app-server` transport reuses the active Codex login through short-lived auth-only stdio sessions; `codex exec` retains its cached `~/.codex/auth.json` behavior
+  - keyless Codex evals automatically use that managed login for plain and tool-using judges; an explicit `evaluate(..., { llm })` still wins
 - **Cursor**
   - forwards `CURSOR_API_KEY` when set
   - macOS: reuses `cursor-agent login` OAuth tokens from the login Keychain
@@ -47,7 +48,9 @@ By default, Pathgrade tries to reuse the agent CLI's native auth before falling
 
 If you set `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, or `CURSOR_API_BASE_URL`, set the matching API key too.
 
-Do not add `copyFromHome: ['.codex']` just to reuse Codex authentication. When no OpenAI API key is available, Pathgrade automatically stages only `~/.codex/auth.json`. A deliberate full `.codex` copy remains supported, but it also imports host config, MCP definitions, plugins, caches, sessions, and other potentially large or sensitive state; Pathgrade prints a warning when requested.
+An [experimental ChatGPT judge that reuses Codex-managed authentication](docs/OPENAI_OAUTH_JUDGE.md) is also available. It requires no API key, auth-file option, or second login and is selected automatically for keyless Codex evals.
+
+Do not add `copyFromHome: ['.codex']` just to reuse Codex authentication. Keyless app-server runs stage no credential file; the legacy exec transport stages only `~/.codex/auth.json`. A deliberate full `.codex` copy remains supported, but it also imports host config, MCP definitions, plugins, caches, sessions, and other potentially large or sensitive state; Pathgrade prints a warning when requested.
 
 Override credentials per test with `env`:
 
@@ -64,7 +67,7 @@ const agent = await createAgent({
 
 Codex supports two transports and Pathgrade defaults to `app-server`:
 
-- `app-server` (default) — uses `codex app-server` and keeps native thread state. Required for `AskUserReaction` handshakes (`request_user_input` reaches the model). Prefer `OPENAI_API_KEY`; cached ChatGPT auth can fail if the app-server asks Pathgrade to refresh tokens.
+- `app-server` (default) — uses `codex app-server` and keeps native thread state. Required for `AskUserReaction` handshakes (`request_user_input` reaches the model). Without API credentials it acquires and refreshes access sessions through the active Codex login.
 - `exec` — uses `codex exec` and re-injects the transcript every turn. Kept for stateless CI matrices that don't need the handshake.
 
 Precedence: `createAgent({ transport })` > `PATHGRADE_CODEX_TRANSPORT` env > default (`app-server`). An invalid env value throws at `createAgent` time.
@@ -80,7 +83,7 @@ If `transport: 'exec'` is resolved and any `AskUserReaction` is present in `Conv
 
 Migrating from `exec` to `app-server`:
 
-- Export `OPENAI_API_KEY`, or set `transport: 'exec'` / `PATHGRADE_CODEX_TRANSPORT=exec` to stay on the old transport and its cached-auth behavior.
+- Sign in with `codex login` for subscription-backed app-server and judge calls, export `OPENAI_API_KEY` for API billing, or select `transport: 'exec'` for the old cached-auth behavior.
 - The `noninteractive-user-question` runtime policy no longer attaches under `app-server`. Snapshots that captured model output influenced by that policy text may need re-recording.
 - `MAX_TURN_RETRIES` does not apply under `app-server` — a crashed turn ends the conversation with `completionReason: 'agent_crashed'`.
 

package/dist/agents/codex-app-server/agent.d.ts

@@ -28,6 +28,8 @@ export interface CodexAppServerAgentDeps {
     onPermissionGrant?: (entry: PermissionGrantLogEntry) => void;
     /** Injectable clocks keep wall timestamps and monotonic durations independently testable. */
     clock?: LifecycleClock;
+    /** Inject Codex-managed ChatGPT access sessions for deterministic tests. */
+    authBroker?: import('../../openai-oauth/codex-auth-broker.js').CodexAuthBroker;
 }
 export declare class CodexAppServerAgent extends BaseAgent {
     private deps;

package/dist/agents/codex-app-server/agent.js

@@ -15,6 +15,7 @@ import { resolveCodexModel } from '../codex-model.js';
 import { CodexMcpApprovalCorrelator, extractMcpToolApprovalRequest, hasScriptedApprovalPolicy, isMcpToolCallApprovalRequest, recordPolicyDeniedMcpToolCall } from './mcp-approval-correlator.js';
 import { projectItemIntoTurn } from './item-projection.js';
 import { CodexItemLifecycle, } from './item-lifecycle.js';
+import { createCodexManagedAuth } from './managed-auth.js';
 const TURN_COMPLETED_METHOD = 'turn/completed';
 function projectMcpStartupStatusIntoTurn(params, turn) {
     const name = params.name ?? 'unknown';
@@ -80,6 +81,12 @@ export class CodexAppServerAgent extends BaseAgent {
         let activeTurn = null;
         let disposed = false;
         let codexUserAgent = 'unknown';
+        const managedAuth = createCodexManagedAuth({
+            enabled: !runtimeEnv.OPENAI_API_KEY && !runtimeEnv.OPENAI_BASE_URL
+                && (this.deps.authBroker !== undefined || this.deps.createTransport === undefined),
+            ...(this.deps.authBroker ? { broker: this.deps.authBroker } : {}),
+            ...(runtimeEnv.CODEX_HOME ? { codexHome: runtimeEnv.CODEX_HOME } : {}),
+        });
         const scriptedHost = options?.scriptedMcpHost;
         const correlator = scriptedHost
             ? new CodexMcpApprovalCorrelator(scriptedHost, () => turnCounter, () => threadId, () => options?.getRemainingMs?.() ?? Number.POSITIVE_INFINITY)
@@ -92,8 +99,9 @@ export class CodexAppServerAgent extends BaseAgent {
             const factory = this.deps.createTransport
                 ?? (async (ctx) => spawnAppServerTransport({ cwd: ctx.workspacePath, env: ctx.env,
                     args: scriptedHost ? ['--enable', 'tool_call_mcp_elicitation'] : [] }));
-            handle = await factory({ workspacePath, env: runtimeEnv });
-            const transport = handle.transport;
+            const spawnedHandle = await factory({ workspacePath, env: runtimeEnv });
+            handle = spawnedHandle;
+            const transport = spawnedHandle.transport;
             transport.onServerRequest((req) => this.dispatchServerRequest(req, {
                 transport,
                 askBus,
@@ -102,6 +110,7 @@ export class CodexAppServerAgent extends BaseAgent {
                 mcpSafety: options?.mcpSafety,
                 scriptedHost,
                 correlator,
+                managedAuth,
             }));
             transport.onClose((info) => {
                 closeInfo = info;
@@ -132,17 +141,27 @@ export class CodexAppServerAgent extends BaseAgent {
                 if (params)
                     turn.itemLifecycle?.receiveCompleted(params);
             });
-            const initialized = await transport.sendRequest('initialize', {
-                clientInfo: { name: 'pathgrade', version: '0.5.0', title: null },
-                capabilities: { experimentalApi: true, optOutNotificationMethods: null },
+            const initialize = async () => {
+                const initialized = await transport.sendRequest('initialize', {
+                    clientInfo: { name: 'pathgrade', version: '0.5.0', title: null },
+                    capabilities: { experimentalApi: true, optOutNotificationMethods: null },
+                });
+                if (typeof initialized.userAgent === 'string') {
+                    codexUserAgent = initialized.userAgent.slice(0, 200);
+                }
+                // Upstream ClientNotification = { method: "initialized" }: send it
+                // before any thread/start so the handshake matches the v0.124
+                // contract and is forward-compatible with servers that enforce it.
+                transport.sendNotification('initialized', null);
+                await managedAuth.login(transport);
+                return transport;
+            };
+            return initialize().catch(async (error) => {
+                if (handle === spawnedHandle)
+                    handle = null;
+                await spawnedHandle.close().catch(() => undefined);
+                throw error;
             });
-            if (typeof initialized.userAgent === 'string')
-                codexUserAgent = initialized.userAgent.slice(0, 200);
-            // Upstream ClientNotification = { method: "initialized" }: send it
-            // before any thread/start so the handshake matches the v0.124
-            // contract and is forward-compatible with servers that enforce it.
-            transport.sendNotification('initialized', null);
-            return transport;
         };
         const runTurn = async (message) => {
             const t = await ensureTransport();
@@ -462,11 +481,11 @@ export class CodexAppServerAgent extends BaseAgent {
                 }
                 return;
             case 'account/chatgptAuthTokens/refresh': {
-                const message = 'codex app-server requires OPENAI_API_KEY for pathgrade and honors OPENAI_BASE_URL when set; ChatGPT/cached auth unsupported under transport=app-server';
-                transport.sendErrorResponse(req.id, -32001, message);
-                const turn = activeTurn();
-                if (turn)
-                    failTurn(turn, message);
+                ctx.managedAuth.respondToRefresh(req.id, transport, (message) => {
+                    const turn = activeTurn();
+                    if (turn)
+                        failTurn(turn, message);
+                });
                 return;
             }
             default:

package/dist/agents/codex-app-server/managed-auth.d.ts

@@ -0,0 +1,12 @@
+import { createDefaultCodexAuthBroker, type CodexAuthBroker } from '../../openai-oauth/codex-auth-broker.js';
+import type { AppServerTransport } from './transport.js';
+export interface CodexManagedAuth {
+    login(transport: AppServerTransport): Promise<void>;
+    respondToRefresh(requestId: number | string, transport: AppServerTransport, failTurn: (message: string) => void): void;
+}
+export declare function createCodexManagedAuth(input: {
+    enabled: boolean;
+    broker?: CodexAuthBroker;
+    codexHome?: string;
+    createBroker?: typeof createDefaultCodexAuthBroker;
+}): CodexManagedAuth;

package/dist/agents/codex-app-server/managed-auth.js

@@ -0,0 +1,53 @@
+import { createDefaultCodexAuthBroker, } from '../../openai-oauth/codex-auth-broker.js';
+const UNSUPPORTED_MESSAGE = 'codex app-server requires OPENAI_API_KEY for pathgrade and honors OPENAI_BASE_URL when set; ChatGPT/cached auth unsupported under transport=app-server';
+export function createCodexManagedAuth(input) {
+    let brokerPromise;
+    const broker = () => brokerPromise ??= input.broker
+        ? Promise.resolve(input.broker)
+        : (input.createBroker ?? createDefaultCodexAuthBroker)({
+            env: {
+                ...process.env,
+                ...(input.codexHome ? { CODEX_HOME: input.codexHome } : {}),
+            },
+        });
+    let refreshPromise;
+    const refresh = () => refreshPromise ??= broker()
+        .then((value) => value.acquireAccessSession({ refresh: true }))
+        .finally(() => { refreshPromise = undefined; });
+    return {
+        async login(transport) {
+            if (!input.enabled)
+                return;
+            try {
+                const session = await (await broker()).acquireAccessSession({ refresh: false });
+                await transport.sendRequest('account/login/start', {
+                    type: 'chatgptAuthTokens',
+                    accessToken: session.accessToken,
+                    chatgptAccountId: session.accountId,
+                    chatgptPlanType: null,
+                });
+            }
+            catch {
+                throw new Error('Codex-managed ChatGPT authentication unavailable');
+            }
+        },
+        respondToRefresh(requestId, transport, failTurn) {
+            if (!input.enabled) {
+                transport.sendErrorResponse(requestId, -32001, UNSUPPORTED_MESSAGE);
+                failTurn(UNSUPPORTED_MESSAGE);
+                return;
+            }
+            void refresh()
+                .then((session) => transport.sendResponse(requestId, {
+                accessToken: session.accessToken,
+                chatgptAccountId: session.accountId,
+                chatgptPlanType: null,
+            }))
+                .catch(() => {
+                const message = 'Codex-managed ChatGPT authentication refresh failed';
+                transport.sendErrorResponse(requestId, -32001, message);
+                failTurn(message);
+            });
+        },
+    };
+}

package/dist/agents/codex-app-server/transport.d.ts

@@ -44,6 +44,8 @@ export interface SpawnAppServerTransportInput {
      * Exposed for tests; defaults to 2s for production spawns.
      */
     killGracePeriodMs?: number;
+    /** Disable stderr logging for secret-bearing control-plane uses. */
+    logStderrOnExit?: boolean;
 }
 export declare function buildAppServerSpawnArgs(args?: readonly string[], env?: NodeJS.ProcessEnv): string[];
 /**

package/dist/agents/codex-app-server/transport.js

@@ -73,6 +73,12 @@ function createNdjsonTransportInternal(cfg) {
             return;
         output.write(JSON.stringify(obj) + '\n');
     };
+    const rejectPending = () => {
+        for (const resolver of pendingRequests.values()) {
+            resolver({ error: { code: -32_000, message: 'AppServerTransport closed' } });
+        }
+        pendingRequests.clear();
+    };
     return {
         sendRequest(method, params) {
             if (closed)
@@ -121,9 +127,10 @@ function createNdjsonTransportInternal(cfg) {
                 return;
             closed = true;
             rl.close();
-            pendingRequests.clear();
+            rejectPending();
         },
         notifyClose(info) {
+            rejectPending();
             for (const h of closeHandlers) {
                 try {
                     h(info);
@@ -234,15 +241,35 @@ export function spawnAppServerTransport(cfg = {}) {
         input: child.stdout,
         pid: child.pid,
     });
+    let spawnFailed = false;
+    child.on('error', () => {
+        spawnFailed = true;
+        transport.notifyClose({ exitCode: null, signal: null, pid: child.pid });
+    });
     child.on('exit', (exitCode, signal) => {
-        if (stderrBuf.trim().length > 0) {
+        if (cfg.logStderrOnExit !== false && stderrBuf.trim().length > 0) {
             console.error(`[codex app-server pid=${child.pid}] exited with code=${exitCode} signal=${signal}. stderr:\n${stderrBuf}`);
         }
         transport.notifyClose({ exitCode, signal, pid: child.pid });
     });
+    const sessionChild = {
+        pid: child.pid,
+        kill: (signal) => child.kill(signal),
+        once: (_event, listener) => {
+            const finish = () => {
+                child.off('exit', finish);
+                child.off('error', finish);
+                listener();
+            };
+            child.once('exit', finish);
+            child.once('error', finish);
+        },
+        get exitCode() { return spawnFailed ? -1 : child.exitCode; },
+        get signalCode() { return child.signalCode; },
+    };
     return createAppServerSessionHandle({
         transport,
-        child,
+        child: sessionChild,
         ...(cfg.killGracePeriodMs !== undefined ? { killGracePeriodMs: cfg.killGracePeriodMs } : {}),
     });
 }

package/dist/openai-oauth/chatgpt-oauth-llm.d.ts

@@ -0,0 +1,25 @@
+import type { ToolCapableLLMPort } from '../utils/llm-types.js';
+import { type CodexAuthBroker } from './codex-auth-broker.js';
+export interface ChatGptOAuthJudgeOptions {
+    model: string;
+    reasoningEffort: 'low' | 'medium' | 'high';
+    requestTimeoutMs?: number;
+}
+export type ChatGptOAuthJudgeErrorCode = 'OAUTH_CONFIG_INVALID' | 'OAUTH_DEPENDENCY_UNAVAILABLE' | 'OAUTH_CODEX_UNAVAILABLE' | 'OAUTH_CODEX_LOGIN_REQUIRED' | 'OAUTH_AUTH_TIMEOUT' | 'OAUTH_MODEL_MISMATCH' | 'OAUTH_MODEL_UNAVAILABLE' | 'OAUTH_REQUEST_TIMEOUT' | 'OAUTH_UPSTREAM_RATE_LIMITED' | 'OAUTH_UPSTREAM_FAILED' | 'OAUTH_PROTOCOL_RESPONSE_INVALID';
+export declare class ChatGptOAuthJudgeError extends Error {
+    readonly code: ChatGptOAuthJudgeErrorCode;
+    constructor(code: ChatGptOAuthJudgeErrorCode, message?: string);
+}
+type CoreModule = typeof import('@openai-oauth/core');
+export interface ChatGptOAuthJudgeDependencies {
+    broker?: CodexAuthBroker;
+    fetch?: typeof globalThis.fetch;
+    loadCore?: () => Promise<CoreModule>;
+    codexBinary?: string;
+    codexEnv?: NodeJS.ProcessEnv;
+    authTimeoutMs?: number;
+}
+export declare function createChatGptOAuthJudgeLLM(options: ChatGptOAuthJudgeOptions): ToolCapableLLMPort;
+/** Internal deterministic seam; intentionally omitted from the package subpath exports. */
+export declare function createChatGptOAuthJudgeLLMWithDependencies(options: ChatGptOAuthJudgeOptions, dependencies?: ChatGptOAuthJudgeDependencies): ToolCapableLLMPort;
+export {};

package/dist/openai-oauth/chatgpt-oauth-llm.js

@@ -0,0 +1,398 @@
+import { CodexAuthBrokerError, createCodexAuthBroker, } from './codex-auth-broker.js';
+const CORE_VERSION = '2.0.0';
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+export class ChatGptOAuthJudgeError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = 'ChatGptOAuthJudgeError';
+    }
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const oauthError = (code) => new ChatGptOAuthJudgeError(code);
+const mapBrokerError = (error) => {
+    if (error instanceof ChatGptOAuthJudgeError)
+        return error;
+    if (error instanceof CodexAuthBrokerError)
+        return oauthError(error.code);
+    if (error instanceof Error && error.name === 'AbortError')
+        return oauthError('OAUTH_REQUEST_TIMEOUT');
+    return oauthError('OAUTH_CODEX_UNAVAILABLE');
+};
+const normalizeProfile = (options) => {
+    if (options.model.trim().length === 0 ||
+        !['low', 'medium', 'high'].includes(options.reasoningEffort)) {
+        throw oauthError('OAUTH_CONFIG_INVALID');
+    }
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (!Number.isFinite(requestTimeoutMs) || !Number.isInteger(requestTimeoutMs) || requestTimeoutMs <= 0) {
+        throw oauthError('OAUTH_CONFIG_INVALID');
+    }
+    return Object.freeze({
+        model: options.model,
+        reasoningEffort: options.reasoningEffort,
+        requestTimeoutMs,
+    });
+};
+const loadCore = async () => {
+    try {
+        return await import('@openai-oauth/core');
+    }
+    catch {
+        throw new ChatGptOAuthJudgeError('OAUTH_DEPENDENCY_UNAVAILABLE', `OAUTH_DEPENDENCY_UNAVAILABLE: install @openai-oauth/core@${CORE_VERSION}`);
+    }
+};
+const createBoundedFetch = (timeoutMs, sourceFetch = globalThis.fetch) => async (input, init) => {
+    if (typeof sourceFetch !== 'function') {
+        throw oauthError('OAUTH_UPSTREAM_FAILED');
+    }
+    const timeoutController = new AbortController();
+    const timeout = setTimeout(() => timeoutController.abort(), timeoutMs);
+    timeout.unref?.();
+    const signal = init?.signal
+        ? AbortSignal.any([init.signal, timeoutController.signal])
+        : timeoutController.signal;
+    try {
+        return await sourceFetch(input, { ...init, signal });
+    }
+    catch (error) {
+        if (error instanceof ChatGptOAuthJudgeError ||
+            (error instanceof Error && error.name === 'AbortError')) {
+            throw error;
+        }
+        throw oauthError('OAUTH_UPSTREAM_FAILED');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+const classifyStatus = (status) => {
+    if (status === 401 || status === 403)
+        return oauthError('OAUTH_CODEX_LOGIN_REQUIRED');
+    if (status === 429)
+        return oauthError('OAUTH_UPSTREAM_RATE_LIMITED');
+    return oauthError('OAUTH_UPSTREAM_FAILED');
+};
+const assertModel = (profile, requested) => {
+    if (requested !== undefined && requested !== profile.model) {
+        throw oauthError('OAUTH_MODEL_MISMATCH');
+    }
+};
+const requestBody = (profile, input, instructions, tools) => ({
+    model: profile.model,
+    reasoning: { effort: profile.reasoningEffort },
+    instructions,
+    input,
+    ...(tools === undefined ? {} : {
+        tools,
+        tool_choice: tools.length === 0 ? 'none' : 'auto',
+        parallel_tool_calls: true,
+    }),
+});
+const toResponsesInput = (messages) => {
+    const input = [];
+    for (const message of messages) {
+        if (typeof message.content === 'string') {
+            input.push({
+                role: message.role,
+                content: [{
+                        type: message.role === 'assistant' ? 'output_text' : 'input_text',
+                        text: message.content,
+                    }],
+            });
+            continue;
+        }
+        let text = [];
+        const flushText = () => {
+            if (text.length === 0)
+                return;
+            input.push({
+                role: message.role,
+                content: text.map((block) => ({
+                    type: message.role === 'assistant' ? 'output_text' : 'input_text',
+                    text: block.text,
+                })),
+            });
+            text = [];
+        };
+        for (const block of message.content) {
+            if (block.type === 'text') {
+                text.push(block);
+                continue;
+            }
+            flushText();
+            if (block.type === 'tool_use') {
+                if (message.role !== 'assistant' || block.id.length === 0 || block.name.length === 0 ||
+                    !isRecord(block.input)) {
+                    throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+                }
+                input.push({
+                    type: 'function_call', call_id: block.id,
+                    name: block.name, arguments: JSON.stringify(block.input),
+                });
+            }
+            else if (block.type === 'tool_result') {
+                if (message.role !== 'user' || block.tool_use_id.length === 0) {
+                    throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+                }
+                input.push({
+                    type: 'function_call_output', call_id: block.tool_use_id,
+                    output: block.content,
+                });
+            }
+        }
+        flushText();
+    }
+    return input;
+};
+const safeToken = (value) => Number.isInteger(value) && value >= 0 ? value : undefined;
+const parseResponse = async (response) => {
+    if (!response.ok)
+        throw classifyStatus(response.status);
+    try {
+        const parsed = await response.json();
+        if (!isRecord(parsed) || parsed.status !== 'completed' || !Array.isArray(parsed.output)) {
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        }
+        for (const item of parsed.output)
+            validateOutputItem(item);
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof ChatGptOAuthJudgeError)
+            throw error;
+        throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+    }
+};
+const validateOutputItem = (value) => {
+    if (!isRecord(value) || !['reasoning', 'message', 'function_call'].includes(String(value.type))) {
+        throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+    }
+    if (value.type === 'function_call') {
+        if (value.status !== undefined && value.status !== 'completed') {
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        }
+        return;
+    }
+    if (value.type === 'reasoning')
+        return;
+    if (value.role !== 'assistant' || !Array.isArray(value.content)) {
+        throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+    }
+    for (const content of value.content) {
+        if (!isRecord(content) || content.type !== 'output_text' || typeof content.text !== 'string') {
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        }
+    }
+};
+const outputText = (result) => (result.output ?? []).flatMap((item) => Array.isArray(item.content) ? item.content : [])
+    .filter((item) => isRecord(item) && item.type === 'output_text')
+    .map((item) => typeof item.text === 'string' ? item.text : '')
+    .join('');
+const toolBlocks = (result, allowedNames) => {
+    const seenIds = new Set();
+    return (result.output ?? [])
+        .filter((item) => item.type === 'function_call')
+        .map((item) => {
+        if (typeof item.call_id !== 'string' || item.call_id.length === 0 ||
+            typeof item.name !== 'string' || item.name.length === 0 ||
+            !allowedNames.has(item.name) || typeof item.arguments !== 'string' ||
+            seenIds.has(item.call_id)) {
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        }
+        seenIds.add(item.call_id);
+        let input;
+        try {
+            input = JSON.parse(item.arguments);
+        }
+        catch {
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        }
+        if (!isRecord(input))
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        return { type: 'tool_use', id: item.call_id, name: item.name, input };
+    });
+};
+export function createChatGptOAuthJudgeLLM(options) {
+    return createChatGptOAuthJudgeLLMWithDependencies(options);
+}
+/** Internal deterministic seam; intentionally omitted from the package subpath exports. */
+export function createChatGptOAuthJudgeLLMWithDependencies(options, dependencies = {}) {
+    const profile = normalizeProfile(options);
+    const boundedFetch = createBoundedFetch(profile.requestTimeoutMs, dependencies.fetch);
+    let corePromise;
+    let brokerPromise;
+    let session;
+    let sessionGeneration = 0;
+    let acquirePromise;
+    let refreshPromise;
+    let transportPromise;
+    let preflight;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    const core = () => corePromise ??= (dependencies.loadCore ?? loadCore)();
+    const broker = () => brokerPromise ??= dependencies.broker
+        ? Promise.resolve(dependencies.broker)
+        : core().then((loaded) => createCodexAuthBroker({
+            ...(dependencies.codexBinary !== undefined ? { binary: dependencies.codexBinary } : {}),
+            ...(dependencies.codexEnv !== undefined ? { env: dependencies.codexEnv } : {}),
+            ...(dependencies.authTimeoutMs !== undefined ? { authTimeoutMs: dependencies.authTimeoutMs } : {}),
+            deriveAccountId: loaded.deriveAccountId,
+            deriveIsFedRamp: loaded.deriveChatGptAccountIsFedRamp,
+        }));
+    const getSession = async () => {
+        if (session)
+            return session;
+        acquirePromise ??= broker()
+            .then((value) => value.acquireAccessSession({ refresh: false }))
+            .then((value) => {
+            session = value;
+            sessionGeneration += 1;
+            return value;
+        })
+            .catch((error) => { throw mapBrokerError(error); })
+            .finally(() => { acquirePromise = undefined; });
+        return acquirePromise;
+    };
+    const refreshAfterUnauthorized = async (staleGeneration) => {
+        if (session && sessionGeneration !== staleGeneration)
+            return session;
+        refreshPromise ??= broker()
+            .then((value) => value.acquireAccessSession({ refresh: true }))
+            .then((value) => {
+            session = value;
+            sessionGeneration += 1;
+            // The core transport caches its model catalog by account. A catalog
+            // request made with an expired token can therefore cache the failure;
+            // rebuild it after refresh so the retry uses both the new token and a
+            // fresh catalog resolver.
+            transportPromise = undefined;
+            return value;
+        })
+            .catch((error) => { throw mapBrokerError(error); })
+            .finally(() => { refreshPromise = undefined; });
+        return refreshPromise;
+    };
+    const transport = () => transportPromise ??= core().then((loaded) => loaded.createOpenAIOAuthTransport({
+        auth: getSession,
+        codexVersion: '0.144.1',
+        fetch: boundedFetch,
+        responsesState: false,
+    }));
+    const requestWithAuthRetry = async (path, init, refreshStatuses = [401]) => {
+        await getSession();
+        const generation = sessionGeneration;
+        let response = await (await transport()).request(path, init);
+        if (!refreshStatuses.includes(response.status))
+            return response;
+        await refreshAfterUnauthorized(generation);
+        response = await (await transport()).request(path, init);
+        return response;
+    };
+    const ensurePreflight = () => preflight ??= (async () => {
+        const response = await requestWithAuthRetry('/v1/models', {
+            method: 'GET',
+            signal: AbortSignal.timeout(profile.requestTimeoutMs),
+        }, [401, 502]);
+        if (!response.ok)
+            throw classifyStatus(response.status);
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        }
+        // @openai-oauth/core normalizes the upstream Codex `models[].slug`
+        // catalog into this OpenAI-compatible `data[].id` response.
+        const compatibleModels = isRecord(parsed) && Array.isArray(parsed.data) ? parsed.data : [];
+        if (!compatibleModels.some((entry) => isRecord(entry) && entry.id === profile.model)) {
+            throw oauthError('OAUTH_MODEL_UNAVAILABLE');
+        }
+    })().catch((error) => {
+        preflight = undefined;
+        if (error instanceof ChatGptOAuthJudgeError)
+            throw error;
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw oauthError('OAUTH_REQUEST_TIMEOUT');
+        }
+        throw oauthError('OAUTH_UPSTREAM_FAILED');
+    });
+    const send = async (body) => {
+        await ensurePreflight();
+        try {
+            const response = await requestWithAuthRetry('/v1/responses', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(profile.requestTimeoutMs),
+            });
+            const result = await parseResponse(response);
+            inputTokens += safeToken(result.usage?.input_tokens) ?? 0;
+            outputTokens += safeToken(result.usage?.output_tokens) ?? 0;
+            return result;
+        }
+        catch (error) {
+            if (error instanceof ChatGptOAuthJudgeError)
+                throw error;
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw oauthError('OAUTH_REQUEST_TIMEOUT');
+            }
+            throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+        }
+    };
+    const port = {
+        get tokenUsage() { return { inputTokens, outputTokens }; },
+        get supportsToolUse() { return true; },
+        async measure(fn) {
+            const beforeInput = inputTokens;
+            const beforeOutput = outputTokens;
+            const result = await fn();
+            return {
+                result,
+                tokens: {
+                    inputTokens: inputTokens - beforeInput,
+                    outputTokens: outputTokens - beforeOutput,
+                },
+                costUsd: 0,
+            };
+        },
+        async call(prompt, callOptions = {}) {
+            assertModel(profile, callOptions.model);
+            const result = await send(requestBody(profile, [{
+                    role: 'user', content: [{ type: 'input_text', text: prompt }],
+                }], ''));
+            if ((result.output ?? []).some((item) => item.type === 'function_call')) {
+                throw oauthError('OAUTH_PROTOCOL_RESPONSE_INVALID');
+            }
+            return {
+                text: outputText(result),
+                inputTokens: safeToken(result.usage?.input_tokens),
+                outputTokens: safeToken(result.usage?.output_tokens),
+                provider: 'openai',
+                model: profile.model,
+            };
+        },
+        async callWithTools(messages, callOptions) {
+            assertModel(profile, callOptions.model);
+            const tools = callOptions.tools.map((tool) => ({
+                type: 'function',
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.input_schema,
+            }));
+            const result = await send(requestBody(profile, toResponsesInput(messages), callOptions.system ?? '', tools));
+            const blocks = toolBlocks(result, new Set(callOptions.tools.map((tool) => tool.name)));
+            const text = outputText(result);
+            const usage = {
+                inputTokens: safeToken(result.usage?.input_tokens),
+                outputTokens: safeToken(result.usage?.output_tokens),
+            };
+            return blocks.length > 0
+                ? { kind: 'tool_use', blocks, text: text || undefined, ...usage }
+                : { kind: 'final', text, ...usage };
+        },
+    };
+    return Object.freeze(port);
+}

package/dist/openai-oauth/codex-auth-broker.d.ts

@@ -0,0 +1,32 @@
+import type { OpenAIOAuthSession } from '@openai-oauth/core';
+import { type AppServerSessionHandle } from '../agents/codex-app-server/transport.js';
+export type CodexAuthBrokerErrorCode = 'OAUTH_CODEX_UNAVAILABLE' | 'OAUTH_CODEX_LOGIN_REQUIRED' | 'OAUTH_AUTH_TIMEOUT';
+export declare class CodexAuthBrokerError extends Error {
+    readonly code: CodexAuthBrokerErrorCode;
+    constructor(code: CodexAuthBrokerErrorCode);
+}
+export interface CodexAuthBroker {
+    acquireAccessSession(input: {
+        refresh: boolean;
+        signal?: AbortSignal;
+    }): Promise<OpenAIOAuthSession>;
+}
+export interface CodexAuthBrokerDependencies {
+    binary?: string;
+    env?: NodeJS.ProcessEnv;
+    authTimeoutMs?: number;
+    spawn?: (input: {
+        binary?: string;
+        env: NodeJS.ProcessEnv;
+    }) => AppServerSessionHandle;
+    deriveAccountId: (token: string | undefined) => string | undefined;
+    deriveIsFedRamp: (token: string | undefined) => boolean;
+}
+export declare const sanitizeCodexAuthEnvironment: (source?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+export declare function createCodexAuthBroker(deps: CodexAuthBrokerDependencies): CodexAuthBroker;
+/** Build the production broker lazily so @openai-oauth/core stays an optional runtime dependency. */
+export declare function createDefaultCodexAuthBroker(input?: {
+    binary?: string;
+    env?: NodeJS.ProcessEnv;
+    authTimeoutMs?: number;
+}): Promise<CodexAuthBroker>;

package/dist/openai-oauth/codex-auth-broker.js

@@ -0,0 +1,110 @@
+import { spawnAppServerTransport, } from '../agents/codex-app-server/transport.js';
+const DEFAULT_AUTH_TIMEOUT_MS = 10_000;
+const AUTH_ENV_ALLOWLIST = new Set([
+    'PATH', 'HOME', 'CODEX_HOME', 'SHELL', 'USER', 'LOGNAME',
+    'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM', 'TMPDIR', 'TMP', 'TEMP',
+    'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT',
+]);
+export class CodexAuthBrokerError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'CodexAuthBrokerError';
+    }
+}
+const brokerError = (code) => new CodexAuthBrokerError(code);
+export const sanitizeCodexAuthEnvironment = (source = process.env) => Object.fromEntries(Object.entries(source).filter(([name]) => AUTH_ENV_ALLOWLIST.has(name.toUpperCase())));
+const abortError = () => new DOMException('Aborted', 'AbortError');
+async function withDeadline(promise, timeoutMs, signal) {
+    if (signal?.aborted)
+        throw abortError();
+    let timeout;
+    let onAbort;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => reject(brokerError('OAUTH_AUTH_TIMEOUT')), timeoutMs);
+        timeout.unref?.();
+        if (signal) {
+            onAbort = () => reject(abortError());
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+    try {
+        return await Promise.race([promise, deadline]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+        if (signal && onAbort)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+export function createCodexAuthBroker(deps) {
+    const timeoutMs = deps.authTimeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS;
+    const spawn = deps.spawn ?? ((input) => spawnAppServerTransport({
+        ...input,
+        logStderrOnExit: false,
+    }));
+    return {
+        async acquireAccessSession({ refresh, signal }) {
+            let session;
+            try {
+                session = spawn({
+                    ...(deps.binary !== undefined ? { binary: deps.binary } : {}),
+                    env: sanitizeCodexAuthEnvironment(deps.env),
+                });
+                const operation = (async () => {
+                    await session.transport.sendRequest('initialize', {
+                        clientInfo: { name: 'pathgrade-auth', version: '1.0.0', title: null },
+                        capabilities: { experimentalApi: true, optOutNotificationMethods: null },
+                    });
+                    session.transport.sendNotification('initialized', null);
+                    const status = await session.transport.sendRequest('getAuthStatus', {
+                        includeToken: true,
+                        refreshToken: refresh,
+                    });
+                    if (status?.authMethod !== 'chatgpt') {
+                        throw brokerError('OAUTH_CODEX_LOGIN_REQUIRED');
+                    }
+                    if (typeof status.authToken !== 'string' || status.authToken.length === 0) {
+                        throw brokerError('OAUTH_CODEX_LOGIN_REQUIRED');
+                    }
+                    const accountId = deps.deriveAccountId(status.authToken);
+                    if (!accountId)
+                        throw brokerError('OAUTH_CODEX_LOGIN_REQUIRED');
+                    return {
+                        accessToken: status.authToken,
+                        accountId,
+                        isFedRamp: deps.deriveIsFedRamp(status.authToken),
+                    };
+                })();
+                return await withDeadline(operation, timeoutMs, signal);
+            }
+            catch (error) {
+                if (error instanceof CodexAuthBrokerError ||
+                    (error instanceof Error && error.name === 'AbortError')) {
+                    throw error;
+                }
+                throw brokerError('OAUTH_CODEX_UNAVAILABLE');
+            }
+            finally {
+                await session?.close().catch(() => undefined);
+            }
+        },
+    };
+}
+/** Build the production broker lazily so @openai-oauth/core stays an optional runtime dependency. */
+export async function createDefaultCodexAuthBroker(input = {}) {
+    let core;
+    try {
+        core = await import('@openai-oauth/core');
+    }
+    catch {
+        throw brokerError('OAUTH_CODEX_UNAVAILABLE');
+    }
+    return createCodexAuthBroker({
+        ...input,
+        deriveAccountId: core.deriveAccountId,
+        deriveIsFedRamp: core.deriveChatGptAccountIsFedRamp,
+    });
+}

package/dist/openai-oauth/index.d.ts

@@ -0,0 +1,2 @@
+export { ChatGptOAuthJudgeError, createChatGptOAuthJudgeLLM, } from './chatgpt-oauth-llm.js';
+export type { ChatGptOAuthJudgeErrorCode, ChatGptOAuthJudgeOptions, } from './chatgpt-oauth-llm.js';

package/dist/openai-oauth/index.js

@@ -0,0 +1 @@
+export { ChatGptOAuthJudgeError, createChatGptOAuthJudgeLLM, } from './chatgpt-oauth-llm.js';

package/dist/providers/credentials.d.ts

@@ -1,4 +1,4 @@
-import type { AgentName } from '../sdk/types.js';
+import type { AgentName, AgentTransport } from '../sdk/types.js';
 export interface CredentialPorts {
     /** Read a host environment variable. */
     hostEnv(key: string): string | undefined;
@@ -46,5 +46,6 @@ export interface CredentialResult {
 export declare function defaultPorts(): CredentialPorts;
 export interface CredentialContext {
     model?: string;
+    transport?: AgentTransport;
 }
 export declare function resolveCredentials(agent: AgentName, userEnv: Record<string, string>, ports?: CredentialPorts, context?: CredentialContext): Promise<CredentialResult>;

package/dist/providers/credentials.js

@@ -61,7 +61,7 @@ export async function resolveCredentials(agent, userEnv, ports, context = {}) {
         case 'claude':
             return resolveClaude(userEnv, p);
         case 'codex':
-            return resolveCodex(userEnv, p);
+            return resolveCodex(userEnv, p, context.transport);
         case 'cursor':
             return resolveCursor(userEnv, p);
         case 'opencode':
@@ -260,7 +260,7 @@ async function resolveCursor(userEnv, ports) {
     }
     return { env, setupCommands: [], copyFromHome: [], linkFromHome };
 }
-async function resolveCodex(userEnv, ports) {
+async function resolveCodex(userEnv, ports, transport) {
     const env = {};
     const setupCommands = [];
     const copyFromHome = [];
@@ -295,7 +295,7 @@ async function resolveCodex(userEnv, ports) {
             setupCommands.push('if [ ! -d "$HOME/.codex" ] && [ -n "${OPENAI_API_KEY:-}" ]; then printenv OPENAI_API_KEY | codex login --with-api-key >/dev/null 2>&1; fi');
         }
     }
-    else {
+    else if (transport !== 'app-server') {
         // No key — check for cached auth.json
         const authCachePath = path.join(ports.homedir, '.codex', 'auth.json');
         if (await ports.fileExists(authCachePath)) {

package/dist/providers/sandbox.d.ts

@@ -2,6 +2,8 @@ export interface SandboxConfig {
     agent: import('../sdk/types.js').AgentName;
     /** Internal provider/model context; ignored by sandbox creation itself. */
     model?: string;
+    /** Internal Codex transport context used while resolving credentials. */
+    transport?: import('../sdk/types.js').AgentTransport;
     workspace?: string;
     skillDir?: string;
     copyFromHome?: string[];

package/dist/providers/scripted-mcp-mock-host.d.ts

@@ -33,7 +33,10 @@ type Observer = (identity: {
     serverName: string;
     toolName: string;
 }) => void;
+type ResourceObserver = (activeTransports: number) => void;
 /** Non-public acceptance seam. It observes only authenticated manifest-member calls. */
 export declare function __setScriptedMcpMockObserverForTesting(observer: Observer | null): void;
+/** Non-public regression seam for request-scoped transport retention. */
+export declare function __setScriptedMcpMockResourceObserverForTesting(observer: ResourceObserver | null): void;
 export declare function startScriptedMcpMockHost(plan: CompiledMcpMockSession): Promise<ScriptedMcpMockHost>;
 export {};

package/dist/providers/scripted-mcp-mock-host.js

@@ -10,10 +10,15 @@ import { getOriginalMcpInput } from '../sdk/mcp-event-input.js';
 import { cloneToolEventWithRuntimeMetadata } from '../sdk/tool-event-secrets.js';
 import { createMcpArgumentDigest, createMcpReceiptKey, matchesMcpApprovalArguments, } from '../sdk/mcp-mock-approvals.js';
 let testObserver = null;
+let testResourceObserver = null;
 /** Non-public acceptance seam. It observes only authenticated manifest-member calls. */
 export function __setScriptedMcpMockObserverForTesting(observer) {
     testObserver = observer;
 }
+/** Non-public regression seam for request-scoped transport retention. */
+export function __setScriptedMcpMockResourceObserverForTesting(observer) {
+    testResourceObserver = observer;
+}
 const MAX_BODY_BYTES = 1024 * 1024;
 const MATCH_TIMEOUT_MS = 250;
 function isRecord(value) {
@@ -173,9 +178,37 @@ export async function startScriptedMcpMockHost(plan) {
             });
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
             activeTransports.add(transport);
-            transport.onclose = () => activeTransports.delete(transport);
-            await server.connect(transport);
-            await transport.handleRequest(req, res, body);
+            testResourceObserver?.(activeTransports.size);
+            const releaseTransport = () => {
+                if (activeTransports.delete(transport))
+                    testResourceObserver?.(activeTransports.size);
+            };
+            transport.onclose = releaseTransport;
+            let cleanupPromise;
+            const cleanup = () => {
+                cleanupPromise ??= (async () => {
+                    try {
+                        await server.close();
+                    }
+                    catch {
+                        await transport.close().catch(() => undefined);
+                    }
+                    finally {
+                        releaseTransport();
+                    }
+                })();
+                return cleanupPromise;
+            };
+            const cleanupOnResponseClose = () => { void cleanup(); };
+            res.once('close', cleanupOnResponseClose);
+            try {
+                await server.connect(transport);
+                await transport.handleRequest(req, res, body);
+            }
+            finally {
+                res.off('close', cleanupOnResponseClose);
+                await cleanup();
+            }
         }
         catch (error) {
             latch(error instanceof Error ? error : new Error(String(error)));

package/dist/providers/workspace.js

@@ -48,7 +48,10 @@ export async function prepareWorkspace(spec) {
     try {
         // Resolve credentials: pass user's original env (not sandboxEnv) so
         // the resolver can distinguish explicit user intent from auto-resolved values.
-        const creds = await resolveCredentials(spec.agent, spec.env ?? {}, undefined, { model: spec.model });
+        const creds = await resolveCredentials(spec.agent, spec.env ?? {}, undefined, {
+            model: spec.model,
+            transport: spec.transport,
+        });
         Object.assign(sandboxEnv, creds.env);
         await copyPathsFromHostHome(creds.copyFromHome, homePath);
         await linkPathsFromHostHome(creds.linkFromHome ?? [], homePath);

package/dist/sdk/agent.js

@@ -430,6 +430,7 @@ export async function createAgent(opts) {
     const workspace = await prepareWorkspace({
         ...rest,
         agent: agentName,
+        transport,
         mcp: scriptedMcp
             ? undefined
             : mcpConfigFile ? { configFile: mcpConfigFile } : mcpMock ? { mock: mcpMock } : undefined,

package/dist/sdk/judge-tools.js

@@ -69,10 +69,21 @@ async function checkFinalContainment(workspace, absolutePath) {
         return false;
     }
 }
+async function resolveExistingInWorkspace(workspace, relPath) {
+    const resolved = await resolveInWorkspace(workspace, relPath);
+    const [workspaceReal, targetReal] = await Promise.all([
+        fs.realpath(workspace),
+        fs.realpath(resolved),
+    ]);
+    if (!isInside(workspaceReal, targetReal)) {
+        throw new Error(`Path "${relPath}" is outside workspace`);
+    }
+    return targetReal;
+}
 export async function readFile(ctx, relPath) {
-    const resolved = await resolveInWorkspace(ctx.workspace, relPath);
     let content;
     try {
+        const resolved = await resolveExistingInWorkspace(ctx.workspace, relPath);
         content = await fs.readFile(resolved, 'utf8');
     }
     catch (err) {
@@ -88,9 +99,9 @@ export async function readFile(ctx, relPath) {
     return content;
 }
 export async function listDir(ctx, relPath) {
-    const resolved = await resolveInWorkspace(ctx.workspace, relPath);
     let entries;
     try {
+        const resolved = await resolveExistingInWorkspace(ctx.workspace, relPath);
         entries = await fs.readdir(resolved, { withFileTypes: true });
     }
     catch (err) {
@@ -107,7 +118,7 @@ export async function listDir(ctx, relPath) {
 }
 export async function grep(ctx, pattern, relPath) {
     const rootRel = relPath ?? '.';
-    const root = await resolveInWorkspace(ctx.workspace, rootRel);
+    const root = await resolveExistingInWorkspace(ctx.workspace, rootRel);
     const workspaceReal = await fs.realpath(ctx.workspace);
     const regex = new RegExp(pattern);
     const matches = [];

package/dist/utils/llm.js

@@ -1,3 +1,5 @@
+import { resolveCodexModel } from '../agents/codex-model.js';
+import { createChatGptOAuthJudgeLLM } from '../openai-oauth/chatgpt-oauth-llm.js';
 import { cliProvider } from './llm-providers/cli.js';
 import { anthropicProvider } from './llm-providers/anthropic.js';
 import { openaiProvider } from './llm-providers/openai.js';
@@ -191,6 +193,15 @@ export async function callLLM(prompt, opts = {}) {
  * the agent's env propagates to persona/judge/summarization calls.
  */
 export function createAgentLLM(agentName, agentEnv, agentModel) {
+    const effectiveAgentEnv = agentEnv ?? process.env;
+    if (agentName === 'codex'
+        && !effectiveAgentEnv.OPENAI_API_KEY
+        && !effectiveAgentEnv.OPENAI_BASE_URL) {
+        return createChatGptOAuthJudgeLLM({
+            model: resolveCodexModel(agentModel),
+            reasoningEffort: 'high',
+        });
+    }
     // Tool-using judges need a provider that implements callWithTools.
     // For claude, anthropicProvider is added as a tool-use-capable fallback
     // alongside the CLI. The CLI still wins for plain call() when available.

package/docs/OPENAI_OAUTH_JUDGE.md

@@ -0,0 +1,91 @@
+# Experimental Codex-authenticated ChatGPT judge
+
+Status: **experimental**. W0b passed for the direct
+`@openai-oauth/core@2.0.0` Responses mapping, and W0c passed for acquiring a
+managed ChatGPT access session from Codex App Server.
+
+## Install and authenticate
+
+Install the exact optional peer and sign in once with Codex:
+
+```bash
+yarn add -D @wix/pathgrade @openai-oauth/core@2.0.0
+codex login
+```
+
+Pathgrade starts a short-lived `codex app-server` child over stdio, calls only
+the auth-status RPC, then closes it before making the direct judge request. It
+does not read, copy, or write `~/.codex/auth.json`, receive a refresh token,
+open a local port, or start a Codex model thread. After a real upstream 401 it
+asks Codex to refresh, retries once, and otherwise fails closed.
+
+## Inject explicitly
+
+Codex agents select this judge automatically when neither `OPENAI_API_KEY` nor
+`OPENAI_BASE_URL` is present. The judge uses the resolved Codex model (Luna by
+default) with high reasoning effort. Passing `evaluate(agent, scorers, { llm })`
+remains the highest-precedence override. Explicit construction is available for
+other agents and custom flows:
+
+```typescript
+import { createChatGptOAuthJudgeLLM } from '@wix/pathgrade/openai-oauth';
+import { evaluate, judge } from '@wix/pathgrade';
+
+const llm = createChatGptOAuthJudgeLLM({
+    model: 'gpt-5.6-sol',
+    reasoningEffort: 'high',
+    requestTimeoutMs: 60_000,
+});
+
+const result = await evaluate(agent, [
+    judge('quality', { rubric: 'Apply the frozen rubric.', model: 'gpt-5.6-sol' }),
+], { llm });
+```
+
+The scorer model must exactly equal the factory model. There is no auth-file,
+API-key, base-URL, login callback, provider fallback, model rewrite, or default
+provider registration. Plain calls expose zero tools. Tool judges expose only
+their declared Pathgrade schemas through the existing bounded tool registry.
+
+## Stable public failures
+
+- `OAUTH_CONFIG_INVALID`
+- `OAUTH_DEPENDENCY_UNAVAILABLE`
+- `OAUTH_CODEX_UNAVAILABLE`
+- `OAUTH_CODEX_LOGIN_REQUIRED`
+- `OAUTH_AUTH_TIMEOUT`
+- `OAUTH_MODEL_MISMATCH`
+- `OAUTH_MODEL_UNAVAILABLE`
+- `OAUTH_REQUEST_TIMEOUT`
+- `OAUTH_UPSTREAM_RATE_LIMITED`
+- `OAUTH_UPSTREAM_FAILED`
+- `OAUTH_PROTOCOL_RESPONSE_INVALID`
+
+Tokens, Codex paths, auth JSON, prompts, App Server stderr/RPC text, upstream
+bodies, and tool results are never included in public errors. Failures never
+fall back to another provider.
+
+## Repository-only verification
+
+These maintainer probes run from a source checkout and are not included in the
+published npm package. Run them from the repository root.
+
+The no-cost installed-binary probe reports only version, auth-mode booleans,
+and its ADAPT/STOP verdict:
+
+```bash
+yarn smoke:codex-auth
+```
+
+The explicit paid live suite uses only the active Codex login. It exercises
+direct plain and bounded `readFile` judges, then a real keyless Codex app-server
+agent followed by automatically selected plain and `readFile` judges:
+
+```bash
+yarn test:evals:judge-oauth:live
+```
+
+It writes redacted reports to `.pathgrade/judge-oauth-live-smoke.{json,md}` and
+`.pathgrade/codex-oauth-agent-judge-e2e.json`.
+Any `@openai-oauth/core` or Codex protocol upgrade must rerun W0b, W0c, and
+the live smoke.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/pathgrade",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "packageManager": "yarn@4.12.0",
   "description": "Evaluate whether AI agents discover and use your skills correctly",
   "exports": {
@@ -44,6 +44,10 @@
       "types": "./dist/core/mcp-mock.d.ts",
       "default": "./dist/core/mcp-mock.js"
     },
+    "./openai-oauth": {
+      "types": "./dist/openai-oauth/index.d.ts",
+      "default": "./dist/openai-oauth/index.js"
+    },
     "./cli": {
       "types": "./dist/pathgrade.d.ts",
       "default": "./dist/pathgrade.js"
@@ -59,6 +63,7 @@
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
     "bin/",
+    "docs/OPENAI_OAUTH_JUDGE.md",
     "templates/",
     "README.md"
   ],
@@ -102,10 +107,14 @@
     "node": ">=20.19.0"
   },
   "peerDependencies": {
+    "@openai-oauth/core": "2.0.0",
     "jest": "^30.0.0",
     "vitest": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@openai-oauth/core": {
+      "optional": true
+    },
     "jest": {
       "optional": true
     },
@@ -114,11 +123,13 @@
     }
   },
   "devDependencies": {
+    "@openai-oauth/core": "2.0.0",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^30.0.0",
     "@types/picomatch": "^4.0.2",
     "@vitest/coverage-v8": "4.1.10",
     "jest": "^30.0.0",
+    "openai-oauth": "2.0.0",
     "vitest": "4.1.10"
   },
   "dependencies": {
@@ -133,5 +144,5 @@
     "typescript": "^5.9.3",
     "zod": "4.3.6"
   },
-  "falconPackageHash": "3b9bb9a9b04396a2419626ab26afcee636663d2a034597d2e4fcff92"
+  "falconPackageHash": "4b55cfec1102172799601d1b5a3a8089a73b9c5e093a4533316f1e7c"
 }