@rol1n/pi-kit 0.0.0-stage → 0.1.0

package/extensions/multi-harness/turn-hook.mjs

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { complete, readJson, taskId, writeJson } from "./ipc.mjs";
+
+const [directory, harness, raw] = process.argv.slice(2);
+if (!directory || !["codex", "claude", "claude-start"].includes(harness)) throw new Error("Invalid multi-harness hook arguments.");
+const event = JSON.parse(harness === "codex" ? raw : readFileSync(0, "utf8"));
+const request = readJson(join(directory, "request.json"));
+if (!request) process.exit(0);
+if (harness === "claude-start") {
+  if (event.hook_event_name !== "UserPromptSubmit") process.exit(0);
+  writeJson(join(directory, "state.json"), { status: "running", id: taskId(event.prompt), at: Date.now() });
+  process.exit(0);
+}
+if (harness === "codex" && event.type !== "agent-turn-complete") process.exit(0);
+if (harness === "claude" && event.hook_event_name !== "Stop") process.exit(0);
+const sessionId = event["thread-id"] ?? event.thread_id ?? event.session_id;
+const inputs = event["input-messages"] ?? event.input_messages;
+const state = readJson(join(directory, "state.json"));
+const id = harness === "codex"
+  ? (Array.isArray(inputs) ? inputs.map(taskId).filter(Boolean).at(-1) : request.id)
+  : state?.id;
+if (sessionId) writeJson(join(directory, "metadata.json"), { sessionId, harness });
+if (id !== request.id) {
+  // Manual turns must return to idle too, without completing a coordinator dispatch.
+  writeJson(join(directory, "state.json"), { status: "idle", at: Date.now() });
+  process.exit(0);
+}
+complete(directory, { id, status: "completed", sessionId, summary: event["last-assistant-message"] ?? event.last_assistant_message });

package/extensions/multi-harness/worker-bridge.ts

@@ -0,0 +1,52 @@
+import { watch, renameSync, unlinkSync, type FSWatcher } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { complete, readJson, taskId, writeJson } from "./ipc.mjs";
+
+/** Native Pi inbox and settlement events; never shuts down an idle TUI. */
+export default function workerBridge(pi: ExtensionAPI) {
+  const directory = process.env.PI_MULTI_HARNESS_DIR;
+  if (process.env.PI_MULTI_HARNESS_WORKER !== "1" || !directory) return;
+  let watcher: FSWatcher | undefined;
+  let id: string | undefined;
+  let summary = "";
+  let error: string | undefined;
+  const inbox = join(directory, "inbox.json");
+
+  function receive() {
+    let payload: { id?: string; task?: string } | undefined;
+    const processing = `${inbox}.processing`;
+    try {
+      renameSync(inbox, processing);
+      payload = readJson(processing);
+      unlinkSync(processing);
+      if (!payload?.id || !payload.task) throw new Error("Inbox requires id and task.");
+      pi.sendUserMessage(payload.task, { deliverAs: "followUp", expandPromptTemplates: false });
+      writeJson(join(directory, "ack.json"), { id: payload.id, status: "ok" });
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code === "ENOENT") return;
+      writeJson(join(directory, "ack.json"), { id: payload?.id, status: "error", error: String(cause) });
+    }
+  }
+  pi.on("session_start", () => {
+    watcher = watch(directory, (_event, name) => { if (name?.toString() === "inbox.json") receive(); });
+    watcher.on("error", (cause) => console.error(`Multi-harness inbox watcher failed: ${cause.message}`));
+    receive();
+  });
+  pi.on("before_agent_start", (event) => {
+    id = event.messageType === "user" ? taskId(event.prompt) : undefined;
+    summary = "";
+    error = undefined;
+    writeJson(join(directory, "state.json"), { status: "running", id, at: Date.now() });
+  });
+  pi.on("agent_end", (event) => {
+    const last = event.messages.filter((message) => message.role === "assistant").at(-1);
+    summary = last?.content?.filter((part) => part.type === "text").map((part) => part.text).join("\n") ?? "";
+    error = last?.stopReason === "error" ? last.errorMessage || "Model error" : undefined;
+  });
+  pi.on("agent_settled", (event) => {
+    if (id) complete(directory, { id, status: error || event.aborted ? "failed" : "completed", summary, error: error ?? (event.aborted ? "Turn aborted" : undefined) });
+    else writeJson(join(directory, "state.json"), { status: "idle", at: Date.now() });
+  });
+  pi.on("session_shutdown", () => { watcher?.close(); });
+}

