saros-proxy 0.10.2 → 1.0.0

package/dist/providers/opencode-go.js

@@ -5,6 +5,14 @@
  * Usage: GET /zen/go/v1/usage with Bearer = the key itself.
  */
 import { API_KEY_PREFIX, MIN_KEY_LENGTH, OPENCODE_GO_KEY_PREFIX, USAGE_PATH, } from '../constants.js';
+/**
+ * Identity the zen upstream expects. Cloudflare in front of opencode.ai
+ * rejects browser-like signatures with `403 error code: 1010` (verified live
+ * 2026-11-05: no UA, `Python-urllib/3.14` and `node` all 403; `cli` reaches
+ * the API). Forwarding the client's UA therefore killed every request made
+ * with an opencode-go key, so the provider overrides it.
+ */
+export const OPENCODE_GO_USER_AGENT = 'cli';
 /** Bare-name index of the live opencode-go catalog. */
 let catalogCache = null;
 /** Ensures the background refresh fires at most once per process. */
@@ -18,6 +26,7 @@ async function refreshCatalog(baseUrl, timeoutMs) {
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const res = await fetch(`${baseUrl.replace(/\/$/, '')}${USAGE_PATH.replace(/\/usage$/, '/models')}`, {
+            headers: { 'User-Agent': OPENCODE_GO_USER_AGENT },
             signal: controller.signal,
         });
         if (!res.ok)
@@ -47,10 +56,11 @@ async function refreshCatalog(baseUrl, timeoutMs) {
         clearTimeout(timer);
     }
 }
+/** Percent from one window; null when the window carries no numeric percent. */
 function parsePercent(window) {
     const percent = window?.percent;
     if (typeof percent !== 'number' || !Number.isFinite(percent))
-        return 0;
+        return null;
     return Math.min(100, Math.max(0, percent));
 }
 /** Parse opencode-go usage JSON (moved from usage-client.ts). */
