@opengeni/codex 0.2.7 → 0.2.10

package/dist/mcp-sanitize.d.ts

@@ -0,0 +1,33 @@
+import type { FetchLike } from "./fetch";
+/**
+ * Maps connector tool names to a Responses-API-legal charset and back. One
+ * instance per codex_apps transport (i.e. per turn): tools/list populates it,
+ * tools/call reads it. Idempotent across repeat listings.
+ */
+export declare class ToolNameMapper {
+    private readonly sanitizedToOriginal;
+    private readonly used;
+    /** Return a legal, unique name (<= EFFECTIVE_MAX_TOOL_NAME_LEN, so `<prefix>__name` <= 64) for `original`, recording the reverse mapping. */
+    sanitize(original: string): string;
+    /** Reverse a sanitized name back to the MCP server's original, if known. */
+    toOriginal(sanitized: string): string | undefined;
+}
+/** Sanitize a single JSON body (application/json MCP response). */
+export declare function sanitizeMcpJsonBody(text: string, mapper?: ToolNameMapper, namespaceSink?: Set<string>): string;
+/** Sanitize an SSE body: each JSON-RPC message rides on a `data:` line. */
+export declare function sanitizeMcpSseBody(text: string, mapper?: ToolNameMapper, namespaceSink?: Set<string>): string;
+/** Reverse a sanitized tools/call name back to the original; returns null if no rewrite is needed. */
+export declare function remapToolCallRequestBody(body: string, mapper: ToolNameMapper): string | null;
+/**
+ * Wrap a base fetch so the codex_apps MCP transport is Responses-API-compatible:
+ * tools/list responses get their names sanitized + bad outputSchemas dropped (and
+ * the name mapping recorded), and tools/call requests get their name reversed back
+ * to the MCP server's original. Only the POST request/response is buffered; the
+ * long-lived GET notification SSE stream is passed through untouched.
+ *
+ * P4 (Part B.1): an optional `namespaceSink` Set accumulates the ORIGINAL-dotted
+ * connector namespaces seen across every tools/list this turn (captured before the
+ * dot is sanitized away). The worker reads the (live, by-reference) Set after the
+ * turn to cache the serving account's connector set — packages/codex stays db-free.
+ */
+export declare function codexAppsSanitizingFetch(base?: FetchLike, namespaceSink?: Set<string>): FetchLike;

package/dist/model-output-truncation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Canonical model-facing tool-output truncation.
+ *
+ * Ported from openai/codex `rust-v0.144.6` (commit
+ * 5d1fbf26c43abc65a203928b2e31561cb039e06d):
+ *
+ * - `codex-rs/utils/string/src/truncate.rs`
+ * - `codex-rs/utils/output-truncation/src/lib.rs`
+ * - `codex-rs/core/src/context_manager/history.rs`
+ *
+ * The live gpt-5.6 model catalog declares a 10,000-token truncation policy.
+ * Codex applies a 1.2x allowance before serializing a function-call output, so
+ * the effective textual payload budget is 12,000 approximate tokens. Images,
+ * files, and encrypted content are preserved; textual content shares one
+ * sequential budget and carries an explicit head/tail truncation marker.
+ *
+ * This module deliberately has no database or Agents SDK dependency. Both the
+ * runtime request seam and the database history boundary call the same pure
+ * function, so replayed conversation truth is identical to live model input.
+ */
+export { MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL } from "./oversized-image-card";
+export type ModelHistoryItem = Record<string, unknown>;
+export declare const CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS = 10000;
+export declare const CODEX_TOOL_OUTPUT_SERIALIZATION_ALLOWANCE = 1.2;
+export declare const DEFAULT_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS = 10000;
+export declare const MODEL_TOOL_OUTPUT_OPAQUE_PAYLOAD_MAX_BYTES: number;
+export declare function modelToolOutputSerializationBudgetTokens(policyTokens?: number): number;
+export declare function approximateTokenCount(value: string): number;
+/** Exact Codex-style middle truncation for a token policy. */
+export declare function truncateMiddleWithTokenBudget(value: string, maxTokens: number): string;
+/**
+ * Bound every model-visible tool-result item. Non-result items are returned by
+ * reference. Result items are cloned only when their textual output changes.
+ */
+export declare function boundModelToolOutputItem<T extends ModelHistoryItem>(item: T, policyTokens?: number): T;
+export declare function boundModelToolOutputItems<T extends ModelHistoryItem>(items: readonly T[], policyTokens?: number): T[];

