@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/codex-browser-auth.d.ts

@@ -0,0 +1,74 @@
+import { type CodexConnect } from './codex-rpc.js';
+import { type CodexModel } from './codex-auth.js';
+export interface CodexAuthState {
+    state: 'signedOut' | 'starting' | 'waiting' | 'signedIn' | 'cancelled' | 'error';
+    attemptId?: string;
+    email?: string;
+    planType?: string;
+    models?: CodexModel[];
+    message?: string;
+    reason?: 'unavailable' | 'timeout' | 'denied' | 'connectionClosed' | 'unsupported' | 'busy' | 'unverified' | 'catalogUnavailable' | 'logoutFailed';
+    /** Returned only by start, never by status or a notification. */
+    authUrl?: string;
+}
+/** An authorization link may open only the official browser ceremony, never a supplied callback. */
+export declare function codexBrowserAuthUrl(value: unknown): string;
+/** Owns browser login and its official Codex child; it never reads or exports credential files. */
+export declare class CodexBrowserAuth {
+    private view;
+    private active?;
+    private read?;
+    private signingOut?;
+    private generation;
+    private closed;
+    private readonly connect;
+    private readonly timeoutMs;
+    private readonly requestTimeoutMs;
+    constructor(options?: {
+        connect?: CodexConnect;
+        timeoutMs?: number;
+        requestTimeoutMs?: number;
+    });
+    private snapshot;
+    status(attemptId?: string): Promise<CodexAuthState>;
+    start(attemptId: string): Promise<CodexAuthState>;
+    cancel(attemptId: string): Promise<CodexAuthState>;
+    /** Sign out only the current ChatGPT account, never a different Codex credential mode. */
+    logout(): Promise<CodexAuthState>;
+    close(): Promise<void>;
+    private ownedConnection;
+    private models;
+    private verified;
+    private readStatus;
+    private signOut;
+    private run;
+    private cancelOfficial;
+    private stop;
+    private dispose;
+}
+/**
+ * One browser sign-in manager per Codex account home.
+ *
+ * Codex carries a single active ChatGPT session per `CODEX_HOME`, so several linked accounts are
+ * several homes, and each home's sign-in state must be told apart: a status read for one account
+ * must never answer with another's, and a sign-out must reach only the account it names. The
+ * default home keeps the unsuffixed manager, which is what every window used before accounts
+ * existed, so a client that names no provider keeps the behaviour it has always had.
+ */
+export declare class CodexAccountAuth {
+    private readonly options;
+    private readonly managers;
+    private readonly connectForHome;
+    constructor(options?: {
+        connect?: CodexConnect;
+        connectForHome?: (home: string | undefined) => CodexConnect;
+        timeoutMs?: number;
+        requestTimeoutMs?: number;
+    });
+    private manager;
+    status(attemptId?: string, home?: string): Promise<CodexAuthState>;
+    start(attemptId: string, home?: string): Promise<CodexAuthState>;
+    cancel(attemptId: string, home?: string): Promise<CodexAuthState>;
+    logout(home?: string): Promise<CodexAuthState>;
+    close(): Promise<void>;
+}

package/dist/src/codex-browser-auth.js

