@iislee/opencodex 2.11.0 → 2.31.0

package/src/codex/prompt-lock.ts

@@ -0,0 +1,143 @@
+/**
+ * prompt-lock.ts — advisory cross-process lock for prompt-layer mutations.
+ *
+ * An in-process mutex only serialises browser tabs behind one service. A CLI
+ * invocation, a second service, or a stale process can all reach the same
+ * files, so the lock lives on disk.
+ *
+ * STALE TAKEOVER IS A RENAME, NOT AN UNLINK. Naive breaking is racy: A judges
+ * the lock stale, B removes it and acquires its own, then A unlinks *B's live
+ * lock* and both proceed. Unlinking a path you did not verify is the bug. Here
+ * the contender renames the observed stale lock to a token-quarantined name —
+ * an atomic operation exactly one contender can win — and only the winner
+ * creates the real lock.
+ *
+ * RELEASE ONLY DELETES A LOCK WHOSE TOKEN IS STILL OURS. A mismatch means we
+ * were superseded, and deleting it would hand the critical section to two
+ * writers at once.
+ *
+ * This does NOT cover Codex, which knows nothing about our lock. That residual
+ * is handled by the per-target byte checks in the write path, and the rename
+ * window itself is documented as irreducible from user space.
+ */
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+
+const FILE_MODE = 0o600;
+
+/** A lock younger than this is respected even if its pid looks gone. */
+export const STALE_AFTER_MS = 10_000;
+
+export interface LockRecord {
+  token: string;
+  pid: number;
+  acquiredAt: number;
+}
+
+export interface LockHandle {
+  path: string;
+  token: string;
+}
+
+export type AcquireResult =
+  | { ok: true; handle: LockHandle }
+  | { ok: false; error: "locked" };
+
+export interface LockDeps {
+  /** Injectable so tests can simulate a live or dead owner. */
+  isProcessAlive: (pid: number) => boolean;
+  now: () => number;
+}
+
+const defaultDeps: LockDeps = {
+  isProcessAlive: pid => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // EPERM means it exists but belongs to another user.
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  },
+  now: () => Date.now(),
+};
+
+function readRecord(path: string): LockRecord | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as LockRecord;
+    if (typeof parsed?.token !== "string" || typeof parsed?.pid !== "number") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** True when the holder is gone AND the lock is older than the grace window. */
+function isStale(record: LockRecord | null, deps: LockDeps): boolean {
+  if (record === null) return true; // unparseable: treat as debris
+  if (deps.isProcessAlive(record.pid)) return false;
+  return deps.now() - record.acquiredAt > STALE_AFTER_MS;
+}
+
+/**
+ * One attempt. The caller decides whether to retry — a loser must go back to
+ * re-reading the lock rather than assuming its quarantine still applies.
+ */
+export function tryAcquire(path: string, deps: LockDeps = defaultDeps): AcquireResult {
+  const token = randomBytes(8).toString("hex");
+  const record: LockRecord = { token, pid: process.pid, acquiredAt: deps.now() };
+  const body = JSON.stringify(record);
+
+  try {
+    writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
+    return { ok: true, handle: { path, token } };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+
+  if (!isStale(readRecord(path), deps)) return { ok: false, error: "locked" };
+
+  // Quarantine by rename: atomic, and exactly one contender wins it.
+  const quarantine = `${path}.stale-${token}`;
+  try {
+    renameSync(path, quarantine);
+  } catch {
+    // Someone else won the rename, or the owner released between our checks.
+    // Either way we do NOT touch the path — retry from the top.
+    return { ok: false, error: "locked" };
+  }
+
+  try {
+    writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
+  } catch (error) {
+    // A successor acquired the real lock between our rename and this create.
+    // Its lock is live and is not ours to remove.
+    try { unlinkSync(quarantine); } catch { /* debris */ }
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return { ok: false, error: "locked" };
+    throw error;
+  }
+
+  try { unlinkSync(quarantine); } catch { /* debris */ }
+  return { ok: true, handle: { path, token } };
+}
+
+/**
+ * Release. Deletes nothing unless the on-disk token is still ours; returns false
+ * when we were superseded, which the caller surfaces as `write_superseded`.
+ */
+export function release(handle: LockHandle): boolean {
+  const record = readRecord(handle.path);
+  if (record === null || record.token !== handle.token) return false;
+  try {
+    unlinkSync(handle.path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True when the on-disk lock is still the one this handle acquired. */
+export function stillHeld(handle: LockHandle): boolean {
+  if (!existsSync(handle.path)) return false;
+  return readRecord(handle.path)?.token === handle.token;
+}

package/src/codex/quota-rejection.ts

@@ -0,0 +1,298 @@
+import { readBoundedResponseBody } from "../lib/bounded-body";
+
+const RESET_ELIGIBLE_CODE_VALUES = [
+  "usage_limit_exceeded",
+  "insufficient_quota",
+] as const;
+
+export type CodexResetEligibleExhaustionCode =
+  (typeof RESET_ELIGIBLE_CODE_VALUES)[number];
+
+export type CodexPreStreamRejectionKind =
+  | "reset-eligible-exhaustion"
+  | "generic-rate-limit"
+  | "unverified-billing-or-quota"
+  | "transient-server-error"
+  | "authentication-error"
+  | "permission-error"
+  | "other";
+
+export interface CodexPreStreamRejection {
+  kind: CodexPreStreamRejectionKind;
+  status: number;
+  alternateRetryEligible: boolean;
+  resetCreditEligible: boolean;
+  semanticCode?: CodexResetEligibleExhaustionCode;
+  /**
+   * Structured denial evidence for a 403. Present only when the upstream body names a
+   * workspace/entitlement denial, which proves the CREDENTIAL is valid and the account
+   * simply lacks access here (#1789). Status alone can never set this.
+   */
+  denial?: "workspace" | "entitlement";
+}
+
+/**
+ * Upstream codes that identify a WORKSPACE denial rather than a bad credential.
+ *
+ * #1789: a K12 account whose credential validates and whose WHAM usage returns 200 still
+ * gets 403 `codex_workspace_access_denied` on a routed prompt. Treating that as a credential
+ * failure tells the user to re-authenticate a credential that is already valid, and the loop
+ * repeats forever.
+ */
+const WORKSPACE_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "codex_workspace_access_denied",
+  "workspace_access_denied",
+]);
+
+const ENTITLEMENT_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "codex_entitlement_missing",
+  "entitlement_missing",
+]);
+
+/** Read a structured denial code out of a 403 body. Fails closed to undefined. */
+async function denialFromResponse(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<"workspace" | "entitlement" | undefined> {
+  try {
+    const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
+    if (isUnsafeJsonDocument(body.text)) return undefined;
+    const payload = JSON.parse(body.text) as unknown;
+    const code = structuredDenialCode(payload);
+    if (code === undefined) return undefined;
+    if (WORKSPACE_DENIAL_CODES.has(code)) return "workspace";
+    if (ENTITLEMENT_DENIAL_CODES.has(code)) return "entitlement";
+    return undefined;
+  } catch {
+    // Same fail-closed rule as the exhaustion classifier: an unreadable body must not
+    // downgrade a credential failure into a workspace one.
+    return undefined;
+  }
+}
+
+function ownStringField(container: Record<string, unknown>, field: string): string | undefined {
+  const descriptor = Object.getOwnPropertyDescriptor(container, field);
+  return descriptor && "value" in descriptor && typeof descriptor.value === "string"
+    ? descriptor.value
+    : undefined;
+}
+
+/** Own-property `code` lookup at the top level or under `error` / `detail`. No coercion or accessors. */
+function structuredDenialCode(payload: unknown): string | undefined {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const record = payload as Record<string, unknown>;
+  const direct = ownStringField(record, "code");
+  if (direct !== undefined) return direct;
+
+  for (const field of ["error", "detail"] as const) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, field);
+    if (!descriptor || !("value" in descriptor)) continue;
+    const nested = descriptor.value;
+    if (nested === null || typeof nested !== "object" || Array.isArray(nested)) continue;
+    const code = ownStringField(nested as Record<string, unknown>, "code");
+    if (code !== undefined) return code;
+  }
+  return undefined;
+}
+
+const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES);
+
+const TRANSIENT_SERVER_STATUSES = new Set([500, 502, 503, 504, 520, 521, 522]);
+const JSON_NUMBER_PATTERN = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+
+function rejection(
+  status: number,
+  kind: CodexPreStreamRejectionKind,
+  options: {
+    alternateRetryEligible?: boolean;
+    semanticCode?: CodexResetEligibleExhaustionCode;
+  } = {},
+): CodexPreStreamRejection {
+  return {
+    kind,
+    status,
+    alternateRetryEligible: options.alternateRetryEligible === true,
+    resetCreditEligible: options.semanticCode !== undefined,
+    ...(options.semanticCode ? { semanticCode: options.semanticCode } : {}),
+  };
+}
+
+function hasOwnField(container: Record<string, unknown>, field: string): boolean {
+  return Object.prototype.hasOwnProperty.call(container, field);
+}
+
+type JsonScanResult = {
+  next: number;
+  duplicate: boolean;
+};
+
+function skipJsonWhitespace(text: string, index: number): number {
+  while (index < text.length && /[\t\n\r ]/.test(text[index] ?? "")) index += 1;
+  return index;
+}
+
+function scanJsonStringEnd(text: string, index: number): number {
+  if (text[index] !== '"') throw new SyntaxError("expected JSON string");
+  for (let cursor = index + 1; cursor < text.length; cursor += 1) {
+    const char = text[cursor];
+    if (char === '"') return cursor + 1;
+    if (char === "\\") cursor += 1;
+  }
+  throw new SyntaxError("unterminated JSON string");
+}
+
+function scanJsonValue(text: string, index: number): JsonScanResult {
+  const start = skipJsonWhitespace(text, index);
+  if (text[start] === "{") return scanJsonObject(text, start);
+  if (text[start] === "[") return scanJsonArray(text, start);
+  if (text[start] === '"') return { next: scanJsonStringEnd(text, start), duplicate: false };
+
+  for (const literal of ["true", "false", "null"]) {
+    if (text.startsWith(literal, start)) {
+      return { next: start + literal.length, duplicate: false };
+    }
+  }
+  JSON_NUMBER_PATTERN.lastIndex = start;
+  const number = JSON_NUMBER_PATTERN.exec(text);
+  if (!number) throw new SyntaxError("expected JSON value");
+  return { next: start + number[0].length, duplicate: false };
+}
+
+function scanJsonObject(text: string, index: number): JsonScanResult {
+  const keys = new Set<string>();
+  let duplicate = false;
+  let cursor = skipJsonWhitespace(text, index + 1);
+  if (text[cursor] === "}") return { next: cursor + 1, duplicate: false };
+
+  while (cursor < text.length) {
+    const keyEnd = scanJsonStringEnd(text, cursor);
+    const key = JSON.parse(text.slice(cursor, keyEnd)) as unknown;
+    if (typeof key !== "string") throw new SyntaxError("invalid JSON object key");
+    if (keys.has(key)) duplicate = true;
+    keys.add(key);
+
+    cursor = skipJsonWhitespace(text, keyEnd);
+    if (text[cursor] !== ":") throw new SyntaxError("expected JSON object colon");
+    const value = scanJsonValue(text, cursor + 1);
+    duplicate ||= value.duplicate;
+    cursor = skipJsonWhitespace(text, value.next);
+    if (text[cursor] === "}") return { next: cursor + 1, duplicate };
+    if (text[cursor] !== ",") throw new SyntaxError("expected JSON object separator");
+    cursor = skipJsonWhitespace(text, cursor + 1);
+  }
+  throw new SyntaxError("unterminated JSON object");
+}
+
+function scanJsonArray(text: string, index: number): JsonScanResult {
+  let duplicate = false;
+  let cursor = skipJsonWhitespace(text, index + 1);
+  if (text[cursor] === "]") return { next: cursor + 1, duplicate: false };
+
+  while (cursor < text.length) {
+    const value = scanJsonValue(text, cursor);
+    duplicate ||= value.duplicate;
+    cursor = skipJsonWhitespace(text, value.next);
+    if (text[cursor] === "]") return { next: cursor + 1, duplicate };
+    if (text[cursor] !== ",") throw new SyntaxError("expected JSON array separator");
+    cursor = skipJsonWhitespace(text, cursor + 1);
+  }
+  throw new SyntaxError("unterminated JSON array");
+}
+
+function isUnsafeJsonDocument(text: string): boolean {
+  try {
+    const result = scanJsonValue(text, 0);
+    return result.duplicate || skipJsonWhitespace(text, result.next) !== text.length;
+  } catch {
+    // Scanner disagreement is untrusted input, just like JSON.parse failure.
+    return true;
+  }
+}
+
+function exactResetEligibleCode(
+  container: Record<string, unknown>,
+): CodexResetEligibleExhaustionCode | undefined {
+  const hasCode = hasOwnField(container, "code");
+  const hasType = hasOwnField(container, "type");
+  if (!hasCode && !hasType) return undefined;
+
+  const code = hasCode ? container.code : undefined;
+  const type = hasType ? container.type : undefined;
+  if ((hasCode && typeof code !== "string") || (hasType && typeof type !== "string")) {
+    return undefined;
+  }
+  if (hasCode && hasType && code !== type) return undefined;
+
+  const value = hasCode ? code : type;
+  if (typeof value !== "string") return undefined;
+  return RESET_ELIGIBLE_CODES.has(value as CodexResetEligibleExhaustionCode)
+    ? value as CodexResetEligibleExhaustionCode
+    : undefined;
+}
+
+function structuredResetEligibleCode(payload: unknown): CodexResetEligibleExhaustionCode | undefined {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const root = payload as Record<string, unknown>;
+  const hasRootDiscriminator = hasOwnField(root, "code") || hasOwnField(root, "type");
+
+  if (!hasOwnField(root, "error")) return exactResetEligibleCode(root);
+  if (hasRootDiscriminator) return undefined;
+
+  const nested = root.error;
+  if (!nested || typeof nested !== "object" || Array.isArray(nested)) return undefined;
+  return exactResetEligibleCode(nested as Record<string, unknown>);
+}
+
+async function resetEligibleCodeFromResponse(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<CodexResetEligibleExhaustionCode | undefined> {
+  try {
+    const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
+    const payload = JSON.parse(body.text) as unknown;
+    // JSON.parse silently keeps the last duplicate key, making contradictory
+    // payloads order-dependent. Reject any duplicate at any object depth.
+    if (isUnsafeJsonDocument(body.text)) return undefined;
+    return structuredResetEligibleCode(payload);
+  } catch {
+    // Classification must fail closed. A malformed, oversized, consumed, or
+    // cancelled body cannot authorize an irreversible reset-credit operation.
+    return undefined;
+  }
+}
+
+/**
+ * Classify an upstream Codex rejection before any response event is exposed.
+ *
+ * Only an exact structured exhaustion code on HTTP 429/402 is reset-eligible.
+ * Status alone and message text are intentionally insufficient. The broad
+ * alternate-account retry remains eligible for 429/402 to preserve #584.
+ */
+export async function classifyCodexPreStreamRejection(
+  response: Response,
+  options: { signal?: AbortSignal } = {},
+): Promise<CodexPreStreamRejection> {
+  const status = response.status;
+  if (status === 401) return rejection(status, "authentication-error");
+  if (status === 403) {
+    const denial = await denialFromResponse(response, options.signal);
+    return { ...rejection(status, "permission-error"), ...(denial ? { denial } : {}) };
+  }
+  if (TRANSIENT_SERVER_STATUSES.has(status)) return rejection(status, "transient-server-error");
+  if (status !== 429 && status !== 402) return rejection(status, "other");
+
+  const semanticCode = await resetEligibleCodeFromResponse(response, options.signal);
+  if (semanticCode) {
+    return rejection(status, "reset-eligible-exhaustion", {
+      alternateRetryEligible: true,
+      semanticCode,
+    });
+  }
+  return rejection(
+    status,
+    status === 429 ? "generic-rate-limit" : "unverified-billing-or-quota",
+    { alternateRetryEligible: true },
+  );
+}