cartethyia 2.7.3 → 2.7.5

package/src/providers/integrations/claude/claude-cch.ts

@@ -1,148 +1,148 @@
-import { createHash } from "node:crypto";
-
-const MASK = 0xffffffffffffffffn;
-const PRIME1 = 0x9e3779b185ebca87n;
-const PRIME2 = 0xc2b2ae3d27d4eb4fn;
-const PRIME3 = 0x165667b19e3779f9n;
-const PRIME4 = 0x85ebca77c2b2ae63n;
-const PRIME5 = 0x27d4eb2f165667c5n;
-const CCH_SEED = 0x4d659218e32a3268n;
-const PLACEHOLDER = "cch=00000";
-const encoder = new TextEncoder();
-
-function round(acc: bigint, input: bigint): bigint {
-  let value = (acc + input * PRIME2) & MASK;
-  value = ((value << 31n) | (value >> 33n)) & MASK;
-  return (value * PRIME1) & MASK;
-}
-
-function mergeRound(acc: bigint, value: bigint): bigint {
-  let result = acc ^ round(0n, value);
-  return (result * PRIME1 + PRIME4) & MASK;
-}
-
-function read32(bytes: Uint8Array, offset: number): bigint {
-  return (
-    BigInt(bytes[offset] ?? 0) |
-    (BigInt(bytes[offset + 1] ?? 0) << 8n) |
-    (BigInt(bytes[offset + 2] ?? 0) << 16n) |
-    (BigInt(bytes[offset + 3] ?? 0) << 24n)
-  );
-}
-
-function read64(bytes: Uint8Array, offset: number): bigint {
-  let value = 0n;
-  for (let index = 0; index < 8; index += 1)
-    value |= BigInt(bytes[offset + index] ?? 0) << BigInt(index * 8);
-  return value;
-}
-
-function xxHash64(bytes: Uint8Array, seed: bigint): bigint {
-  let offset = 0;
-  let hash: bigint;
-  if (bytes.length >= 32) {
-    let v1 = (seed + PRIME1 + PRIME2) & MASK;
-    let v2 = (seed + PRIME2) & MASK;
-    let v3 = seed & MASK;
-    let v4 = (seed - PRIME1) & MASK;
-    while (offset <= bytes.length - 32) {
-      v1 = round(v1, read64(bytes, offset));
-      v2 = round(v2, read64(bytes, offset + 8));
-      v3 = round(v3, read64(bytes, offset + 16));
-      v4 = round(v4, read64(bytes, offset + 24));
-      offset += 32;
-    }
-    hash =
-      (((v1 << 1n) | (v1 >> 63n)) +
-        ((v2 << 7n) | (v2 >> 57n)) +
-        ((v3 << 12n) | (v3 >> 52n)) +
-        ((v4 << 18n) | (v4 >> 46n))) &
-      MASK;
-    hash = mergeRound(hash, v1);
-    hash = mergeRound(hash, v2);
-    hash = mergeRound(hash, v3);
-    hash = mergeRound(hash, v4);
-  } else hash = (seed + PRIME5) & MASK;
-  hash = (hash + BigInt(bytes.length)) & MASK;
-  while (offset <= bytes.length - 8) {
-    const value = round(0n, read64(bytes, offset));
-    hash ^= value;
-    hash = (((hash << 27n) | (hash >> 37n)) * PRIME1 + PRIME4) & MASK;
-    offset += 8;
-  }
-  if (offset <= bytes.length - 4) {
-    hash ^= (read32(bytes, offset) * PRIME1) & MASK;
-    hash = (((hash << 23n) | (hash >> 41n)) * PRIME2 + PRIME3) & MASK;
-    offset += 4;
-  }
-  while (offset < bytes.length) {
-    hash ^= (BigInt(bytes[offset] ?? 0) * PRIME5) & MASK;
-    hash = (((hash << 11n) | (hash >> 53n)) * PRIME1) & MASK;
-    offset += 1;
-  }
-  hash ^= hash >> 33n;
-  hash = (hash * PRIME2) & MASK;
-  hash ^= hash >> 29n;
-  hash = (hash * PRIME3) & MASK;
-  return (hash ^ (hash >> 32n)) & MASK;
-}
-
-/** Computes Claude Code's five-hex-digit CCH from the exact outgoing body bytes. */
-export function computeClaudeCch(body: Uint8Array): string {
-  return (xxHash64(body, CCH_SEED) & 0xfffffn).toString(16).padStart(5, "0");
-}
-
-/** Replaces the anchored Claude billing placeholder in a mutable body before sending. */
-export function patchClaudeCch(body: Uint8Array): boolean {
-  const marker = encoder.encode('"system":[{"type":"text","text":"x-anthropic-billing-header:');
-  const placeholder = encoder.encode(PLACEHOLDER);
-  let markerIndex = -1;
-  outer: for (let index = 0; index <= body.length - marker.length; index += 1) {
-    for (let j = 0; j < marker.length; j += 1) if (body[index + j] !== marker[j]) continue outer;
-    markerIndex = index;
-    break;
-  }
-  if (markerIndex < 0) return false;
-  const start = markerIndex + marker.length;
-  const end = Math.min(body.length - placeholder.length, start + 150);
-  for (let index = start; index <= end; index += 1) {
-    let found = true;
-    for (let j = 0; j < placeholder.length; j += 1)
-      if (body[index + j] !== placeholder[j]) {
-        found = false;
-        break;
-      }
-    if (!found) continue;
-    const cch = encoder.encode(computeClaudeCch(body));
-    body.set(cch, index + 4);
-    return true;
-  }
-  return false;
-}
-
-/** Harness identity instruction, sent on OAuth dispatch. */
-export const CLAUDE_CODE_SYSTEM_INSTRUCTION =
-  "You are Claude Code, Anthropic's official CLI for Claude.";
-
-/**
- * Builds the billing header text with the captured version suffix:
- * `cc_version={ver}.{sha256("59cf53e54c78" + chars + ver)[0:3]}` where
- * chars are the 5th/8th/21st chars of the first user text (or "0" when
- * absent). `cc_entrypoint=cli` matches the harness UA `(external, cli)`;
- * an older snapshot used `claude-desktop`, which is unverified from local
- * evidence, so cli is kept with this note.
- */
-export function createClaudeBillingText(userText: string, version: string): string {
-  const chars = [4, 7, 20].map((index) => userText[index] ?? "0").join("");
-  const suffix = createHash("sha256")
-    .update(`59cf53e54c78${chars}${version}`)
-    .digest("hex")
-    .slice(0, 3);
-  return `x-anthropic-billing-header: cc_version=${version}.${suffix}; cc_entrypoint=cli; cch=00000;`;
-}
-
-/** Patches a string request body and returns its encoded bytes, or undefined when no billing block exists. */
-export function patchClaudeCchBody(body: string): Uint8Array | undefined {
-  const bytes = encoder.encode(body);
-  return patchClaudeCch(bytes) ? bytes : undefined;
-}
+import { createHash } from "node:crypto";
+
+const MASK = 0xffffffffffffffffn;
+const PRIME1 = 0x9e3779b185ebca87n;
+const PRIME2 = 0xc2b2ae3d27d4eb4fn;
+const PRIME3 = 0x165667b19e3779f9n;
+const PRIME4 = 0x85ebca77c2b2ae63n;
+const PRIME5 = 0x27d4eb2f165667c5n;
+const CCH_SEED = 0x4d659218e32a3268n;
+const PLACEHOLDER = "cch=00000";
+const encoder = new TextEncoder();
+
+function round(acc: bigint, input: bigint): bigint {
+  let value = (acc + input * PRIME2) & MASK;
+  value = ((value << 31n) | (value >> 33n)) & MASK;
+  return (value * PRIME1) & MASK;
+}
+
+function mergeRound(acc: bigint, value: bigint): bigint {
+  let result = acc ^ round(0n, value);
+  return (result * PRIME1 + PRIME4) & MASK;
+}
+
+function read32(bytes: Uint8Array, offset: number): bigint {
+  return (
+    BigInt(bytes[offset] ?? 0) |
+    (BigInt(bytes[offset + 1] ?? 0) << 8n) |
+    (BigInt(bytes[offset + 2] ?? 0) << 16n) |
+    (BigInt(bytes[offset + 3] ?? 0) << 24n)
+  );
+}
+
+function read64(bytes: Uint8Array, offset: number): bigint {
+  let value = 0n;
+  for (let index = 0; index < 8; index += 1)
+    value |= BigInt(bytes[offset + index] ?? 0) << BigInt(index * 8);
+  return value;
+}
+
+function xxHash64(bytes: Uint8Array, seed: bigint): bigint {
+  let offset = 0;
+  let hash: bigint;
+  if (bytes.length >= 32) {
+    let v1 = (seed + PRIME1 + PRIME2) & MASK;
+    let v2 = (seed + PRIME2) & MASK;
+    let v3 = seed & MASK;
+    let v4 = (seed - PRIME1) & MASK;
+    while (offset <= bytes.length - 32) {
+      v1 = round(v1, read64(bytes, offset));
+      v2 = round(v2, read64(bytes, offset + 8));
+      v3 = round(v3, read64(bytes, offset + 16));
+      v4 = round(v4, read64(bytes, offset + 24));
+      offset += 32;
+    }
+    hash =
+      (((v1 << 1n) | (v1 >> 63n)) +
+        ((v2 << 7n) | (v2 >> 57n)) +
+        ((v3 << 12n) | (v3 >> 52n)) +
+        ((v4 << 18n) | (v4 >> 46n))) &
+      MASK;
+    hash = mergeRound(hash, v1);
+    hash = mergeRound(hash, v2);
+    hash = mergeRound(hash, v3);
+    hash = mergeRound(hash, v4);
+  } else hash = (seed + PRIME5) & MASK;
+  hash = (hash + BigInt(bytes.length)) & MASK;
+  while (offset <= bytes.length - 8) {
+    const value = round(0n, read64(bytes, offset));
+    hash ^= value;
+    hash = (((hash << 27n) | (hash >> 37n)) * PRIME1 + PRIME4) & MASK;
+    offset += 8;
+  }
+  if (offset <= bytes.length - 4) {
+    hash ^= (read32(bytes, offset) * PRIME1) & MASK;
+    hash = (((hash << 23n) | (hash >> 41n)) * PRIME2 + PRIME3) & MASK;
+    offset += 4;
+  }
+  while (offset < bytes.length) {
+    hash ^= (BigInt(bytes[offset] ?? 0) * PRIME5) & MASK;
+    hash = (((hash << 11n) | (hash >> 53n)) * PRIME1) & MASK;
+    offset += 1;
+  }
+  hash ^= hash >> 33n;
+  hash = (hash * PRIME2) & MASK;
+  hash ^= hash >> 29n;
+  hash = (hash * PRIME3) & MASK;
+  return (hash ^ (hash >> 32n)) & MASK;
+}
+
+/** Computes Claude Code's five-hex-digit CCH from the exact outgoing body bytes. */
+export function computeClaudeCch(body: Uint8Array): string {
+  return (xxHash64(body, CCH_SEED) & 0xfffffn).toString(16).padStart(5, "0");
+}
+
+/** Replaces the anchored Claude billing placeholder in a mutable body before sending. */
+export function patchClaudeCch(body: Uint8Array): boolean {
+  const marker = encoder.encode('"system":[{"type":"text","text":"x-anthropic-billing-header:');
+  const placeholder = encoder.encode(PLACEHOLDER);
+  let markerIndex = -1;
+  outer: for (let index = 0; index <= body.length - marker.length; index += 1) {
+    for (let j = 0; j < marker.length; j += 1) if (body[index + j] !== marker[j]) continue outer;
+    markerIndex = index;
+    break;
+  }
+  if (markerIndex < 0) return false;
+  const start = markerIndex + marker.length;
+  const end = Math.min(body.length - placeholder.length, start + 150);
+  for (let index = start; index <= end; index += 1) {
+    let found = true;
+    for (let j = 0; j < placeholder.length; j += 1)
+      if (body[index + j] !== placeholder[j]) {
+        found = false;
+        break;
+      }
+    if (!found) continue;
+    const cch = encoder.encode(computeClaudeCch(body));
+    body.set(cch, index + 4);
+    return true;
+  }
+  return false;
+}
+
+/** Harness identity instruction, sent on OAuth dispatch. */
+export const CLAUDE_CODE_SYSTEM_INSTRUCTION =
+  "You are Claude Code, Anthropic's official CLI for Claude.";
+
+/**
+ * Builds the billing header text with the captured version suffix:
+ * `cc_version={ver}.{sha256("59cf53e54c78" + chars + ver)[0:3]}` where
+ * chars are the 5th/8th/21st chars of the first user text (or "0" when
+ * absent). `cc_entrypoint=cli` matches the harness UA `(external, cli)`;
+ * an older snapshot used `claude-desktop`, which is unverified from local
+ * evidence, so cli is kept with this note.
+ */
+export function createClaudeBillingText(userText: string, version: string): string {
+  const chars = [4, 7, 20].map((index) => userText[index] ?? "0").join("");
+  const suffix = createHash("sha256")
+    .update(`59cf53e54c78${chars}${version}`)
+    .digest("hex")
+    .slice(0, 3);
+  return `x-anthropic-billing-header: cc_version=${version}.${suffix}; cc_entrypoint=cli; cch=00000;`;
+}
+
+/** Patches a string request body and returns its encoded bytes, or undefined when no billing block exists. */
+export function patchClaudeCchBody(body: string): Uint8Array | undefined {
+  const bytes = encoder.encode(body);
+  return patchClaudeCch(bytes) ? bytes : undefined;
+}