@@ -0,0 +1,429 @@
+import { connectCodex } from './codex-rpc.js';
+import { readCodexModels } from './codex-auth.js';
+class AuthFailure extends Error {
+    reason;
+    constructor(message, reason = 'unavailable') {
+        super(message);
+        this.reason = reason;
+    }
+}
+const unavailable = 'Could not communicate with Codex. Install or update the official Codex CLI, then try again.';
+const interrupted = 'The Codex connection closed during ChatGPT sign-in. Try signing in again.';
+const timedOut = 'ChatGPT sign-in timed out. Try signing in again.';
+const cancelled = 'ChatGPT sign-in cancelled.';
+const logoutFailed = 'ChatGPT sign-out could not be confirmed. Refresh status and try again.';
+function validAttempt(id) { return typeof id === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(id); }
+function closeRpc(rpc) { try {
+    rpc?.close();
+}
+catch { /* Never forward child diagnostics. */ } }
+function copy(view) {
+    return { ...view, ...(view.models === undefined ? {} : { models: view.models.map(model => ({ ...model })) }) };
+}
+/** An authorization link may open only the official browser ceremony, never a supplied callback. */
+export function codexBrowserAuthUrl(value) {
+    if (typeof value !== 'string' || value.length > 16_384)
+        throw new AuthFailure('Codex returned an unsupported sign-in URL. Update the official Codex CLI and try again.', 'unsupported');
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new AuthFailure('Codex returned an unsupported sign-in URL. Update the official Codex CLI and try again.', 'unsupported');
+    }
+    if (url.protocol !== 'https:' || !['auth.openai.com', 'chatgpt.com'].includes(url.hostname) || url.username || url.password || url.hash || url.port) {
+        throw new AuthFailure('Codex returned an unsupported sign-in URL. Update the official Codex CLI and try again.', 'unsupported');
+    }
+    for (const name of url.searchParams.keys()) {
+        if (['access_token', 'refresh_token', 'id_token', 'accesstoken', 'refreshtoken', 'idtoken', 'client_secret', 'token', 'code'].includes(name.toLowerCase())) {
+            throw new AuthFailure('Codex returned an unsupported sign-in URL. Update the official Codex CLI and try again.', 'unsupported');
+        }
+    }
+    if (url.searchParams.getAll('redirect_uri').length > 1)
+        throw new AuthFailure('Codex returned an unsupported sign-in callback. Update the official Codex CLI and try again.', 'unsupported');
+    const redirect = url.searchParams.get('redirect_uri');
+    if (redirect !== null) {
+        let callback;
+        try {
+            callback = new URL(redirect);
+        }
+        catch {
+            throw new AuthFailure('Codex returned an unsupported sign-in callback. Update the official Codex CLI and try again.', 'unsupported');
+        }
+        if (callback.protocol !== 'http:' || !['localhost', '127.0.0.1', '[::1]'].includes(callback.hostname) || callback.pathname !== '/auth/callback' || callback.username || callback.password || callback.hash || callback.search) {
+            throw new AuthFailure('Codex returned an unsupported sign-in callback. Update the official Codex CLI and try again.', 'unsupported');
+        }
+    }
+    return url.href;
+}
+function accountView(result) {
+    if (result?.account?.type !== 'chatgpt')
+        return undefined;
+    const account = result.account;
+    return {
+        ...(typeof account.email === 'string' && account.email.length <= 320 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(account.email) ? { email: account.email } : {}),
+        ...(typeof account.planType === 'string' && /^[A-Za-z0-9 _-]{1,64}$/.test(account.planType) ? { planType: account.planType } : {}),
+    };
+}
+function within(task, signal, ms) {
+    return new Promise((resolve, reject) => {
+        const finish = (action) => { clearTimeout(timer); signal.removeEventListener('abort', abort); action(); };
+        const abort = () => finish(() => reject(new AuthFailure(cancelled)));
+        const timer = setTimeout(() => finish(() => reject(new AuthFailure(timedOut, 'timeout'))), ms);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        task.then(value => finish(() => resolve(value)), error => finish(() => reject(error)));
+    });
+}
+/** Owns browser login and its official Codex child; it never reads or exports credential files. */
+export class CodexBrowserAuth {
+    view = { state: 'signedOut' };
+    active;
+    read;
+    signingOut;
+    generation = 0;
+    closed = false;
+    connect;
+    timeoutMs;
+    requestTimeoutMs;
+    constructor(options = {}) {
+        this.connect = options.connect ?? connectCodex;
+        this.timeoutMs = options.timeoutMs ?? 15 * 60_000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+    }
+    snapshot() { return copy(this.view); }
+    async status(attemptId) {
+        if (attemptId !== undefined && !validAttempt(attemptId))
+            return { state: 'error', reason: 'unsupported', message: 'A valid ChatGPT sign-in attempt ID is required.' };
+        if (this.closed)
+            return { state: 'error', reason: 'connectionClosed', message: 'The Codex sign-in service has closed.' };
+        if (this.signingOut)
+            return this.signingOut.task;
+        if (attemptId && this.view.attemptId !== attemptId)
+            return { state: 'cancelled', attemptId, message: 'This ChatGPT sign-in attempt is no longer active.' };
+        if (this.active || attemptId)
+            return this.snapshot();
+        if (this.read)
+            return this.read.task;
+        const controller = new AbortController();
+        const generation = this.generation;
+        const holder = { controller, task: Promise.resolve({ state: 'signedOut' }) };
+        this.read = holder;
+        holder.task = this.readStatus(controller).then(view => {
+            if (!this.closed && generation === this.generation && !this.active)
+                this.view = view;
+            return this.snapshot();
+        }).finally(() => { if (this.read === holder)
+            this.read = undefined; });
+        return holder.task;
+    }
+    start(attemptId) {
+        if (!validAttempt(attemptId))
+            return Promise.resolve({ state: 'error', reason: 'unsupported', message: 'A valid ChatGPT sign-in attempt ID is required.' });
+        if (this.closed)
+            return Promise.resolve({ state: 'error', reason: 'connectionClosed', attemptId, message: 'The Codex sign-in service has closed.' });
+        if (this.signingOut)
+            return Promise.resolve({ state: 'error', reason: 'busy', attemptId, message: 'ChatGPT sign-out is in progress. Wait for it to finish before signing in.' });
+        if (this.active) {
+            if (this.active.id === attemptId)
+                return this.active.stopped ? Promise.resolve(this.snapshot()) : this.active.ready.then(copy);
+            return Promise.resolve({ state: 'error', reason: 'busy', attemptId, message: 'Another ChatGPT sign-in is already in progress. Finish or cancel it first.' });
+        }
+        if (this.view.attemptId === attemptId)
+            return Promise.resolve(this.snapshot());
+        this.read?.controller.abort();
+        this.generation++;
+        let resolveReady;
+        const ready = new Promise(resolve => { resolveReady = resolve; });
+        const attempt = { id: attemptId, controller: new AbortController(), ready, resolveReady: value => resolveReady(copy(value)), stopped: false, succeeded: false };
+        this.active = attempt;
+        this.view = { state: 'starting', attemptId };
+        attempt.timer = setTimeout(() => { void this.stop(attempt, 'error', timedOut, 'timeout'); }, this.timeoutMs);
+        attempt.task = this.run(attempt);
+        return ready.then(copy);
+    }
+    async cancel(attemptId) {
+        if (!validAttempt(attemptId))
+            return { state: 'error', reason: 'unsupported', message: 'A valid ChatGPT sign-in attempt ID is required.' };
+        const attempt = this.active;
+        if (attempt?.id === attemptId)
+            await this.stop(attempt, 'cancelled', cancelled);
+        else if (this.view.attemptId !== attemptId)
+            return { state: 'cancelled', attemptId, message: 'This ChatGPT sign-in attempt is no longer active.' };
+        return this.snapshot();
+    }
+    /** Sign out only the current ChatGPT account, never a different Codex credential mode. */
+    logout() {
+        if (this.closed)
+            return Promise.resolve({ state: 'error', reason: 'connectionClosed', message: 'The Codex sign-in service has closed.' });
+        if (this.signingOut)
+            return this.signingOut.task.then(copy);
+        if (this.active)
+            return Promise.resolve({ state: 'error', reason: 'busy', message: 'A ChatGPT sign-in is in progress. Finish or cancel it before signing out.' });
+        this.read?.controller.abort();
+        const generation = ++this.generation;
+        const previous = this.snapshot();
+        const holder = { controller: new AbortController(), task: Promise.resolve({ state: 'signedOut' }) };
+        this.signingOut = holder;
+        holder.task = this.signOut(holder.controller, previous).then(view => {
+            if (!this.closed && generation === this.generation)
+                this.view = view;
+            return copy(view);
+        }).finally(() => { if (this.signingOut === holder)
+            this.signingOut = undefined; });
+        return holder.task;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.generation++;
+        const read = this.read;
+        read?.controller.abort();
+        const signingOut = this.signingOut;
+        signingOut?.controller.abort();
+        const attempt = this.active;
+        if (attempt)
+            await this.stop(attempt, 'cancelled', cancelled);
+        if (read)
+            await read.task;
+        if (signingOut)
+            await signingOut.task;
+    }
+    async ownedConnection(controller) {
+        const task = this.connect(controller.signal).then(rpc => {
+            if (controller.signal.aborted) {
+                closeRpc(rpc);
+                throw new AuthFailure(cancelled);
+            }
+            return rpc;
+        });
+        return within(task, controller.signal, this.requestTimeoutMs);
+    }
+    async models(rpc, signal) {
+        const models = await within(readCodexModels(rpc, { includeHidden: true }), signal, this.requestTimeoutMs);
+        return models.filter(model => model.id.length > 0 && model.id.length <= 512 && !/[\r\n\x00]/.test(model.id)).map(model => ({ id: model.id, isDefault: model.isDefault === true }));
+    }
+    async verified(rpc, signal, attemptId) {
+        const account = accountView(await within(rpc.request('account/read', { refreshToken: false }), signal, this.requestTimeoutMs));
+        if (!account)
+            return { state: 'signedOut', ...(attemptId ? { attemptId } : {}) };
+        try {
+            return { state: 'signedIn', ...(attemptId ? { attemptId } : {}), ...account, models: await this.models(rpc, signal), message: 'Signed in with ChatGPT. Model availability can vary by account.' };
+        }
+        catch {
+            signal.throwIfAborted();
+            return { state: 'signedIn', reason: 'catalogUnavailable', ...(attemptId ? { attemptId } : {}), ...account, models: [], message: 'Signed in with ChatGPT. The model list could not be loaded; refresh or enter a model ID manually.' };
+        }
+    }
+    async readStatus(controller) {
+        let rpc;
+        let expired = false;
+        const timer = setTimeout(() => { expired = true; controller.abort(); }, this.requestTimeoutMs);
+        try {
+            rpc = await this.ownedConnection(controller);
+            return await this.verified(rpc, controller.signal);
+        }
+        catch (error) {
+            return { state: 'error', reason: expired ? 'timeout' : error instanceof AuthFailure ? error.reason : 'unavailable', message: expired ? timedOut : error instanceof AuthFailure ? error.message : unavailable };
+        }
+        finally {
+            clearTimeout(timer);
+            controller.abort();
+            closeRpc(rpc);
+        }
+    }
+    async signOut(controller, previous) {
+        let rpc;
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            rpc = await this.ownedConnection(controller);
+            const before = await within(rpc.request('account/read', { refreshToken: false }), controller.signal, this.requestTimeoutMs);
+            controller.signal.throwIfAborted();
+            if (before?.account === null)
+                return { state: 'signedOut' };
+            if (before?.account && typeof before.account.type === 'string' && before.account.type !== 'chatgpt') {
+                // The account could have changed since the last window refresh. Preserve API keys and
+                // other official credential modes instead of calling their generic logout endpoint.
+                return { state: 'signedOut' };
+            }
+            const account = accountView(before);
+            if (!account)
+                throw new AuthFailure(logoutFailed, 'logoutFailed');
+            await within(rpc.request('account/logout'), controller.signal, this.requestTimeoutMs);
+            const after = await within(rpc.request('account/read', { refreshToken: false }), controller.signal, this.requestTimeoutMs);
+            if (after?.account !== null)
+                throw new AuthFailure(logoutFailed, 'logoutFailed');
+            controller.signal.throwIfAborted();
+            return { state: 'signedOut' };
+        }
+        catch {
+            // A failed response can follow a successful logout. Never put the old signed-in account
+            // back on screen without a fresh observation of the actual official credential state.
+            if (rpc && !controller.signal.aborted) {
+                try {
+                    const observed = await within(rpc.request('account/read', { refreshToken: false }), controller.signal, this.requestTimeoutMs);
+                    controller.signal.throwIfAborted();
+                    if (observed?.account === null)
+                        return { state: 'signedOut' };
+                    const current = accountView(observed);
+                    if (current)
+                        return { state: 'signedIn', ...current,
+                            ...(previous.state === 'signedIn' && previous.email === current.email && previous.planType === current.planType && previous.models
+                                ? { models: previous.models } : {}), reason: 'logoutFailed', message: logoutFailed };
+                }
+                catch { /* State is unknown; no raw error or previously cached identity is exposed. */ }
+            }
+            return { state: 'error', reason: 'logoutFailed', message: logoutFailed };
+        }
+        finally {
+            clearTimeout(timer);
+            controller.abort();
+            closeRpc(rpc);
+        }
+    }
+    async run(attempt) {
+        const signal = attempt.controller.signal;
+        try {
+            const rpc = await this.ownedConnection(attempt.controller);
+            attempt.rpc = rpc;
+            const existing = await this.verified(rpc, signal, attempt.id);
+            if (existing.state === 'signedIn') {
+                if (!attempt.stopped) {
+                    attempt.succeeded = true;
+                    this.view = existing;
+                    attempt.resolveReady(this.snapshot());
+                }
+                return;
+            }
+            let settle;
+            let fail;
+            let connectionClosed = false;
+            const completions = new Map();
+            const completed = new Promise((resolve, reject) => { settle = resolve; fail = reject; });
+            // Observe a rejection even while account/login/start is still in flight.
+            void completed.catch(() => { });
+            attempt.unsubscribe = rpc.onNotification((method, params) => {
+                if (method === 'andorra/connectionClosed') {
+                    connectionClosed = true;
+                    fail(new AuthFailure(interrupted, 'connectionClosed'));
+                }
+                if (method !== 'account/login/completed' || typeof params?.loginId !== 'string' || params.loginId.length === 0 || params.loginId.length > 512 || typeof params.success !== 'boolean')
+                    return;
+                if (params.loginId === attempt.loginId)
+                    settle({ success: params.success });
+                else if (completions.size < 32 && !completions.has(params.loginId))
+                    completions.set(params.loginId, { success: params.success });
+            });
+            const login = await within(rpc.request('account/login/start', { type: 'chatgpt' }), signal, this.requestTimeoutMs);
+            if (typeof login?.loginId === 'string' && login.loginId.length > 0 && login.loginId.length <= 512)
+                attempt.loginId = login.loginId;
+            if (login?.type !== 'chatgpt' || !attempt.loginId)
+                throw new AuthFailure('Codex does not support browser sign-in. Update the official Codex CLI and try again.', 'unsupported');
+            const authUrl = codexBrowserAuthUrl(login.authUrl);
+            signal.throwIfAborted();
+            if (connectionClosed)
+                throw new AuthFailure(interrupted, 'connectionClosed');
+            const early = completions.get(attempt.loginId);
+            if (!early && !attempt.stopped) {
+                this.view = { state: 'waiting', attemptId: attempt.id, message: 'Waiting for ChatGPT sign-in in your browser.' };
+                attempt.resolveReady({ ...this.snapshot(), authUrl });
+            }
+            const result = early ?? await within(completed, signal, this.timeoutMs);
+            if (attempt.stopped)
+                return;
+            if (!result.success)
+                throw new AuthFailure('ChatGPT sign-in did not complete. Try signing in again.', 'denied');
+            const verified = await this.verified(rpc, signal, attempt.id);
+            if (verified.state !== 'signedIn')
+                throw new AuthFailure('Codex did not confirm a ChatGPT account. Try signing in again.', 'unverified');
+            if (!attempt.stopped) {
+                attempt.succeeded = true;
+                this.view = verified;
+                attempt.resolveReady(this.snapshot());
+            }
+        }
+        catch (error) {
+            if (!attempt.stopped) {
+                this.view = { state: 'error', attemptId: attempt.id, reason: error instanceof AuthFailure ? error.reason : 'unavailable', message: error instanceof AuthFailure ? error.message : unavailable };
+                attempt.resolveReady(this.snapshot());
+            }
+        }
+        finally {
+            if (!attempt.stopped) {
+                if (!attempt.succeeded)
+                    await this.cancelOfficial(attempt);
+                this.dispose(attempt);
+            }
+        }
+    }
+    async cancelOfficial(attempt) {
+        if (!attempt.rpc || !attempt.loginId || attempt.controller.signal.aborted)
+            return;
+        try {
+            await within(attempt.rpc.request('account/login/cancel', { loginId: attempt.loginId }), attempt.controller.signal, Math.min(this.requestTimeoutMs, 1_000));
+        }
+        catch { /* Closing the owned app-server below also releases its local callback. */ }
+    }
+    stop(attempt, state, message, reason) {
+        if (attempt.stopTask)
+            return attempt.stopTask;
+        attempt.stopped = true;
+        this.view = { state, attemptId: attempt.id, message, ...(reason ? { reason } : {}) };
+        attempt.resolveReady(this.snapshot());
+        if (attempt.timer !== undefined)
+            clearTimeout(attempt.timer);
+        attempt.stopTask = (async () => {
+            await this.cancelOfficial(attempt);
+            attempt.controller.abort();
+            closeRpc(attempt.rpc);
+            await attempt.task;
+            this.dispose(attempt);
+        })();
+        return attempt.stopTask;
+    }
+    dispose(attempt) {
+        if (attempt.timer !== undefined)
+            clearTimeout(attempt.timer);
+        attempt.unsubscribe?.();
+        attempt.controller.abort();
+        closeRpc(attempt.rpc);
+        if (this.active === attempt)
+            this.active = undefined;
+    }
+}
+/**
+ * One browser sign-in manager per Codex account home.
+ *
+ * Codex carries a single active ChatGPT session per `CODEX_HOME`, so several linked accounts are
+ * several homes, and each home's sign-in state must be told apart: a status read for one account
+ * must never answer with another's, and a sign-out must reach only the account it names. The
+ * default home keeps the unsuffixed manager, which is what every window used before accounts
+ * existed, so a client that names no provider keeps the behaviour it has always had.
+ */
+export class CodexAccountAuth {
+    options;
+    managers = new Map();
+    connectForHome;
+    constructor(options = {}) {
+        this.options = options;
+        this.connectForHome = options.connectForHome ?? (home => home === undefined
+            ? options.connect ?? connectCodex
+            : signal => connectCodex(signal, { home }));
+    }
+    manager(home) {
+        const key = home ?? '';
+        let manager = this.managers.get(key);
+        if (!manager) {
+            manager = new CodexBrowserAuth({ connect: this.connectForHome(home), ...(this.options.timeoutMs === undefined ? {} : { timeoutMs: this.options.timeoutMs }), ...(this.options.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: this.options.requestTimeoutMs }) });
+            this.managers.set(key, manager);
+        }
+        return manager;
+    }
+    status(attemptId, home) { return this.manager(home).status(attemptId); }
+    start(attemptId, home) { return this.manager(home).start(attemptId); }
+    cancel(attemptId, home) { return this.manager(home).cancel(attemptId); }
+    logout(home) { return this.manager(home).logout(); }
+    async close() { await Promise.all([...this.managers.values()].map(manager => manager.close().catch(() => { }))); this.managers.clear(); }
+}