package/dist/normalize.d.ts

@@ -0,0 +1,8 @@
+/** Mutates a parsed Responses request body in place and returns it. Pure + synchronous + unit-testable. */
+export declare function normalizeCodexRequestBody(body: Record<string, unknown>, resolveModel: (slug: string) => string): Record<string, unknown>;
+/**
+ * Build a longest-prefix model resolver. Catalog slugs come from GET /models
+ * (api-client.ts). One leading `namespace/` segment is stripped first; an
+ * unknown slug returns the fallback (caller should log — spec §1.4 step 4).
+ */
+export declare function buildModelResolver(liveSlugs: readonly string[], fallbackSlug: string): (slug: string) => string;

package/dist/oversized-image-card.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Protocol-valid image shown to the model when an inline tool image exceeds the
+ * hard model-input allowance. The image channel cannot carry a text marker, so
+ * the omission itself is rendered as a legible PNG instead of corrupting the
+ * original base64 or pretending the placeholder is the real screenshot.
+ *
+ * Generated with the dependency-free bitmap/PNG encoder documented in
+ * `scripts/gen-screenshot-error-card.mjs`; the source image is 1,076x284 RGBA
+ * and 5,255 bytes. Rendered text:
+ *
+ *   SCREEN CAPTURE OMITTED
+ *   THE SCREEN CAPTURE IS TOO LARGE.
+ *   THIS IS A PLACEHOLDER, NOT THE REAL SCREEN.
+ *   DO NOT SAY THIS IS THE REAL SCREEN.
+ *   TELL THE USER TO TAKE A SMALLER CAPTURE.
+ */
+export declare const MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL = "data:image/png;base64,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";

package/dist/realtime-v3.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Codex GPT-Live Frameless Bidi (V3) wire adapter.
+ *
+ * These shapes are pinned to openai/codex@fa1d4c40. V3 delegates work with
+ * `delegation.created`; it does not expose the ordinary Realtime V2
+ * `function_call` protocol.
+ */
+export declare const CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT = 128;
+export declare const CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS = 8192;
+export declare const CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES = 500;
+export declare const CODEX_REALTIME_V3_MAX_EVENT_BYTES = 1048576;
+export declare const CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES = 1024;
+export declare const CODEX_REALTIME_V3_MAX_TEXT_BYTES = 131072;
+export type CodexRealtimeInitialItem = {
+    role: "user" | "developer" | "assistant";
+    text: string;
+};
+type ProviderEventIdentity = {
+    providerEventId: string | null;
+};
+export type CodexRealtimeV3Event = (ProviderEventIdentity & {
+    type: "session.started" | "session.updated";
+    sessionId: string;
+    instructions: string | null;
+}) | (ProviderEventIdentity & {
+    type: "input_transcript.added" | "output_transcript.added";
+    itemId: string | null;
+    text: string;
+}) | (ProviderEventIdentity & {
+    type: "output_audio.delta";
+    audio: string;
+    startMs: number | null;
+    endMs: number | null;
+}) | (ProviderEventIdentity & {
+    type: "turn.done";
+    turnId: string;
+    role: "user" | "assistant";
+    transcript: string;
+}) | (ProviderEventIdentity & {
+    type: "delegation.created";
+    delegationItemId: string;
+    inputTranscript: string;
+    offsetMs: number | null;
+}) | (ProviderEventIdentity & {
+    type: "error";
+    message: string;
+});
+export type CodexRealtimeV3ParseFailure = {
+    ok: false;
+    reason: "invalid_json" | "missing_type" | "unsupported_type" | "invalid_shape" | "oversized_event" | "oversized_field";
+    eventType: string | null;
+};
+export type CodexRealtimeV3ParseResult = {
+    ok: true;
+    event: CodexRealtimeV3Event;
+} | CodexRealtimeV3ParseFailure;
+export type CodexRealtimeV3ContextAppendChannel = "speakable" | "commentary";
+export type CodexRealtimeV3DelegationContextAppend = {
+    type: "delegation.context.append";
+    delegation_item_id: string;
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+    content: Array<{
+        type: "input_text";
+        text: string;
+    }>;
+};
+export type CodexRealtimeV3SessionContextAppend = {
+    type: "session.context.append";
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+    content: Array<{
+        type: "input_text";
+        text: string;
+    }>;
+};
+export declare function parseCodexRealtimeV3Event(payload: string): CodexRealtimeV3ParseResult;
+export declare function encodeCodexRealtimeV3DelegationContextAppend(input: {
+    delegationItemId: string;
+    text: string;
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+}): CodexRealtimeV3DelegationContextAppend[];
+export declare function encodeCodexRealtimeV3SessionContextAppend(input: {
+    text: string;
+    channel?: CodexRealtimeV3ContextAppendChannel | undefined;
+}): CodexRealtimeV3SessionContextAppend[];
+export declare function contextAppendChunks(text: string): string[];
+export {};

