ag-common 0.0.908 → 0.0.910

package/README.md

@@ -2,6 +2,38 @@
 
 > Various reusable TypeScript libraries for common, API (AWS Cognito and AWS CDK), and React UI use cases.
 
+The provider-neutral AI helpers are exported from `ag-common` and support text,
+multimodal input, typed media output, and optional direct Codex endpoints.
+
+```ts
+import { createAIClient } from "ag-common";
+
+const ai = createAIClient({
+  endpoint: {
+    protocol: "codex",
+    url: "http://192.168.0.205:4501/v1",
+    token: process.env.CODEX_TOKEN!,
+  },
+});
+
+const result = await ai.generate({
+  input: [{ role: "user", content: [{ type: "text", text: "Describe this image." }] }],
+  output: ["text"],
+  model: "local-model",
+});
+
+const models = await ai.models();
+const imageModels = models.filter((model) => model.outputModalities?.includes("image"));
+```
+
+Codex URLs must be direct private LAN IPv4 addresses. The client sends the
+version-one job protocol under `/v1`, polls bounded job status, and keeps one
+idempotency key for retries. Omitting `endpoint` uses the configured Google AI
+adapter and its API keys. `models()` returns provider-neutral metadata with the
+model id and any input/output modalities, reasoning efforts, preferences, web
+search, default, and readiness fields the provider exposes. Capability fields
+may be omitted when a provider does not publish them.
+
 [![NPM Version][npm-image]][npm-url]
 
 ## Install

package/dist/api/helpers/ai/adapters/codex.d.ts

@@ -0,0 +1,12 @@
+import type { AIClientDependencies, AIEndpoint, AIModel, AIRequest, GenerationResult } from "../types";
+export type CodexAdapterConfig = {
+    endpoint: AIEndpoint;
+    dependencies?: AIClientDependencies;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+};
+/** Validate and normalize the direct private LAN endpoint used by Codex. */
+export declare const normalizeCodexEndpoint: (endpoint: AIEndpoint) => AIEndpoint;
+export declare const generateCodex: (request: AIRequest, config: CodexAdapterConfig) => Promise<GenerationResult>;
+export declare const listCodexModels: (endpoint: AIEndpoint, dependencies?: AIClientDependencies) => Promise<AIModel[]>;

package/dist/api/helpers/ai/adapters/codex.js