package/dist/src/codex-errors.d.ts

@@ -0,0 +1,3 @@
+import { ProviderRequestError } from './providers.js';
+export declare function codexTurnFailure(error: unknown): ProviderRequestError;
+export declare function codexRequestFailure(error: unknown): ProviderRequestError;

package/dist/src/codex-errors.js

@@ -0,0 +1,50 @@
+import { ProviderRequestError } from './providers.js';
+// Provider text, additionalDetails and policy continuation instructions may contain secrets or
+// task content. Only protocol-defined categories and a valid HTTP status reach local diagnostics.
+const descriptions = {
+    contextWindowExceeded: 'input exceeds the context window',
+    sessionBudgetExceeded: 'the session budget was exceeded',
+    usageLimitExceeded: 'the account usage limit was reached',
+    rateLimitExceeded: 'the provider rate limit was reached',
+    flexUnavailable: 'the requested service tier is unavailable',
+    serverOverloaded: 'the provider is overloaded',
+    cyberPolicy: 'the provider declined the request under its cyber policy',
+    misalignmentPolicyViolation: 'the provider declined the request under its policy',
+    tooManyDenials: 'the provider stopped after repeated denials',
+    internalServerError: 'the provider encountered an internal error',
+    unauthorized: 'the provider rejected authentication; check Codex sign-in',
+    badRequest: 'the provider rejected the request parameters',
+    threadRollbackFailed: 'the provider could not roll back the thread',
+    sandboxError: 'the native Codex sandbox failed',
+    httpConnectionFailed: 'the provider connection failed',
+    responseStreamConnectionFailed: 'the provider response stream could not connect',
+    responseStreamDisconnected: 'the provider response stream disconnected',
+    responseTooManyFailedAttempts: 'the provider exhausted its response retries',
+    activeTurnNotSteerable: 'the active turn cannot accept steering',
+};
+const objectCategories = ['httpConnectionFailed', 'responseStreamConnectionFailed', 'responseStreamDisconnected', 'responseTooManyFailedAttempts', 'activeTurnNotSteerable'];
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+export function codexTurnFailure(error) {
+    const info = record(error) ? error.codexErrorInfo : undefined;
+    let category;
+    let status;
+    if (typeof info === 'string' && Object.hasOwn(descriptions, info))
+        category = info;
+    else if (record(info)) {
+        const keys = Object.keys(info);
+        if (keys.length === 1 && objectCategories.includes(keys[0]) && record(info[keys[0]])) {
+            category = keys[0];
+            if (category !== 'activeTurnNotSteerable')
+                status = info[category].httpStatusCode;
+        }
+    }
+    const http = typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599 ? `; HTTP ${status}` : '';
+    return new ProviderRequestError(category
+        ? `Codex inference failed (${category}${http}): ${descriptions[category]}.`
+        : 'Codex inference failed', category === 'contextWindowExceeded');
+}
+export function codexRequestFailure(error) {
+    const code = record(error) ? error.code : undefined;
+    const safeCode = typeof code === 'number' && Number.isSafeInteger(code) ? String(code) : 'unknown';
+    return new ProviderRequestError(`Codex rejected the request (${safeCode}). Check Codex sign-in and version.`);
+}

package/dist/src/codex-executable.d.ts

@@ -0,0 +1,12 @@
+export interface CodexExecutableOptions {
+    platform?: NodeJS.Platform;
+    arch?: string;
+    env?: NodeJS.ProcessEnv;
+    extraCandidates?: string[];
+    validateCandidate?: (candidate: string) => Promise<string | undefined>;
+    signal?: AbortSignal;
+    /** Read-only package query injection for deterministic tests. */
+    queryWindowsPackage?: (signal?: AbortSignal) => Promise<string>;
+}
+/** Resolve npm shims to the packaged native binary, never through cmd.exe. */
+export declare function resolveCodexExecutable(options?: CodexExecutableOptions): Promise<string>;