package/dist/realtime-v3.js

@@ -0,0 +1,25 @@
+import {
+  CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS,
+  CODEX_REALTIME_V3_MAX_EVENT_BYTES,
+  CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES,
+  CODEX_REALTIME_V3_MAX_TEXT_BYTES,
+  contextAppendChunks,
+  encodeCodexRealtimeV3DelegationContextAppend,
+  encodeCodexRealtimeV3SessionContextAppend,
+  parseCodexRealtimeV3Event
+} from "./chunk-MFVGCR3N.js";
+export {
+  CODEX_REALTIME_CONTEXT_APPEND_MAX_BYTES,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT,
+  CODEX_REALTIME_INITIAL_ITEMS_MAX_TOKENS,
+  CODEX_REALTIME_V3_MAX_EVENT_BYTES,
+  CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES,
+  CODEX_REALTIME_V3_MAX_TEXT_BYTES,
+  contextAppendChunks,
+  encodeCodexRealtimeV3DelegationContextAppend,
+  encodeCodexRealtimeV3SessionContextAppend,
+  parseCodexRealtimeV3Event
+};
+//# sourceMappingURL=realtime-v3.js.map

package/dist/realtime-v3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/realtime.d.ts

@@ -0,0 +1,48 @@
+import { type CodexAuthHeaders } from "./api-client";
+import { CODEX_REALTIME_MODEL, CODEX_REALTIME_VERSION } from "./constants";
+import type { CodexFetch } from "./device-code";
+import { type CodexRealtimeInitialItem } from "./realtime-v3";
+export declare const CODEX_REALTIME_VOICES: readonly ["juniper", "maple", "spruce", "ember", "vale", "breeze", "arbor", "sol", "cove"];
+export type CodexRealtimeVoice = (typeof CODEX_REALTIME_VOICES)[number];
+export type CodexRealtimeCallInput = {
+    /** Browser-created WebRTC offer. It must negotiate an audio media section. */
+    sdp: string;
+    /** This transport intentionally supports only Codex's Frameless/V3 protocol. */
+    version: typeof CODEX_REALTIME_VERSION;
+    /** Server-owned session/thread binding; sent upstream but never returned. */
+    sessionId: string;
+    /** Server-projected ordinary-session history for Frameless V3 bootstrap. */
+    initialItems?: CodexRealtimeInitialItem[] | undefined;
+    instructions?: string | undefined;
+    voice?: CodexRealtimeVoice | undefined;
+};
+export type CodexRealtimeCallResult = {
+    sdp: string;
+    version: typeof CODEX_REALTIME_VERSION;
+    model: typeof CODEX_REALTIME_MODEL;
+};
+export type CodexRealtimeErrorCode = "invalid_request" | "incompatible" | "authentication" | "entitlement" | "rate_limited" | "provider" | "invalid_response" | "network" | "timeout" | "cancelled";
+/** Safe provider failure: it contains no response body, credential, or account identity. */
+export declare class CodexRealtimeError extends Error {
+    readonly code: CodexRealtimeErrorCode;
+    readonly providerStatus: number | null;
+    constructor(code: CodexRealtimeErrorCode, message: string, providerStatus?: number | null);
+}
+export type CodexRealtimeCallOptions = {
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+};
+/**
+ * Create one native subscription-authenticated Codex GPT-Live V3 WebRTC call.
+ *
+ * There is deliberately no API-key or WebSocket fallback and no transport
+ * retry. A caller may refresh the same connected subscription after one 401,
+ * but this adapter always performs exactly one provider request.
+ */
+export declare function createCodexRealtimeCall(auth: CodexAuthHeaders, input: CodexRealtimeCallInput, fetchImpl?: CodexFetch, options?: CodexRealtimeCallOptions): Promise<CodexRealtimeCallResult>;
+/** Shared pin→active selection for worker turns and direct realtime calls. */
+export declare function selectCodexCredentialId(args: {
+    sessionPinnedCredentialId: string | null;
+    activeCredentialId: string | null;
+    connectedIds: ReadonlySet<string>;
+}): string | null;