package/extensions/oai-subquota/README.md

@@ -0,0 +1,30 @@
+# oai-subquota
+
+Display OpenAI Codex subscription quota, reset windows, and a compact status line using the authenticated `openai-codex` provider.
+
+## Install
+
+```sh
+pi install npm:@rol1n/oai-subquota
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Commands
+
+| Command | Action |
+|---|---|
+| `/oai-subquota codex` | Show the Codex quota summary |
+| `/oai-subquota refresh` | Force a new quota query |
+| `/oai-subquota statusline` | Print compact quota text |
+| `/oai-subquota chatgpt` | Report the parked ChatGPT OAuth integration's status |
+
+## Authentication and cache
+
+Authenticate through `/login openai-codex`. The extension uses Pi's provider authentication rather than a separate API-key setting. Cached snapshots are stored at `$XDG_CACHE_HOME/oai-subquota/usage.json`, falling back to `~/.cache/oai-subquota/usage.json`. The normal cache lifetime is 60 seconds.
+
+The current implementation supports the Codex usage endpoint. General ChatGPT subscription quota lookup is explicitly parked and does not provide a working second quota source. Backend availability and subscription eligibility determine whether fresh quota data can be retrieved.
+
+## Source layout
+
+`index.ts` registers the command and lifecycle hooks and coordinates refreshes. `auth.ts` reads account claims from the provider token; `api.ts` handles usage requests; `cache.ts` handles snapshot persistence; `snapshot.ts` normalizes API responses and captured headers and merges snapshots. `types.ts` defines the shared data model, and `ui.ts` formats and renders quota output. The entrypoint re-exports the existing public types and formatting helpers.

package/extensions/oai-subquota/api.ts

@@ -0,0 +1,27 @@
+import { isRecord } from "./snapshot.ts";
+
+const USAGE_ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
+const REQUEST_TIMEOUT_MS = 15_000;
+
+export async function queryUsage(accessToken: string, accountId?: string): Promise<Record<string, unknown>> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${accessToken}`,
+    "User-Agent": "codex-cli",
+    Accept: "application/json",
+  };
+  if (accountId) headers["ChatGPT-Account-Id"] = accountId;
+
+  const res = await fetch(USAGE_ENDPOINT, {
+    method: "GET",
+    headers,
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+
+  if (res.status === 401 || res.status === 403) throw new Error(`Authentication rejected (HTTP ${res.status}). Please run /login openai-codex.`);
+  if (res.status === 429) throw new Error("Rate limit exceeded for usage endpoint (HTTP 429). Please try again later.");
+  if (!res.ok) throw new Error(`Usage request failed (HTTP ${res.status}).`);
+
+  const body = await res.json();
+  if (!isRecord(body)) throw new Error("Invalid JSON received from usage endpoint.");
+  return body;
+}

package/extensions/oai-subquota/auth.ts

@@ -0,0 +1,34 @@
+import { Buffer } from "node:buffer";
+import { isRecord } from "./snapshot.ts";
+import type { AccountSnapshot } from "./types.ts";
+
+const JWT_AUTH_CLAIM = "https://api.openai.com/auth";
+const JWT_PROFILE_CLAIM = "https://api.openai.com/profile";
+
+function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+  const part = token.split(".")[1];
+  if (!part) return undefined;
+  try {
+    const json = JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+    return isRecord(json) ? json : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function extractAccountFromToken(token: string): AccountSnapshot {
+  const payload = decodeJwtPayload(token);
+  if (!payload) return {};
+
+  const auth = isRecord(payload[JWT_AUTH_CLAIM]) ? payload[JWT_AUTH_CLAIM] : undefined;
+  const profile = isRecord(payload[JWT_PROFILE_CLAIM]) ? payload[JWT_PROFILE_CLAIM] : undefined;
+
+  const accountId = typeof auth?.chatgpt_account_id === "string" ? auth.chatgpt_account_id : undefined;
+  const plan = typeof auth?.chatgpt_plan_type === "string" ? auth.chatgpt_plan_type : undefined;
+  const email =
+    (typeof profile?.email === "string" && profile.email) ||
+    (typeof payload.email === "string" && payload.email) ||
+    undefined;
+
+  return { accountId, plan, email };
+}

package/extensions/oai-subquota/cache.ts

@@ -0,0 +1,30 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { isRecord } from "./snapshot.ts";
+import type { CodexUsageSnapshot } from "./types.ts";
+
+function getCachePath(): string {
+  const base = process.env.XDG_CACHE_HOME || join(homedir() || ".", ".cache");
+  return join(base, "oai-subquota", "usage.json");
+}
+
+export async function readCachedSnapshot(): Promise<CodexUsageSnapshot | undefined> {
+  try {
+    const raw = await readFile(getCachePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return isRecord(parsed) ? (parsed as unknown as CodexUsageSnapshot) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeCachedSnapshot(snapshot: CodexUsageSnapshot): Promise<void> {
+  try {
+    const file = getCachePath();
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(snapshot, null, 2)}\n`, { mode: 0o600 });
+  } catch {
+    // Non-fatal if filesystem is read-only
+  }
+}

package/extensions/oai-subquota/index.ts

@@ -0,0 +1,276 @@
+/**
+ * oai-subquota — OpenAI Codex subscription quota & status monitor for Pi
+ *
+ * Capabilities:
+ * - Queries ChatGPT Codex backend usage quota (5-hour window, 7-day weekly window,
+ *   banked rate-limit resets, and flexible credits).
+ * - Renders a boxed quota summary in chat transcript on `/oai-subquota [codex]`.
+ * - Displays a persistent, right-aligned single-line status in the footer:
+ *     5h:100% 7d:71% ↺4d5h
+ * - Provider-scoped: active exclusively when current model provider is "openai-codex".
+ *   Automatically clears when switching away and restores upon switching back.
+ * - Turn-based hot refresh: passively collects x-codex-* headers during agent loops
+ *   and refreshes the footer on turn completion (agent_end / agent_settled).
+ * - ChatGPT OAuth (provider: "openai") quota querying is parked pending official API.
+ */
+
+import type { AutocompleteItem, ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { extractAccountFromToken } from "./auth.ts";
+import { queryUsage } from "./api.ts";
+import { readCachedSnapshot, writeCachedSnapshot } from "./cache.ts";
+import { mergeSnapshots, parseCodexRateLimitHeaders, parseUsageApiResponse } from "./snapshot.ts";
+import { dimText, formatBoxedStatus, formatRightAlignedStatusline, formatStatusline, renderStatusMessage } from "./ui.ts";
+import type { CodexUsageSnapshot } from "./types.ts";
+
+export type { LimitWindow, RateLimit, CreditsSnapshot, ResetsSnapshot, AccountSnapshot, CodexUsageSnapshot } from "./types.ts";
+export { bar, formatDuration, formatStatusline, formatBoxedStatus, formatRightAlignedStatusline } from "./ui.ts";
+
+const CODEX_PROVIDER = "openai-codex";
+const CHATGPT_PROVIDER = "openai";
+const STATUS_KEY = "oai-subquota";
+const MESSAGE_TYPE = "codex-quota";
+const CACHE_TTL_MS = 60_000;
+
+function isCodexProvider(ctx: ExtensionContext | ExtensionCommandContext): boolean {
+  return ctx.model?.provider === CODEX_PROVIDER;
+}
+
+let activeCtx: ExtensionContext | ExtensionCommandContext | null = null;
+let latestSnapshot: CodexUsageSnapshot | undefined;
+
+function setFooterStatus(ctx: ExtensionContext | ExtensionCommandContext, snapshot: CodexUsageSnapshot | undefined): void {
+  latestSnapshot = snapshot;
+  activeCtx = ctx;
+  try {
+    if (!ctx.ui?.setStatus) return;
+    if (!snapshot || !isCodexProvider(ctx)) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+    ctx.ui.setStatus(STATUS_KEY, dimText(ctx, formatRightAlignedStatusline(snapshot)));
+  } catch {
+    // UI unavailable
+  }
+}
+
+async function refreshCodexSnapshot(
+  ctx: ExtensionContext | ExtensionCommandContext,
+  force = false,
+): Promise<CodexUsageSnapshot | undefined> {
+  const cached = await readCachedSnapshot();
+  if (cached) {
+    setFooterStatus(ctx, cached);
+    if (!force && Date.now() - Date.parse(cached.fetchedAt) < CACHE_TTL_MS) {
+      return cached;
+    }
+  }
+
+  const resolved = await ctx.modelRegistry.getProviderAuth(CODEX_PROVIDER).catch(() => undefined);
+  const accessToken = resolved?.auth.apiKey;
+  if (!accessToken) {
+    if (!cached) setFooterStatus(ctx, undefined);
+    return undefined;
+  }
+
+  const tokenAccount = extractAccountFromToken(accessToken);
+  const rawBody = await queryUsage(accessToken, tokenAccount.accountId);
+  const snapshot = parseUsageApiResponse(rawBody, tokenAccount);
+
+  await writeCachedSnapshot(snapshot);
+  setFooterStatus(ctx, snapshot);
+  return snapshot;
+}
+
+// ----------------- Extension Entrypoint -----------------
+
+export default function (pi: ExtensionAPI): void {
+  pi.registerMessageRenderer(MESSAGE_TYPE, renderStatusMessage);
+
+  const onResize = () => {
+    if (activeCtx && latestSnapshot && isCodexProvider(activeCtx)) {
+      setFooterStatus(activeCtx, latestSnapshot);
+    }
+  };
+  process.stdout?.on?.("resize", onResize);
+
+  let queryInFlight = false;
+  let isLoopActive = false;
+  let latestLoopHeaders: Record<string, string> | null = null;
+  let lastLoopRefreshTime = 0;
+
+  pi.on("session_shutdown", () => {
+    process.stdout?.off?.("resize", onResize);
+    activeCtx = null;
+  });
+
+  // Session start: activate only if current model provider is openai-codex
+  pi.on("session_start", async (_event, ctx) => {
+    if (!isCodexProvider(ctx)) {
+      setFooterStatus(ctx, undefined);
+      return;
+    }
+    try {
+      const cached = await readCachedSnapshot();
+      if (cached) setFooterStatus(ctx, cached);
+      void refreshCodexSnapshot(ctx, false).catch(() => undefined);
+    } catch {
+      // Non-blocking
+    }
+  });
+
+  // Dynamically react to model selection changes (/model or Ctrl+P)
+  pi.on("model_select", async (event, ctx) => {
+    if (event.model.provider === CODEX_PROVIDER) {
+      try {
+        const cached = await readCachedSnapshot();
+        if (cached) setFooterStatus(ctx, cached);
+        void refreshCodexSnapshot(ctx, false).catch(() => undefined);
+      } catch {
+        // Non-blocking
+      }
+    } else {
+      setFooterStatus(ctx, undefined);
+    }
+  });
+
+  // Turn start: activate hot-capture only for openai-codex
+  pi.on("before_agent_start", (_event, ctx) => {
+    if (!isCodexProvider(ctx)) {
+      isLoopActive = false;
+      latestLoopHeaders = null;
+      return;
+    }
+    isLoopActive = true;
+    latestLoopHeaders = null;
+  });
+
+  // Provider response: passively buffer rate limit headers during turn
+  pi.on("after_provider_response", (event, ctx) => {
+    if (!isCodexProvider(ctx) || !isLoopActive || !event.headers) return;
+    for (const [k, v] of Object.entries(event.headers)) {
+      if (k.toLowerCase().startsWith("x-codex-")) {
+        if (!latestLoopHeaders) latestLoopHeaders = {};
+        latestLoopHeaders[k] = v;
+      }
+    }
+  });
+
+  // Turn completion: refresh quota on agent loop boundary
+  const onAgentLoopFinished = async (ctx: ExtensionContext) => {
+    if (!isCodexProvider(ctx)) {
+      isLoopActive = false;
+      latestLoopHeaders = null;
+      return;
+    }
+    isLoopActive = false;
+    const now = Date.now();
+    if (now - lastLoopRefreshTime < 1500) return;
+    lastLoopRefreshTime = now;
+
+    try {
+      if (latestLoopHeaders) {
+        const parsed = parseCodexRateLimitHeaders(latestLoopHeaders);
+        latestLoopHeaders = null;
+        if (parsed) {
+          const cached = await readCachedSnapshot();
+          const merged = mergeSnapshots(cached, parsed);
+          await writeCachedSnapshot(merged);
+          setFooterStatus(ctx, merged);
+          return;
+        }
+      }
+      void refreshCodexSnapshot(ctx, false).catch(() => undefined);
+    } catch {
+      // Non-blocking
+    }
+  };
+
+  pi.on("agent_end", (_event, ctx) => {
+    void onAgentLoopFinished(ctx);
+  });
+  pi.on("agent_settled", (_event, ctx) => {
+    void onAgentLoopFinished(ctx);
+  });
+
+  // Slash command registration with English schema
+  pi.registerCommand("oai-subquota", {
+    description: "Check OpenAI Codex subscription quota (5h, 7d, resets); new ChatGPT OAuth quota is parked",
+    getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+      const items: AutocompleteItem[] = [
+        { value: "codex", label: "codex", description: "Display Codex quota summary box and refresh footer" },
+        { value: "refresh", label: "refresh", description: "Force fresh quota query from OpenAI backend" },
+        { value: "statusline", label: "statusline", description: "Print compact single-line quota text" },
+        { value: "chatgpt", label: "chatgpt", description: "Inspect new ChatGPT OAuth status (parked)" },
+      ];
+      const filtered = items.filter((item) => item.value.startsWith(prefix.trimStart()));
+      return filtered.length > 0 ? filtered : null;
+    },
+    handler: async (args, ctx) => {
+      const sub = args.trim().toLowerCase();
+
+      // ChatGPT new provider parked placeholder
+      if (sub === "chatgpt") {
+        const resolved = await ctx.modelRegistry.getProviderAuth(CHATGPT_PROVIDER).catch(() => undefined);
+        const hasAuth = !!resolved?.auth.apiKey;
+        const msg = hasAuth
+          ? "ChatGPT subscription (provider: openai) is parked: official 5h/weekly rate limit endpoint is not yet supported."
+          : "ChatGPT subscription (provider: openai) is not authenticated. Quota querying is parked.";
+
+        if (ctx.hasUI) {
+          ctx.ui.notify(msg, "info");
+        } else {
+          console.log(msg);
+        }
+        return;
+      }
+
+      if (queryInFlight) {
+        if (ctx.hasUI) ctx.ui.notify("oai-subquota: Query in progress.", "warning");
+        return;
+      }
+
+      queryInFlight = true;
+      try {
+        const force = sub === "refresh";
+        const snapshot = await refreshCodexSnapshot(ctx, force);
+        if (!snapshot) {
+          throw new Error("No openai-codex OAuth credentials found. Please run /login openai-codex first.");
+        }
+
+        if (sub === "statusline") {
+          const line = formatStatusline(snapshot);
+          if (ctx.hasUI === false) {
+            console.log(line);
+          } else {
+            ctx.ui.notify(line, "info");
+          }
+          return;
+        }
+
+        // Render boxed quota summary
+        const boxed = formatBoxedStatus(snapshot);
+        if (ctx.hasUI === false) {
+          console.log(boxed);
+        } else if (pi.sendMessage) {
+          await pi.sendMessage({
+            customType: MESSAGE_TYPE,
+            content: boxed,
+            display: true,
+            details: snapshot,
+          });
+        } else {
+          ctx.ui.notify(formatStatusline(snapshot), "info");
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (ctx.hasUI) {
+          ctx.ui.notify(`oai-subquota error: ${message}`, "error");
+        } else {
+          console.error(`oai-subquota error: ${message}`);
+        }
+      } finally {
+        queryInFlight = false;
+      }
+    },
+  });
+}

package/extensions/oai-subquota/snapshot.ts

@@ -0,0 +1,167 @@
+import type { AccountSnapshot, CodexUsageSnapshot, CreditsSnapshot, LimitWindow, ResetsSnapshot } from "./types.ts";
+
+export function isRecord(val: unknown): val is Record<string, unknown> {
+  return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+
+function normalizeResetAt(val: unknown): number | undefined {
+  if (typeof val !== "number" || !Number.isFinite(val) || val <= 0) return undefined;
+  return val > 10_000_000_000 ? Math.round(val / 1000) : val;
+}
+
+function normalizeWindow(val: unknown, nowMs = Date.now()): LimitWindow | undefined {
+  if (!isRecord(val)) return undefined;
+
+  const rawUsed = typeof val.used_percent === "number" ? val.used_percent : val.usedPercent;
+  if (typeof rawUsed !== "number" || !Number.isFinite(rawUsed) || rawUsed < 0) return undefined;
+
+  const usedPercent = Math.min(100, Math.max(0, rawUsed));
+  const leftPercent = Math.max(0, Math.min(100, 100 - usedPercent));
+
+  const resetAt = normalizeResetAt(val.reset_at ?? val.resetAt);
+  const rawAfter = typeof val.reset_after_seconds === "number" ? val.reset_after_seconds : val.resetAfterSeconds;
+  const resetAfterSeconds =
+    typeof rawAfter === "number" && Number.isFinite(rawAfter) && rawAfter >= 0
+      ? rawAfter
+      : resetAt !== undefined
+        ? Math.max(0, Math.round(resetAt - nowMs / 1000))
+        : undefined;
+
+  const rawSec = typeof val.limit_window_seconds === "number" ? val.limit_window_seconds : val.windowSeconds;
+  const rawMin = typeof val.window_minutes === "number" ? val.window_minutes : val.windowMinutes;
+  const windowSeconds =
+    typeof rawSec === "number" && rawSec > 0
+      ? rawSec
+      : typeof rawMin === "number" && rawMin > 0
+        ? rawMin * 60
+        : undefined;
+
+  return {
+    usedPercent,
+    leftPercent,
+    ...(windowSeconds !== undefined ? { windowSeconds } : {}),
+    ...(resetAt !== undefined ? { resetAt } : {}),
+    ...(resetAfterSeconds !== undefined ? { resetAfterSeconds } : {}),
+  };
+}
+
+function parseCredits(val: unknown): CreditsSnapshot | undefined {
+  if (!isRecord(val)) return undefined;
+  const hasCredits = val.has_credits === true;
+  const unlimited = val.unlimited === true;
+  const rawBalance = val.balance;
+  const balance =
+    typeof rawBalance === "number"
+      ? rawBalance
+      : typeof rawBalance === "string"
+        ? Number(rawBalance.trim())
+        : undefined;
+
+  return {
+    hasCredits,
+    unlimited,
+    ...(balance !== undefined && Number.isFinite(balance) ? { balance } : {}),
+  };
+}
+
+function parseResets(val: unknown): ResetsSnapshot | undefined {
+  if (!isRecord(val)) return undefined;
+  const available = typeof val.available_count === "number" ? val.available_count : undefined;
+  const applicable = typeof val.applicable_available_count === "number" ? val.applicable_available_count : undefined;
+  if (available === undefined && applicable === undefined) return undefined;
+  return {
+    ...(available !== undefined ? { availableCount: available } : {}),
+    ...(applicable !== undefined ? { applicableCount: applicable } : {}),
+  };
+}
+
+export function parseUsageApiResponse(data: unknown, tokenAccount: AccountSnapshot): CodexUsageSnapshot {
+  if (!isRecord(data)) throw new Error("Usage API returned non-object response");
+
+  const rateLimit = isRecord(data.rate_limit) ? data.rate_limit : undefined;
+  const primary = normalizeWindow(rateLimit?.primary_window);
+  const secondary = normalizeWindow(rateLimit?.secondary_window);
+
+  const email = (typeof data.email === "string" && data.email) || tokenAccount.email;
+  const plan = (typeof data.plan_type === "string" && data.plan_type) || tokenAccount.plan;
+  const accountId = (typeof data.account_id === "string" && data.account_id) || tokenAccount.accountId;
+
+  return {
+    source: "api",
+    fetchedAt: new Date().toISOString(),
+    account: { email, plan, accountId },
+    defaultLimit: {
+      id: "codex",
+      name: "Codex",
+      ...(primary ? { primary } : {}),
+      ...(secondary ? { secondary } : {}),
+    },
+    credits: parseCredits(data.credits),
+    resets: parseResets(data.rate_limit_reset_credits),
+  };
+}
+
+export function parseCodexRateLimitHeaders(headers: Record<string, string>): CodexUsageSnapshot | undefined {
+  const norm: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) norm[k.toLowerCase()] = String(v);
+
+  const num = (name: string): number | undefined => {
+    const v = norm[name];
+    if (v === undefined || v === "") return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+  };
+  const bool = (name: string): boolean | undefined => {
+    const v = norm[name]?.trim().toLowerCase();
+    return v === "true" || v === "1" ? true : v === "false" || v === "0" ? false : undefined;
+  };
+
+  const primaryUsed = num("x-codex-primary-used-percent");
+  const secondaryUsed = num("x-codex-secondary-used-percent");
+  if (primaryUsed === undefined && secondaryUsed === undefined) return undefined;
+
+  const primary = normalizeWindow({
+    used_percent: primaryUsed,
+    window_minutes: num("x-codex-primary-window-minutes"),
+    reset_at: normalizeResetAt(num("x-codex-primary-reset-at")),
+  });
+  const secondary = normalizeWindow({
+    used_percent: secondaryUsed,
+    window_minutes: num("x-codex-secondary-window-minutes"),
+    reset_at: normalizeResetAt(num("x-codex-secondary-reset-at")),
+  });
+
+  return {
+    source: "headers",
+    fetchedAt: new Date().toISOString(),
+    account: {},
+    defaultLimit: {
+      id: "codex",
+      name: "Codex",
+      ...(primary ? { primary } : {}),
+      ...(secondary ? { secondary } : {}),
+    },
+    credits: {
+      hasCredits: bool("x-codex-credits-has-credits"),
+      unlimited: bool("x-codex-credits-unlimited"),
+      balance: num("x-codex-credits-balance"),
+    },
+  };
+}
+
+export function mergeSnapshots(existing: CodexUsageSnapshot | undefined, update: CodexUsageSnapshot): CodexUsageSnapshot {
+  if (!existing) return update;
+  const defaultLimit = update.defaultLimit ?? existing.defaultLimit;
+  if (defaultLimit && existing.defaultLimit) {
+    defaultLimit.primary = update.defaultLimit?.primary ?? existing.defaultLimit.primary;
+    defaultLimit.secondary = update.defaultLimit?.secondary ?? existing.defaultLimit.secondary;
+  }
+  return {
+    ...existing,
+    ...update,
+    account: { ...existing.account, ...update.account },
+    ...(defaultLimit ? { defaultLimit } : {}),
+    credits: update.credits ?? existing.credits,
+    resets: update.resets ?? existing.resets,
+  };
+}