@opengeni/codex 0.2.3 → 0.2.7

package/src/request-context.ts

@@ -30,6 +30,38 @@ export type CodexUsageHeaderSnapshot = {
   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;
   /**
@@ -58,6 +90,12 @@ export type CodexRequestContext = {
    * 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;
 };
 
 export const codexRequestStorage = new AsyncLocalStorage<CodexRequestContext>();

package/src/reset-credits.ts

@@ -0,0 +1,157 @@
+// Exact Codex rust-v0.144.6 rate-limit-reset-credit protocol normalization.
+// Provenance: stable commit 5d1fbf26c43abc65a203928b2e31561cb039e06d;
+// protocol-bearing files are byte-identical from rust-v0.144.1 through v0.144.6.
+//
+// Upstream sources (stable tag target 5d1fbf26c43abc65a203928b2e31561cb039e06d):
+// - codex-rs/backend-client/src/types.rs
+// - codex-rs/backend-client/src/client/rate_limit_resets.rs
+// - codex-rs/app-server-protocol/src/protocol/v2/account.rs
+//
+// The backend wire is snake_case. Public OpenGeni callers only receive the
+// normalized camelCase types below. Unknown reset types/statuses remain visible
+// but fail closed as `unknown`; they are never made actionable by this parser.
+
+import * as z from "zod/v4";
+
+export const CODEX_RATE_LIMIT_RESET_OUTCOMES = [
+  "reset",
+  "nothingToReset",
+  "noCredit",
+  "alreadyRedeemed",
+] as const;
+
+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;
+};
+
+const nonNegativeInteger = z.number().int().nonnegative();
+const backendTimestamp = z.string().datetime({ offset: true });
+
+const backendCreditSchema = z
+  .object({
+    id: z.string().min(1),
+    reset_type: z.string().min(1),
+    status: z.string().min(1),
+    granted_at: backendTimestamp,
+    expires_at: backendTimestamp.nullish(),
+    title: z.string().nullish(),
+    description: z.string().nullish(),
+  })
+  .passthrough();
+
+const backendDetailsSchema = z
+  .object({
+    credits: z.array(backendCreditSchema),
+    available_count: nonNegativeInteger,
+  })
+  .passthrough();
+
+const backendUsageSummarySchema = z
+  .object({
+    rate_limit_reset_credits: z
+      .object({ available_count: nonNegativeInteger })
+      .passthrough()
+      .nullish(),
+  })
+  .passthrough();
+
+const backendConsumeOutcomes = [
+  "reset",
+  "nothing_to_reset",
+  "no_credit",
+  "already_redeemed",
+] as const;
+
+const backendConsumeSchema = z
+  .object({
+    code: z.enum(backendConsumeOutcomes),
+    // The app-server intentionally discards this field. OpenGeni also refetches
+    // rather than inferring post-redemption state from it.
+    windows_reset: nonNegativeInteger.default(0),
+  })
+  .passthrough();
+
+function normalizedResetType(value: string): CodexRateLimitResetType {
+  return value === "codex_rate_limits" ? "codexRateLimits" : "unknown";
+}
+
+function normalizedCreditStatus(value: string): CodexRateLimitResetCreditStatus {
+  if (value === "available" || value === "redeeming" || value === "redeemed") {
+    return value;
+  }
+  return "unknown";
+}
+
+/** Parse the exact detailed-credit backend response. Unknown rows stay view-only. */
+export function parseCodexRateLimitResetCreditsDetails(
+  payload: unknown,
+): CodexRateLimitResetCreditsDetails | null {
+  const parsed = backendDetailsSchema.safeParse(payload);
+  if (!parsed.success) return null;
+  return {
+    availableCount: parsed.data.available_count,
+    credits: parsed.data.credits.map((credit) => ({
+      id: credit.id,
+      resetType: normalizedResetType(credit.reset_type),
+      status: normalizedCreditStatus(credit.status),
+      grantedAt: Math.floor(Date.parse(credit.granted_at) / 1000),
+      expiresAt:
+        credit.expires_at == null ? null : Math.floor(Date.parse(credit.expires_at) / 1000),
+      title: credit.title ?? null,
+      description: credit.description ?? null,
+    })),
+  };
+}
+
+/** Parse the count-only summary carried by GET /wham/usage. */
+export function parseCodexRateLimitResetCreditsSummary(
+  payload: unknown,
+): CodexRateLimitResetCreditsSummary | null {
+  const parsed = backendUsageSummarySchema.safeParse(payload);
+  const availableCount = parsed.success
+    ? parsed.data.rate_limit_reset_credits?.available_count
+    : undefined;
+  return availableCount === undefined ? null : { availableCount, credits: null };
+}
+
+/** Parse one of the exact four v0.144.6 consume outcomes. Unknowns fail closed. */
+export function parseCodexRateLimitResetConsumeResponse(
+  payload: unknown,
+): CodexRateLimitResetConsumeResponse | null {
+  const parsed = backendConsumeSchema.safeParse(payload);
+  if (!parsed.success) return null;
+  const outcomes: Record<(typeof backendConsumeOutcomes)[number], CodexRateLimitResetOutcome> = {
+    reset: "reset",
+    nothing_to_reset: "nothingToReset",
+    no_credit: "noCredit",
+    already_redeemed: "alreadyRedeemed",
+  };
+  return { outcome: outcomes[parsed.data.code] };
+}

package/src/response-timeout.ts

@@ -0,0 +1,159 @@
+import {
+  CODEX_RESPONSE_HEADERS_TIMEOUT_MS,
+  CODEX_RESPONSE_NO_BYTE_RETRIES,
+  CODEX_RESPONSE_RETRY_BACKOFF_MS,
+  CODEX_RESPONSE_STREAM_IDLE_TIMEOUT_MS,
+  CODEX_RESPONSE_WHOLE_TIMEOUT_MS,
+} from "./constants";
+import type { CodexResponseTimeoutClass, CodexResponseTimeoutPolicy } from "./request-context";
+
+export const CODEX_RESPONSE_TIMEOUT_ERROR_TYPE = "opengeni_codex_response_timeout";
+
+export const DEFAULT_CODEX_RESPONSE_TIMEOUT_POLICY: CodexResponseTimeoutPolicy = Object.freeze({
+  headersTimeoutMs: CODEX_RESPONSE_HEADERS_TIMEOUT_MS,
+  streamIdleTimeoutMs: CODEX_RESPONSE_STREAM_IDLE_TIMEOUT_MS,
+  wholeRequestTimeoutMs: CODEX_RESPONSE_WHOLE_TIMEOUT_MS,
+  noByteRetries: CODEX_RESPONSE_NO_BYTE_RETRIES,
+  retryBackoffMs: CODEX_RESPONSE_RETRY_BACKOFF_MS,
+});
+
+function positiveFinite(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+export function resolveCodexResponseTimeoutPolicy(
+  override: Partial<CodexResponseTimeoutPolicy> | undefined,
+): CodexResponseTimeoutPolicy {
+  return {
+    headersTimeoutMs: positiveFinite(
+      override?.headersTimeoutMs,
+      DEFAULT_CODEX_RESPONSE_TIMEOUT_POLICY.headersTimeoutMs,
+    ),
+    streamIdleTimeoutMs: positiveFinite(
+      override?.streamIdleTimeoutMs,
+      DEFAULT_CODEX_RESPONSE_TIMEOUT_POLICY.streamIdleTimeoutMs,
+    ),
+    wholeRequestTimeoutMs: positiveFinite(
+      override?.wholeRequestTimeoutMs,
+      DEFAULT_CODEX_RESPONSE_TIMEOUT_POLICY.wholeRequestTimeoutMs,
+    ),
+    // Automatic replay is fail-closed until the provider operation can be
+    // durably read/reconciled. Keep the field for policy/event compatibility,
+    // but never let a caller opt back into an unproved retry.
+    noByteRetries: 0,
+    retryBackoffMs:
+      override?.retryBackoffMs !== undefined &&
+      Number.isFinite(override.retryBackoffMs) &&
+      override.retryBackoffMs >= 0
+        ? override.retryBackoffMs
+        : DEFAULT_CODEX_RESPONSE_TIMEOUT_POLICY.retryBackoffMs,
+  };
+}
+
+export class CodexResponseTimeoutError extends Error {
+  readonly code = CODEX_RESPONSE_TIMEOUT_ERROR_TYPE;
+  readonly type = CODEX_RESPONSE_TIMEOUT_ERROR_TYPE;
+
+  constructor(
+    readonly timeoutClass: CodexResponseTimeoutClass,
+    readonly requestId: string,
+    readonly responseObserved: boolean,
+    message = `Codex response ${timeoutClass.replaceAll("_", " ")} timed out`,
+  ) {
+    super(message);
+    this.name = "CodexResponseTimeoutError";
+  }
+}
+
+export type CodexResponseTimeoutInfo = {
+  timeoutClass: CodexResponseTimeoutClass;
+  requestId: string | null;
+  responseObserved: boolean;
+  message: string;
+};
+
+function parseTimeoutClass(value: unknown): CodexResponseTimeoutClass | null {
+  return value === "connect" ||
+    value === "headers" ||
+    value === "idle_stream" ||
+    value === "whole_request"
+    ? value
+    : null;
+}
+
+/**
+ * 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 function classifyCodexResponseTimeoutError(
+  error: unknown,
+  options: { allowLegacyRequestTimeout?: boolean } = {},
+): CodexResponseTimeoutInfo | null {
+  let current: unknown = error;
+  for (let depth = 0; depth < 8 && current && typeof current === "object"; depth += 1) {
+    const value = current as Record<string, unknown>;
+    const nested =
+      value.error && typeof value.error === "object"
+        ? (value.error as Record<string, unknown>)
+        : undefined;
+    const type =
+      (typeof value.type === "string" ? value.type : undefined) ??
+      (typeof value.code === "string" ? value.code : undefined) ??
+      (typeof nested?.type === "string" ? nested.type : undefined) ??
+      (typeof nested?.code === "string" ? nested.code : undefined);
+    if (type === CODEX_RESPONSE_TIMEOUT_ERROR_TYPE || value.name === "CodexResponseTimeoutError") {
+      const klass =
+        parseTimeoutClass(value.timeoutClass) ??
+        parseTimeoutClass(nested?.timeout_class) ??
+        "headers";
+      return {
+        timeoutClass: klass,
+        requestId:
+          (typeof value.requestId === "string" ? value.requestId : undefined) ??
+          (typeof nested?.request_id === "string" ? nested.request_id : null),
+        responseObserved:
+          typeof value.responseObserved === "boolean"
+            ? value.responseObserved
+            : nested?.response_observed === true,
+        message:
+          (typeof value.message === "string" ? value.message : undefined) ??
+          (typeof nested?.message === "string" ? nested.message : "Codex response timed out"),
+      };
+    }
+    current = value.cause;
+  }
+
+  if (options.allowLegacyRequestTimeout && error && typeof error === "object") {
+    const value = error as Record<string, unknown>;
+    if (
+      value.name === "APIConnectionTimeoutError" ||
+      (value.message === "Request timed out." && value.name === "Error")
+    ) {
+      return {
+        timeoutClass: "headers",
+        requestId: null,
+        responseObserved: false,
+        message: String(value.message ?? "Request timed out."),
+      };
+    }
+  }
+  return null;
+}
+
+export function isPreHeadersTimeoutError(error: unknown): CodexResponseTimeoutClass | null {
+  const structured = classifyCodexResponseTimeoutError(error);
+  if (structured && !structured.responseObserved) {
+    return structured.timeoutClass;
+  }
+  if (!error || typeof error !== "object") return null;
+  const value = error as Record<string, unknown>;
+  const code = typeof value.code === "string" ? value.code : "";
+  const name = typeof value.name === "string" ? value.name : "";
+  const message = typeof value.message === "string" ? value.message : String(error);
+  if (/^(?:ETIMEDOUT|UND_ERR_CONNECT_TIMEOUT)$/i.test(code) || /ConnectTimeout/i.test(name)) {
+    return "connect";
+  }
+  return /connect(?:ion)?[^.]*timed?\s*out/i.test(`${name} ${message}`) ? "connect" : null;
+}

package/src/usage-normalize.ts

@@ -11,6 +11,10 @@
 // limit-reached body. The parser is zod over rate_limit.{primary,secondary}_window.
 
 import * as z from "zod/v4";
+import {
+  parseCodexRateLimitResetCreditsSummary,
+  type CodexRateLimitResetCreditsSummary,
+} from "./reset-credits";
 
 /** The 5-hour (primary) window's `limit_window_seconds`. */
 export const CODEX_FIVE_HOUR_WINDOW_SECONDS = 18000;
@@ -46,12 +50,22 @@ export type CodexUsagePayload = {
   weekly: CodexUsageWindow | null; // ← rate_limit.secondary_window (604800)
   limitReached: boolean; // rate_limit.limit_reached || !rate_limit.allowed
   fetchedAt: string; // ISO; server stamp
+  /**
+   * 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;
   // forward-compat, populated but unused in P2:
   additionalLimits?: CodexAdditionalLimit[] | undefined;
   credits?:
-    | { hasCredits: boolean; unlimited: boolean; overageLimitReached: boolean; balance: string }
+    | {
+        hasCredits: boolean;
+        unlimited: boolean;
+        overageLimitReached: boolean;
+        balance: string;
+      }
     | undefined;
 };
 
@@ -177,7 +191,10 @@ function pickWindows(
   // Track each unplaced window with the slot it came from, so the positional
   // fallback can place it (re-normalizing produces a fresh object that would
   // never match by reference — the bug this replaces).
-  const unplaced: Array<{ slot: "primary" | "secondary"; window: CodexUsageWindow }> = [];
+  const unplaced: Array<{
+    slot: "primary" | "secondary";
+    window: CodexUsageWindow;
+  }> = [];
   for (const [slot, raw] of [
     ["primary", primary],
     ["secondary", secondary],
@@ -219,6 +236,7 @@ export function normalizeCodexUsage(httpStatus: number, rawPayload: unknown): Co
     weekly: null,
     limitReached: false,
     fetchedAt,
+    rateLimitResetCredits: parseCodexRateLimitResetCreditsSummary(rawPayload),
   };
 
   // A non-404 HTTP error, or a body we could not parse at all, is an error state.