@agentionai/agents 1.12.0 → 1.13.0

package/dist/agents/openai/OpenAiAgent.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenAiAgent = void 0;
 exports.lowestReasoningEffort = lowestReasoningEffort;
+exports.wrapErrorBodyFetch = wrapErrorBodyFetch;
+exports.describeOpenAIError = describeOpenAIError;
 const openai_1 = __importDefault(require("openai"));
 const BaseAgent_1 = require("../BaseAgent");
 const AgentEvent_1 = require("../AgentEvent");
@@ -38,6 +40,81 @@ function lowestReasoningEffort(model) {
     const group = model_types_1.OPENAI_REASONING_SUPPORT.find((entry) => entry.models.includes(base));
     return group?.efforts[0];
 }
+/**
+ * `fetch` wrapper that rewrites a non-OpenAI-shaped error body into the shape
+ * the SDK can read.
+ *
+ * `APIError.generate` takes the message from `body.error` and throws the rest
+ * away (`openai/core/error.js`), so a backend that reports failures as
+ * `{"detail": "..."}` — which the ChatGPT Codex endpoint does, for all four of
+ * its body validations plus auth failures — surfaces as the useless
+ * `400 status code (no body)`. Nesting the original body under `error` puts the
+ * real reason back in the thrown error.
+ *
+ * Only touches error responses; successful (streaming) responses pass straight
+ * through untouched.
+ */
+function wrapErrorBodyFetch(baseFetch = fetch) {
+    return async (input, init) => {
+        const res = await baseFetch(input, init);
+        if (res.ok)
+            return res;
+        const text = await res.text().catch(() => "");
+        let body = text;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === "object" && !("error" in parsed)) {
+                body = JSON.stringify({
+                    error: {
+                        message: typeof parsed.detail === "string"
+                            ? parsed.detail
+                            : JSON.stringify(parsed),
+                        ...parsed,
+                    },
+                });
+            }
+        }
+        catch {
+            // Not JSON (an HTML error page, say) — hand the text back unchanged so
+            // the SDK reports it as the message.
+        }
+        // Reading the body consumed it, so the Response has to be rebuilt. Drop the
+        // length/encoding headers, which no longer describe the new payload.
+        const headers = new Headers(res.headers);
+        headers.delete("content-length");
+        headers.delete("content-encoding");
+        // `globalThis.Response`, not `Response`: this module imports the Responses
+        // API's `Response` *type*, which shadows the global class name here.
+        return new globalThis.Response(body, {
+            status: res.status,
+            statusText: res.statusText,
+            headers,
+        });
+    };
+}
+/**
+ * Pull a human-readable message out of an OpenAI-shaped error.
+ *
+ * `api.openai.com` answers with `{ error: { message, code } }`, but not every
+ * host behind this SDK does — the ChatGPT Codex backend reports its validation
+ * failures as `{ detail: "Instructions are required" }`. Reading
+ * `error.error.message` blindly turns those into a `TypeError` that hides the
+ * real cause, so every field is probed defensively and the SDK's own `message`
+ * is the last resort.
+ */
+function describeOpenAIError(error) {
+    const err = error;
+    const body = err?.error;
+    const fromBody = typeof body === "string"
+        ? body
+        : (body?.message ?? body?.detail ?? undefined);
+    return {
+        message: fromBody ?? err?.detail ?? err?.message ?? "Unknown error",
+        code: typeof body === "object" ? body?.code : undefined,
+        status: err?.status,
+        body: body ?? err?.detail,
+    };
+}
 /**
  * Agent for OpenAI models using the Responses API.
  *
@@ -54,17 +131,39 @@ function lowestReasoningEffort(model) {
  * ```
  */
 class OpenAiAgent extends BaseAgent_1.BaseAgent {
+    /**
+     * Whether a non-streaming call must be issued as a stream and collapsed.
+     * `false` here; `CodexAgent` overrides it, since that backend refuses
+     * `stream: false` outright.
+     */
+    get forceStreaming() {
+        return false;
+    }
+    /**
+     * Last chance to reshape a request body before it goes out. Identity here —
+     * `CodexAgent` overrides it to satisfy that backend's extra validations.
+     */
+    transformRequestParams(params) {
+        return params;
+    }
     constructor(config, history) {
+        // Cast: `BaseAgentConfig.apiKey` is `string`, while this agent also accepts
+        // a token-returning function. BaseAgent never reads the field — it only
+        // declares it — so widening the base config for one provider would be the
+        // more invasive fix.
         super({ ...config, vendor: "openai" }, history);
         /** Count of tool calls in current execution */
         this.currentToolCallCount = 0;
+        // Merge flat config (deprecated) with nested vendorConfig
+        // Flat config takes precedence for backward compatibility
+        const vendorConfig = config.vendorConfig?.openai || {};
+        const baseURL = config.baseURL ?? vendorConfig.baseURL;
         this.client = new openai_1.default({
             apiKey: config.apiKey,
+            baseURL,
             defaultHeaders: config.defaultHeaders,
+            fetch: config.fetch,
         });
-        // Merge flat config (deprecated) with nested vendorConfig
-        // Flat config takes precedence for backward compatibility
-        const vendorConfig = config.vendorConfig?.openai || {};
         const disableParallelToolUse = config.disableParallelToolUse ??
             vendorConfig.disableParallelToolUse ??
             false;
@@ -87,6 +186,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             user,
             builtInTools,
             apiKey: config.apiKey,
+            baseURL,
             temperature: config.temperature,
             topP: config.topP,
             seed: config.seed,
@@ -111,6 +211,8 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 id: model.id,
                 created: model.created ? new Date(model.created * 1000) : undefined,
                 ownedBy: model.owned_by,
+                // Cast: this implementation always returns OpenAI's own cards; a
+                // subclass that reports a different shape overrides the whole method.
                 raw: model,
             }));
         }