package/dist/refresh.d.ts

@@ -0,0 +1,28 @@
+import type { CodexFetch } from "./device-code";
+/** Permanent — the workspace must reconnect (status => needs_relogin). */
+export declare class CodexReloginRequired extends Error {
+    constructor(message: string);
+}
+/** Transient — safe to retry later. */
+export declare class CodexRefreshTransient extends Error {
+    constructor(message: string);
+}
+/** Only present fields are returned (the server may rotate any subset). */
+export type CodexRefreshTokens = {
+    idToken?: string | undefined;
+    accessToken?: string | undefined;
+    refreshToken?: string | undefined;
+};
+/** POST {issuer}/oauth/token JSON {client_id, grant_type:"refresh_token", refresh_token}. manager.rs:1336-1340 */
+export declare function refreshCodexToken(refreshToken: string, fetchImpl?: CodexFetch, timeoutMs?: number): Promise<CodexRefreshTokens>;
+/** Decode a JWT payload (base64url, no signature check). */
+export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | null;
+/** access-token `exp` claim -> Date | null. token_data.rs:101-105 */
+export declare function accessTokenExpiry(accessToken: string): Date | null;
+/** id_token -> {chatgptAccountId, planType, isFedramp}. server.rs:827-832; token_data.rs:71-99 */
+export declare function parseIdToken(idToken: string): {
+    chatgptAccountId: string | null;
+    planType: string | null;
+    isFedramp: boolean;
+    email: string | null;
+};

package/dist/request-context.d.ts

