@bitkyc08/opencodex 2.41.0 → 2.43.0-preview.20260906

package/src/claude/inbound.ts

@@ -10,130 +10,24 @@
  *  - top_k is accepted and silently dropped (no Responses equivalent, CCR parity).
  */
 import type { OcxClaudeCodeConfig } from "../types";
-import { isAnthropicOutputSchema } from "../adapters/anthropic-output-schema";
-import { resolveAlias } from "./alias";
-import { stripOneMillionMarker } from "./context-windows";
-import { resolveDesktop3pAlias } from "./desktop-3p";
-import { isClaudeWebSearchToolName } from "./outbound";
 import { createHash } from "node:crypto";
 
-export class AnthropicRequestError extends Error {}
+export { AnthropicRequestError } from "./inbound-records";
+export { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, extractOcxRouteDirective, extractOcxEffortDirective } from "./inbound-model-options";
+import { AnthropicRequestError, isRec, type Rec } from "./inbound-records";
+import { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, formatFromOutputConfig } from "./inbound-model-options";
+import { systemToInstructions, toolsToResponses, toolChoiceToResponses } from "./inbound-content-options";
 
-type Rec = Record<string, unknown>;
 
-function isRec(v: unknown): v is Rec {
-  return !!v && typeof v === "object" && !Array.isArray(v);
-}
-
-function isClaudeClassifierModel(model: string): boolean {
-  const stripped = model.replace(/-\d{8}$/, "");
-  return /^claude-opus-[45]/.test(stripped);
-}
-
-/**
- * Explicitly configured classifier route for Claude Code Auto Mode safety checks (#1697).
- *
- * Only OPERATOR-DECLARED targets are used: `classifierModel`, then the ordered
- * `classifierFallbacks`. Both are qualified `provider/model` strings the operator chose, so
- * routing them crosses no boundary the operator did not ask for.
- *
- * Deliberately NOT here: inferring a provider from `claudeCode.model`. That value is the
- * injected/default config slot, not the provider the live session actually selected, so it goes
- * stale the moment the user changes the model picker -- and acting on it would silently move a
- * classifier turn onto a provider with its own privacy and billing consequences. Live session
- * affinity needs the request/session state this function does not have; it is tracked as
- * follow-up work rather than approximated from static config.
- */
-function configuredClassifierRoute(cc?: OcxClaudeCodeConfig): string | undefined {
-  const explicit = typeof cc?.classifierModel === "string" ? cc.classifierModel.trim() : "";
-  if (explicit.length > 0) return explicit;
-  if (Array.isArray(cc?.classifierFallbacks)) {
-    for (const candidate of cc.classifierFallbacks) {
-      if (typeof candidate === "string" && candidate.trim().length > 0) return candidate.trim();
-    }
-  }
-  return undefined;
-}
-
-/** Alias first, then modelMap: exact id, then date-suffix-stripped (`-\d{8}$`), then classifier affinity/config, else passthrough. */
-export function resolveInboundModel(model: string, cc?: OcxClaudeCodeConfig): string {
-  // Defensive: Desktop/CLI strip the [1m] context-variant marker client-side, but a
-  // leaking build must not break alias decode (devlog 138 — the 1M signal is the
-  // anthropic-beta header, never the id). Case-insensitive: the CLI matches /\[1m\]/i.
-  model = stripOneMillionMarker(model);
-  const aliased = resolveAlias(model);
-  if (aliased) return aliased;
-  // Desktop 3P aliases: claude-opus-4-{code} → provider/model route key
-  const desktop3p = resolveDesktop3pAlias(model);
-  if (desktop3p) {
-    // Native pseudo-provider returns bare slug; routed returns provider/model
-    const sep = desktop3p.indexOf("/");
-    if (sep > 0 && desktop3p.slice(0, sep) === "native") return desktop3p.slice(sep + 1);
-    return desktop3p;
-  }
-  const map = cc?.modelMap ?? {};
-  const exact = map[model];
-  if (typeof exact === "string" && exact.length > 0) return exact;
-  const stripped = model.replace(/-\d{8}$/, "");
-  const dateless = map[stripped];
-  if (typeof dateless === "string" && dateless.length > 0) return dateless;
-
-  // Claude Code Auto Mode classifier routing (#1697). Bare classifier checks such as
-  // `claude-opus-5` carry no provider, so without this they fall through to defaultProvider --
-  // which may not speak Anthropic at all. Only an operator-declared target is used.
-  if (isClaudeClassifierModel(model)) {
-    const configured = configuredClassifierRoute(cc);
-    if (configured) return configured;
-  }
-  return model;
-}
-
-/** budget_tokens ladder -> Responses reasoning effort (003: real API min is 1024; never forward raw). */
-export function effortForThinkingBudget(budget: number): string {
-  if (budget <= 4096) return "low";
-  if (budget <= 16384) return "medium";
-  return "high";
-}
-
-/**
- * Adaptive-thinking wire (devlog 080): Claude Code /effort sends
- * `thinking:{type:"adaptive"}` + `output_config:{effort:"..."}` (verified by local
- * capture of claude 2.1.207 and CLIProxyAPI#1540). Forward the level verbatim when it
- * is a known Responses effort; unknown strings are dropped so downstream defaults win.
- */
-const OUTPUT_CONFIG_EFFORTS = new Set(["minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
-export function effortFromOutputConfig(outputConfig: unknown): string | undefined {
-  if (!isRec(outputConfig)) return undefined;
-  const effort = outputConfig.effort;
-  return typeof effort === "string" && OUTPUT_CONFIG_EFFORTS.has(effort) ? effort : undefined;
-}
-
-function formatFromOutputConfig(outputConfig: unknown): Rec | undefined {
-  if (!isRec(outputConfig) || !isRec(outputConfig.format)) return undefined;
-  const format = outputConfig.format;
-  if (
-    format.type !== "json_schema"
-    || !isRec(format.schema)
-    || !isAnthropicOutputSchema(format.schema)
-  ) return undefined;
-  return { type: "json_schema", name: "response", schema: format.schema };
-}
-
-function systemToInstructions(system: unknown): string | undefined {
-  if (typeof system === "string") return system.length > 0 ? system : undefined;
-  if (Array.isArray(system)) {
-    const parts: string[] = [];
-    for (const block of system) {
-      if (isRec(block) && block.type === "text" && typeof block.text === "string") parts.push(block.text);
-    }
-    return parts.length > 0 ? parts.join("\n\n") : undefined;
-  }
-  return undefined;
-}
 
 function imageBlockToInputImage(block: Rec): Rec | null {
   const source = block.source;
   if (!isRec(source)) return null;
+  if (source.type === "file") {
+    throw new AnthropicRequestError(
+      "File-backed images require native Anthropic passthrough; use base64 or URL images on translated routes.",
+    );
+  }
   if (source.type === "base64" && typeof source.data === "string") {
     const media = typeof source.media_type === "string" ? source.media_type : "image/png";
     return { type: "input_image", image_url: `data:${media};base64,${source.data}` };
@@ -194,47 +88,6 @@ export function effectiveBlockedSkillNames(cc?: Pick<OcxClaudeCodeConfig, "block
     .filter(name => name.length > 0))];
 }
 
-/**
- * ocx-route directive (devlog 072): injected agent-definition bodies carry
- * `<!-- ocx-route: <model> -->` because Claude Code 2.1.207 ignores custom
- * gateway ids in agent frontmatter (live-proven fallback to sonnet). The body
- * rides the subagent's system prompt, so the proxy re-routes here. Only the
- * FIRST directive wins; the scan is bounded to the system field.
- */
-const OCX_ROUTE_RE = /<!--\s*ocx-route:\s*([^\s]+)\s*-->/;
-const OCX_EFFORT_RE = /<!--\s*ocx-effort:\s*(low|medium|high|xhigh|max)\s*-->/;
-
-function systemText(body: unknown): string | null {
-  if (!isRec(body)) return null;
-  const system = body.system;
-  if (typeof system === "string") return system || null;
-  if (!Array.isArray(system)) return null;
-  const text = system
-    .filter((b): b is Rec => isRec(b) && b.type === "text" && typeof b.text === "string")
-    .map(b => b.text as string)
-    .join("\n");
-  return text || null;
-}
-
-export function extractOcxRouteDirective(body: unknown): string | null {
-  const text = systemText(body);
-  if (!text) return null;
-  const match = OCX_ROUTE_RE.exec(text);
-  return match ? match[1]! : null;
-}
-
-/**
- * Claude Code 2.1.220 collapses custom-agent frontmatter `effort: max` and
- * `effort: xhigh` into the legacy `thinking.budget_tokens` shape. Preserve the
- * exact generated-agent setting through the same trusted system-body channel as
- * ocx-route so the inbound translator can restore `output_config.effort`.
- */
-export function extractOcxEffortDirective(body: unknown): NonNullable<OcxClaudeCodeConfig["subagentEffort"]> | null {
-  const text = systemText(body);
-  if (!text) return null;
-  const match = OCX_EFFORT_RE.exec(text);
-  return match ? match[1] as NonNullable<OcxClaudeCodeConfig["subagentEffort"]> : null;
-}
 
 /** Injected-skill payloads below this size are never stubbed (not worth it). */
 const SKILL_ELISION_MIN_CHARS = 10_000;
@@ -391,51 +244,6 @@ function assistantMessageToItems(content: unknown, input: Rec[]): void {
   flush();
 }
 
-function toolsToResponses(tools: unknown): Rec[] | undefined {
-  if (!Array.isArray(tools) || tools.length === 0) return undefined;
-  const out: Rec[] = [];
-  for (const raw of tools) {
-    if (!isRec(raw)) continue;
-    const type = typeof raw.type === "string" ? raw.type : "";
-    if (type.startsWith("web_search")) {
-      out.push({ type: "web_search" }); // hosted sidecar path
-      continue;
-    }
-    if (typeof raw.name === "string" && raw.name.length > 0 && isRec(raw.input_schema)) {
-      out.push({
-        type: "function",
-        name: raw.name,
-        ...(typeof raw.description === "string" ? { description: raw.description } : {}),
-        parameters: raw.input_schema as Record<string, unknown>,
-      });
-      continue;
-    }
-    // Other server tools (bash_*, text_editor_*, ...) have no routed equivalent: drop.
-  }
-  return out.length > 0 ? out : undefined;
-}
-
-function toolChoiceToResponses(choice: unknown, body: Rec): void {
-  if (!isRec(choice)) return;
-  if (choice.disable_parallel_tool_use === true) body.parallel_tool_calls = false;
-  switch (choice.type) {
-    case "auto": body.tool_choice = "auto"; break;
-    case "none": body.tool_choice = "none"; break;
-    case "any": body.tool_choice = "required"; break;
-    case "tool":
-      if (typeof choice.name !== "string" || choice.name.length === 0) {
-        throw new AnthropicRequestError("tool_choice.tool requires a name");
-      }
-      // Anthropic represents hosted WebSearch as a named tool choice, while
-      // Responses requires the choice type to match the hosted declaration.
-      // Preserve forced-tool intent rather than weakening it to `auto`.
-      body.tool_choice = isClaudeWebSearchToolName(choice.name)
-        ? { type: "web_search" }
-        : { type: "function", name: choice.name };
-      break;
-    default: break;
-  }
-}
 
 /** Recursive canonical JSON (keys sorted at every depth) — stable cache-cohort input. */
 function canonicalJson(value: unknown): string {

package/src/claude/model-info.ts

@@ -111,9 +111,32 @@ export function buildAnthropicModelInfos(
   aliasForRoute: (provider: string, modelId: string) => string = desktop3pAlias,
   nativeContextCap?: NativeContextLimitsInput,
   fastMode?: boolean,
+  // Presence is the feature gate: the caller passes undefined when `fastRows` is off, so a
+  // default install publishes nothing. The predicate answers ELIGIBILITY, not enablement.
+  fastRows?: (model: CatalogModel | { provider: string; id: string }) => boolean,
 ): AnthropicModelInfo[] {
   const out: AnthropicModelInfo[] = [];
   const seen = new Set<string>();
+  // Every id the loops below will really emit, computed BEFORE either runs. `seen` alone is
+  // not enough: it grows as they run, so whether a synthetic id collided with a real one
+  // would depend on iteration order. With both `foo` and a real `foo--fast` in the roster,
+  // the synthetic id for `foo` IS the real model's id, and whichever ran first would win it.
+  const realDiscoveryIds = new Set<string>([
+    ...nativeSlugs.map(slug => (
+      idStyle === "readable" ? claudeCodeNativeAlias(slug) : aliasForRoute("native", slug)
+    )),
+    ...routedModels.map(m => {
+      // The same asymmetry the routed loop applies: readable uses the LISTED id, so a
+      // fastMode-rewritten Cursor row is counted under the id it is really published as,
+      // while Desktop 3P hashes the RAW id.
+      const listed = fastMode === true && m.provider === "cursor" && idStyle === "readable"
+        ? cursorFastIdFor(m.id) ?? m.id
+        : m.id;
+      return idStyle === "readable"
+        ? claudeCodeAlias(m.provider, listed)
+        : aliasForRoute(m.provider, m.id);
+    }),
+  ]);
   // [1m] picker variant (devlog 260712 B1): Claude Code accounts exactly 1M for ids
   // carrying the marker (2.1.207 binary: /\[1m\]/i → 1e6, compaction preserved), so
   // ONLY models with an authoritative >=1M window get a second selectable row —
@@ -140,6 +163,21 @@ export function buildAnthropicModelInfos(
       : ONE_MILLION;
     out.push({ ...base, id, display_name: `${base.display_name} · 1M`, max_input_tokens: advertised });
   };
+  /**
+   * Publish a Fast sibling beside a row, following `push1mVariant` rather than the
+   * `fastMode` rewrite below: `fastMode` is a global switch with no per-request choice, so
+   * it REPLACES the listed id, while a selector has to leave the default pickable beside it.
+   *
+   * Because it only ADDS a row, it is safe for the Desktop 3P hashed style too — the
+   * exclusion `fastMode` needs exists because rewriting a hash strands a saved selection.
+   */
+  const pushFastVariant = (base: AnthropicModelInfo) => {
+    const id = `${base.id}--fast`;
+    // A real model always wins its own id, whatever the iteration order.
+    if (realDiscoveryIds.has(id) || seen.has(id)) return;
+    seen.add(id);
+    out.push({ ...base, id, display_name: `${base.display_name} · Fast` });
+  };
   for (const slug of nativeSlugs) {
     const id = idStyle === "readable" ? claudeCodeNativeAlias(slug) : aliasForRoute("native", slug);
     if (seen.has(id)) continue;
@@ -151,6 +189,9 @@ export function buildAnthropicModelInfos(
     const info = modelInfo(id, `${slug} (native)`, nativeEffectiveLadder(slug), true, nativeMaxInput ?? nativeWindow);
     out.push(info);
     push1mVariant(info, nativeWindow, nativeMaxInput);
+    // Natives too, not only routed rows: gpt-5.6-sol is the flagship Fast model, and
+    // omitting it would leave this surface without the model the feature exists for.
+    if (fastRows?.({ provider: "native", id: slug }) === true) pushFastVariant(info);
   }
   for (const m of routedModels) {
     // Global Fast has no toggle on this surface, so the fast identity is what gets listed —
@@ -180,6 +221,10 @@ export function buildAnthropicModelInfos(
     // Anthropic passthrough guard (audit 021 #3): never auto-widen canonical claude
     // routes — only a genuine >=1M window earns the variant row there.
     push1mVariant(info, m.contextWindow, routedMaxInput);
+    // The whole model is passed, not a (provider, id) pair: a combo row lives in its own
+    // namespace with no config.providers entry, so the caller classifies it from the
+    // aggregated supportsServiceTier the row already carries.
+    if (fastRows?.(m) === true) pushFastVariant(info);
   }
   return out;
 }

package/src/cli/account-auth.ts

@@ -1,5 +1,7 @@
 import { writeSync } from "node:fs";
+import { modelSelectionGuidance, modelSelectionNextSteps } from "./model-selection-guidance";
 import { warnIfCodexCatalogRefreshPending } from "./account-catalog-refresh";
+import { isCodexResetCreditOperationId } from "../codex/reset-credit-recovery";
 import {
   CliUsageError,
   printData,
@@ -31,10 +33,15 @@ function writeStdoutFully(text: string): void {
 }
 
 const USAGE = `Usage:
-  ocx account login <provider> [--id <account-id>] [--reauth] [--code -] [--no-wait] [--json]
+  ocx account login <provider> [--id <account-id>] [--reauth] [--device] [--code -] [--no-wait] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json]
-  ocx account reset-credits <account-id|main> [--consume --yes] [--json]
+  ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]
+
+--device runs the OpenAI device-code login instead of the browser callback: use
+it when the proxy has no browser or nothing can reach localhost:1455, such as a
+headless or remote hub. Enter the printed code at the printed URL from any other
+machine.
 
 The redirect URL or authorization code is a short-lived credential. Pipe it in
 rather than passing it as an argument, where it lands in shell history and is
@@ -54,6 +61,9 @@ interface LoginStart {
 /** `-` means "read it from stdin", the documented way to pass a code silently. */
 const STDIN_SENTINEL = "-";
 
+/** Providers whose ONLY login is already a device flow; --device is redundant, not wrong. */
+const DEVICE_NATIVE_PROVIDERS = new Set(["kimi", "nous", "github-copilot"]);
+
 const ARGV_WARNING =
   "warning: the authorization code was passed as a command-line argument, so it is now in your shell history and was visible in the process list while this ran. Pipe it on stdin instead, or pass `-` to read from stdin.";
 
@@ -86,10 +96,17 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const wantsJson = takeFlag(args, "--json");
   const noWait = takeFlag(args, "--no-wait");
   const reauth = takeFlag(args, "--reauth");
+  const device = takeFlag(args, "--device");
   const id = takeOption(args, "--id");
   const suppliedCode = takeOptionWithSyntax(args, "--code");
   if (!provider) throw new CliUsageError("provider is required", USAGE);
   rejectArgs(args, USAGE);
+  // kimi, nous, and github-copilot are already device flows, so --device is a
+  // true statement about them and is accepted as a no-op rather than an error.
+  // Anything else has no device grant at all and must fail loudly.
+  if (device && !CODEX_NAMES.has(provider) && !DEVICE_NATIVE_PROVIDERS.has(provider)) {
+    throw new CliUsageError(`--device is not supported for provider '${provider}'`, USAGE);
+  }
   // Only resolve when --code was actually given: a plain `ocx account login`
   // opens the browser flow and polls, and must not block on stdin.
   const code = await resolveCode(suppliedCode, deps, false);
@@ -97,13 +114,18 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (CODEX_NAMES.has(provider)) {
     const start = await runtimeRequest<LoginStart>("/api/codex-auth/login", {
       method: "POST",
-      body: JSON.stringify({ ...(id ? { id } : {}), ...(reauth ? { reauth: true } : {}) }),
+      body: JSON.stringify({
+        ...(id ? { id } : {}),
+        ...(reauth ? { reauth: true } : {}),
+        ...(device ? { device: true } : {}),
+      }),
     }, deps);
     if (!wantsJson) {
       // One atomic pre-poll block, flushed synchronously so a piped parent
       // reads the URL before the polling window starts (#1007).
       const block = [
         start.url ? `Open this URL to sign in:\n${start.url}` : "",
+        start.deviceCode ? `Device code: ${start.deviceCode}` : "",
         start.instructions ?? "",
         start.flowId ? `Flow: ${start.flowId}` : "",
       ].filter(line => line !== "").join("\n");
@@ -116,18 +138,23 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
       }, deps);
     }
     if (noWait) {
-      if (wantsJson) printData(start, true);
+      printData({ ...start, modelSelection: modelSelectionNextSteps("openai", true) }, wantsJson, modelSelectionGuidance("openai", true));
       return;
     }
     if (!start.flowId) throw new CliUsageError("login did not return a flow id");
-    for (let attempt = 0; attempt < 150; attempt++) {
+    // A device login is deliberately slow: the user leaves this machine to
+    // enter the code elsewhere. Match the 15-minute grant instead of giving up
+    // at minute five while it is still valid, plus settlement margin for the
+    // token exchange and credential write after the final poll.
+    const maxAttempts = device ? 480 : 150;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
       await Bun.sleep(2_000);
       const state = await runtimeRequest<Record<string, unknown>>(
         `/api/codex-auth/login-status?flowId=${encodeURIComponent(start.flowId)}${id ? `&accountId=${encodeURIComponent(id)}` : ""}${reauth ? "&reauth=1" : ""}`,
         {}, deps,
       );
       if (state.status === "done") {
-        printData(state, wantsJson, [`Logged in${state.email ? ` as ${String(state.email)}` : ""}.`]);
+        printData({ ...state, modelSelection: modelSelectionNextSteps("openai") }, wantsJson, [`Logged in${state.email ? ` as ${String(state.email)}` : ""}.`, ...modelSelectionGuidance("openai")]);
         if (!wantsJson) warnIfCodexCatalogRefreshPending(state);
         return;
       }
@@ -158,7 +185,7 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     }, deps);
   }
   if (noWait) {
-    if (wantsJson) printData(start, true);
+    printData({ ...start, modelSelection: modelSelectionNextSteps(provider, true) }, wantsJson, modelSelectionGuidance(provider, true));
     return;
   }
   for (let attempt = 0; attempt < 100; attempt++) {
@@ -166,7 +193,7 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     const state = await runtimeRequest<Record<string, unknown>>(`/api/oauth/status?provider=${encodeURIComponent(provider)}`, {}, deps);
     if (state.error) throw new CliUsageError(String(state.error));
     if (state.loggedIn === true) {
-      printData(state, wantsJson, [`Logged in to ${provider}.`]);
+      printData({ ...state, modelSelection: modelSelectionNextSteps(provider) }, wantsJson, [`Logged in to ${provider}.`, ...modelSelectionGuidance(provider)]);
       return;
     }
   }
@@ -227,12 +254,25 @@ async function resetCredits(argv: string[], deps: RuntimeApiDeps): Promise<void>
   const wantsJson = takeFlag(args, "--json");
   const consume = takeFlag(args, "--consume");
   const yes = takeFlag(args, "--yes");
+  // Before rejectArgs: takeOption splices its two tokens out of `args`.
+  const operationId = takeOption(args, "--operation-id");
   if (!rawId) throw new CliUsageError("account id is required", USAGE);
   if (consume && !yes) throw new CliUsageError("consuming a reset credit requires --yes", USAGE);
+  if (operationId !== undefined && !consume) {
+    throw new CliUsageError("--operation-id requires --consume", USAGE);
+  }
+  if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
+    throw new CliUsageError("--operation-id must be a UUIDv4", USAGE);
+  }
   rejectArgs(args, USAGE);
   const accountId = rawId === "main" ? "__main__" : rawId;
   const result = consume
-    ? await runtimeRequest("/api/codex-auth/reset-credits/consume", { method: "POST", body: JSON.stringify({ accountId }) }, deps)
+    ? await runtimeRequest("/api/codex-auth/reset-credits/consume", {
+      method: "POST",
+      // Spread, not `operationId: undefined`: the server distinguishes an absent
+      // key (legacy random id) from a caller who asked for a stable identity.
+      body: JSON.stringify({ accountId, ...(operationId === undefined ? {} : { operationId }) }),
+    }, deps)
     : await runtimeRequest(`/api/codex-auth/reset-credits?accountId=${encodeURIComponent(accountId)}`, {}, deps);
   printData(result, wantsJson);
 }

package/src/cli/account-extended.ts

@@ -1,4 +1,5 @@
 import { loadConfig } from "../config";
+import { hasPassiveAccountQuota } from "../providers/quota";
 import { closeSync, openSync, readSync } from "node:fs";
 import {
   MAX_ACCOUNT_PRIORITY,
@@ -330,7 +331,12 @@ export async function cmdRefresh(args: string[], deps: AccountDeps): Promise<num
     if (result.status === 0) return proxyUnreachable(result.transportError);
     if (result.status !== 200) return apiError(result.errorJson ?? {}, `failed to refresh ${name}`, result.status);
     if (wantsJson) console.log(JSON.stringify({ provider: name, report: result.report }, null, 2));
-    else console.log(result.report ? providerQuotaLine(name, result.report) : `no quota report available for ${name}`);
+    else if (result.report) console.log(providerQuotaLine(name, result.report));
+    // A passive provider has no probe to run, so "no report available" reads as a
+    // failure of something that was never attempted. Say what is actually true.
+    else if (hasPassiveAccountQuota(name)) {
+      console.log(`${name} reports usage only during a streaming response; there is nothing to refresh. Run a request through this provider to update it, then see \`ocx account list ${name}\`.`);
+    } else console.log(`no quota report available for ${name}`);
     return 0;
   }
   const result = await fetchCodexRows(deps, baseUrl, true);

package/src/cli/capabilities.ts

@@ -11,7 +11,7 @@
  * top-level `const USAGE`, evaluated at import time, so a cycle back into this table
  * would resolve to `undefined` under ESM rather than throwing -- silently emptying the
  * usage text that `rejectArgs` hands to `CliUsageError`, in the exact error-reporting
- * surface the CLI-operability issues are about. `tests/cli-capabilities.test.ts` asserts
+ * surface the CLI-operability issues are about. `tests/cli/cli-capabilities.test.ts` asserts
  * the absence of those imports and that every rendered usage string is non-empty, so the
  * failure mode is loud instead of degraded.
  *
@@ -19,7 +19,7 @@
  * `HEAD_CAPABILITIES`. They exit in the CLI head (`root.ts`) before dispatch and have no
  * runner key, so listing them as ordinary capabilities would break the registry parity
  * assertion that every canonical entry is a direct runner. `help` is excluded from
- * `CLI_COMMANDS` deliberately -- `tests/cli-registry.test.ts` documents it as a
+ * `CLI_COMMANDS` deliberately -- `tests/cli/cli-registry.test.ts` documents it as a
  * head-handled pseudo-case -- and that decision is preserved here rather than reversed.
  */
 
@@ -153,6 +153,17 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "envelope",
     details: ["Reads local config; drives no management API route."],
   },
+  {
+    command: ["provider", "resets"],
+    summary: "Recently detected quota resets and whether reset notifications are enabled.",
+    routes: [{ method: "GET", path: "/api/quota-resets" }],
+    flags: [
+      { name: "--json", value: "boolean", summary: "Emit reset events as JSON." },
+      { name: "--limit", value: "number", summary: "Limit returned events; defaults to 20, capped at 100." },
+    ],
+    mutates: false,
+    json: "payload",
+  },
   {
     command: ["provider", "keychain"],
     summary: "Move a provider's API key into the OS keychain, restore it, or report where it lives.",
@@ -247,7 +258,7 @@ export const CAPABILITIES: readonly Capability[] = [
       "A bare invocation reads and never writes.",
       "The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible.",
       "Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound.",
-      "`anthropic` is the only OAuth pool with this setting; other OAuth providers are refused without a round-trip.",
+      "`anthropic` owns the full pool contract. Other OAuth providers reach the same endpoint with a generic subset (enabled/strategy/autoSwitchThreshold) whose settings persist but do not yet steer selection; `sticky` and `quotaWindow` are refused for them.",
     ],
   },
   {
@@ -274,7 +285,7 @@ export const CAPABILITIES: readonly Capability[] = [
       { name: "--conversation", value: "string", summary: "Restrict to one conversation id (`--conversationId` is accepted too)." },
       { name: "--status", value: "string", summary: "An exact code (429) or a class (5xx)." },
       { name: "--limit", value: "number", summary: "Row cap; defaults to 200." },
-      { name: "--follow", value: "boolean", summary: "Stream new rows as JSONL; implies --jsonl." },
+      { name: "--follow", value: "boolean", summary: "Poll for new rows; add --jsonl to emit JSONL." },
       { name: "--json", value: "boolean", summary: "Emit the server payload as JSON." },
       { name: "--jsonl", value: "boolean", summary: "Emit one row per line." },
     ],