@alvin0/ai-agent-sdk-provider-codex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin0 (chaulamdinhai) <chaulamdinhai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @alvin0/ai-agent-sdk-provider-codex
+
+Runtime: **Universal** (Edge/Worker, browser, Deno, Bun, and Node with an injected auth store).
+
+```sh
+pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-provider-codex
+```
+
+Universal Codex adapter, OAuth flows, memory/custom auth stores, and transactional provider plugin. A `CodexAuthStore` must be injected; filesystem and environment defaults belong to the Node auth package.
+
+```ts
+import { ModelRegistry } from '@alvin0/ai-agent-sdk-core'
+import { codexPlugin } from '@alvin0/ai-agent-sdk-provider-codex'
+
+const registry = new ModelRegistry()
+registry.install(codexPlugin({ authStore: mySecretManagerStore }))
+```
+
+Use `codexAdapter()` for manual route registration. The store contract is
+Universal; a browser, Worker, secret manager, or Node package owns persistence.
+Credential and catalog observation excludes OAuth tokens, account details, store
+locations, and raw authentication errors.
+
+Composition: `runtime.providers`. Lifecycle: `inert-runtime-owned-registration`;
+the runtime owns registration while the injected credential store remains
+caller-owned.

package/dist/index.d.ts

@@ -0,0 +1,280 @@
+import { AgentSdkError, ModelProviderPlugin, RetryPolicyConfig } from "@alvin0/ai-agent-sdk-core";
+import { ComposableModelProviderPlugin, CredentialStore, ModelTarget } from "@alvin0/ai-agent-sdk-core/provider";
+import { HttpModelAdapter, ProviderCatalogModel, ProviderRequestLogger } from "@alvin0/ai-agent-sdk-provider-http";
+import { ResponsesDialect, openAiResponsesProtocol } from "@alvin0/ai-agent-sdk-protocol-responses";
+//#region src/common/store-types.d.ts
+/** OAuth tokens as stored by Codex authentication. */
+interface CodexTokens {
+  id_token: string;
+  access_token: string;
+  refresh_token: string;
+  account_id?: string | null;
+}
+/** Persisted Codex authentication document. */
+interface CodexAuthFile {
+  auth_mode?: string;
+  OPENAI_API_KEY?: string | null;
+  tokens?: CodexTokens | null;
+  last_refresh?: string | null;
+}
+/** @deprecated Marker-free storage contract retained for compatibility. */
+interface CodexAuthStore {
+  readonly location: string;
+  read(): Promise<CodexAuthFile | undefined>;
+  write(file: CodexAuthFile): Promise<void>;
+}
+/** Revision-aware credential storage used by normal runtime composition. */
+type CodexCredentialStore = CredentialStore<CodexAuthFile>;
+//#endregion
+//#region src/auth.d.ts
+/** An in-memory {@link CodexAuthStore}, for tests. */
+declare function memoryCodexAuthStore(initial?: CodexAuthFile): CodexAuthStore;
+/** In-memory compare-and-swap store for deterministic runtime/tests. */
+declare function memoryCodexCredentialStore(initial?: CodexAuthFile): CodexCredentialStore;
+/** Claims this SDK reads out of a Codex JWT. */
+interface CodexJwtClaims {
+  exp?: number;
+  email?: string;
+  accountId?: string;
+  planType?: string;
+  isFedramp: boolean;
+}
+/**
+ * Read the claims this SDK cares about out of a JWT.
+ *
+ * The signature is NOT verified, and does not need to be: this token is being
+ * read to decide which account id to send and whether to refresh, not to grant
+ * anything. The issuer verifies it.
+ * @param jwt - a compact-serialization JWT.
+ * @returns the claims, or `undefined` when the token is unreadable.
+ */
+declare function readJwtClaims(jwt: string): CodexJwtClaims | undefined;
+/**
+ * Resolve the account id to send as `ChatGPT-Account-ID`.
+ *
+ * Prefers the stored value and falls back to the `id_token` claim, because the
+ * stored field is legitimately null for personal accounts.
+ * @param tokens - the stored tokens.
+ * @returns the account id, or `undefined` when neither source has one.
+ */
+declare function resolveAccountId(tokens: CodexTokens): string | undefined;
+/** Whether this account must be routed through the FedRAMP edge. */
+declare function isFedrampAccount(tokens: CodexTokens): boolean;
+/** Refresh this long before the access token actually expires. */
+declare const ACCESS_TOKEN_REFRESH_WINDOW_MS: number;
+/** Fallback staleness bound, used only when `exp` cannot be read. */
+declare const LAST_REFRESH_MAX_AGE_MS: number;
+/**
+ * Whether the access token should be refreshed before the next request.
+ *
+ * Primary signal is the token's own `exp`, with a five-minute margin so a request
+ * cannot expire in flight. The `last_refresh` age is only a fallback for a token
+ * whose `exp` is unreadable — matching how the Codex CLI decides.
+ * @param file - the credential file.
+ * @param now - current time in epoch milliseconds; injectable for tests.
+ * @returns true when a refresh is due.
+ */
+declare function shouldRefresh(file: CodexAuthFile, now?: number): boolean;
+/**
+ * Require usable ChatGPT tokens, with a message that says how to get them.
+ * @param file - the credential file, or `undefined` when absent.
+ * @param location - the path checked, named in the diagnostic.
+ * @returns the tokens.
+ */
+declare function requireTokens(file: CodexAuthFile | undefined, location: string): CodexTokens;
+//#endregion
+//#region src/oauth.d.ts
+/** OpenAI's auth issuer. */
+declare const DEFAULT_CODEX_ISSUER = "https://auth.openai.com";
+/** The public OAuth client id the Codex CLI uses; not a secret. */
+declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+/** Shared settings for the OAuth calls. */
+interface CodexOAuthOptions {
+  /** Auth issuer base URL; defaults to {@link DEFAULT_CODEX_ISSUER}. */
+  issuer?: string;
+  /** OAuth client id; defaults to {@link CODEX_CLIENT_ID}. */
+  clientId?: string;
+  /** Cancellation for the whole flow. */
+  signal?: AbortSignal;
+  /** HTTP implementation for tests and non-browser runtimes. */
+  fetch?: typeof fetch;
+  /** Deadline for each auth HTTP request. Defaults to 30 seconds. */
+  requestTimeoutMs?: number;
+  /** Maximum auth response bytes retained or parsed. Defaults to 1 MiB. */
+  maxResponseBytes?: number;
+  /** Maximum auth response chunks accepted. Defaults to 10,000. */
+  maxResponseChunks?: number;
+  /** Permit an http:// issuer for a trusted local test endpoint. Defaults to false. */
+  allowInsecureIssuer?: boolean;
+}
+/** A pending device authorization the user has to approve. */
+interface CodexDeviceCode {
+  /** URL to open in a browser. */
+  verificationUrl: string;
+  /** One-time code the user types there. */
+  userCode: string;
+  /** Opaque server-side handle for this authorization. */
+  deviceAuthId: string;
+  /** Seconds to wait between polls. */
+  intervalSeconds: number;
+}
+/** Progress reported while a device-code login runs. */
+interface CodexLoginProgress {
+  /** The code is ready; show it to the user. */
+  onPrompt?: (code: CodexDeviceCode) => void;
+  /** Called before each poll, so a CLI can show that it is still waiting. */
+  onPoll?: (elapsedMs: number) => void;
+}
+/**
+ * Start a device authorization.
+ * @param options - issuer, client id, cancellation.
+ * @returns the code and URL to show the user.
+ */
+declare function requestDeviceCode(options?: CodexOAuthOptions): Promise<CodexDeviceCode>;
+/** Result of a completed device-code login. */
+interface CodexLoginResult {
+  /** Where the credentials were written. */
+  location: string;
+  /** Signed-in account email, when the token discloses one. */
+  email: string | undefined;
+  /** Workspace/account id that requests will carry. */
+  accountId: string | undefined;
+  /** Plan type, when disclosed. */
+  planType: string | undefined;
+}
+/**
+ * Run a full device-code login and persist the result.
+ * @param store - where to write the credentials.
+ * @param options - issuer, client id, cancellation.
+ * @param progress - prompt and poll notifications for a CLI to render.
+ * @returns a summary of who signed in and where it was stored.
+ */
+declare function runDeviceCodeLogin(store: CodexCredentialStore, options?: CodexOAuthOptions, progress?: CodexLoginProgress): Promise<CodexLoginResult>;
+declare function runDeviceCodeLogin(store: CodexAuthStore, options?: CodexOAuthOptions, progress?: CodexLoginProgress): Promise<CodexLoginResult>;
+/** Why a refresh failed, which decides whether re-login is required. */
+type RefreshFailureKind = 'permanent' | 'transient';
+/** A refresh that did not succeed. */
+declare class CodexRefreshError extends AgentSdkError {
+  readonly kind: RefreshFailureKind;
+  constructor(message: string, kind: RefreshFailureKind, options?: ErrorOptions);
+}
+/**
+ * Exchange a refresh token for a fresh token set and persist it.
+ *
+ * Refresh tokens are SINGLE USE and rotate on every call, which is why this
+ * writes the result immediately: losing the new token means the next refresh
+ * replays a spent one and permanently fails. It is also why this SDK must not
+ * share a credential file with the Codex CLI.
+ * @param store - the credential store to update in place.
+ * @param options - issuer, client id, cancellation.
+ * @returns the refreshed tokens.
+ */
+declare function refreshCodexTokens(store: CodexCredentialStore, options?: CodexOAuthOptions): Promise<CodexTokens>;
+declare function refreshCodexTokens(store: CodexAuthStore, options?: CodexOAuthOptions): Promise<CodexTokens>;
+//#endregion
+//#region src/adapter.d.ts
+/** The ChatGPT-backed Codex API base. */
+declare const CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex";
+/** Client identifier this endpoint expects. See the module note. */
+declare const CODEX_ORIGINATOR = "codex_cli_rs";
+/**
+ * Client version sent when listing models.
+ *
+ * NOT cosmetic: the model catalog is gated on it, and an older value returns a
+ * shorter list or an empty one. Verified against a live account — `0.45.0` returns
+ * `{"models":[]}` while `1.0.0` returns the full set.
+ */
+declare const CODEX_CLIENT_VERSION = "1.0.0";
+/** Options for {@link codexAdapter}. */
+interface CodexAdapterOptions {
+  /**
+   * Where the credentials live.
+   *
+   * Required injection. Filesystem/env defaults belong to the Node auth wrapper.
+   */
+  authStore: CodexAuthStore;
+  /** Endpoint base; defaults to {@link CODEX_BASE_URL}. */
+  baseUrl?: string;
+  /** Client identifier; defaults to {@link CODEX_ORIGINATOR}. */
+  originator?: string;
+  /**
+   * Model catalog.
+   *
+   * Left undefined, the adapter DISCOVERS it from the endpoint, which is the right
+   * default here: the available models depend on the account's plan and on
+   * {@link CODEX_CLIENT_VERSION}, so no hardcoded list could be correct for
+   * everyone. Discovery also supplies `input_modalities`, without which every model
+   * would be assumed text-only and image input silently stripped.
+   */
+  models?: readonly ProviderCatalogModel[];
+  /** Client version used for catalog discovery; defaults to {@link CODEX_CLIENT_VERSION}. */
+  clientVersion?: string;
+  /** Maximum raw model-catalog response bytes. Defaults to 4 MiB. */
+  maxCatalogBytes?: number;
+  /** Maximum model entries accepted from discovery. Defaults to 2,048. */
+  maxCatalogModels?: number;
+  /** Maximum response chunks accepted during discovery. Defaults to 10,000. */
+  maxCatalogChunks?: number;
+  /** Model-catalog request deadline. Defaults to 30 seconds. */
+  catalogTimeoutMs?: number;
+  catalogTtlMs?: number;
+  catalogStaleTtlMs?: number;
+  catalogFailureBackoffMs?: number;
+  /** Output cap when neither caller nor catalog names one. */
+  defaultMaxTokens?: number;
+  /** Context capacity assumed for an uncatalogued model. */
+  defaultContextWindow?: number;
+  /** Idle bound while a stream read is outstanding. */
+  streamIdleTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  maxRequestBytes?: number;
+  maxResponseBytes?: number;
+  maxResponseChunks?: number;
+  maxSseEvents?: number;
+  maxSseEventChars?: number;
+  maxErrorBodyBytes?: number;
+  requestLoggerTimeoutMs?: number;
+  /** Retry policy this route owns. */
+  retryPolicy?: RetryPolicyConfig;
+  /** Optional exact wire-request logger; credentials/account ids are redacted. */
+  requestLogger?: ProviderRequestLogger;
+  /** Issuer and client id overrides for token refresh. */
+  oauth?: CodexOAuthOptions;
+  /**
+   * Stable key letting the provider reuse a cached prompt prefix across turns.
+   *
+   * Defaults to one id captured by the adapter/provider-plugin instance. Every
+   * conversation routed through that same instance shares the key. Use separate
+   * plugin instances (and routes) when cache identity must be isolated; this is
+   * not a conversation- or tenant-scoped setting.
+   */
+  promptCacheKey?: string;
+  fetch?: typeof globalThis.fetch;
+}
+interface CodexRevisionedAdapterOptions extends Omit<CodexAdapterOptions, 'authStore'> {
+  readonly authStore: CodexCredentialStore;
+}
+/**
+ * Create a Codex adapter.
+ * @param options - credential store, endpoint, and catalog overrides.
+ * @returns the adapter, ready to register.
+ */
+declare function codexAdapter(options: CodexRevisionedAdapterOptions): HttpModelAdapter;
+declare function codexAdapter(options: CodexAdapterOptions): HttpModelAdapter;
+interface CodexPluginOptions extends CodexAdapterOptions {
+  /** Registry routes installed by the plugin. Defaults to `['codex']`. */
+  readonly routes?: readonly string[];
+}
+interface CodexProviderOptions extends CodexRevisionedAdapterOptions {
+  readonly defaultModel?: string | ModelTarget;
+  readonly id?: string;
+  readonly routes?: readonly string[];
+}
+/** Preferred transactional plugin for installing the Universal Codex provider. */
+declare function codexPlugin(options: CodexProviderOptions): ComposableModelProviderPlugin & {
+  readonly family: 'codex';
+};
+declare function codexPlugin(options: CodexPluginOptions): ModelProviderPlugin;
+//#endregion
+export { ACCESS_TOKEN_REFRESH_WINDOW_MS, CODEX_BASE_URL, CODEX_CLIENT_ID, CODEX_CLIENT_VERSION, CODEX_ORIGINATOR, type CodexAdapterOptions, type CodexAuthFile, type CodexAuthStore, type CodexCredentialStore, type CodexDeviceCode, type CodexJwtClaims, type CodexLoginProgress, type CodexLoginResult, type CodexOAuthOptions, type CodexPluginOptions, type CodexProviderOptions, CodexRefreshError, type CodexRevisionedAdapterOptions, type CodexTokens, DEFAULT_CODEX_ISSUER, LAST_REFRESH_MAX_AGE_MS, type RefreshFailureKind, type ResponsesDialect, codexAdapter, codexPlugin, isFedrampAccount, memoryCodexAuthStore, memoryCodexCredentialStore, openAiResponsesProtocol, readJwtClaims, refreshCodexTokens, requestDeviceCode, requireTokens, resolveAccountId, runDeviceCodeLogin, shouldRefresh };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/common/store-types.ts","../src/auth.ts","../src/oauth.ts","../src/adapter.ts"],"mappings":";;;;;;UAGiB;EACf;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA,SAAS;EACT;;;UAIe;WACN;EACT,QAAQ,QAAQ;EAChB,MAAM,MAAM,gBAAgB;;;KAIlB,uBAAuB,gBAAgB;;;;iBCLnC,qBAAqB,UAAU,gBAAgB;;iBAa/C,2BAA2B,UAAU,gBAAgB;;UAgCpD;EACf;EACA;EACA;EACA;EACA;;;;;;;;;;;iBAuBc,cAAc,cAAc;;;;;;;;;iBAmC5B,iBAAiB,QAAQ;;iBAOzB,iBAAiB,QAAQ;;cAK5B;;cAGA;;;;;;;;;;;iBAYG,cAAc,MAAM,eAAe;;;;;;;iBAiBnC,cACd,MAAM,2BACN,mBACC;;;;cC7HU;;cAGA;;UASI;;EAEf;;EAEA;;EAEA,SAAS;;EAET,eAAe;;EAEf;;EAEA;;EAEA;;EAEA;;;UAIe;;EAEf;;EAEA;;EAEA;;EAEA;;;UAIe;;EAEf,YAAY,MAAM;;EAElB,UAAU;;;;;;;iBA6HU,kBACpB,UAAS,oBACR,QAAQ;;UAoKM;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;;;iBAUc,mBACd,OAAO,sBACP,UAAU,mBACV,WAAW,qBACV,QAAQ;iBACK,mBACd,OAAO,gBACP,UAAU,mBACV,WAAW,qBACV,QAAQ;;KA0BC;;cAGC,0BAA0B;WAC5B,MAAM;EAEf,YAAY,iBAAiB,MAAM,oBAAoB,UAAU;;;;;;;;;;;;;iBA0CnD,mBACd,OAAO,sBACP,UAAU,oBACT,QAAQ;iBACK,mBACd,OAAO,gBACP,UAAU,oBACT,QAAQ;;;;cChbE;;cAGA;;;;;;;;cASA;;UAkBI;;;;;;EAMf,WAAW;;EAEX;;EAEA;;;;;;;;;;EAUA,kBAAkB;;EAElB;;EAEA;;EAEA;;EAEA;;EAEA;EACA;EACA;EACA;;EAEA;;EAEA;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA,cAAc;;EAEd,gBAAgB;;EAEhB,QAAQ;;;;;;;;;EASR;EACA,eAAe,WAAW;;UAGX,sCAAsC,KAAK;WACjD,WAAW;;;;;;;iBA4EN,aAAa,SAAS,gCAAgC;iBACtD,aAAa,SAAS,sBAAsB;UAmM3C,2BAA2B;;WAEjC;;UAGM,6BAA6B;WACnC,wBAAwB;WACxB;WACA;;;iBAIK,YACd,SAAS,uBACR;WAA2C;;iBAC9B,YAAY,SAAS,qBAAqB"}