@@ -0,0 +1,99 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export type CodexTokenSnapshot = {
+    accessToken: string;
+    chatgptAccountId: string | null;
+    isFedramp: boolean;
+};
+/**
+ * Multi-account P4 (Part A): a full usage snapshot scraped FOR FREE from the
+ * `x-codex-primary-*` / `x-codex-secondary-*` response headers the codex backend
+ * stamps on every `/codex/responses` turn (success AND 429 hard-cap). Integer-
+ * identical to GET /wham/usage but with zero extra round-trip. parseCodexUsageHeaders
+ * returns this only when BOTH windows parse, so a write is always a full 5-column
+ * snapshot (no partial-window clobber). Shape mirrors db's CodexAccountUsageSnapshot
+ * (non-null here: a partial read is filtered to null upstream, never half-written).
+ */
+export type CodexUsageHeaderSnapshot = {
+    primaryUsedPercent: number;
+    primaryResetAt: Date;
+    secondaryUsedPercent: number;
+    secondaryResetAt: Date;
+    checkedAt: Date;
+};
+export type CodexResponseTimeoutClass = "connect" | "headers" | "idle_stream" | "whole_request";
+export type CodexResponseTimeoutPolicy = {
+    /** Maximum wait for response headers, including DNS/TCP/TLS establishment. */
+    headersTimeoutMs: number;
+    /** Maximum silence between response-body chunks after headers arrive. */
+    streamIdleTimeoutMs: number;
+    /** Maximum wall time for one logical Responses request. */
+    wholeRequestTimeoutMs: number;
+    /**
+     * Reserved compatibility field. It is currently normalized to zero because
+     * an absent response does not prove that the provider never accepted a
+     * request, so automatic replay is not safe without an operation receipt.
+     */
+    noByteRetries: number;
+    retryBackoffMs: number;
+};
+export type CodexModelRequestEvent = {
+    requestId: string;
+    transportAttempt: number;
+    phase: "started" | "headers" | "first_byte" | "completed" | "failed" | "timed_out";
+    model?: string;
+    durationMs: number;
+    responseObserved: boolean;
+    timeoutPolicy: CodexResponseTimeoutPolicy;
+    timeoutClass?: CodexResponseTimeoutClass;
+    providerRequestId?: string;
+    status?: number;
+    willRetry?: boolean;
+};
+export type CodexRequestContext = {
+    clientVersion: string;
+    /**
+     * Stable per-session affinity id, sent as the `session_id` header on every
+     * request. This is the backend's STICKY CACHE-ROUTING key — measured
+     * 2026-07-12 with byte-identical ~99k-token gpt-5.6-sol requests on one idle
+     * account: without the header, repeat requests hit the prompt cache ~50% of
+     * the time (a per-request routing lottery across cache shards; matches the
+     * prod fleet's 48.6%); with a stable session_id, 10/10 requests hit at the
+     * 99.0% ceiling — Codex CLI parity (the CLI always sends it; its own last-3d
+     * token-weighted rate here is 94%). `prompt_cache_key` in the body only
+     * influences routing and does NOT pin it. Use the SAME value as
+     * prompt_cache_key (the OpenGeni sessionId) so routing and cache key agree.
+     */
+    sessionId?: string;
+    /** Worker-supplied: proactive refresh + single-flight + db persist. */
+    getToken: () => Promise<CodexTokenSnapshot>;
+    /** Forced refresh used for the 401 retry. */
+    refresh: () => Promise<CodexTokenSnapshot>;
+    /** Model-slug resolver (longest-prefix against the live catalog). */
+    resolveModel: (slug: string) => string;
+    /**
+     * Multi-account P4 (Part A): fire-and-forget usage-header sink. Called by
+     * codexSubscriptionFetch on EVERY response (sync, non-throwing, never awaited)
+     * with the parsed full-window snapshot. The worker records the latest into the
+     * P2 usage cache once per turn in its `finally` — packages/codex stays db-free.
+     */
+    onUsageHeaders?: (snapshot: CodexUsageHeaderSnapshot) => void;
+    /** Optional per-run override, primarily for deterministic transport tests. */
+    responseTimeoutPolicy?: Partial<CodexResponseTimeoutPolicy>;
+    /** Worker-owned durable audit sink; payloads never contain request bodies or auth. */
+    onModelRequestEvent?: (event: CodexModelRequestEvent) => Promise<void> | void;
+    /** Stable request identity supplied by the owning durable execution. */
+    nextRequestId?: () => string;
+    /**
+     * Optional Codex beta feature flags advertised as `x-codex-beta-features`
+     * (comma-separated). Used for remote compaction v2 (`remote_compaction_v2`).
+     */
+    betaFeatures?: readonly string[];
+    /**
+     * Optional turn analytics / routing metadata sent as `x-codex-turn-metadata`
+     * (JSON). Body `metadata` is stripped by normalize — never put request_kind there.
+     */
+    turnMetadata?: Record<string, unknown>;
+};
+export declare const codexRequestStorage: AsyncLocalStorage<CodexRequestContext>;
+/** Nest a Codex ALS scope with header overrides (e.g. remote compaction v2). */
+export declare function withCodexRequestOverrides<T>(overrides: Pick<CodexRequestContext, "betaFeatures" | "turnMetadata">, fn: () => T): T;