@@ -68,11 +78,23 @@ export function parseOpencodeUsage(body) {
     const rolling = parsePercent(usage.rolling);
     const weekly = parsePercent(usage.weekly);
     const monthly = parsePercent(usage.monthly);
+    // A 200 whose `usage` object has no numeric window is not data: returning
+    // zeros would overwrite the previous percentage and hand the key max weight.
+    if (rolling === null && weekly === null && monthly === null)
+        return null;
+    const rollingPct = rolling ?? 0;
+    const weeklyPct = weekly ?? 0;
+    const monthlyPct = monthly ?? 0;
     return {
-        rollingPercent: rolling,
-        weeklyPercent: weekly,
-        monthlyPercent: monthly,
-        usedPercent: Math.max(rolling, weekly, monthly),
+        rollingPercent: rollingPct,
+        weeklyPercent: weeklyPct,
+        monthlyPercent: monthlyPct,
+        // The monthly window is the budget measure; any window at 100% pulls the
+        // key out of rotation before the upstream rejects it. A missing monthly
+        // stays null so the previous percentage is not overwritten with 0%.
+        usedPercent: monthly,
+        exhausted: rollingPct >= 100 || weeklyPct >= 100 || monthlyPct >= 100,
+        monthlyAvailable: monthly !== null,
         rollingResetsAt: typeof usage.rolling?.resetsAt === 'string' ? usage.rolling.resetsAt : undefined,
         weeklyResetsAt: typeof usage.weekly?.resetsAt === 'string' ? usage.weekly.resetsAt : undefined,
         monthlyResetsAt: typeof usage.monthly?.resetsAt === 'string' ? usage.monthly.resetsAt : undefined,
@@ -97,7 +119,7 @@ export const opencodeGoProvider = {
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const res = await fetch(`${this.baseUrl}${USAGE_PATH}`, {
-                headers: { Authorization: `Bearer ${key}` },
+                headers: { Authorization: `Bearer ${key}`, 'User-Agent': OPENCODE_GO_USER_AGENT },
                 signal: controller.signal,
             });
             if (res.ok) {
@@ -126,6 +148,10 @@ export const opencodeGoProvider = {
     usagePath() {
         return USAGE_PATH;
     },
+    /** Cloudflare rejects forwarded browser UAs; always identify as the CLI. */
+    extraUpstreamHeaders() {
+        return { 'User-Agent': OPENCODE_GO_USER_AGENT };
+    },
     parseUsageResponse(body) {
         return parseOpencodeUsage(body);
     },
@@ -174,7 +200,9 @@ export const opencodeGoProvider = {
             return null;
         // Re-fetch and return the raw list for catalog consumers (harness sync).
         try {
-            const res = await fetch(`${this.baseUrl.replace(/\/$/, '')}${USAGE_PATH.replace(/\/usage$/, '/models')}`);
+            const res = await fetch(`${this.baseUrl.replace(/\/$/, '')}${USAGE_PATH.replace(/\/usage$/, '/models')}`, {
+                headers: { 'User-Agent': OPENCODE_GO_USER_AGENT },
+            });
             if (!res.ok)
                 return null;
             const body = (await res.json());

package/dist/providers/opencode-go.js.map

@@ -1 +1 @@
-{"version":3,"file":"opencode-go.js","sourceRoot":"","sources":["../../src/providers/opencode-go.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"opencode-go.js","sourceRoot":"","sources":["../../src/providers/opencode-go.ts"],"names":[],"mappings":"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"}

package/dist/providers/types.d.ts

@@ -123,9 +123,17 @@ export interface KeyProvider {
  * Used for request routing in mixed-provider key pools.
  */
 export type ModelAffinity = 'yes' | 'no' | 'maybe';
-/** Shared usage shape used across providers (mirrors usage-client KeyUsage). */
+/**
+ * Shared usage shape used across providers (mirrors usage-client KeyUsage).
+ * `usedPercent` is the monthly percentage of the key's own provider budget;
+ * `exhausted` means any window is at 100% and the key must not serve traffic.
+ */
 export interface KeyUsage {
-    usedPercent: number;
+    /** Monthly used percent, or null when it cannot be derived. */
+    usedPercent: number | null;
+    exhausted: boolean;
+    /** False when the payload carries no monthly percentage (CLI shows n/a). */
+    monthlyAvailable: boolean;
     rollingPercent: number;
     weeklyPercent: number;
     monthlyPercent: number;

package/dist/proxy-logic.d.ts

@@ -18,8 +18,14 @@ interface ApiKey {
     consecutiveFailures: number;
     lastUsed: number | null;
     disabledAt: number | null;
-    /** Worst-window used percent (0-100) reported by the upstream usage API. */
+    /** Monthly used percent (0-100) reported by the upstream usage API. */
     usagePercent: number | null;
+    /**
+     * True when any quota window (5h, weekly or monthly) is at 100%. Weight 0
+     * in rotation: a month with room does not help when the upstream already
+     * rejects the key for a spent shorter window.
+     */
+    exhausted: boolean;
     /**
      * False when the upstream rejected this key for lack of plan
      * (403 EntitlementError / upgrade_required): the account cannot use the
@@ -30,6 +36,58 @@ interface ApiKey {
     entitled: boolean;
     /** Smooth weighted round-robin state (nginx-style). */
     currentWeight: number;
+    /** Why the key last left rotation — reported by /health and the 503 body. */
+    lastError: KeyFailure | null;
+    /**
+     * True when the key was retired in config (`enabled: false`). Separate from
+     * `enabled` so a success (or a cooldown) can never put it back in rotation.
+     */
+    disabledByConfig: boolean;
+    /** True when the credential arrived as an `enc:` envelope in config. */
+    encrypted: boolean;
+}
+/** Why a key is out of rotation, derived from the upstream verdict. */
+export type KeyFailureReason = 'auth' | 'quota' | 'rate_limit' | 'server';
+export interface KeyFailure {
+    /** Upstream HTTP status, when the failure came from a response. */
+    status: number | null;
+    reason: KeyFailureReason;
+    /** Epoch ms. */
+    at: number;
+    /** Short upstream message (≤200 chars). Never contains the credential. */
+    detail: string | null;
+}
+/** Upstream context for a failure, passed by the caller that saw it. */
+export interface KeyFailureInfo {
+    status?: number;
+    body?: string;
+}
+/** Public projection of one key's state — never contains the credential. */
+export interface KeyHealthReport {
+    label: string;
+    provider: string;
+    enabled: boolean;
+    entitled: boolean;
+    /** True when the key was retired in config (`enabled: false`). */
+    disabledByConfig: boolean;
+    /** True when the credential is stored as an `enc:` envelope, never its value. */
+    encrypted: boolean;
+    consecutiveFailures: number;
+    disabledAt: string | null;
+    retryAfterMs: number | null;
+    lastError: {
+        status: number | null;
+        reason: KeyFailureReason;
+        at: string;
+    } | null;
+    /** Monthly used percent (0-100) of this key's provider budget. */
+    usagePercent: number | null;
+}
+/** Fields needed to answer "can this key be used right now?". */
+export interface KeyAvailability {
+    enabled: boolean;
+    consecutiveFailures: number;
+    disabledAt: number | null;
 }
 /** Read-only projection returned to callers — cannot mutate internal state. */
 export interface KeySnapshot {
@@ -81,15 +139,33 @@ export declare function createProxyState(keys: Array<{
     label: string;
     key: string;
     provider?: string;
+    enabled?: boolean;
+    encrypted?: boolean;
 }>, options?: {
     circuitBreakerThreshold?: number;
     circuitBreakerCooldownMs?: number;
 }): ProxyState;
+/** Usage snapshot applied to one key. */
+export interface KeyUsageMetrics {
+    /**
+     * Monthly used percent, 0-100, of the key's own provider budget; null when
+     * the payload had no derivable monthly value and the previous one must stay.
+     */
+    usedPercent: number | null;
+    /** True when any quota window is at 100%. */
+    exhausted: boolean;
+}
 /**
- * Update per-key usage data (worst-window used percent, 0-100).
- * Keys absent from the map keep their previous value.
+ * Update per-key usage data. `usedPercent` is the **monthly** percentage of
+ * the key's **own provider budget**, not absolute capacity: a mixed pool
+ * feeds every provider's number into `pickWeighted`, where only this
+ * normalized percent is comparable (opencode-go publishes percentages alone —
+ * no counts or caps). `exhausted` means a shorter window already hit its cap,
+ * so the key weighs 0 even when the month has room. A null `usedPercent` means
+ * the payload had no derivable monthly value and the previous percentage is
+ * kept. Keys absent from the map keep their previous values.
  */
-export declare function updateKeyUsage(state: ProxyState, usage: Map<string, number>): void;
+export declare function updateKeyUsage(state: ProxyState, usage: Map<string, KeyUsageMetrics>): void;
 /**
  * Mark a key as (not) entitled to use its provider. Unentitled keys are
  * skipped by selection without touching the circuit breaker; the usage
@@ -121,16 +197,34 @@ export declare function failoverRequest(state: ProxyState, requestId: string): K
  */
 export declare function completeRequest(state: ProxyState, requestId: string, success: boolean): void;
 /**
- * Mark a key as failed according to the error type (C2).
+ * Mark a key as failed according to the error type (C2) and record why.
  * - KeyFault / ServerFault: penalise the key (KeyFault disables immediately)
  * - RequestFault / NetworkFault: no penalisation (bad request, or network
  *   trouble that is not the key's fault)
  */
-export declare function markKeyFailed(state: ProxyState, keyLabel: string, errorType: ErrorType): void;
+export declare function markKeyFailed(state: ProxyState, keyLabel: string, errorType: ErrorType, info?: KeyFailureInfo): void;
 /**
- * Mark a key as succeeded — resets consecutive failures.
+ * Mark a key as succeeded — resets consecutive failures and clears any
+ * cooldown. `enabled` must come back too: a success can arrive after the key
+ * was disabled (tier 2 shares a key between concurrent requests, and a stream
+ * that fails after completeRequest(…, true) marks failure late). Leaving
+ * `enabled=false` with `disabledAt=null` made the key unselectable forever,
+ * because isKeyAvailable only revives keys that still carry a disabledAt.
  */
 export declare function markKeySucceeded(state: ProxyState, keyLabel: string): void;
+/**
+ * Milliseconds until the key becomes selectable again, or null when nothing
+ * will bring it back (healthy, retired in config, or no cooldown recorded).
+ * A key past its cooldown but not yet lazily revived reports 0 — it is
+ * selectable on the next request, which is not "already selectable" here.
+ * Pure: unlike isKeyAvailable this never revives the key.
+ */
+export declare function keyRetryAfterMs(state: Pick<ProxyState, 'circuitBreakerThreshold' | 'circuitBreakerCooldownMs'>, key: KeyAvailability, now?: number): number | null;
+/**
+ * Per-key state for /health. Labels are already public (X-Proxy-Key-Label);
+ * the credential and the upstream message are not part of this projection.
+ */
+export declare function describeKeys(state: ProxyState, now?: number): KeyHealthReport[];
 /**
  * Classify an HTTP error status + optional response body into an ErrorType.
  *