pi-cliproxyapi-native 0.1.5 → 0.1.7

package/README.md

@@ -6,15 +6,15 @@ Chat uses Pi's native API adapters and model metadata, with availability from yo
 
 ## Install
 
-This release targets Pi 1.0.0 and CLIProxyAPI 8.0.7, with Node.js 22.19 or newer. Run CLIProxyAPI with your upstream accounts configured before connecting Pi. The extension uses Pi's host-provided packages, adds no runtime dependencies, and needs no compilation.
+This release targets Pi 1.0.4 and CLIProxyAPI 8.0.18, with Node.js 22.19 or newer. Run CLIProxyAPI with your upstream accounts configured before connecting Pi. The extension uses Pi's host-provided packages, adds no runtime dependencies, and needs no compilation.
 
 If you installed `pi-cliproxy-native`, remove it before installing the renamed package. Both register the same `cliproxyapi` provider.
 
 ```sh
-pi install npm:pi-cliproxyapi-native@0.1.5
+pi install npm:pi-cliproxyapi-native@0.1.7
 ```
 
-For Git installation, use `pi install git:github.com/hawkff/pi-cliproxyapi-native@v0.1.5`. For a local checkout, use `pi install /path/to/pi-cliproxyapi-native`.
+For Git installation, use `pi install git:github.com/hawkff/pi-cliproxyapi-native@v0.1.7`. For a local checkout, use `pi install /path/to/pi-cliproxyapi-native`.
 
 The default proxy address is `http://localhost:8317`. For another address, set the [connection](#connection) before logging in. Restart Pi, then run:
 
@@ -44,6 +44,7 @@ Set `CLIPROXYAPI_BASE_URL` or create `~/.pi/agent/pi-cliproxyapi.json`:
 | --- | --- |
 | `CLIPROXYAPI_BASE_URL` | Overrides `baseUrl` in the configuration file. |
 | `CLIPROXYAPI_API_KEY` | Supplies a client key when Pi has no stored login credential. |
+| `CLIPROXYAPI_MANAGEMENT_KEY` | Enables live Claude quota lookup through the same proxy's management API. Keep this separate from the client key. |
 
 Use an absolute URL. Root URLs and URLs ending in `/v1` or `/v1beta` work; the extension preserves path prefixes. Remote endpoints require HTTPS. HTTP works on loopback addresses. URLs cannot contain credentials, query strings, or fragments.
 
@@ -176,6 +177,30 @@ The extension discovers available IDs through `/v1/models` and matches them agai
 
 Run `/cliproxyapi-refresh` to update the chat catalog.
 
+### Wait for quota reset
+
+Set `CLIPROXYAPI_MANAGEMENT_KEY` in Pi's environment to enable live Claude quota lookup. With live lookup enabled, Claude subscription requests enter quota handling on the first quota rejection, before SDK or Pi retries. The extension asks CLIProxyAPI to fetch Claude's OAuth usage, using the same upstream endpoint as the management dashboard. It reads absolute `resets_at` timestamps.
+
+The extension refreshes usage every minute while waiting and at the reported reset, with a one-second buffer. It checks the five-hour allowance and applicable weekly limits, including model-specific limits. A request that would exceed the remaining account allowance can wait for the five-hour reset before utilization reaches 100%. For an account pool, it considers enabled Claude subscription accounts that advertise the selected model and uses the earliest eligible recovery. The terminal countdown follows updated reset times. Cancel the current request to stop waiting; closing or reloading Pi discards the wait.
+
+Weekly exhaustion stops the request by default and reports the reset time. To wait for weekly resets too, merge this setting into `~/.pi/agent/pi-cliproxyapi.json`, then run `/reload`:
+
+```json
+{
+  "quota": {
+    "waitForWeeklyReset": true
+  }
+}
+```
+
+Without a management key, Claude retains its SDK retry settings and response-based waits. If live usage shows available quota before a wait begins, the extension uses valid response reset timing or returns the original error for Pi's bounded retries.
+
+Invalid management credentials, rejected account access, invalid usage data, or an exhausted allowance with an expired reset stop the quota wait with an explanation. These failures do not trigger Pi's quick retries. Extension-managed waits share one fixed seven-day deadline per provider call; a new cooldown cannot extend it. The extension checks the deadline after waking and before accepting available quota, including after machine sleep. It does not replay a request that has started streaming.
+
+Management requests stay on the configured proxy and reject redirects. Account access tokens stay in CLIProxyAPI. The extension reads account metadata and proxies usage GETs; it does not reset quotas, change credentials, or clear proxy cooldowns. Management keys grant broader access than chat keys, so keep them private. Live lookup supports up to 100 active Claude subscription accounts.
+
+Other chat routes retain the response-based fallback: `Retry-After` on HTTP 429 or a recognized quota HTTP 403, or `reset_seconds` in a `model_cooldown` error. Google's native adapter exposes only the structured error body. Those waits share the same seven-day deadline but cannot inspect live weekly usage. Image and video generation still do not retry.
+
 ### Aliases and model limits
 
 The chat catalog skips unknown IDs rather than guessing their capabilities. Recognized catalog owners resolve duplicate metadata IDs; ambiguous cross-family matches stay out.
@@ -194,6 +219,8 @@ Replace `<canonical-model-id>` with an ID from Pi's Anthropic catalog. Reference
 
 A `vertex/` or `antigravity/` route can reuse its unprefixed ID's alias if that reference resolves to one metadata entry. An alias for the full prefixed ID takes precedence. Custom prefixes need an explicit chat alias. Arbitrary aliases may lack ID-specific adapter behavior; canonical Gemini IDs and the two recognized prefixes retain native thinking and tool-turn handling.
 
+For Antigravity IDs `claude-opus-5-5-high` and `claude-sonnet-5-5-high`, the extension falls back to `anthropic/claude-opus-5-5` and `anthropic/claude-sonnet-5-5` metadata. This applies to bare IDs and recognized `antigravity/` or `vertex/` routes. Explicit aliases take precedence, followed by exact native metadata. The fallback requires the corresponding canonical entry in Pi and names the model like a configured alias, for example `claude-opus-5-5-high (Claude Opus 5.5)`; requests keep the advertised `-high` ID.
+
 Use Pi's `models.json` `modelOverrides` for limits, prices, or compatibility changes. Use its `models` array for IDs with no built-in metadata. Updating Pi supplies newer metadata. Catalog prices are estimates, not the proxy's bill; check upstream limits before increasing them.
 
 ## Backend routes
@@ -213,6 +240,8 @@ Set the CLIProxyAPI auth record's top-level `prefix` to `vertex` or `antigravity
 
 Use a reference such as `cliproxyapi/<model-id>:high` in Pi or pi-subagents. Pi separates the thinking suffix from the request ID. Supported levels come from model metadata; `xhigh` and `max` require explicit support. Pi clamps unsupported levels, and models that require thinking cannot use `off`. Keep thinking suffixes out of alias references.
 
+The `-high` in Antigravity model IDs belongs to the request ID. Pi's `:high` suffix sets thinking effort. For example, `cliproxyapi/antigravity/claude-opus-5-5-high:high` sends `antigravity/claude-opus-5-5-high` with high effort.
+
 Child loading depends on the [pi-subagents extension settings](https://github.com/nicobailon/pi-subagents/blob/main/docs/agents.md#tool-and-extension-selection). Local foreground children can inherit providers from the parent. Background children load extensions through discovery or an allowlist. A saved catalog alone does not register this provider.
 
 For native roles that need explicit loading, add this extension to `subagentOnlyExtensions`. Merge this example into `~/.pi/agent/settings.json`, replacing the path and role name while preserving existing entries:

package/extensions/index.ts

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { PROVIDER_ID, parseConfig } from "../src/config.ts";
 import { registerMediaTools } from "../src/media.ts";
 import { registerModelPicker } from "../src/picker.ts";
@@ -22,7 +22,37 @@ export default async function (pi: ExtensionAPI) {
     throw new Error("pi-cliproxyapi.json must contain valid JSON.");
   }
   const config = parseConfig(raw, process.env.CLIPROXYAPI_BASE_URL);
-  pi.registerProvider(createCliproxyProvider(config));
+  let context: ExtensionContext | undefined;
+  const waits = new Map<symbol, number>();
+  pi.on("session_start", (_event, ctx) => {
+    context = ctx;
+  });
+  pi.on("session_shutdown", () => {
+    context?.ui.setStatus("cliproxyapi-quota", undefined);
+    context = undefined;
+    waits.clear();
+  });
+  pi.registerProvider(
+    createCliproxyProvider(config, undefined, (id, seconds) => {
+      if (!context) return;
+      if (seconds === undefined) waits.delete(id);
+      else {
+        if (!waits.has(id)) {
+          const message = `CLIProxyAPI quota limit. Retrying at ${new Date(Date.now() + seconds * 1000).toLocaleString()}. Cancel the current request to stop waiting.`;
+          if (context.mode === "print" || context.mode === "json") process.stderr.write(`${message}\n`);
+          else context.ui.notify(message, "warning");
+        }
+        waits.set(id, seconds);
+      }
+      const remaining = Math.min(...waits.values());
+      context.ui.setStatus(
+        "cliproxyapi-quota",
+        waits.size
+          ? `CLIProxyAPI quota: retry in ${Math.floor(remaining / 3600)}h ${Math.floor(remaining / 60) % 60}m ${remaining % 60}s`
+          : undefined,
+      );
+    }),
+  );
   registerMediaTools(pi, config);
   registerModelPicker(pi, config);
   pi.registerCommand("cliproxyapi-refresh", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cliproxyapi-native",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "CLIProxyAPI chat discovery and image/video generation with Pi's native adapters",
   "publishConfig": {
     "access": "public"
@@ -39,9 +39,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.13",
-    "@earendil-works/pi-ai": "^1.0.0",
-    "@earendil-works/pi-coding-agent": "^1.0.0",
-    "@earendil-works/pi-tui": "^1.0.0",
+    "@earendil-works/pi-ai": "^1.0.4",
+    "@earendil-works/pi-coding-agent": "^1.0.4",
+    "@earendil-works/pi-tui": "^1.0.4",
     "@types/node": "^24.13.4",
     "typescript": "5.9.3"
   },

package/src/catalog.ts

@@ -171,9 +171,17 @@ const owners: Readonly<Record<string, string>> = {
   "gemini-cli": "google",
 };
 
+// Built-in aliases for advertised IDs without native metadata; exact metadata still wins.
+const metadataFallbacks = new Map([
+  ["claude-opus-5-5-high", "anthropic/claude-opus-5-5"],
+  ["claude-sonnet-5-5-high", "anthropic/claude-sonnet-5-5"],
+]);
+
 export function mapCatalog(value: unknown, config: Config, known: readonly Model<Api>[]) {
   const models = new Map<string, Model<CpaApi>>();
   const skipped = new Set<string>();
+  const byId = Map.groupBy(known, (model) => model.id);
+  const byReference = Map.groupBy(known, (model) => `${model.provider}/${model.id}`);
   for (const entry of parseCatalog(value)) {
     if (entry.hidden || models.has(entry.id)) continue;
     if (mediaPurpose(entry.id)) {
@@ -181,16 +189,15 @@ export function mapCatalog(value: unknown, config: Config, known: readonly Model
       continue;
     }
     const { metadataId, backend } = modelRoute(entry.id);
+    const routed = !entry.id.includes("/") || backend;
     const alias = Object.hasOwn(config.aliases, entry.id)
       ? config.aliases[entry.id]
       : backend && Object.hasOwn(config.aliases, metadataId)
         ? config.aliases[metadataId]
-        : undefined;
-    const candidates = known.filter((model) =>
-      alias
-        ? `${model.provider}/${model.id}` === alias
-        : (!entry.id.includes("/") || backend) && model.id === metadataId,
-    );
+        : routed && !byId.has(metadataId)
+          ? metadataFallbacks.get(metadataId)
+          : undefined;
+    const candidates = (alias ? byReference.get(alias) : routed ? byId.get(metadataId) : undefined) ?? [];
     const families = new Set(
       candidates.map((model) => (model.provider === "openai-codex" ? "openai" : model.provider)),
     );

package/src/claude-quota.ts

@@ -0,0 +1,273 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { type Config, isRecord } from "./config.ts";
+
+export type QuotaWaitHandler = (id: symbol, remainingSeconds: number | undefined) => void;
+
+const WEEK_MS = 7 * 86400000;
+
+async function managementRequest(
+  config: Config,
+  key: string,
+  path: string,
+  signal: AbortSignal,
+  body?: object,
+) {
+  let response: Response;
+  try {
+    response = await fetch(`${config.baseUrl}/v0/management/${path}`, {
+      method: body ? "POST" : "GET",
+      headers: { Authorization: `Bearer ${key}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+      redirect: "error",
+      signal,
+    });
+  } catch {
+    throw new Error("The live quota request could not complete.");
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw new Error(
+      response.status === 401 || response.status === 403
+        ? "Management API authentication or access was rejected. Check its key and access settings."
+        : "The management API is unavailable. Waiting stopped.",
+    );
+  }
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error("The management API returned an empty response.");
+  try {
+    const decoder = new TextDecoder();
+    let text = "";
+    let size = 0;
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 2 * 1024 * 1024) {
+        await reader.cancel();
+        throw new Error("Response too large.");
+      }
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    return JSON.parse(text + decoder.decode()) as unknown;
+  } catch {
+    throw new Error("The live quota response is invalid, incomplete, or larger than 2 MiB.");
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+export function claudeQuotaState(
+  payload: unknown,
+  modelId: string,
+  now = Date.now(),
+  serverNow = now,
+  requestRejected = false,
+) {
+  if (!isRecord(payload) || !("five_hour" in payload) || !("seven_day" in payload)) {
+    throw new Error("Claude did not report both five-hour and seven-day quota windows.");
+  }
+  const family = ["opus", "sonnet", "fable"].find((name) => modelId.toLowerCase().includes(name));
+  const keys = ["five_hour", "seven_day", "seven_day_oauth_apps"];
+  if (family) keys.push(family === "fable" ? "iguana_necktie" : `seven_day_${family}`);
+  const windows = keys.map((key) => ({ value: payload[key], weekly: key !== "five_hour" }));
+  if (family === "fable" && Array.isArray(payload.limits)) {
+    const scoped = payload.limits.filter((limit: unknown) => {
+      if (!isRecord(limit) || limit.kind !== "weekly_scoped" || limit.is_active === false) return false;
+      const model = isRecord(limit.scope) && isRecord(limit.scope.model) ? limit.scope.model : undefined;
+      return (
+        typeof model?.display_name === "string" &&
+        ["fable", "fable 5"].includes(model.display_name.trim().toLowerCase())
+      );
+    });
+    const limit: unknown =
+      scoped.find((limit: unknown) => isRecord(limit) && limit.is_active === true) ?? scoped[0];
+    if (isRecord(limit)) {
+      windows.pop();
+      windows.push({ value: { utilization: limit.percent, resets_at: limit.resets_at }, weekly: true });
+    }
+  }
+  const blocked: { retryAt: number; resetAt: number; weekly: boolean }[] = [];
+  for (const { value, weekly } of windows) {
+    if (value === undefined || value === null) continue;
+    if (
+      !isRecord(value) ||
+      typeof value.utilization !== "number" ||
+      !Number.isFinite(value.utilization) ||
+      value.utilization < 0 ||
+      value.utilization > 100
+    ) {
+      throw new Error("Claude returned an invalid quota window.");
+    }
+    // A rejected request can need more tokens than the unused part of the five-hour allowance.
+    if (value.utilization < 100 && (weekly || !requestRejected || value.utilization === 0)) continue;
+    const resetAt =
+      typeof value.resets_at === "string" && /T.*(?:Z|[+-]\d{2}:\d{2})$/i.test(value.resets_at)
+        ? Date.parse(value.resets_at)
+        : NaN;
+    const delay = resetAt - serverNow;
+    if (!Number.isFinite(delay) || delay <= 0 || delay > WEEK_MS) {
+      throw new Error("Claude still reports exhausted quota without a valid future reset. Waiting stopped.");
+    }
+    blocked.push({ resetAt, retryAt: now + delay + 1000, weekly });
+  }
+  if (!blocked.length) return { state: "ready" as const };
+  const latest = blocked.reduce((a, b) => (a.retryAt > b.retryAt ? a : b));
+  const weekly = blocked.filter((window) => window.weekly);
+  return {
+    state: "blocked" as const,
+    retryAt: latest.retryAt,
+    resetAt: latest.resetAt,
+    weeklyResetAt: weekly.length ? Math.max(...weekly.map((window) => window.resetAt)) : undefined,
+  };
+}
+
+export async function fetchClaudeQuota(
+  config: Config,
+  key: string,
+  modelId: string,
+  signal?: AbortSignal,
+  requestRejected = false,
+) {
+  if (!/^[!-~]{1,4096}$/.test(key)) {
+    throw new Error(
+      "Set CLIPROXYAPI_MANAGEMENT_KEY to read live Claude quota. The chat API key is not a management key.",
+    );
+  }
+  const bounded = AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(15000)]);
+  const listing = await managementRequest(config, key, "auth-files", bounded);
+  if (!isRecord(listing) || !Array.isArray(listing.files) || listing.files.length > 10000) {
+    throw new Error("The management API returned an invalid account list.");
+  }
+  const accounts = listing.files.filter(
+    (file: unknown) =>
+      isRecord(file) &&
+      (file.provider ?? file.type) === "claude" &&
+      file.disabled !== true &&
+      file.status !== "disabled" &&
+      file.account_type !== "api_key",
+  );
+  if (!accounts.length) throw new Error("No supported active Claude subscription account was found.");
+  // ponytail: probe at most 100 accounts; batch larger pools before raising this limit.
+  if (accounts.length > 100)
+    throw new Error("Live quota lookup supports at most 100 active Claude accounts.");
+  const reference = config.aliases[modelId] ?? modelId;
+  const results = await Promise.allSettled(
+    accounts.map(async (account: unknown) => {
+      if (
+        !isRecord(account) ||
+        typeof account.auth_index !== "string" ||
+        !account.auth_index ||
+        typeof account.name !== "string" ||
+        !account.name
+      ) {
+        throw new Error("A Claude account is missing its quota lookup identifier.");
+      }
+      const models = await managementRequest(
+        config,
+        key,
+        `auth-files/models?name=${encodeURIComponent(account.name)}`,
+        bounded,
+      );
+      if (!isRecord(models) || !Array.isArray(models.models))
+        throw new Error("The management API returned an invalid account catalog.");
+      if (!models.models.some((model: unknown) => isRecord(model) && model.id === modelId)) return undefined;
+      const response = await managementRequest(config, key, "api-call", bounded, {
+        auth_index: account.auth_index,
+        method: "GET",
+        url: "https://api.anthropic.com/api/oauth/usage",
+        header: {
+          Authorization: "Bearer $TOKEN$",
+          "Content-Type": "application/json",
+          "anthropic-beta": "oauth-2025-04-20",
+          "User-Agent": "claude-cli/2.1.280 (external, cli)",
+        },
+      });
+      if (!isRecord(response) || typeof response.status_code !== "number")
+        throw new Error("The management API returned an invalid quota result.");
+      if (response.status_code === 401 || response.status_code === 403) return { state: "rejected" as const };
+      if (response.status_code !== 200 || typeof response.body !== "string")
+        throw new Error("Claude usage is unavailable. Waiting stopped rather than guessing a reset time.");
+      let payload: unknown;
+      try {
+        payload = JSON.parse(response.body);
+      } catch {
+        throw new Error("Claude returned invalid usage data.");
+      }
+      const date = isRecord(response.header)
+        ? Object.entries(response.header).find(([name]) => name.toLowerCase() === "date")?.[1]
+        : undefined;
+      const serverNow = Array.isArray(date) && typeof date[0] === "string" ? Date.parse(date[0]) : NaN;
+      return claudeQuotaState(
+        payload,
+        reference,
+        Date.now(),
+        Number.isFinite(serverNow) ? serverNow : Date.now(),
+        requestRejected,
+      );
+    }),
+  );
+  const eligible = results.flatMap((result) =>
+    result.status === "fulfilled" && result.value !== undefined ? [result.value] : [],
+  );
+  if (!eligible.length) {
+    const failed = results.find((result) => result.status === "rejected");
+    if (failed?.status === "rejected" && failed.reason instanceof Error) throw failed.reason;
+    throw new Error("No active Claude subscription account advertises the selected model.");
+  }
+  if (eligible.some((result) => result.state === "ready")) return { state: "ready" as const };
+  const blocked = eligible.filter((result) => result.state === "blocked");
+  if (!blocked.length)
+    throw new Error(
+      "Claude rejected the account credentials or access. Sign in again or check the account status.",
+    );
+  const permitted = config.quota.waitForWeeklyReset
+    ? blocked
+    : blocked.filter((result) => result.weeklyResetAt === undefined);
+  if (!permitted.length) {
+    const resetAt = Math.min(...blocked.map((result) => result.weeklyResetAt ?? result.resetAt));
+    throw new Error(
+      `Seven-day quota is exhausted. Earliest weekly reset: ${new Date(resetAt).toISOString()}. Set quota.waitForWeeklyReset to true in pi-cliproxyapi.json to wait for it.`,
+    );
+  }
+  return permitted.reduce((a, b) => (a.retryAt < b.retryAt ? a : b));
+}
+
+export async function waitForClaudeQuota(
+  config: Config,
+  key: string,
+  modelId: string,
+  deadline: number,
+  signal?: AbortSignal,
+  onWait?: QuotaWaitHandler,
+  remainingInsufficient = false,
+) {
+  const id = Symbol();
+  let retryAt: number | undefined;
+  try {
+    for (;;) {
+      signal?.throwIfAborted();
+      const quota = await fetchClaudeQuota(
+        config,
+        key,
+        modelId,
+        signal,
+        remainingInsufficient && (retryAt === undefined || Date.now() < retryAt),
+      );
+      signal?.throwIfAborted();
+      if (Date.now() >= deadline || (quota.state === "blocked" && quota.retryAt > deadline))
+        throw new Error(
+          "The seven-day quota waiting deadline was reached. Start a new request after confirming account access.",
+        );
+      if (quota.state === "ready") return retryAt !== undefined;
+      retryAt = quota.retryAt;
+      const refreshAt = Math.min(quota.retryAt, Date.now() + 60000);
+      while (Date.now() < refreshAt) {
+        signal?.throwIfAborted();
+        onWait?.(id, Math.max(0, Math.ceil((quota.retryAt - Date.now()) / 1000)));
+        await sleep(Math.min(1000, refreshAt - Date.now()), undefined, { signal });
+      }
+    }
+  } finally {
+    onWait?.(id, undefined);
+  }
+}

package/src/config.ts

@@ -28,12 +28,20 @@ export function normalizeBaseUrl(value: string) {
 }
 
 export function parseConfig(value: unknown, baseUrlOverride?: string) {
-  if (!isRecord(value) || Object.keys(value).some((key) => !["baseUrl", "aliases"].includes(key))) {
-    throw new Error("pi-cliproxyapi.json accepts only baseUrl and aliases.");
+  if (!isRecord(value) || Object.keys(value).some((key) => !["baseUrl", "aliases", "quota"].includes(key))) {
+    throw new Error("pi-cliproxyapi.json accepts only baseUrl, aliases, and quota.");
   }
   if (value.baseUrl !== undefined && typeof value.baseUrl !== "string") {
     throw new Error("CLIProxyAPI baseUrl must be a string.");
   }
+  const quota = value.quota === undefined ? {} : value.quota;
+  if (
+    !isRecord(quota) ||
+    Object.keys(quota).some((key) => key !== "waitForWeeklyReset") ||
+    (quota.waitForWeeklyReset !== undefined && typeof quota.waitForWeeklyReset !== "boolean")
+  ) {
+    throw new Error("CLIProxyAPI quota accepts only a boolean waitForWeeklyReset.");
+  }
   const rawAliases = value.aliases === undefined ? {} : value.aliases;
   if (!isRecord(rawAliases)) throw new Error("CLIProxyAPI aliases must be an object.");
   const aliases = Object.fromEntries(
@@ -58,6 +66,7 @@ export function parseConfig(value: unknown, baseUrlOverride?: string) {
   return {
     baseUrl: normalizeBaseUrl(baseUrlOverride ?? value.baseUrl ?? DEFAULT_BASE_URL),
     aliases,
+    quota: { waitForWeeklyReset: quota.waitForWeeklyReset ?? false },
   };
 }
 

package/src/media.ts

@@ -8,7 +8,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { mapMediaCatalog, mediaCapability, mediaControls } from "./catalog.ts";
 import { type Config, isRecord, PROVIDER_ID } from "./config.ts";
 import { type DefaultsContext, effectiveMediaDefaults, resolveMediaModel } from "./media-defaults.ts";
-import { fetchCatalog, validateKey } from "./provider.ts";
+import { deadline, fetchCatalog, validateKey } from "./provider.ts";
 
 type MediaContext = Pick<ExtensionContext, "cwd" | "model"> &
   DefaultsContext & {
@@ -102,10 +102,6 @@ function mediaOutputOptions(
   return options;
 }
 
-function deadline(signal: AbortSignal | undefined, milliseconds: number) {
-  return AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(milliseconds)]);
-}
-
 export async function mediaKey(ctx: Pick<MediaContext, "modelRegistry">, signal: AbortSignal) {
   signal.throwIfAborted();
   const cancelled = Promise.withResolvers<never>();

package/src/picker.ts

@@ -16,7 +16,7 @@ import {
   type MediaDefaults,
   readMediaDefaults,
 } from "./media-defaults.ts";
-import { fetchCatalog } from "./provider.ts";
+import { deadline, fetchCatalog } from "./provider.ts";
 
 export function pickerCatalog(value: unknown) {
   const rows = new Map<
@@ -58,6 +58,10 @@ export function searchPickerItems(items: readonly PickerItem[], query: string) {
   );
 }
 
+function clearedPurpose(choice: string) {
+  return choice === "clear image" ? "image" : choice === "clear video" ? "video" : undefined;
+}
+
 function defaultsLabel(defaults: MediaDefaults, automatic?: string) {
   const label = (id?: string | null) => (id === null ? "invalid / disabled" : id ? routedName(id) : "none");
   return `Image: ${label(defaults.image)}${automatic ? " (automatic default)" : ""} | Video: ${label(defaults.video)}`;
@@ -207,6 +211,8 @@ export class ModelPicker extends Container implements Focusable {
 }
 
 export function registerModelPicker(pi: ExtensionAPI, config: Config) {
+  let commandSequence = 0;
+  const savedSequence = { image: 0, video: 0 };
   pi.registerCommand("cli:model", {
     description: "Search CLIProxyAPI image/video models and select a session media default",
     getArgumentCompletions: (prefix) =>
@@ -214,6 +220,7 @@ export function registerModelPicker(pi: ExtensionAPI, config: Config) {
         .filter((value) => value.startsWith(prefix))
         .map((value) => ({ value, label: value })),
     async handler(args, ctx) {
+      const sequence = ++commandSequence;
       const report = (content: string, error = false) => {
         if (ctx.hasUI) ctx.ui.notify(content, error ? "error" : "info");
         else if (ctx.mode === "print") console.error(content);
@@ -225,39 +232,41 @@ export function registerModelPicker(pi: ExtensionAPI, config: Config) {
       };
       try {
         const input = args.trim();
-        const clear = input === "clear image" ? "image" : input === "clear video" ? "video" : undefined;
         const save = (choice: string) => {
-          const defaults = readMediaDefaults(config, ctx);
-          if (choice === "clear image") delete defaults.image;
-          else if (choice === "clear video") delete defaults.video;
-          else {
-            const capability = mediaCapability(choice);
-            if (!capability || capability.disabledReason)
-              throw new Error("Unsupported CLIProxyAPI media selection.");
-            defaults[capability.purpose] = choice;
+          const clearing = clearedPurpose(choice);
+          const capability = clearing ? undefined : mediaCapability(choice);
+          const purpose = clearing ?? capability?.purpose;
+          if (!purpose || capability?.disabledReason)
+            throw new Error("Unsupported CLIProxyAPI media selection.");
+          ctx.signal?.throwIfAborted();
+          if (sequence < savedSequence[purpose]) {
+            report(`CLIProxyAPI ${purpose} choice superseded by a newer command; no change saved.`);
+            return;
           }
+          const defaults = readMediaDefaults(config, ctx);
+          if (clearing) delete defaults[purpose];
+          else defaults[purpose] = choice;
           pi.appendEntry(MEDIA_DEFAULTS_ENTRY, { version: 1, endpoint: config.baseUrl, defaults });
+          savedSequence[purpose] = sequence;
           const effective = effectiveMediaDefaults(config, ctx);
           report(defaultsLabel(effective.defaults, effective.automatic));
         };
-        if (clear) {
-          save(`clear ${clear}`);
+        if (clearedPurpose(input)) {
+          save(input);
           return;
         }
         if (input.startsWith("clear")) throw new Error("Usage: /cli:model clear image|video");
-        const disabledReason = input.startsWith("select ")
-          ? mediaCapability(input.slice(7).trim())?.disabledReason
-          : undefined;
+        const explicit = input.startsWith("select ") ? input.slice(7).trim() : undefined;
+        const disabledReason = explicit === undefined ? undefined : mediaCapability(explicit)?.disabledReason;
         if (disabledReason) {
           report(disabledReason, true);
           return;
         }
-        const signal = AbortSignal.any([...(ctx.signal ? [ctx.signal] : []), AbortSignal.timeout(15000)]);
+        const signal = deadline(ctx.signal, 15000);
         const key = await mediaKey(ctx, signal);
         const rows = pickerCatalog(await fetchCatalog(config, key, signal));
         const { defaults, automatic } = effectiveMediaDefaults(config, ctx);
         const items = pickerItems(rows, defaults);
-        const explicit = input.startsWith("select ") ? input.slice(7).trim() : undefined;
         const query = input === "list" ? "" : input.startsWith("search ") ? input.slice(7) : input;
         let choice = explicit;
         if (choice === undefined) {
@@ -291,14 +300,9 @@ export function registerModelPicker(pi: ExtensionAPI, config: Config) {
           }
         }
         if (choice === undefined) return;
-        if (choice === "clear image" || choice === "clear video") {
-          save(choice);
-          return;
-        }
-        const row = rows.find((row) => row.id === choice);
-        if (!row?.supported)
+        if (!clearedPurpose(choice) && !rows.find((row) => row.id === choice)?.supported)
           throw new Error("Model unavailable or unsupported. Use /cli:model to list supported IDs.");
-        save(row.id);
+        save(choice);
       } catch {
         report(
           "CLIProxyAPI model selection failed: unavailable/unsupported model, invalid command, authentication, or connection error. Check /login cliproxyapi. Use /cli:model list, select <exact ID>, or clear image|video.",

package/src/provider.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
 import {
   type Api,
   createProvider,
@@ -18,8 +19,11 @@ import {
 } from "@earendil-works/pi-ai/compat";
 import { getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
 import { type CpaApi, endpoint, mapCatalog, modelRoute } from "./catalog.ts";
+import { type QuotaWaitHandler, waitForClaudeQuota } from "./claude-quota.ts";
 import { type Config, isRecord, PROVIDER_ID } from "./config.ts";
 
+export type { QuotaWaitHandler } from "./claude-quota.ts";
+
 export function builtinCatalog() {
   return [
     ...getBuiltinModels("anthropic"),
@@ -36,9 +40,13 @@ export function validateKey(key: string) {
   return key;
 }
 
+export function deadline(signal: AbortSignal | undefined, milliseconds: number) {
+  return AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(milliseconds)]);
+}
+
 export async function fetchCatalog(config: Config, key: string, signal: AbortSignal) {
   validateKey(key);
-  const boundedSignal = AbortSignal.any([signal, AbortSignal.timeout(10000)]);
+  const boundedSignal = deadline(signal, 10000);
   let response: Response;
   try {
     response = await fetch(`${config.baseUrl}/v1/models`, {
@@ -102,14 +110,83 @@ export function nonStrictTools(payload: unknown) {
   };
 }
 
-function route(streams: ProviderStreams, baseUrl: string): ProviderStreams {
+function quotaError(message: string | undefined) {
+  let error: unknown;
+  if (message && message.length <= 65536) {
+    try {
+      const body: unknown = JSON.parse(message.slice(message.indexOf("{"), message.lastIndexOf("}") + 1));
+      error = isRecord(body) && isRecord(body.error) ? body.error : body;
+    } catch {
+      // SDK messages without a JSON body can still carry Retry-After headers.
+    }
+  }
+  return isRecord(error) ? error : undefined;
+}
+
+const quotaErrorTypes = ["model_cooldown", "rate_limit_error", "rate_limit_exceeded", "usage_limit_reached"];
+
+function isQuotaFailure(error: ReturnType<typeof quotaError>, status?: number) {
+  const code = error?.code ?? error?.type;
+  if (code === "permission_error" || code === "authentication_error") return false;
+  const quota = typeof code === "string" && quotaErrorTypes.includes(code);
+  return status === undefined ? code === "model_cooldown" : status === 429 || (status === 403 && quota);
+}
+
+export function quotaRetryAt(
+  message: string | undefined,
+  response?: Pick<Response, "status" | "headers">,
+  now = Date.now(),
+) {
+  const error = quotaError(message);
+  if (!isQuotaFailure(error, response?.status)) return undefined;
+  const resets: number[] = [];
+  const retryAfter = response?.headers.get("retry-after")?.trim();
+  if (retryAfter) {
+    const serverDate = Date.parse(response?.headers.get("date") ?? "");
+    resets.push(
+      /^\d+$/.test(retryAfter)
+        ? now + Number(retryAfter) * 1000
+        : now + Date.parse(retryAfter) - (Number.isFinite(serverDate) ? serverDate : now),
+    );
+  }
+  const code = error?.code ?? error?.type;
+  if (
+    typeof code === "string" &&
+    quotaErrorTypes.includes(code) &&
+    typeof error?.reset_seconds === "number"
+  ) {
+    resets.push(now + error.reset_seconds * 1000);
+  }
+  // Support five-hour and weekly windows without trusting unbounded server delays.
+  const valid = resets.filter((at) => Number.isSafeInteger(at) && at > now && at - now <= 7 * 86400000);
+  return valid.length ? Math.max(...valid) + 1000 : undefined;
+}
+
+async function waitForQuota(resetAt: number, signal?: AbortSignal, onWait?: QuotaWaitHandler) {
+  const id = Symbol();
+  try {
+    for (let remaining = resetAt - Date.now(); remaining > 0; remaining = resetAt - Date.now()) {
+      signal?.throwIfAborted();
+      onWait?.(id, Math.ceil(remaining / 1000));
+      await sleep(Math.min(remaining, 1000), undefined, { signal });
+    }
+    signal?.throwIfAborted();
+  } finally {
+    onWait?.(id, undefined);
+  }
+}
+
+function route(streams: ProviderStreams, config: Config, onWait?: QuotaWaitHandler): ProviderStreams {
   const wrap =
     (stream: ProviderStreams["streamSimple"]): ProviderStreams["streamSimple"] =>
     (selected, context, options) => {
       // A resumed selection must not send the current key to an old endpoint.
-      const model = { ...selected, baseUrl: endpoint(baseUrl, selected.api) };
+      const model = { ...selected, baseUrl: endpoint(config.baseUrl, selected.api) };
       const { metadataId, backend } = modelRoute(model.id);
       const google = backend && model.api === "google-generative-ai";
+      const managementKey =
+        options?.env?.CLIPROXYAPI_MANAGEMENT_KEY ?? process.env.CLIPROXYAPI_MANAGEMENT_KEY ?? "";
+      const liveClaude = model.api === "anthropic-messages" && !backend && managementKey !== "";
       const adapterModel = google ? { ...model, id: metadataId } : model;
       // Google needs canonical IDs for tool turns. Swap identities to keep bare history cross-route.
       const adapterContext = google
@@ -141,22 +218,114 @@ function route(streams: ProviderStreams, baseUrl: string): ProviderStreams {
         const result = await options?.onPayload?.(adapted, model);
         return result === undefined ? adapted : result;
       };
-      const run = () =>
-        stream(adapterModel, adapterContext, {
+      let response: Pick<Response, "status" | "headers"> | undefined;
+      const run = () => {
+        response = undefined;
+        return stream(adapterModel, adapterContext, {
           ...options,
+          // Google rejects custom fetch; its structured cooldown body remains available on errors.
+          fetch:
+            model.api === "google-generative-ai"
+              ? options?.fetch
+              : async (input, init) => {
+                  response = undefined;
+                  const result = await (options?.fetch ?? globalThis.fetch)(input, init);
+                  response = { status: result.status, headers: result.headers };
+                  if (liveClaude && result.status === 429) {
+                    // Inspect the first quota rejection without disabling transient-error retries.
+                    const headers = new Headers(result.headers);
+                    headers.set("x-should-retry", "false");
+                    return new Response(result.body, {
+                      status: result.status,
+                      statusText: result.statusText,
+                      headers,
+                    });
+                  }
+                  return result;
+                },
           onPayload,
           onResponse: options?.onResponse ? (response) => options.onResponse?.(response, model) : undefined,
           onProviderStreamEvent: options?.onProviderStreamEvent
             ? (event) => options.onProviderStreamEvent?.(event, model)
             : undefined,
         });
-      if (!google) return run();
+      };
       return lazyStream(model, async () => ({
         async *[Symbol.asyncIterator]() {
-          for await (const event of run()) {
-            if (event.type === "done") yield { ...event, message: { ...event.message, model: model.id } };
-            else if (event.type === "error") yield { ...event, error: { ...event.error, model: model.id } };
-            else yield { ...event, partial: { ...event.partial, model: model.id } };
+          let quotaDeadline: number | undefined;
+          for (;;) {
+            let started = false;
+            let retry = false;
+            for await (const event of run()) {
+              if (event.type === "error" && event.reason === "error" && !started) {
+                const resetAt = quotaRetryAt(event.error.errorMessage, response);
+                const failure = quotaError(event.error.errorMessage);
+                const upstream =
+                  failure?.provider ??
+                  (typeof failure?.message === "string"
+                    ? /via provider ([\w-]+)/.exec(failure.message)?.[1]
+                    : undefined);
+                const checkClaude =
+                  liveClaude &&
+                  (upstream === undefined || upstream === "claude") &&
+                  isQuotaFailure(failure, response?.status);
+                if ((checkClaude || resetAt) && !options?.signal?.aborted) {
+                  quotaDeadline ??= Date.now() + 7 * 86400000 + 1000;
+                  try {
+                    // Keep quota waits outside HTTP timeouts and within one fixed weekly deadline.
+                    let waited = false;
+                    if (checkClaude) {
+                      waited = await waitForClaudeQuota(
+                        config,
+                        managementKey,
+                        model.id,
+                        quotaDeadline,
+                        options?.signal,
+                        onWait,
+                        typeof failure?.message === "string" &&
+                          /would exceed your account's rate limit/i.test(failure.message),
+                      );
+                    }
+                    if (!waited) {
+                      if (!resetAt) {
+                        yield event;
+                        return;
+                      }
+                      if (resetAt > quotaDeadline)
+                        throw new Error("The seven-day quota waiting deadline was reached.");
+                      await waitForQuota(resetAt, options?.signal, onWait);
+                    }
+                    if (Date.now() >= quotaDeadline)
+                      throw new Error("The seven-day quota waiting deadline was reached.");
+                  } catch (error) {
+                    const reason = options?.signal?.aborted ? ("aborted" as const) : ("error" as const);
+                    yield {
+                      type: "error" as const,
+                      reason,
+                      error: {
+                        ...event.error,
+                        model: model.id,
+                        stopReason: reason,
+                        errorMessage:
+                          reason === "aborted"
+                            ? "Request was aborted during the quota wait."
+                            : `CLIProxyAPI quota wait stopped. ${error instanceof Error ? error.message : "Live quota could not be verified."}`,
+                      },
+                    };
+                    return;
+                  }
+                  retry = true;
+                  break;
+                }
+              }
+              started = true;
+              if (!google) yield event;
+              else if (event.type === "done")
+                yield { ...event, message: { ...event.message, model: model.id } };
+              else if (event.type === "error") yield { ...event, error: { ...event.error, model: model.id } };
+              else yield { ...event, partial: { ...event.partial, model: model.id } };
+            }
+            if (!retry) return;
           }
         },
       }));
@@ -164,10 +333,14 @@ function route(streams: ProviderStreams, baseUrl: string): ProviderStreams {
   return { stream: wrap(streams.stream), streamSimple: wrap(streams.streamSimple) };
 }
 
-export function createCliproxyProvider(config: Config, known: readonly Model<Api>[] = builtinCatalog()) {
+export function createCliproxyProvider(
+  config: Config,
+  known: readonly Model<Api>[] = builtinCatalog(),
+  onQuotaWait?: QuotaWaitHandler,
+) {
   const standardAuth = envApiKeyAuth("CLIProxyAPI API key", ["CLIPROXYAPI_API_KEY"]);
   const scope = createHash("sha256")
-    .update(JSON.stringify([4, config]))
+    .update(JSON.stringify([4, { baseUrl: config.baseUrl, aliases: config.aliases }]))
     .digest("hex");
   const provider = createProvider<CpaApi>({
     id: PROVIDER_ID,
@@ -199,10 +372,10 @@ export function createCliproxyProvider(config: Config, known: readonly Model<Api
       return (await discover(config, context.credential.key, context.signal, known)).models;
     },
     api: {
-      "anthropic-messages": route(anthropicMessagesApi(), config.baseUrl),
-      "openai-responses": route(openAIResponsesApi(), config.baseUrl),
-      "openai-completions": route(openAICompletionsApi(), config.baseUrl),
-      "google-generative-ai": route(googleGenerativeAIApi(), config.baseUrl),
+      "anthropic-messages": route(anthropicMessagesApi(), config, onQuotaWait),
+      "openai-responses": route(openAIResponsesApi(), config, onQuotaWait),
+      "openai-completions": route(openAICompletionsApi(), config, onQuotaWait),
+      "google-generative-ai": route(googleGenerativeAIApi(), config, onQuotaWait),
     },
   });
   const refresh = provider.refreshModels;