package/src/providers/integrations/claude/claude-credentials.ts

@@ -10,7 +10,7 @@ function invalidHeader(
   message: string,
   details: Readonly<Record<string, unknown>> = {},
 ): GatewayError {
-  return new GatewayError("invalid_request", 400, message, details);
+  return new GatewayError("invalid_request", 400, `${message} (request {requestId}). Check the shape of what you sent — then resend 🪞`, details);
 }
 
 function decodeSecret(secret: Uint8Array | undefined): string | undefined {

package/src/providers/integrations/claude/claude-slow-lane-retry.ts

@@ -96,5 +96,5 @@ export function planSlowLaneRetry(
 
 /** Typed error for a caller-aborted wait, so it is never read as a failure. */
 export function slowLaneAborted(): GatewayError {
-  return new GatewayError("transport_closed", 499, "Aborted during slow-lane capacity wait");
+  return new GatewayError("transport_closed", 499, "The request was cancelled during the slow-lane capacity wait (request {requestId}). Send it again whenever ready 🙃");
 }

package/src/providers/integrations/claude/claude.ts

@@ -61,6 +61,7 @@ import {
   refusalCreditToken,
   sharedFallbackCreditCache,
 } from "./fallback-credit";
+import { assertCredentialKind, assertWireFamily } from "../../provider-contracts";
 import type { ProviderDispatchTarget, ProviderAdapter, ProviderDispatchContext } from "../../provider-contracts";
 import { defineModel } from "../../provider-model-definition";
 import type { ModelDefinition } from "../../provider-model-definition";
@@ -185,21 +186,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        "claude supports messages only",
-      );
+      assertWireFamily(candidate, "messages", "claude");
     }
     if (
       context.credential.credential_kind !== "oauth" &&
       context.credential.credential_kind !== "scoped_access_token"
     ) {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        `claude: the assistant OAuth credential required (got credential_kind=${context.credential.credential_kind})`,
-      );
+      assertCredentialKind(context.credential, ["oauth", "scoped_access_token"], "claude");
     }
     const customHeaders = filterClaudeCustomHeaders({
       ...this.customHeaders,

package/src/providers/integrations/claude/fallback-credit.ts

@@ -27,6 +27,7 @@
  */
 
 import { GatewayError } from "../../../protocol/gateway-error";
+import { fnv1a32 } from "../shared/hash";
 
 const CREDIT_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_CACHE_SIZE = 64;
@@ -122,15 +123,10 @@ export class FallbackCreditCache {
 
 /**
  * Compute a simple hash of the request body for cache keying.
- * Uses FNV-1a — fast, deterministic, sufficient for cache identity.
+ * FNV-1a — fast, deterministic, sufficient for cache identity.
  */
 export function hashBody(body: string): string {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < body.length; i++) {
-    hash ^= body.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193);
-  }
-  return (hash >>> 0).toString(36);
+  return fnv1a32(body).toString(36);
 }
 
 // Shared process-wide cache instance

package/src/providers/integrations/cline/cline.ts

@@ -28,7 +28,7 @@ const CLINE_MODELS_CATALOG_PATH = "/ai/cline/models" as const;
 
 
 
-export function workosToken(token: string): string {
+function workosToken(token: string): string {
   return token.startsWith("workos:") ? token : `workos:${token}`;
 }
 
@@ -150,7 +150,7 @@ function clinePrePayload(
     const cur = typeof payload["max_tokens"] === "number" ? (payload["max_tokens"] as number) : 0;
     payload["max_tokens"] = Math.max(cur, 256);
     // keep GatewayError reachable
-    if (!model) throw new GatewayError("invalid_request", 400, "Cline model is required");
+    if (!model) throw new GatewayError("invalid_request", 400, "Cline model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
 }
 

package/src/providers/integrations/cloudflareai/cloudflareai.ts

@@ -16,6 +16,7 @@
  *    protocol at the `/anthropic` path suffix, including `thinking_delta`
  *    blocks, so the Messages leg is built directly.
  */
+import { assertWireFamily } from "../../provider-contracts";
 import type {
   ProviderAdapter,
   ProviderDispatchContext,
@@ -57,7 +58,7 @@ function cloudflareEnvelope(context: ProviderDispatchContext): {
 } {
   const secret = context.credential.secret;
   if (secret === undefined || secret.length === 0) {
-    throw new GatewayError("invalid_request", 400, "cloudflareai: credential is missing a secret value");
+    throw new GatewayError("invalid_request", 400, "cloudflareai: credential is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑");
   }
   let envelope: ReturnType<typeof decodeCloudflareAiGatewayCredential>;
   try {
@@ -66,7 +67,7 @@ function cloudflareEnvelope(context: ProviderDispatchContext): {
     throw new GatewayError(
       "invalid_request",
       400,
-      `cloudflareai: ${error instanceof Error ? error.message : "stored credential is not a Cloudflare envelope"}`,
+      `cloudflareai: ${error instanceof Error ? error.message : "stored credential is not a Cloudflare envelope"} (request {requestId}). Wrong key, right door — check the credential 🔑`,
     );
   }
   return { token: envelope.token, baseUrl: cloudflareBaseUrl(envelope.accountId, envelope.gatewayId) };
@@ -93,11 +94,7 @@ class CloudflareAiGatewayAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "messages") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `cloudflareai supports messages only, got ${candidate.wire_family}`,
-      );
+      assertWireFamily(candidate, "messages", "cloudflareai");
     }
     const { token, baseUrl } = cloudflareEnvelope(context);
     const outbound = buildClaudeMessagesRequest({

package/src/providers/integrations/codex/codex-device-code.ts

@@ -1,101 +1,101 @@
-import type { FetchLike } from "../../authentication/oauth-client";
-
-export const CODEX_DEVICE_USERCODE_URL = "https://auth.openai.com/api/accounts/deviceauth/usercode";
-export const CODEX_DEVICE_TOKEN_URL = "https://auth.openai.com/api/accounts/deviceauth/token";
-
-/**
- * Lifetime of one device authorization, in seconds.
- *
- * The Codex device endpoint states no expiry, so the flow bounds itself: this
- * is both what `startDeviceAuth` reports to the dashboard (its own countdown)
- * and what the poll checks before spending a request on a dead authorization.
- */
-export const CODEX_DEVICE_TTL_SECONDS = 900;
-
-interface CodexDeviceStart {
-  readonly deviceAuthId: string;
-  readonly userCode: string;
-  readonly intervalSeconds: number;
-}
-
-interface CodexDeviceAuthorization {
-  readonly authorizationCode: string;
-  readonly codeVerifier: string;
-}
-
-/** Validates persisted provider-private device state read back from the flow store. */
-export function parseCodexDeviceStart(value: Record<string, unknown>): CodexDeviceStart | undefined {
-  const { deviceAuthId, userCode, intervalSeconds } = value;
-  if (typeof deviceAuthId !== "string" || typeof userCode !== "string") return undefined;
-  if (typeof intervalSeconds !== "number" || !Number.isFinite(intervalSeconds)) return undefined;
-  return { deviceAuthId, userCode, intervalSeconds: Math.max(0, intervalSeconds) };
-}
-
-interface DeviceUserCodeResponse {
-  device_auth_id?: unknown;
-  user_code?: unknown;
-  interval?: unknown;
-}
-interface DeviceTokenResponse {
-  authorization_code?: unknown;
-  code_verifier?: unknown;
-}
-
-function jsonHeaders(): HeadersInit {
-  return { "content-type": "application/json", accept: "application/json" };
-}
-
-export async function startCodexDeviceAuth(
-  clientId: string,
-  fetchFn: FetchLike = globalThis.fetch,
-): Promise<CodexDeviceStart> {
-  const response = await fetchFn(CODEX_DEVICE_USERCODE_URL, {
-    method: "POST",
-    headers: jsonHeaders(),
-    body: JSON.stringify({ client_id: clientId }),
-  });
-  if (!response.ok) throw new Error(`Codex device authorization failed (${response.status})`);
-  const body = (await response.json()) as DeviceUserCodeResponse;
-  if (typeof body.device_auth_id !== "string" || typeof body.user_code !== "string")
-    throw new Error("Codex device authorization returned an invalid response");
-  const interval =
-    typeof body.interval === "number" && Number.isFinite(body.interval)
-      ? Math.max(0, body.interval)
-      : 5;
-  return { deviceAuthId: body.device_auth_id, userCode: body.user_code, intervalSeconds: interval };
-}
-
-/**
- * One device-token poll attempt.
- *
- * Returns `undefined` while the user has not approved yet (the endpoint answers
- * 403/404) and the parsed PKCE pair once it has. Deliberately a single request:
- * the dashboard owns the polling cadence, so the console route returns
- * `pending` between attempts instead of holding one HTTP request open for the
- * whole authorization window. A blocking loop here occupied a console worker
- * for up to the full TTL and made the dialog's own interval meaningless.
- */
-export async function pollCodexDeviceAuth(
-  device: CodexDeviceStart,
-  fetchFn: FetchLike = globalThis.fetch,
-): Promise<CodexDeviceAuthorization | undefined> {
-  let response: Response;
-  try {
-    response = await fetchFn(CODEX_DEVICE_TOKEN_URL, {
-      method: "POST",
-      headers: jsonHeaders(),
-      body: JSON.stringify({ device_auth_id: device.deviceAuthId, user_code: device.userCode }),
-    });
-  } catch (error) {
-    // A network failure is not "not approved yet": surface it so the caller
-    // can return a failed verdict instead of polling to expiry.
-    throw new Error(`Codex device polling failed: ${error instanceof Error ? error.message : String(error)}`);
-  }
-  // 403/404 are the endpoint's "not approved yet" answers, not failures.
-  if (response.status === 403 || response.status === 404) return undefined;
-  if (!response.ok) throw new Error(`Codex device polling failed (${response.status})`);
-  const body = (await response.json()) as DeviceTokenResponse;
-  if (typeof body.authorization_code === "string" && typeof body.code_verifier === "string")
-    return { authorizationCode: body.authorization_code, codeVerifier: body.code_verifier };
-  return undefined;
-}
+import type { FetchLike } from "../../authentication/oauth-client";
+
+export const CODEX_DEVICE_USERCODE_URL = "https://auth.openai.com/api/accounts/deviceauth/usercode";
+export const CODEX_DEVICE_TOKEN_URL = "https://auth.openai.com/api/accounts/deviceauth/token";
+
+/**
+ * Lifetime of one device authorization, in seconds.
+ *
+ * The Codex device endpoint states no expiry, so the flow bounds itself: this
+ * is both what `startDeviceAuth` reports to the dashboard (its own countdown)
+ * and what the poll checks before spending a request on a dead authorization.
+ */
+export const CODEX_DEVICE_TTL_SECONDS = 900;
+
+interface CodexDeviceStart {
+  readonly deviceAuthId: string;
+  readonly userCode: string;
+  readonly intervalSeconds: number;
+}
+
+interface CodexDeviceAuthorization {
+  readonly authorizationCode: string;
+  readonly codeVerifier: string;
+}
+
+/** Validates persisted provider-private device state read back from the flow store. */
+export function parseCodexDeviceStart(value: Record<string, unknown>): CodexDeviceStart | undefined {
+  const { deviceAuthId, userCode, intervalSeconds } = value;
+  if (typeof deviceAuthId !== "string" || typeof userCode !== "string") return undefined;
+  if (typeof intervalSeconds !== "number" || !Number.isFinite(intervalSeconds)) return undefined;
+  return { deviceAuthId, userCode, intervalSeconds: Math.max(0, intervalSeconds) };
+}
+
+interface DeviceUserCodeResponse {
+  device_auth_id?: unknown;
+  user_code?: unknown;
+  interval?: unknown;
+}
+interface DeviceTokenResponse {
+  authorization_code?: unknown;
+  code_verifier?: unknown;
+}
+
+function jsonHeaders(): HeadersInit {
+  return { "content-type": "application/json", accept: "application/json" };
+}
+
+export async function startCodexDeviceAuth(
+  clientId: string,
+  fetchFn: FetchLike = globalThis.fetch,
+): Promise<CodexDeviceStart> {
+  const response = await fetchFn(CODEX_DEVICE_USERCODE_URL, {
+    method: "POST",
+    headers: jsonHeaders(),
+    body: JSON.stringify({ client_id: clientId }),
+  });
+  if (!response.ok) throw new Error(`Codex device authorization failed (${response.status})`);
+  const body = (await response.json()) as DeviceUserCodeResponse;
+  if (typeof body.device_auth_id !== "string" || typeof body.user_code !== "string")
+    throw new Error("Codex device authorization returned an invalid response");
+  const interval =
+    typeof body.interval === "number" && Number.isFinite(body.interval)
+      ? Math.max(0, body.interval)
+      : 5;
+  return { deviceAuthId: body.device_auth_id, userCode: body.user_code, intervalSeconds: interval };
+}
+
+/**
+ * One device-token poll attempt.
+ *
+ * Returns `undefined` while the user has not approved yet (the endpoint answers
+ * 403/404) and the parsed PKCE pair once it has. Deliberately a single request:
+ * the dashboard owns the polling cadence, so the console route returns
+ * `pending` between attempts instead of holding one HTTP request open for the
+ * whole authorization window. A blocking loop here occupied a console worker
+ * for up to the full TTL and made the dialog's own interval meaningless.
+ */
+export async function pollCodexDeviceAuth(
+  device: CodexDeviceStart,
+  fetchFn: FetchLike = globalThis.fetch,
+): Promise<CodexDeviceAuthorization | undefined> {
+  let response: Response;
+  try {
+    response = await fetchFn(CODEX_DEVICE_TOKEN_URL, {
+      method: "POST",
+      headers: jsonHeaders(),
+      body: JSON.stringify({ device_auth_id: device.deviceAuthId, user_code: device.userCode }),
+    });
+  } catch (error) {
+    // A network failure is not "not approved yet": surface it so the caller
+    // can return a failed verdict instead of polling to expiry.
+    throw new Error(`Codex device polling failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  // 403/404 are the endpoint's "not approved yet" answers, not failures.
+  if (response.status === 403 || response.status === 404) return undefined;
+  if (!response.ok) throw new Error(`Codex device polling failed (${response.status})`);
+  const body = (await response.json()) as DeviceTokenResponse;
+  if (typeof body.authorization_code === "string" && typeof body.code_verifier === "string")
+    return { authorizationCode: body.authorization_code, codeVerifier: body.code_verifier };
+  return undefined;
+}

package/src/providers/integrations/codex/codex-errors.ts

@@ -167,7 +167,7 @@ export async function mapCodexErrorResponse(res: Response): Promise<never> {
   throw new GatewayError(
     classification.code,
     classification.status,
-    friendlyMessage ?? sanitized,
+    `${friendlyMessage ?? sanitized} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
     details,
     classification.origin,
   );

package/src/providers/integrations/codex/codex-oauth.ts

@@ -272,4 +272,3 @@ export class CodexOAuthClient extends OAuthDeviceFlow {
 }
 
 export const codexOAuthClient = new CodexOAuthClient();
-export { exchangeCodeForToken };