package/dist/reset-credits.d.ts

@@ -0,0 +1,33 @@
+export declare const CODEX_RATE_LIMIT_RESET_OUTCOMES: readonly ["reset", "nothingToReset", "noCredit", "alreadyRedeemed"];
+export type CodexRateLimitResetOutcome = (typeof CODEX_RATE_LIMIT_RESET_OUTCOMES)[number];
+export type CodexRateLimitResetType = "codexRateLimits" | "unknown";
+export type CodexRateLimitResetCreditStatus = "available" | "redeeming" | "redeemed" | "unknown";
+export type CodexRateLimitResetCredit = {
+    id: string;
+    resetType: CodexRateLimitResetType;
+    status: CodexRateLimitResetCreditStatus;
+    /** Unix seconds, matching account/rateLimits/read in Codex v0.144.6. */
+    grantedAt: number;
+    /** Unix seconds, or null when the provider says the credit does not expire. */
+    expiresAt: number | null;
+    title: string | null;
+    description: string | null;
+};
+export type CodexRateLimitResetCreditsDetails = {
+    availableCount: number;
+    credits: CodexRateLimitResetCredit[];
+};
+export type CodexRateLimitResetCreditsSummary = {
+    availableCount: number;
+    /** null means the provider supplied an authoritative count but no detail rows. */
+    credits: null;
+};
+export type CodexRateLimitResetConsumeResponse = {
+    outcome: CodexRateLimitResetOutcome;
+};
+/** Parse the exact detailed-credit backend response. Unknown rows stay view-only. */
+export declare function parseCodexRateLimitResetCreditsDetails(payload: unknown): CodexRateLimitResetCreditsDetails | null;
+/** Parse the count-only summary carried by GET /wham/usage. */
+export declare function parseCodexRateLimitResetCreditsSummary(payload: unknown): CodexRateLimitResetCreditsSummary | null;
+/** Parse one of the exact four v0.144.6 consume outcomes. Unknowns fail closed. */
+export declare function parseCodexRateLimitResetConsumeResponse(payload: unknown): CodexRateLimitResetConsumeResponse | null;

package/dist/response-timeout.d.ts

@@ -0,0 +1,28 @@
+import type { CodexResponseTimeoutClass, CodexResponseTimeoutPolicy } from "./request-context";
+export declare const CODEX_RESPONSE_TIMEOUT_ERROR_TYPE = "opengeni_codex_response_timeout";
+export declare const DEFAULT_CODEX_RESPONSE_TIMEOUT_POLICY: CodexResponseTimeoutPolicy;
+export declare function resolveCodexResponseTimeoutPolicy(override: Partial<CodexResponseTimeoutPolicy> | undefined): CodexResponseTimeoutPolicy;
+export declare class CodexResponseTimeoutError extends Error {
+    readonly timeoutClass: CodexResponseTimeoutClass;
+    readonly requestId: string;
+    readonly responseObserved: boolean;
+    readonly code = "opengeni_codex_response_timeout";
+    readonly type = "opengeni_codex_response_timeout";
+    constructor(timeoutClass: CodexResponseTimeoutClass, requestId: string, responseObserved: boolean, message?: string);
+}
+export type CodexResponseTimeoutInfo = {
+    timeoutClass: CodexResponseTimeoutClass;
+    requestId: string | null;
+    responseObserved: boolean;
+    message: string;
+};
+/**
+ * Recover structured transport timeouts through SDK wrapping. The optional
+ * legacy match is deliberately opt-in: `Request timed out.` alone has no
+ * provider provenance and the worker enables it only for a confirmed Codex
+ * subscription turn.
+ */
+export declare function classifyCodexResponseTimeoutError(error: unknown, options?: {
+    allowLegacyRequestTimeout?: boolean;
+}): CodexResponseTimeoutInfo | null;
+export declare function isPreHeadersTimeoutError(error: unknown): CodexResponseTimeoutClass | null;