@@ -118,6 +220,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             throw new AgentError_1.ExecutionError(`Failed to list OpenAI models: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /** The configured key, resolving the function form if that is what was given. */
+    async resolveApiKey() {
+        const key = this.config.apiKey;
+        return typeof key === "function" ? await key() : (key ?? "");
+    }
     getToolDefinitions() {
         return Array.from(this.tools.values()).map((tool) => {
             const prompt = tool.getPrompt();
@@ -152,6 +259,66 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             ...(this.config.builtInTools ?? []),
         ];
     }
+    /**
+     * Rebuild a terminal response's `output` from the items streamed alongside it.
+     *
+     * The Codex backend sends `response.completed` with `output: []` and no
+     * `output_text`, unlike the platform API which fills both in — the content
+     * only ever arrives as `response.output_item.done` events. Everything
+     * downstream (tool-call detection, the text written to history) reads
+     * `output`, so without this a Codex turn silently commits an empty assistant
+     * message and drops every tool call.
+     *
+     * A no-op wherever `output` is already populated, so the platform path is
+     * untouched.
+     */
+    repairStreamedOutput(response, streamedItems) {
+        if (response.output?.length || streamedItems.length === 0)
+            return response;
+        const output = streamedItems;
+        const outputText = output
+            .filter((item) => item.type === "message")
+            .flatMap((item) => ("content" in item ? (item.content ?? []) : []))
+            .filter((part) => part?.type === "output_text")
+            .map((part) => ("text" in part ? part.text : ""))
+            .join("");
+        return { ...response, output, output_text: outputText };
+    }
+    /**
+     * Issue a non-streaming Responses API call.
+     *
+     * When {@link forceStreaming} is set the request is streamed and the terminal
+     * event's `response` handed back instead — giving callers the same `Response`
+     * either way, at the cost of buffering the turn.
+     */
+    async createResponse(params, requestOptions) {
+        const body = this.transformRequestParams(params);
+        if (!this.forceStreaming) {
+            return this.client.responses.create({ ...body, stream: false }, requestOptions);
+        }
+        const stream = (await this.client.responses.create({ ...body, stream: true }, requestOptions));
+        let terminal;
+        const streamedItems = [];
+        for await (const event of stream) {
+            // Collected because the Codex backend leaves `output` empty on the
+            // terminal event — see repairStreamedOutput().
+            if (event.type === "response.output_item.done") {
+                streamedItems.push(event.item);
+            }
+            // `incomplete` and `failed` carry a Response too — handleResponse()
+            // already reads `status` off it, so let it report the reason rather than
+            // failing here with a vaguer message.
+            if (event.type === "response.completed" ||
+                event.type === "response.incomplete" ||
+                event.type === "response.failed") {
+                terminal = event.response;
+            }
+        }
+        if (!terminal) {
+            throw new AgentError_1.ExecutionError("OpenAI stream ended without a terminal response event");
+        }
+        return this.repairStreamedOutput(terminal, streamedItems);
+    }
     /**
      * Build the `reasoning` field for a Responses API request, as an object to
      * spread into the request params.
@@ -217,7 +384,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         try {
             const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
             this.startTurnTimer();
-            const response = await this.client.responses.create({
+            const response = await this.createResponse({
                 model: this.config.model,
                 max_output_tokens: this.config.maxTokens,
                 input: inputMessages,
@@ -242,16 +409,16 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 throw abortError;
             }
             if (error && typeof error === "object" && "error" in error) {
-                const openAIError = error;
-                const apiError = new AgentError_1.ApiError(`OpenAI API error: ${openAIError.error.message || "Unknown error"}`, openAIError.status, openAIError.error);
-                if (openAIError.error.code === "insufficient_quota") {
+                const openAIError = describeOpenAIError(error);
+                const apiError = new AgentError_1.ApiError(`OpenAI API error: ${openAIError.message}`, openAIError.status, openAIError.body);
+                if (openAIError.code === "insufficient_quota") {
                     apiError.message =
                         "OpenAI API quota exceeded. Please check your billing details.";
                 }
                 this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
                 // Report error to viz
                 if (this.vizEventId) {
-                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, openAIError.error.code === "rate_limit_exceeded");
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, openAIError.code === "rate_limit_exceeded");
                     this.vizEventId = undefined;
                 }
                 throw apiError;
@@ -344,7 +511,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 try {
                     const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
                     this.startTurnTimer();
-                    const newResponse = await this.client.responses.create({
+                    const newResponse = await this.createResponse({
                         model: this.config.model,
                         max_output_tokens: this.config.maxTokens,
                         input: inputMessages,
@@ -361,8 +528,8 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 }
                 catch (error) {
                     if (error && typeof error === "object" && "error" in error) {
-                        const openAIError = error;
-                        const apiError = new AgentError_1.ApiError(`OpenAI API error during tool response: ${openAIError.error.message || "Unknown error"}`, openAIError.status, openAIError.error);
+                        const openAIError = describeOpenAIError(error);
+                        const apiError = new AgentError_1.ApiError(`OpenAI API error during tool response: ${openAIError.message}`, openAIError.status, openAIError.body);
                         this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
                         throw apiError;
                     }
@@ -501,11 +668,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 throw this.withPartialTurn(error);
             }
             if (error && typeof error === "object" && "error" in error) {
-                const openAIError = error;
-                const apiError = new AgentError_1.ApiError(`OpenAI API error: ${openAIError.error.message || "Unknown error"}`, openAIError.status, openAIError.error);
+                const openAIError = describeOpenAIError(error);
+                const apiError = new AgentError_1.ApiError(`OpenAI API error: ${openAIError.message}`, openAIError.status, openAIError.body);
                 this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
                 if (this.vizEventId) {
-                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, openAIError.error.code === "rate_limit_exceeded");
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, openAIError.code === "rate_limit_exceeded");
                     this.vizEventId = undefined;
                 }
                 throw this.withPartialTurn(apiError);
@@ -525,7 +692,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
     async *streamTurn(options) {
         const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
         this.startTurnTimer();
-        const stream = await this.client.responses.create({
+        const stream = await this.client.responses.create(this.transformRequestParams({
             model: this.config.model,
             max_output_tokens: this.config.maxTokens,
             input: inputMessages,
@@ -536,8 +703,9 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             top_p: this.config.topP,
             user: this.config.user,
             ...this.buildReasoningParams("auto"),
-        }, { signal: options?.signal });
+        }), { signal: options?.signal });
         let completedEvent = null;
+        const streamedItems = [];
         // The Responses API builds the committed turn out of `response.completed`,
         // which only arrives on success, so the deltas are mirrored here as well:
         // without them a stream that dies mid-flight leaves nothing behind at all,
@@ -580,6 +748,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                     if (acc)
                         acc.arguments += event.delta;
                 }
+                if (event.type === "response.output_item.done") {
+                    // The Codex backend leaves `output` empty on the terminal event, so
+                    // the finished items are kept here — see repairStreamedOutput().
+                    streamedItems.push(event.item);
+                }
                 if (event.type === "response.completed") {
                     completedEvent = event;
                     if (event.response.usage) {
@@ -597,7 +770,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             if (!completedEvent) {
                 throw new AgentError_1.ExecutionError("OpenAI stream ended without a completed event");
             }
-            const response = completedEvent.response;
+            const response = this.repairStreamedOutput(completedEvent.response, streamedItems);
             const toolCalls = response.output.filter((o) => o.type === "function_call");
             if (toolCalls.length > 0) {
                 // As in handleResponse(): bail out before the assistant turn is written,

package/dist/agents/openai/codex-auth.d.ts

@@ -0,0 +1,166 @@
+/**
+ * OAuth against a ChatGPT subscription, as used by OpenAI's Codex CLI.
+ *
+ * This is a different product surface from the platform API: the credentials are
+ * a ChatGPT login rather than a `sk-...` platform key, and requests are billed
+ * against the subscription instead of an API account. The endpoint differs too —
+ * see {@link CODEX_BASE_URL}.
+ *
+ * None of it is a documented public API. The values here were cross-checked
+ * against the Codex CLI's own behaviour and several independent
+ * reimplementations, but OpenAI can change them without notice.
+ */
+/**
+ * Base URL for the ChatGPT-backed Codex Responses API.
+ *
+ * The SDK appends `/responses`, giving
+ * `https://chatgpt.com/backend-api/codex/responses`.
+ */
+export declare const CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex";
+/** Public OAuth client id the Codex CLI uses. Not a secret. */
+export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+/** Token endpoint used to exchange a refresh token for a fresh access token. */
+export declare const CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token";
+/**
+ * Default `originator` header value.
+ *
+ * OpenAI gates parts of the model catalog on this, so an unrecognised value can
+ * quietly change which models an account may reach.
+ */
+export declare const CODEX_ORIGINATOR = "codex_cli_rs";
+/**
+ * `client_version` for the Codex models endpoint, which 400s without one.
+ *
+ * Each model also carries a `minimal_client_version`; the backend hides models
+ * newer than the version claimed here, so an old value quietly shortens the
+ * list rather than erroring.
+ */
+export declare const CODEX_CLIENT_VERSION = "0.153.4";
+/**
+ * One entry from the Codex `/models` response.
+ *
+ * Nothing like the platform API's `/v1/models` — richer, and shaped for the
+ * Codex client. Only the fields worth relying on are named; the rest come
+ * through on `ModelInfo.raw`.
+ */
+export interface CodexModelCard {
+    slug: string;
+    display_name?: string;
+    description?: string;
+    /** Default context window for this account's plan. */
+    context_window?: number;
+    /** Largest window the model can be driven at. */
+    max_context_window?: number;
+    input_modalities?: string[];
+    supported_reasoning_levels?: {
+        effort: string;
+        description?: string;
+    }[];
+    default_reasoning_level?: string;
+    /** Subscription plans that may select this model. */
+    available_in_plans?: string[];
+    /** `"list"` for models meant to be shown in a picker. */
+    visibility?: string;
+    supported_in_api?: boolean;
+    minimal_client_version?: string;
+    supports_parallel_tool_calls?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Credentials for the ChatGPT/Codex backend.
+ */
+export interface CodexCredentials {
+    /** Bearer token sent as `Authorization`. */
+    accessToken: string;
+    /** Used to mint a new access token once the current one expires. */
+    refreshToken?: string;
+    /**
+     * Workspace/account the request is billed to, sent as the
+     * `chatgpt-account-id` header. Read from `auth.json`, or decoded from the
+     * `id_token` when absent.
+     */
+    accountId?: string;
+    /** Account e-mail, when the `id_token` carried one. Informational. */
+    email?: string;
+    /** Subscription tier (`plus`, `pro`, …), when present. Informational. */
+    planType?: string;
+}
+/**
+ * Decode a JWT's payload without verifying its signature.
+ *
+ * Verification is the token endpoint's job — we are only reading claims out of a
+ * token we were just handed over TLS, never making a trust decision on it.
+ * Returns `undefined` for anything that does not parse, so a malformed or
+ * opaque token degrades to "no claims" rather than throwing.
+ */
+export declare function decodeJwtClaims<T = Record<string, unknown>>(token: string): T | undefined;
+/**
+ * Seconds-since-epoch expiry of a JWT, or `undefined` if it has no `exp`.
+ */
+export declare function jwtExpiry(token: string): number | undefined;
+/** Default location of Codex's credential file. */
+export declare function codexAuthFilePath(codexHome?: string): string;
+/**
+ * Read the credentials the Codex CLI stored at `$CODEX_HOME/auth.json`
+ * (`~/.codex/auth.json` by default).
+ *
+ * Sign in with `codex login` first — this only reads what that wrote, it does
+ * not run the OAuth flow itself.
+ *
+ * @throws if the file is missing, unreadable, not JSON, or holds no access token.
+ */
+export declare function loadCodexCredentials(codexHome?: string): Promise<CodexCredentials>;
+/**
+ * Exchange a refresh token for a fresh access token.
+ *
+ * The returned credentials carry the new `refresh_token` when the server
+ * rotated it, and the previous one otherwise.
+ */
+export declare function refreshCodexCredentials(refreshToken: string, options?: {
+    clientId?: string;
+    tokenUrl?: string;
+    signal?: AbortSignal;
+}): Promise<CodexCredentials>;
+/** Options for {@link createCodexTokenProvider}. */
+export interface CodexTokenProviderOptions {
+    /** OAuth client id. Defaults to {@link CODEX_CLIENT_ID}. */
+    clientId?: string;
+    /** Token endpoint. Defaults to {@link CODEX_TOKEN_URL}. */
+    tokenUrl?: string;
+    /**
+     * Refresh this many seconds before the access token actually expires, so a
+     * request is never sent with a token that dies in flight.
+     *
+     * @default 300
+     */
+    refreshSkewSeconds?: number;
+    /**
+     * Called after every successful refresh, e.g. to persist the rotated refresh
+     * token. Errors thrown here are ignored — a failed write must not fail the
+     * request the token was minted for.
+     */
+    onRefresh?: (credentials: CodexCredentials) => void | Promise<void>;
+}
+/**
+ * A token source that hands out an access token and silently refreshes it.
+ *
+ * The `getToken` function is shaped for the OpenAI SDK's `apiKey` option, which
+ * accepts an async function and calls it before *every* request — so a
+ * long-running agent keeps working past the ~1h life of an access token without
+ * anyone reaching for the credential file again.
+ */
+export interface CodexTokenProvider {
+    /** Current access token, refreshed on demand. Pass as the SDK's `apiKey`. */
+    getToken: () => Promise<string>;
+    /** Latest known credentials, including `accountId`. */
+    current: () => CodexCredentials;
+}
+/**
+ * Wrap credentials in a self-refreshing token provider.
+ *
+ * Refreshes lazily — only when a token is actually asked for and the current
+ * one is within `refreshSkewSeconds` of expiry. Concurrent callers share a
+ * single in-flight refresh rather than each starting their own.
+ */
+export declare function createCodexTokenProvider(credentials: CodexCredentials, options?: CodexTokenProviderOptions): CodexTokenProvider;
+//# sourceMappingURL=codex-auth.d.ts.map