@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/providers/api-key-resolve.ts

@@ -18,9 +18,12 @@
  */
 import { resolveEnvValue } from "../config/proxy-env";
 import { loadKeyringBinding } from "../lib/keyring-native";
+import { isGcpCredentialMaterial } from "../lib/gcp-credential-input";
 import type { OcxProviderConfig } from "../types";
 
 export const KEYCHAIN_REFERENCE_PREFIX = "keychain:";
+/** Stored GCP JSON uses the same OS service, but must never be restored as a literal API key. */
+export const GCP_CREDENTIAL_MARKER_PREFIX = "gcp-sa:";
 export const PROVIDER_KEYCHAIN_SERVICE = "opencodex.provider-api-key.v1";
 
 export interface ProviderKeychainEntry {
@@ -87,15 +90,17 @@ export function providerKeychainEntry(account: string): ProviderKeychainEntry {
 function readKeychain(account: string, quiet = false): string | undefined {
   const cached = resolvedCache.get(account);
   if (cached !== undefined) return cached;
+  let value: string | null = null;
   try {
-    const value = providerKeychainEntry(account).getPassword();
-    if (typeof value === "string" && value.trim()) {
-      resolvedCache.set(account, value);
-      return value;
-    }
+    value = providerKeychainEntry(account).getPassword();
   } catch {
     // fall through to the single warning below
   }
+  if (typeof value === "string" && value.trim()) {
+    if (isGcpCredentialMaterial(value)) throw new Error("GCP credential JSON cannot be used as a literal API key; select a gcp-sa reference");
+    resolvedCache.set(account, value);
+    return value;
+  }
   if (!quiet && !warnedAccounts.has(account)) {
     warnedAccounts.add(account);
     console.warn(`[opencodex] provider key reference keychain:${account} could not be read from the OS keychain; requests for this provider have no credential until the keychain is available (no plaintext fallback)`);
@@ -125,7 +130,7 @@ export type ProviderKeyStoreKind = "keychain" | "env" | "file" | "none";
 export function providerKeyStoreKind(provider: Pick<OcxProviderConfig, "apiKey"> | undefined): ProviderKeyStoreKind {
   const key = provider?.apiKey;
   if (!key) return "none";
-  if (isKeychainReference(key)) return "keychain";
+  if (key.startsWith(GCP_CREDENTIAL_MARKER_PREFIX) || isKeychainReference(key)) return "keychain";
   if (/^\$\{?\w+\}?$/.test(key)) return "env";
   return "file";
 }

package/src/providers/api-key-response-ownership.ts

@@ -0,0 +1,57 @@
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { isEgressTransparentExecutor, markEgressTransparentExecutor } from "../lib/provider-egress";
+import { isNonReplayableResponse } from "../lib/upstream-retry";
+import { providerApiKeySelectionOwnsFailure } from "./api-key-selection";
+import { recordDistributedKeyFailure } from "./key-failover";
+import { registerProviderResponseProvenance } from "./request-pacing";
+
+interface KeyResponseOwner {
+  readonly providerName: string;
+  readonly provider: OcxProviderConfig;
+}
+const owners = new WeakMap<Response, KeyResponseOwner | null>();
+registerProviderResponseProvenance(owners);
+
+/** Capture the credential after connection-policy rewrites, immediately before fetch. */
+export function distributedKeyPhysicalFetch(
+  physicalFetch: typeof globalThis.fetch, providerName: string, provider: OcxProviderConfig, target: string,
+  authHeader: "authorization" | "x-api-key" = "authorization",
+): typeof globalThis.fetch {
+  if (!provider._apiKeyAttempt?.distributed) return physicalFetch;
+  const wrapped = (async (input, init) => {
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    const destination = input instanceof Request ? input.url : String(input);
+    const ownsCredential = destination === target && !headers.has("api-key")
+      && (authHeader === "authorization"
+        ? headers.get("authorization") === `Bearer ${provider.apiKey}` && !headers.has("x-api-key")
+        : headers.get("x-api-key") === provider.apiKey && !headers.has("authorization"));
+    const owner: KeyResponseOwner | null = provider._apiKeyAttempt?.distributed && ownsCredential
+      ? Object.freeze({ providerName, provider: Object.freeze({ ...provider,
+        _apiKeyAttempt: Object.freeze({ ...provider._apiKeyAttempt }) }) }) : null;
+    const response = await physicalFetch(input, init);
+    // Reused response identities cannot safely describe two physical sends.
+    owners.set(response, owners.has(response) ? null : owner);
+    return response;
+  }) as typeof globalThis.fetch;
+  return isEgressTransparentExecutor(physicalFetch) ? markEgressTransparentExecutor(wrapped) : wrapped;
+}
+
+/** Return only a still-configured credential captured at the physical send. */
+export function distributedKeyResponseOwner(
+  response: Response, config: OcxConfig, providerName: string,
+): OcxProviderConfig | null {
+  const owner = owners.get(response);
+  return owner?.providerName === providerName
+    && providerApiKeySelectionOwnsFailure(config, providerName, owner.provider) ? owner.provider : null;
+}
+
+/** Settle only the terminal refusal; configured same-key 429 retries retain their key. */
+export function recordDistributedResponseFailure(
+  response: Response, config: OcxConfig, providerName: string, signal?: AbortSignal,
+): void {
+  if (signal?.aborted || isNonReplayableResponse(response) || (response.status !== 401 && response.status !== 429)) return;
+  const owner = distributedKeyResponseOwner(response, config, providerName);
+  if (!owner) return;
+  recordDistributedKeyFailure(config, providerName, owner._apiKeyAttempt,
+    response.status, Date.now(), response.headers.get("retry-after"));
+}

package/src/providers/api-key-selection.ts

@@ -1,10 +1,11 @@
+import { isKeyInCooldown } from "./api-key-cooldowns";
 import { randomUUID } from "node:crypto";
 import { mutatePersistedConfig } from "../config";
 import { publishAccountSelection } from "../lib/account-selection-events";
 import { clearModelCache } from "../codex/model-cache";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import type { ProviderApiKeySelection } from "../types/provider";
-import { routedProviderConfig } from "../router";
+import { routedProviderConfig } from "./routed-config";
 import { OPENCODE_GO_SESSION_HEADER } from "./opencode-go-transport";
 import { resolveProviderTransport, XAI_GROK_COMPATIBILITY, type OcxProviderTransport } from "./xai-transport";
 import { captureProviderApiKeySelection } from "./api-key-selection-capture";
@@ -17,10 +18,17 @@ function matchesSelection(provider: OcxProviderConfig, expected: ProviderApiKeyS
     && current.revision === expected.revision;
 }
 
-function currentKeyProvider(config: OcxConfig, name: string): OcxProviderConfig | null {
+function currentKeyProvider(config: OcxConfig, name: string, selection?: ProviderApiKeySelection, allowCooling = false): OcxProviderConfig | null {
   const configured = config.providers[name];
   if (!configured || configured.disabled) return null;
-  const current = routedProviderConfig(name, { ...configured, _apiKeyAttempt: undefined });
+  let row = configured;
+  if (selection?.distributed) {
+    const entry = configured.apiKeyPool?.find(key => key.id === selection.entryId && key.key === selection.reference);
+    if (!entry || (!allowCooling && isKeyInCooldown(name, entry.id)) || configured.apiKeySelectionRevision !== selection.revision
+      || !configured.requestPacing?.enabled || configured.requestPacing.keySelection !== "round-robin") return null;
+    row = { ...configured, apiKey: entry.key, _apiKeyAttempt: selection };
+  }
+  const current = routedProviderConfig(name, { ...row, _apiKeyAttempt: selection?.distributed ? selection : undefined });
   if (current.authMode === "oauth" || current.authMode === "forward") return null;
   if (current.authMode === "key" && !current.keyOptional && !current.apiKey?.trim()) return null;
   return current;
@@ -32,10 +40,23 @@ export function providerApiKeySelectionIsCurrent(
   name: string,
   routedProvider: OcxProviderConfig,
 ): boolean {
-  const current = currentKeyProvider(config, name);
+  return matchesConfiguredSelection(config, name, routedProvider, false);
+}
+
+/** An already sent failure can extend cooldown, but cannot authorize another dispatch. */
+export function providerApiKeySelectionOwnsFailure(
+  config: OcxConfig, name: string, routedProvider: OcxProviderConfig,
+): boolean {
+  return matchesConfiguredSelection(config, name, routedProvider, true);
+}
+
+function matchesConfiguredSelection(
+  config: OcxConfig, name: string, routedProvider: OcxProviderConfig, allowCooling: boolean,
+): boolean {
   const expected = routedProvider._apiKeyAttempt;
+  const current = currentKeyProvider(config, name, expected, allowCooling);
   return current !== null && expected !== undefined
-    && matchesSelection(config.providers[name]!, expected)
+    && (expected.distributed === true || matchesSelection(config.providers[name]!, expected))
     && current.apiKey === routedProvider.apiKey
     && current.authMode === routedProvider.authMode
     && current.baseUrl === routedProvider.baseUrl;
@@ -47,7 +68,11 @@ export function resolveCurrentProviderApiKeyTransport(
   name: string,
   routedProvider: OcxProviderConfig,
 ): OcxProviderConfig | null {
-  const current = currentKeyProvider(config, name);
+  // A permit acquired for one key cannot authorize a different key after a manual edit.
+  if (routedProvider.requestPacing?.enabled && routedProvider.requestPacing.keys
+    && routedProvider._apiKeyAttempt && config.providers[name]
+    && !routedProvider._apiKeyAttempt.distributed && !matchesSelection(config.providers[name]!, routedProvider._apiKeyAttempt)) return null;
+  const current = currentKeyProvider(config, name, routedProvider._apiKeyAttempt);
   if (!current) return null;
   const runtime = routedProvider as OcxProviderTransport;
   const headers = { ...current.headers };

package/src/providers/api-keys.ts

@@ -9,8 +9,11 @@
 import { createHash } from "node:crypto";
 import { saveConfigPreservingClaudeCode } from "../config";
 import type { OcxConfig, OcxProviderConfig } from "../types";
+import { GCP_CREDENTIAL_MARKER_PREFIX, isGcpCredentialMaterial, parseGcpCredentialJson } from "../lib/gcp-adc";
+import { invalidateResolvedProviderKeyCache, probeProviderKeychain, providerKeychainEntry } from "./api-key-resolve";
 import type { AccountQuotaFields } from "./quota-types";
 import { commitProviderApiKeySelection } from "./api-key-selection";
+import { cleanupRemovedGcpCredentials } from "./gcp-credential-cleanup";
 
 export interface ProviderApiKeyInfo extends AccountQuotaFields {
   id: string;
@@ -28,11 +31,159 @@ function isEnvReference(value: string): boolean {
 export function maskApiKey(value: string): string {
   // Env and keychain references carry no secret material; show them verbatim so an operator
   // can tell where the key lives.
-  if (isEnvReference(value) || value.startsWith("keychain:")) return value;
+  if (isEnvReference(value) || value.startsWith("keychain:") || value.startsWith(GCP_CREDENTIAL_MARKER_PREFIX)) return value;
   if (value.length <= 8) return "****";
   return `${value.slice(0, 4)}****${value.slice(-4)}`;
 }
 
+/**
+ * Split a pasted key value into candidate credentials. A plain API key is one row; a pasted GCP
+ * credential JSON (or several, comma/space-separated — the same convention as newline-separated
+ * API keys) is one row per JSON object. File paths are rejected with guidance rather
+ * than stored, because they are the most common paste mistake and silently break at runtime.
+ *
+ * Honors the parseGcpCredentialJson contract "a literal key that starts with `{` is never eaten":
+ * a brace-leading value that is NOT recognizable credential JSON falls back to a plain literal
+ * row (preserving the old single-line behavior), and only a multi-line or multi-object paste that
+ * fails credential validation rejects with guidance. The brace scanner tracks JSON string and
+ * escape state so a `}` inside a string field does not split the object early; any non-separator
+ * text between objects is rejected rather than silently discarded.
+ */
+export function splitCredentialPaste(value: string): Array<string | { credentialJson: string }> {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) return [];
+  // Fast path: a plain key (no JSON braces) — also covers env/keychain/gcp-sa references.
+  if (!trimmed.startsWith("{")) {
+    if (/(?:^|[\s,])\{/.test(trimmed)) {
+      throw new Error("Mixing credential JSON and literal API keys in one paste is not supported. Add them separately.");
+    }
+    if (isGcpCredentialMaterial(trimmed)) {
+      throw new Error("Invalid credential JSON: paste a GCP credential object without wrapping it in an array or string.");
+    }
+    if (/^(?:[A-Za-z]:[\\/]|[\\/]|~[\\/]|\.{1,2}[\\/])/.test(trimmed) || /^[^\s{}]+\.json$/i.test(trimmed)) {
+      throw new Error("This looks like a file path. Paste the full JSON body of the credential, not a file path.");
+    }
+    return [trimmed];
+  }
+  // Brace-leading scans: split adjacent JSON objects (comma/newline separated). The scanner
+  // tracks string/escape state so braces inside JSON string fields do not count, and records
+  // each object's [start, end] so the gap check below can reject non-separator junk between
+  // objects in one pass.
+  const spans: Array<{ start: number; end: number }> = [];
+  const objects: string[] = [];
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < trimmed.length; i++) {
+    const ch = trimmed[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; continue; }
+    if (ch === "{" && depth === 0) {
+      start = i;
+    }
+    if (ch === "{") depth += 1;
+    if (ch === "}") {
+      depth -= 1;
+      if (depth === 0 && start >= 0) {
+        objects.push(trimmed.slice(start, i + 1));
+        spans.push({ start, end: i });
+        start = -1;
+      }
+      if (depth < 0) throw new Error("Invalid credential JSON: unbalanced braces.");
+    }
+  }
+  if (depth !== 0 || start >= 0) throw new Error("Invalid credential JSON: the pasted text ends inside a JSON object.");
+  // Single unrecognized object on a single line = a plain key starting with `{` (never eaten) —
+  // BUT only when it is NOT real JSON: a parseable JSON object with an unrecognized `type`
+  // (e.g. `external_account`) is a credential the user believes is valid, and saving it as a
+  // plaintext literal key would send it to the wire. Distinguish by parse success, not shape.
+  const singleLine = !/[\r\n]/.test(trimmed);
+  const isRealJson = (() => {
+    try { JSON.parse(objects[0]!); return true; } catch { return false; }
+  })();
+  if (objects.length === 1 && singleLine && spans[0]!.end === trimmed.length - 1 && !parseGcpCredentialJson(objects[0]!) && !isRealJson && !isGcpCredentialMaterial(trimmed)) {
+    return [trimmed];
+  }
+  // Non-separator content BETWEEN and AFTER objects is rejected, not silently discarded:
+  // everything between/after one object's close must be a separator character.
+  for (let i = 0; i < spans.length; i++) {
+    if (i === 0) {
+      if (!/^[\s,]*$/.test(trimmed.slice(0, spans[0]!.start))) {
+        throw new Error("Unrecognized credential JSON: unexpected content before the first JSON object. Paste credential JSON(s) separated by commas or newlines, or a plain API key.");
+      }
+      continue;
+    }
+    const gap = trimmed.slice(spans[i - 1]!.end + 1, spans[i]!.start);
+    if (!/^[\s,]*$/.test(gap)) {
+      throw new Error("Unrecognized credential JSON: unexpected content between JSON objects. Paste credential JSON(s) separated by commas or newlines, or a plain API key.");
+    }
+  }
+  // Tail gap: content after the LAST object's close up to EOF must also be separators —
+  // trailing garbage (`<json> garbage`) is rejected rather than silently kept.
+  const tailGap = trimmed.slice(spans[spans.length - 1]!.end + 1);
+  if (!/^[\s,]*$/.test(tailGap)) {
+    throw new Error("Unrecognized credential JSON: unexpected content after the last JSON object. Mixing JSON and literal keys is not supported; add them separately.");
+  }
+  return objects.map((json) => {
+    if (!parseGcpCredentialJson(json)) {
+      throw new Error("Unrecognized credential JSON: expected a GCP Service Account or authorized_user JSON with a \"type\" field.");
+    }
+    return { credentialJson: json };
+  });
+}
+
+/** Generic provider writes do not own the keychain transaction. Refuse before persistence. */
+export function providerCredentialInputError(provider: { apiKey?: unknown; apiKeyPool?: unknown }): string | undefined {
+  const values = [provider.apiKey, ...(Array.isArray(provider.apiKeyPool)
+    ? provider.apiKeyPool.map(entry => entry && typeof entry === "object" ? entry.key : undefined) : [])];
+  try {
+    for (const value of values) {
+      if (typeof value !== "string") continue;
+      if (splitCredentialPaste(value).some(part => typeof part !== "string")) {
+        return "Credential JSON must be added through the provider API-key pool endpoint (/api/providers/keys), after creating the provider without a key. Nothing was saved.";
+      }
+    }
+  } catch (error) {
+    return error instanceof Error ? error.message : "Invalid credential paste";
+  }
+  return undefined;
+}
+
+/**
+ * Store a pasted GCP credential JSON in the OS keychain and return the `gcp-sa:` marker for it.
+ * Verified write (read-back check) mirrors storeProviderKeyInKeychain; on any failure the caller
+ * receives an error instead of half-stored state.
+ */
+function storeGcpCredentialJson(config: OcxConfig, name: string, credentialJson: string, existedBefore: boolean): string {
+  const probe = probeProviderKeychain();
+  if (!probe.available) throw new Error(`OS keychain unavailable: ${probe.reason}`);
+  const id = apiKeyPoolEntryId(credentialJson);
+  const account = gcpCredentialStoreAccount(name, id);
+  const entry = providerKeychainEntry(account);
+  entry.setPassword(credentialJson);
+  if (entry.getPassword() !== credentialJson) {
+    // Delete on mismatch ONLY when this write created the entry: a re-paste targets an account an
+    // existing `gcp-sa:` marker already names, and deleting it would destroy the live credential
+    // the config still references.
+    if (!existedBefore) {
+      try { entry.deletePassword(); } catch { /* best effort */ }
+    }
+    throw new Error(`keychain read-back mismatch for ${account}`);
+  }
+  return `${GCP_CREDENTIAL_MARKER_PREFIX}${account}`;
+}
+
+/** The credential-store account a marker names for `name`/`id` (write + cleanup share it). */
+function gcpCredentialStoreAccount(name: string, id: string): string {
+  return `${name}/${id}`;
+}
+
 /** Content-derived id: re-adding the same key upserts instead of duplicating. */
 export function apiKeyPoolEntryId(key: string): string {
   return createHash("sha256").update(key).digest("hex").slice(0, 8);
@@ -84,6 +235,60 @@ export function addProviderApiKey(config: OcxConfig, name: string, key: string,
   const provider = config.providers[name];
   if (!provider || !isKeyAuthProvider(provider)) return { error: "provider does not use API-key auth" };
   if (typeof key !== "string" || !key.trim()) return { error: "key is required" };
+  // GCP credential JSON never enters the literal-key path: it is diverted to the OS keychain and
+  // only the `gcp-sa:` marker is stored. splitCredentialPaste runs FIRST (before the CRLF
+  // rejection) because pretty-printed JSON contains line breaks, and it also catches the
+  // file-path paste mistake with its own guidance before anything is stored.
+  try {
+    const parts = splitCredentialPaste(key);
+    const first = parts[0];
+    const isJsonPaste = first !== undefined && typeof first !== "string";
+    if (!isJsonPaste) {
+      // Not a credential paste — fall through to the plain API-key path below. splitCredentialPaste
+      // has already thrown for file paths; a plain key lands here as a single literal row.
+    } else {
+      const stored: Array<{ id: string; marker: string }> = [];
+      const created: string[] = [];
+      try {
+        const committed = commitProviderApiKeySelection(config, name, fresh => {
+          // Hold the same mutation lock as cleanup from the verified OS write through marker
+          // persistence. Re-run idempotent writes on rebase so a removed payload is restored.
+          stored.length = 0;
+          for (const part of parts) {
+            const credentialJson = (part as { credentialJson: string }).credentialJson;
+            const id = apiKeyPoolEntryId(credentialJson);
+            const account = gcpCredentialStoreAccount(name, id);
+            const existedBefore = providerKeychainEntry(account).getPassword() !== null;
+            if (!existedBefore) created.push(`${GCP_CREDENTIAL_MARKER_PREFIX}${account}`);
+            stored.push({ id, marker: storeGcpCredentialJson(config, name, credentialJson, existedBefore) });
+          }
+          const pool = ensurePool(fresh);
+          for (const { id, marker } of stored) {
+            const existing = pool.find(e => e.id === id);
+            if (existing) {
+              existing.key = marker;
+              if (label?.trim()) existing.label = label.trim();
+            } else {
+              pool.push({ id, key: marker, ...(label?.trim() ? { label: label.trim() } : {}), addedAt: Date.now() });
+            }
+          }
+          fresh.apiKey = stored[0]!.marker;
+          return { changed: true, selectionChanged: true, value: stored[0]!.id };
+        });
+        if (committed.status === "committed") {
+          invalidateResolvedProviderKeyCache();
+          return { id: committed.value };
+        }
+        cleanupRemovedGcpCredentials(created);
+        return { error: "provider selection unavailable" };
+      } catch (error) {
+        cleanupRemovedGcpCredentials(created);
+        return { error: "credential storage failed; configuration was not changed" };
+      }
+    }
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "credential parse failed" };
+  }
   const trimmed = sanitizeApiKeyValue(key);
   if (!trimmed) return { error: "key must not include line breaks" };
   const id = apiKeyPoolEntryId(trimmed);
@@ -98,7 +303,8 @@ export function addProviderApiKey(config: OcxConfig, name: string, key: string,
     fresh.apiKey = trimmed;
     return { changed: true, selectionChanged: true, value: id };
   });
-  return committed.status === "committed" ? { id } : { error: "provider selection unavailable" };
+  if (committed.status !== "committed") return { error: "provider selection unavailable" };
+  return { id };
 }
 
 /** Switch the ACTIVE key (mirrors into `provider.apiKey`). Persists config. */
@@ -129,11 +335,13 @@ export function setProviderApiKeyLabel(config: OcxConfig, name: string, id: stri
 
 /** Remove one key; removing the active one promotes the first remaining. Persists config. */
 export function removeProviderApiKey(config: OcxConfig, name: string, id: string): boolean {
+  let removed: string | undefined;
   const committed = commitProviderApiKeySelection(config, name, provider => {
     const pool = provider.apiKeyPool?.length ? provider.apiKeyPool
       : provider.apiKey ? [{ id: apiKeyPoolEntryId(provider.apiKey), key: provider.apiKey }] : [];
     const entry = pool.find(e => e.id === id);
     if (!entry) return { changed: false, value: false };
+    removed = entry.key;
     provider.apiKeyPool = pool.filter(e => e.id !== id);
     if (provider.apiKey === entry.key) {
       const next = provider.apiKeyPool[0];
@@ -143,5 +351,8 @@ export function removeProviderApiKey(config: OcxConfig, name: string, id: string
     if (provider.apiKeyPool.length === 0) delete provider.apiKeyPool;
     return { changed: true, value: true };
   });
-  return committed.status === "committed" && committed.value;
+  if (committed.status !== "committed" || !committed.value) return false;
+  if (removed?.startsWith(GCP_CREDENTIAL_MARKER_PREFIX)) cleanupRemovedGcpCredentials([removed]);
+  invalidateResolvedProviderKeyCache();
+  return true;
 }

package/src/providers/claude-cli-usage.ts

@@ -0,0 +1,96 @@
+import { markAnthropicFamilyEnumeration } from "./quota/anthropic-family-headers";
+import { CLAUDE_CLI_USER_AGENT } from "./claude-cli-identity";
+import { asRecord, normalizePercent, normalizeResetAt, readQuotaJson, REQUEST_TIMEOUT_MS } from "./quota-wire";
+import type { ProviderQuota, ProviderQuotaWindow } from "./quota-types";
+const hasQuotaRows = (q: ProviderQuota) => q.fiveHourPercent !== undefined || q.weeklyPercent !== undefined || Boolean(q.customWindows?.length);
+
+function parseClaudeBucket(value: unknown): { percent?: number; resetAt?: number } | null {
+  const rec = asRecord(value);
+  if (!rec) return null;
+  const percent = normalizePercent(rec.utilization);
+  const resetAt = normalizeResetAt(rec.resets_at);
+  if (percent === undefined && resetAt === undefined) return null;
+  return { percent, resetAt };
+}
+
+const TERMINAL_CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/gu;
+
+function parseClaudeLimit(value: unknown): ProviderQuotaWindow | null {
+  const rec = asRecord(value);
+  if (!rec) return null;
+  const percent = normalizePercent(rec.percent);
+  if (percent === undefined) return null;
+  const scope = asRecord(rec.scope);
+  const model = asRecord(scope?.model);
+  const rawLabel = String(model?.display_name ?? "")
+    .replace(TERMINAL_CONTROL_CHARACTERS, "")
+    .trim();
+  if (!rawLabel) return null;
+  const lowerLabel = rawLabel.toLowerCase();
+  const label = lowerLabel.includes("fable") ? "Fable"
+    : lowerLabel.includes("opus") ? "Opus"
+      : lowerLabel.includes("sonnet") ? "Sonnet"
+        : null;
+  // An unrecognized display_name is never published as a quota label: stripping
+  // control characters still leaves attacker-chosen residue on the quota line.
+  if (label === null) return null;
+  const resetAt = normalizeResetAt(rec.resets_at);
+  // Model scope is proven structurally here, not guessed from text: the caller admits only
+  // `kind: "weekly_scoped"`, and a limit without a recognized `scope.model.display_name` has
+  // already returned null above. Routing keys on `scope`, never on `label`.
+  return { label, scope: "model", percent, ...(resetAt !== undefined ? { resetAt } : {}) };
+}
+
+export async function readAnthropicUsageQuota(accessToken: string): Promise<ProviderQuota | null> {
+  const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
+    headers: {
+      Accept: "application/json, text/plain, */*",
+      "Content-Type": "application/json",
+      "User-Agent": CLAUDE_CLI_USER_AGENT,
+      "anthropic-beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05",
+      Authorization: `Bearer ${accessToken}`,
+    },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!response.ok) return null;
+  const body = asRecord(await readQuotaJson(response));
+  if (!body) return null;
+  const fiveHour = parseClaudeBucket(body.five_hour);
+  const sevenDay = parseClaudeBucket(body.seven_day);
+  const fable = parseClaudeBucket(body.seven_day_fable);
+  const opus = parseClaudeBucket(body.seven_day_opus);
+  const sonnet = parseClaudeBucket(body.seven_day_sonnet);
+  const customWindows: ProviderQuotaWindow[] = [];
+  if (fable?.percent !== undefined) customWindows.push({ label: "Fable", scope: "model", percent: fable.percent, ...(fable.resetAt !== undefined ? { resetAt: fable.resetAt } : {}) });
+  if (opus?.percent !== undefined) customWindows.push({ label: "Opus", scope: "model", percent: opus.percent, ...(opus.resetAt !== undefined ? { resetAt: opus.resetAt } : {}) });
+  if (sonnet?.percent !== undefined) customWindows.push({ label: "Sonnet", scope: "model", percent: sonnet.percent, ...(sonnet.resetAt !== undefined ? { resetAt: sonnet.resetAt } : {}) });
+  const knownLabels = new Set(customWindows.map(window => window.label.toLowerCase()));
+  const limits = Array.isArray(body.limits) ? body.limits : [];
+  for (const rawLimit of limits) {
+    const limitRecord = asRecord(rawLimit);
+    // `session` and `weekly_all` mirror the canonical five-hour and weekly
+    // buckets above; only model-scoped weekly limits add a third window.
+    if (String(limitRecord?.kind ?? "").trim().toLowerCase() !== "weekly_scoped") continue;
+    const limit = parseClaudeLimit(rawLimit);
+    if (!limit || knownLabels.has(limit.label.toLowerCase())) continue;
+    knownLabels.add(limit.label.toLowerCase());
+    customWindows.push(limit);
+  }
+  const quota: ProviderQuota = {
+    // Claude's 5-hour window is a first-class rate limit, same as the Codex login 5h/weekly
+    // rows: report it in the canonical fields so the dashboard renders it with the standard
+    // "5-hour limit" label and ordering instead of as a generic extra window.
+    ...(fiveHour?.percent !== undefined ? { fiveHourPercent: fiveHour.percent } : {}),
+    ...(fiveHour?.resetAt !== undefined ? { fiveHourResetAt: fiveHour.resetAt } : {}),
+    ...(sevenDay?.percent !== undefined ? { weeklyPercent: sevenDay.percent } : {}),
+    ...(sevenDay?.resetAt !== undefined ? { weeklyResetAt: sevenDay.resetAt } : {}),
+    ...(customWindows.length > 0 ? { customWindows } : {}),
+    updatedAt: Date.now(),
+  };
+  // Empty / schema-changed payloads must not cache as "success with no bars".
+  return hasQuotaRows(quota) ? markAnthropicFamilyEnumeration(quota, Array.isArray(body.limits) && body.limits.every(raw => {
+    const kind = asRecord(raw)?.kind;
+    return kind === "session" || kind === "weekly_all" || kind === "weekly_scoped" && parseClaudeLimit(raw) !== null;
+  })) : null;
+}
+

package/src/providers/dsh-account-destination.ts

@@ -0,0 +1,31 @@
+/**
+ * The one destination a DeepSeek Harness account token may reach. Kept free of adapter imports so
+ * config validation can enforce the same pin the adapter applies at send time.
+ */
+export const DSH_ACCOUNT_DEFAULT_MESSAGES_URL = "https://api.deepseek.com/anthropic/v1/messages";
+
+export function resolveDshAccountMessagesUrl(baseUrl?: string): string {
+  if (!baseUrl || !baseUrl.trim()) {
+    return DSH_ACCOUNT_DEFAULT_MESSAGES_URL;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(baseUrl.trim());
+  } catch {
+    throw new Error(`Untrusted dsh-account destination: "${baseUrl}". DSH credentials may only be transmitted to https://api.deepseek.com`);
+  }
+
+  // Pin protocol and hostname strictly to official DeepSeek API endpoint
+  if (parsed.protocol !== "https:" || parsed.hostname.toLowerCase() !== "api.deepseek.com") {
+    throw new Error(
+      `Untrusted dsh-account destination host: "${parsed.hostname}". DSH credentials may only be transmitted to https://api.deepseek.com`,
+    );
+  }
+
+  const pathname = parsed.pathname.replace(/\/+$/, "");
+  if (!pathname || pathname === "" || pathname === "/anthropic" || pathname === "/anthropic/v1" || pathname === "/anthropic/v1/messages") {
+    return DSH_ACCOUNT_DEFAULT_MESSAGES_URL;
+  }
+
+  throw new Error(`Untrusted dsh-account destination path: "${parsed.pathname}". Expected /anthropic/v1/messages.`);
+}

package/src/providers/dsh-account-models.ts

@@ -0,0 +1,41 @@
+/**
+ * DeepSeek Harness Account (dsh-account) model definitions and capabilities.
+ *
+ * Provenance:
+ * DeepSeek Harness upstream v0.2.0-rc.2 (tag: dsh-v0.2.0-rc.2, commit: 639ed01539).
+ * Directly mirrors packages/llm/llm-deepseek/src/models.ts and model-info.ts.
+ */
+
+export const DSH_ACCOUNT_MODELS = [
+  "deepseek-flash",
+  "deepseek-v4-pro",
+] as const;
+
+export const DSH_ACCOUNT_DEFAULT_MODEL = "deepseek-flash";
+
+export const DSH_ACCOUNT_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "deepseek-flash": 1_000_000,
+  "deepseek-v4-pro": 1_000_000,
+};
+
+export const DSH_ACCOUNT_MODEL_INPUT_MODALITIES: Record<string, string[]> = {
+  "deepseek-flash": ["text", "image"],
+  "deepseek-v4-pro": ["text"],
+};
+
+export const DSH_ACCOUNT_MODEL_MAX_OUTPUT_TOKENS: Record<string, number> = {
+  "deepseek-flash": 64_000,
+  "deepseek-v4-pro": 64_000,
+};
+
+export const DSH_ACCOUNT_REASONING_EFFORTS = ["off", "low", "high", "max"] as const;
+
+export const DSH_ACCOUNT_MODEL_REASONING_EFFORTS: Record<string, string[]> = {
+  "deepseek-flash": [...DSH_ACCOUNT_REASONING_EFFORTS],
+  "deepseek-v4-pro": [...DSH_ACCOUNT_REASONING_EFFORTS],
+};
+
+export const DSH_ACCOUNT_MODEL_DISPLAY_NAMES: Record<string, string> = {
+  "deepseek-flash": "DeepSeek-V4.1-Flash",
+  "deepseek-v4-pro": "DeepSeek-V4-Pro",
+};