@@ -0,0 +1,573 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCodexModels = exports.generateCodex = exports.normalizeCodexEndpoint = void 0;
+const node_crypto_1 = require("node:crypto");
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+const DEFAULT_MAX_POLL_INTERVAL_MS = 2000;
+const CREATE_RETRY_DELAY_MS = 1000;
+const CANCEL_TIMEOUT_MS = 1000;
+const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+const TERMINAL_SUCCESS_STATUSES = new Set(["completed"]);
+const TERMINAL_FAILURE_STATUSES = new Set(["failed", "cancelled", "unknown"]);
+const PENDING_STATUSES = new Set(["queued", "running", "cancelling"]);
+class CodexHTTPError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "CodexHTTPError";
+        this.status = status;
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const getString = (record, key) => {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+};
+const getRecord = (record, key) => {
+    const value = record[key];
+    return isRecord(value) ? value : undefined;
+};
+const getErrorMessage = (body, fallback) => {
+    if (!isRecord(body))
+        return fallback;
+    const error = body.error;
+    if (typeof error === "string" && error.trim().length > 0)
+        return error;
+    if (isRecord(error)) {
+        const message = getString(error, "message");
+        if (message && message.trim().length > 0)
+            return message;
+    }
+    const message = getString(body, "message");
+    return message && message.trim().length > 0 ? message : fallback;
+};
+const parseIPv4 = (hostname) => {
+    const octets = hostname.split(".");
+    if (octets.length !== 4 || octets.some((octet) => !/^\d{1,3}$/.test(octet)))
+        return undefined;
+    const numbers = octets.map((octet) => Number(octet));
+    return numbers.every((octet) => octet >= 0 && octet <= 255) ? numbers : undefined;
+};
+const isPrivateIPv4 = (hostname) => {
+    const octets = parseIPv4(hostname);
+    if (!octets)
+        return false;
+    const [first, second] = octets;
+    return (first === 10 ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168));
+};
+/** Validate and normalize the direct private LAN endpoint used by Codex. */
+const normalizeCodexEndpoint = (endpoint) => {
+    const candidate = endpoint;
+    if (!isRecord(candidate) || candidate.protocol !== "codex") {
+        throw new Error("Unsupported AI endpoint protocol");
+    }
+    const rawURL = candidate.url;
+    const rawToken = candidate.token;
+    if (typeof rawURL !== "string" || rawURL.trim().length === 0) {
+        throw new Error("Codex endpoint URL is required");
+    }
+    if (typeof rawToken !== "string" || rawToken.trim().length === 0) {
+        throw new Error("Codex endpoint token is required");
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawURL);
+    }
+    catch {
+        throw new Error("Codex endpoint URL is invalid");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Codex endpoint URL must use HTTP or HTTPS");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("Codex endpoint URL must not contain credentials, query, or fragment");
+    }
+    if (parsed.hostname.toLowerCase() === "gec.dev" ||
+        parsed.hostname.toLowerCase().endsWith(".gec.dev")) {
+        throw new Error("Codex endpoint must connect directly to the private LAN address");
+    }
+    if (!isPrivateIPv4(parsed.hostname)) {
+        throw new Error("Codex endpoint must use a private LAN IPv4 address");
+    }
+    const path = parsed.pathname.replace(/\/+$/, "");
+    if (path !== "" && path !== "/v1") {
+        throw new Error("Codex endpoint URL path must be empty or /v1");
+    }
+    parsed.pathname = "/v1";
+    parsed.search = "";
+    parsed.hash = "";
+    return { protocol: "codex", url: parsed.toString().replace(/\/$/, ""), token: rawToken.trim() };
+};
+exports.normalizeCodexEndpoint = normalizeCodexEndpoint;
+const defaultSleep = (milliseconds) => new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+});
+const getDependencies = (dependencies) => ({
+    fetch: dependencies?.fetch ?? globalThis.fetch,
+    sleep: dependencies?.sleep ?? defaultSleep,
+    now: dependencies?.now ?? (() => Date.now()),
+    createIdempotencyKey: dependencies?.createIdempotencyKey ?? node_crypto_1.randomUUID,
+});
+const throwIfAborted = (signal) => {
+    if (signal?.aborted) {
+        throw new Error("Codex generation aborted");
+    }
+};
+const createAbortError = () => {
+    const error = new Error("Codex request aborted");
+    error.name = "AbortError";
+    return error;
+};
+const awaitWithSignal = async (promise, signal) => {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        throw createAbortError();
+    const abort = new Promise((_, reject) => {
+        const onAbort = () => reject(createAbortError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        void promise.then(() => signal.removeEventListener("abort", onAbort), () => signal.removeEventListener("abort", onAbort));
+    });
+    return Promise.race([promise, abort]);
+};
+const responseJSON = async (response, signal) => {
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null && Number(contentLength) > MAX_RESPONSE_BYTES) {
+        throw new Error("Codex response body is too large");
+    }
+    const body = response.body;
+    if (body === null)
+        return undefined;
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            // oxlint-disable-next-line no-await-in-loop -- response bytes must be bounded sequentially
+            const chunk = await awaitWithSignal(reader.read(), signal);
+            if (chunk.done)
+                break;
+            total += chunk.value.byteLength;
+            if (total > MAX_RESPONSE_BYTES)
+                throw new Error("Codex response body is too large");
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return undefined;
+    }
+};
+const fetchJSON = async ({ fetch, url, headers, method, body, signal, }) => {
+    const response = await awaitWithSignal(fetch(url, {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body }),
+        redirect: "manual",
+        ...(signal === undefined ? {} : { signal }),
+    }), signal);
+    const payload = await responseJSON(response, signal);
+    if (!response.ok) {
+        throw new CodexHTTPError(response.status, getErrorMessage(payload, `Codex endpoint returned HTTP ${response.status}`));
+    }
+    return payload;
+};
+const isRetryable = (error) => {
+    if (error instanceof CodexHTTPError)
+        return error.status === 429 || error.status >= 500;
+    return error instanceof Error && error.name !== "AbortError";
+};
+const withCreateRetry = async (operation, sleep, signal) => {
+    try {
+        const result = await operation();
+        return result;
+    }
+    catch (error) {
+        if (!isRetryable(error))
+            throw error;
+        // oxlint-disable-next-line no-await-in-loop -- retry delay precedes the one allowed replay
+        await awaitWithSignal(sleep(CREATE_RETRY_DELAY_MS), signal);
+        throwIfAborted(signal);
+        return operation();
+    }
+};
+const isBase64 = (value) => value.length > 0 &&
+    value.length % 4 === 0 &&
+    /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+const parseOutputPart = (value) => {
+    if (!isRecord(value))
+        throw new Error("Codex result contains an invalid output part");
+    const type = getString(value, "type");
+    if (type === "text") {
+        const text = getString(value, "text");
+        if (text === undefined)
+            throw new Error("Codex text output is missing text");
+        return { type, text };
+    }
+    if (type !== "image" && type !== "audio" && type !== "video" && type !== "file") {
+        throw new Error("Codex result contains an unsupported output part");
+    }
+    const mimeType = getString(value, "mimeType");
+    const data = getString(value, "data");
+    if (!mimeType || data === undefined || !isBase64(data)) {
+        throw new Error("Codex media output is missing MIME type or data");
+    }
+    if (type !== "file" && !mimeType.toLowerCase().startsWith(`${type}/`)) {
+        throw new Error("Codex media output type does not match its MIME type");
+    }
+    const name = getString(value, "name");
+    return name === undefined ? { type, mimeType, data } : { type, mimeType, data, name };
+};
+const parseJob = (value) => {
+    if (!isRecord(value))
+        throw new Error("Codex endpoint returned an invalid job");
+    const id = getString(value, "id");
+    const status = getString(value, "status");
+    if (!id || !status)
+        throw new Error("Codex job is missing id or status");
+    return value;
+};
+const parseResult = (job) => {
+    const result = getRecord(job, "result");
+    if (!result)
+        throw new Error("Codex successful job is missing its result");
+    const rawOutput = result.output;
+    if (!Array.isArray(rawOutput))
+        throw new Error("Codex result is missing typed output parts");
+    const model = getString(result, "model");
+    if (!model || model.trim().length === 0)
+        throw new Error("Codex result is missing its actual model");
+    const generatedAtValue = result.generatedAt;
+    if (typeof generatedAtValue !== "number" ||
+        !Number.isSafeInteger(generatedAtValue) ||
+        generatedAtValue < 0) {
+        throw new Error("Codex result is missing a valid generatedAt timestamp");
+    }
+    const rawUsage = result.usage;
+    let usage;
+    if (rawUsage !== undefined) {
+        if (!isRecord(rawUsage))
+            throw new Error("Codex result usage is invalid");
+        const inputTokens = rawUsage.inputTokens;
+        const outputTokens = rawUsage.outputTokens;
+        const totalTokens = rawUsage.totalTokens;
+        if (typeof inputTokens !== "number" ||
+            !Number.isSafeInteger(inputTokens) ||
+            inputTokens < 0 ||
+            typeof outputTokens !== "number" ||
+            !Number.isSafeInteger(outputTokens) ||
+            outputTokens < 0 ||
+            typeof totalTokens !== "number" ||
+            !Number.isSafeInteger(totalTokens) ||
+            totalTokens < 0) {
+            throw new Error("Codex result usage is invalid");
+        }
+        usage = { inputTokens, outputTokens, totalTokens };
+    }
+    return {
+        output: rawOutput.map(parseOutputPart),
+        model,
+        generatedAt: generatedAtValue,
+        ...(usage === undefined ? {} : { usage }),
+    };
+};
+const getFailureMessage = (job) => {
+    const error = job.error;
+    const status = getString(job, "status");
+    if (status === "unknown") {
+        const detail = getErrorMessage(error, "execution outcome is unknown");
+        return `Codex generation outcome is uncertain; do not retry automatically: ${detail}`;
+    }
+    return getErrorMessage(error, "Codex generation failed");
+};
+const endpointHeaders = (endpoint, idempotencyKey) => ({
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${endpoint.token}`,
+    ...(idempotencyKey === undefined ? {} : { "Idempotency-Key": idempotencyKey }),
+});
+const jobURL = (endpoint, id) => `${endpoint.url}/jobs${id === undefined ? "" : `/${encodeURIComponent(id)}`}`;
+const cancelJob = async (endpoint, id, fetch) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CANCEL_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${jobURL(endpoint, id)}/cancel`, {
+            method: "POST",
+            headers: endpointHeaders(endpoint),
+            redirect: "manual",
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new CodexHTTPError(response.status, `Codex cancellation returned HTTP ${response.status}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+};
+const abortWithCancellation = async (endpoint, id, fetch, reason) => {
+    try {
+        await Promise.race([
+            cancelJob(endpoint, id, fetch),
+            new Promise((resolve) => setTimeout(resolve, CANCEL_TIMEOUT_MS)),
+        ]);
+    }
+    catch {
+        // Preserve the original abort or timeout reason when best-effort cancellation fails.
+    }
+    throw reason;
+};
+const createOperationAbort = (request, timeoutMs) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    const onAbort = () => controller.abort();
+    request.signal?.addEventListener("abort", onAbort, { once: true });
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            request.signal?.removeEventListener("abort", onAbort);
+        },
+    };
+};
+const generateCodex = async (request, config) => {
+    const endpoint = (0, exports.normalizeCodexEndpoint)(config.endpoint);
+    const dependencies = getDependencies(config.dependencies);
+    const timeoutMs = request.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const maxPollIntervalMs = config.maxPollIntervalMs ?? DEFAULT_MAX_POLL_INTERVAL_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new Error("Codex timeout must be positive");
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+        throw new Error("Codex poll interval must be positive");
+    }
+    if (!Number.isFinite(maxPollIntervalMs) || maxPollIntervalMs < pollIntervalMs) {
+        throw new Error("Codex maximum poll interval is invalid");
+    }
+    throwIfAborted(request.signal);
+    const operationAbort = createOperationAbort(request, timeoutMs);
+    let jobId;
+    const deadline = dependencies.now() + timeoutMs;
+    const abortError = () => request.signal?.aborted
+        ? new Error("Codex generation aborted")
+        : new Error("Codex generation timed out");
+    try {
+        const idempotencyKey = dependencies.createIdempotencyKey();
+        if (idempotencyKey.trim().length === 0)
+            throw new Error("Codex idempotency key is empty");
+        const body = {
+            version: 1,
+            input: request.input,
+            output: request.output ?? ["text"],
+            ...(request.instructions === undefined ? {} : { instructions: request.instructions }),
+            ...(request.model === undefined ? {} : { model: request.model }),
+            ...(request.model === undefined && request.prefer !== undefined
+                ? { prefer: request.prefer }
+                : {}),
+            ...(request.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: request.reasoningEffort }),
+            ...(request.maxOutputTokens === undefined
+                ? {}
+                : { maxOutputTokens: request.maxOutputTokens }),
+            ...(request.outputSchema === undefined ? {} : { outputSchema: request.outputSchema }),
+            ...(request.webSearch === undefined ? {} : { webSearch: request.webSearch }),
+        };
+        const created = parseJob(await withCreateRetry(() => fetchJSON({
+            fetch: dependencies.fetch,
+            url: jobURL(endpoint),
+            headers: endpointHeaders(endpoint, idempotencyKey),
+            method: "POST",
+            body: JSON.stringify(body),
+            signal: operationAbort.signal,
+        }), dependencies.sleep, operationAbort.signal));
+        jobId = getString(created, "id");
+        if (!jobId)
+            throw new Error("Codex job is missing its id");
+        const status = getString(created, "status");
+        if (!status)
+            throw new Error("Codex job is missing its status");
+        if (TERMINAL_FAILURE_STATUSES.has(status))
+            throw new Error(getFailureMessage(created));
+        if (!PENDING_STATUSES.has(status) && !TERMINAL_SUCCESS_STATUSES.has(status)) {
+            throw new Error(`Unknown Codex job status: ${status}`);
+        }
+        let delay = TERMINAL_SUCCESS_STATUSES.has(status) ? 0 : pollIntervalMs;
+        const maxPollAttempts = Math.max(1, Math.ceil(timeoutMs / pollIntervalMs)) + 2;
+        let pollAttempts = 0;
+        while (pollAttempts < maxPollAttempts) {
+            if (dependencies.now() >= deadline) {
+                return abortWithCancellation(endpoint, jobId, dependencies.fetch, new Error("Codex generation timed out"));
+            }
+            if (delay > 0) {
+                // oxlint-disable-next-line no-await-in-loop -- polling must remain sequential
+                await awaitWithSignal(dependencies.sleep(Math.min(delay, Math.max(0, deadline - dependencies.now()))), operationAbort.signal);
+            }
+            if (operationAbort.signal.aborted) {
+                return abortWithCancellation(endpoint, jobId, dependencies.fetch, abortError());
+            }
+            if (dependencies.now() >= deadline) {
+                return abortWithCancellation(endpoint, jobId, dependencies.fetch, new Error("Codex generation timed out"));
+            }
+            let current;
+            pollAttempts += 1;
+            try {
+                current = parseJob(
+                // oxlint-disable-next-line no-await-in-loop -- each poll depends on the prior status
+                await fetchJSON({
+                    fetch: dependencies.fetch,
+                    url: jobURL(endpoint, jobId),
+                    headers: endpointHeaders(endpoint),
+                    method: "GET",
+                    signal: operationAbort.signal,
+                }));
+            }
+            catch (error) {
+                if (!isRetryable(error))
+                    throw error;
+                const retryDelay = Math.max(pollIntervalMs, delay);
+                // oxlint-disable-next-line no-await-in-loop -- backoff precedes the next status check
+                await awaitWithSignal(dependencies.sleep(retryDelay), operationAbort.signal);
+                delay = Math.min(maxPollIntervalMs, retryDelay * 2);
+                continue;
+            }
+            const currentStatus = getString(current, "status");
+            if (!currentStatus)
+                throw new Error("Codex job is missing its status");
+            if (TERMINAL_SUCCESS_STATUSES.has(currentStatus)) {
+                return parseResult(current);
+            }
+            if (TERMINAL_FAILURE_STATUSES.has(currentStatus))
+                throw new Error(getFailureMessage(current));
+            if (!PENDING_STATUSES.has(currentStatus)) {
+                throw new Error(`Unknown Codex job status: ${currentStatus}`);
+            }
+            delay = Math.min(maxPollIntervalMs, Math.max(pollIntervalMs, delay * 2));
+        }
+        return abortWithCancellation(endpoint, jobId, dependencies.fetch, new Error("Codex generation timed out"));
+    }
+    catch (error) {
+        if (operationAbort.signal.aborted && jobId !== undefined) {
+            return abortWithCancellation(endpoint, jobId, dependencies.fetch, abortError());
+        }
+        if (operationAbort.signal.aborted)
+            throw abortError();
+        throw error;
+    }
+    finally {
+        operationAbort.cleanup();
+    }
+};
+exports.generateCodex = generateCodex;
+const MODEL_MODALITIES = new Set(["text", "image", "audio", "video", "file"]);
+const getModelId = (record) => {
+    for (const key of ["id", "name", "model", "modelId"]) {
+        const value = getString(record, key)?.trim();
+        if (value !== undefined && value.length > 0)
+            return value;
+    }
+    return undefined;
+};
+const parseStringList = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    return [
+        ...new Set(value.flatMap((item) => {
+            if (typeof item === "string") {
+                const normalized = item.trim();
+                return normalized.length > 0 ? [normalized] : [];
+            }
+            if (isRecord(item)) {
+                const normalized = getString(item, "reasoningEffort")?.trim();
+                return normalized === undefined || normalized.length === 0 ? [] : [normalized];
+            }
+            return [];
+        })),
+    ];
+};
+const parseModalities = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    return [
+        ...new Set(value.flatMap((item) => {
+            if (typeof item !== "string")
+                return [];
+            const normalized = item.trim();
+            return MODEL_MODALITIES.has(normalized) ? [normalized] : [];
+        })),
+    ];
+};
+const parsePreferences = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    return [
+        ...new Set(value.filter((item) => item === "fast" || item === "quality")),
+    ];
+};
+const parseModel = (value) => {
+    if (typeof value === "string") {
+        const id = value.trim();
+        return id.length === 0 ? undefined : { id };
+    }
+    if (!isRecord(value))
+        return undefined;
+    const id = getModelId(value);
+    if (id === undefined)
+        return undefined;
+    const capabilities = getRecord(value, "capabilities") ?? value;
+    const model = { id };
+    const inputModalities = parseModalities(capabilities.inputModalities);
+    const outputModalities = parseModalities(capabilities.outputModalities);
+    const supportedReasoningEfforts = parseStringList(capabilities.supportedReasoningEfforts ?? capabilities.reasoningEfforts);
+    const defaultReasoningEffort = getString(capabilities, "defaultReasoningEffort")?.trim();
+    const prefer = parsePreferences(capabilities.prefer ?? capabilities.preferences);
+    if (inputModalities !== undefined)
+        model.inputModalities = inputModalities;
+    if (outputModalities !== undefined)
+        model.outputModalities = outputModalities;
+    if (supportedReasoningEfforts !== undefined) {
+        model.supportedReasoningEfforts = supportedReasoningEfforts;
+    }
+    if (defaultReasoningEffort !== undefined && defaultReasoningEffort.length > 0) {
+        model.defaultReasoningEffort = defaultReasoningEffort;
+    }
+    if (prefer !== undefined)
+        model.prefer = prefer;
+    for (const key of ["webSearch", "isDefault", "ready"]) {
+        const flag = capabilities[key];
+        if (typeof flag === "boolean")
+            model[key] = flag;
+    }
+    return model;
+};
+const listCodexModels = async (endpoint, dependencies) => {
+    const normalizedEndpoint = (0, exports.normalizeCodexEndpoint)(endpoint);
+    const { fetch } = getDependencies(dependencies);
+    const payload = await fetchJSON({
+        fetch,
+        url: `${normalizedEndpoint.url}/models`,
+        headers: endpointHeaders(normalizedEndpoint),
+        method: "GET",
+    });
+    const models = isRecord(payload) ? payload.models : payload;
+    if (!Array.isArray(models))
+        throw new Error("Codex models response is invalid");
+    return models.map(parseModel).filter((model) => model !== undefined);
+};
+exports.listCodexModels = listCodexModels;

package/dist/api/helpers/ai/adapters/google.d.ts

@@ -0,0 +1,12 @@
+import { GoogleGenAI } from "@google/genai";
+import { resetModelBackoff } from "../quota";
+import type { AIClientDependencies, AIModel, AIRequest, GenerationResult } from "../types";
+export type GoogleAdapterConfig = {
+    dependencies?: AIClientDependencies;
+    createAI?: (apiKey: string) => GoogleGenAI;
+};
+export declare const generateGoogle: (request: AIRequest, config?: GoogleAdapterConfig) => Promise<GenerationResult>;
+export declare const listGoogleModels: (dependencies?: AIClientDependencies) => Promise<AIModel[]>;
+export { resetModelBackoff };
+/** Test seam: reset adapter clients, model cache, and per-model rate-limit backoff. */
+export declare const resetGoogleAdapterForTests: () => void;