package/dist/usage-normalize.d.ts

@@ -0,0 +1,61 @@
+import { type CodexRateLimitResetCreditsSummary } from "./reset-credits";
+/** The 5-hour (primary) window's `limit_window_seconds`. */
+export declare const CODEX_FIVE_HOUR_WINDOW_SECONDS = 18000;
+/** The weekly (secondary) window's `limit_window_seconds`. */
+export declare const CODEX_WEEKLY_WINDOW_SECONDS = 604800;
+/** One normalized usage window (applied to BOTH primary_window and secondary_window). */
+export type CodexUsageWindow = {
+    used: number;
+    limit: number;
+    remaining: number;
+    percent: number;
+    resetAt: string | null;
+    resetAfterSeconds: number | null;
+    limitWindowSeconds: number;
+};
+/** One additional (per-feature) limit (forward-compat; P2 renders nothing from it). */
+export type CodexAdditionalLimit = {
+    limitName: string;
+    meteredFeature: string;
+    fiveHour: CodexUsageWindow | null;
+    weekly: CodexUsageWindow | null;
+};
+export type CodexUsageStatus = "ok" | "limit_reached" | "error" | "no-data";
+/** The normalized usage payload — the P2/P3 contract. */
+export type CodexUsagePayload = {
+    status: CodexUsageStatus;
+    planType: string | null;
+    fiveHour: CodexUsageWindow | null;
+    weekly: CodexUsageWindow | null;
+    limitReached: boolean;
+    fetchedAt: string;
+    /**
+     * Authoritative count-only reset-credit summary from the usage response.
+     * Detail rows are fetched separately and are never synthesized from this.
+     */
+    rateLimitResetCredits: CodexRateLimitResetCreditsSummary | null;
+    /** Present only on a refresh/auth failure path; carries the precise reason. */
+    reason?: "needs_relogin" | undefined;
+    additionalLimits?: CodexAdditionalLimit[] | undefined;
+    credits?: {
+        hasCredits: boolean;
+        unlimited: boolean;
+        overageLimitReached: boolean;
+        balance: string;
+    } | undefined;
+};
+/**
+ * Build a normalized window from the PERSISTED cache columns (used_percent +
+ * absolute reset timestamp). The same 0–100 synthesis as the live path, with the
+ * skew-free countdown derived from `resetAt − now` at read time. Returns null when
+ * there is no cached percent yet. `limitWindowSeconds` is the constant that
+ * identifies the window (18000 ⇒ 5h, 604800 ⇒ weekly).
+ */
+export declare function buildCodexUsageWindowFromCache(usedPercent: number | null | undefined, resetAt: Date | string | null | undefined, limitWindowSeconds: number): CodexUsageWindow | null;
+/**
+ * Normalize a /wham/usage fetch result into the P2/P3 contract.
+ *
+ * @param httpStatus the HTTP status from fetchCodexUsage (404 ⇒ a limit body)
+ * @param rawPayload the parsed JSON body (or null when the body was unreadable)
+ */
+export declare function normalizeCodexUsage(httpStatus: number, rawPayload: unknown): CodexUsagePayload;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/codex",
-  "version": "0.2.7",
+  "version": "0.2.10",
   "description": "ChatGPT/Codex subscription auth + transport: device-code login, token refresh, and the Responses-backend fetch. Pure HTTP + transforms; no database dependency.",
   "license": "Apache-2.0",
   "repository": {
@@ -25,6 +25,10 @@
     "./constants": {
       "types": "./dist/constants.d.ts",
       "import": "./dist/constants.js"
+    },
+    "./realtime-v3": {
+      "types": "./dist/realtime-v3.d.ts",
+      "import": "./dist/realtime-v3.js"
     }
   },
   "publishConfig": {
@@ -32,8 +36,8 @@
     "provenance": true
   },
   "scripts": {
-    "typecheck": "tsgo --noEmit",
-    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "build": "bun ../../scripts/build-typescript-package.ts",
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {

package/src/api-client.ts

@@ -28,7 +28,8 @@ export type ResetCreditFetchFailureReason =
   | "network_error"
   | "timeout";
 
-function subscriptionHeaders(a: CodexAuthHeaders): Record<string, string> {
+/** Server-only headers shared by every ChatGPT/Codex subscription transport. */
+export function codexSubscriptionHeaders(a: CodexAuthHeaders): Record<string, string> {
   return {
     Authorization: `Bearer ${a.accessToken}`,
     ...(a.chatgptAccountId ? { "ChatGPT-Account-ID": a.chatgptAccountId } : {}),
@@ -48,7 +49,7 @@ export async function fetchCodexModels(
   const fetched = await runBoundedCodexOperation(async (signal) => {
     const res = await fetchImpl(
       `${CODEX_RESPONSES_BASE}/models?client_version=${encodeURIComponent(a.clientVersion)}`,
-      { method: "GET", headers: subscriptionHeaders(a), signal },
+      { method: "GET", headers: codexSubscriptionHeaders(a), signal },
     );
     if (!res.ok) {
       await res.arrayBuffer().catch(() => undefined);
@@ -72,7 +73,7 @@ export async function fetchCodexUsage(
   const fetched = await runBoundedCodexOperation(async (signal) => {
     const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/usage`, {
       method: "GET",
-      headers: subscriptionHeaders(a),
+      headers: codexSubscriptionHeaders(a),
       signal,
     });
     // A 404 may carry a usage-limit body; the route layer normalizes it to a limits state (spec §1.8c).
@@ -102,19 +103,27 @@ export async function fetchCodexRateLimitResetCredits(
   const fetched = await runBoundedCodexOperation(async (signal) => {
     const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/rate-limit-reset-credits`, {
       method: "GET",
-      headers: subscriptionHeaders(a),
+      headers: codexSubscriptionHeaders(a),
       signal,
     });
     if (!res.ok) {
       // Drain the body without retaining/logging it. Provider error bodies may
       // contain account-specific details and are not part of this contract.
       await res.arrayBuffer().catch(() => undefined);
-      return { ok: false as const, status: res.status, reason: "http_error" as const };
+      return {
+        ok: false as const,
+        status: res.status,
+        reason: "http_error" as const,
+      };
     }
     const details = parseCodexRateLimitResetCreditsDetails(await res.json().catch(() => null));
     return details
       ? { ok: true as const, status: res.status, details }
-      : { ok: false as const, status: res.status, reason: "invalid_response" as const };
+      : {
+          ok: false as const,
+          status: res.status,
+          reason: "invalid_response" as const,
+        };
   }, timeoutMs);
   return fetched.ok ? fetched.value : { ok: false, status: 0, reason: fetched.reason };
 }
@@ -146,7 +155,7 @@ export async function consumeCodexRateLimitResetCredit(
     const res = await fetchImpl(`${CODEX_WHAM_BASE}/wham/rate-limit-reset-credits/consume`, {
       method: "POST",
       headers: {
-        ...subscriptionHeaders(a),
+        ...codexSubscriptionHeaders(a),
         "content-type": "application/json",
       },
       body: JSON.stringify({
@@ -157,12 +166,20 @@ export async function consumeCodexRateLimitResetCredit(
     });
     if (!res.ok) {
       await res.arrayBuffer().catch(() => undefined);
-      return { ok: false as const, status: res.status, reason: "http_error" as const };
+      return {
+        ok: false as const,
+        status: res.status,
+        reason: "http_error" as const,
+      };
     }
     const result = parseCodexRateLimitResetConsumeResponse(await res.json().catch(() => null));
     return result
       ? { ok: true as const, status: res.status, result }
-      : { ok: false as const, status: res.status, reason: "invalid_response" as const };
+      : {
+          ok: false as const,
+          status: res.status,
+          reason: "invalid_response" as const,
+        };
   }, timeoutMs);
   return fetched.ok ? fetched.value : { ok: false, status: 0, reason: fetched.reason };
 }