saros-proxy 0.7.3 → 0.9.0

package/dist/providers/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * types.ts — Provider abstraction for multi-provider API key support.
+ *
+ * A KeyProvider encapsulates everything saros needs to know about one
+ * upstream API platform: how to recognize its keys structurally, how to
+ * verify them with a cheap network ping (smoke test), where its usage
+ * endpoint lives, and how to parse its usage response shape.
+ */
+export type ProviderId = 'opencode-go' | 'commandcode';
+/** Result of a provider smoke test (key verification ping). */
+export interface SmokeResult {
+    /** Provider that ran the test. */
+    provider: ProviderId;
+    /**
+     * - 'valid'      — key authenticated successfully (HTTP 200)
+     * - 'invalid'    — upstream definitively rejected the key (401/403 auth)
+     * - 'error'      — network/timeout/5xx; inconclusive, may retry
+     */
+    status: 'valid' | 'invalid' | 'error';
+    /** HTTP status code when available. */
+    httpStatus?: number;
+    /** Human-readable detail (safe to show in the TUI — never the key). */
+    detail?: string;
+    /** Provider-specific extras (e.g. commandcode planId). */
+    meta?: Record<string, string>;
+}
+/** Structural prefix check result. */
+export type PrefixMatch = 'yes' | 'no' | 'maybe';
+/**
+ * Common interface every key provider implements.
+ * All network methods must never log or echo the key itself.
+ */
+export interface KeyProvider {
+    readonly id: ProviderId;
+    /** Human-readable name for TUI output. */
+    readonly displayName: string;
+    /** Upstream base URL (HTTPS enforced by callers). */
+    readonly baseUrl: string;
+    /**
+     * Canonical chat route prefix saros accepts from clients. Clients always
+     * speak opencode-go shapes (/zen/go/v1/...); providers without a matching
+     * upstream path get their requests remapped (see remapChatPath).
+     */
+    readonly chatBasePath: string;
+    /**
+     * Cheap structural check. 'yes' = prefix uniquely identifies this
+     * provider, 'maybe' = prefix shared with another provider (empirical
+     * smoke test required), 'no' = definitely not this provider's format.
+     */
+    quickMatch(key: string): PrefixMatch;
+    /**
+     * Verify a key with a cheap authenticated GET.
+     * Implementations must use a read-only endpoint (no token spend).
+     */
+    smokeTest(key: string, timeoutMs?: number): Promise<SmokeResult>;
+    /**
+     * Usage/quota endpoint path for this provider (empty string when the
+     * provider has no per-key usage API saros can query).
+     */
+    usagePath(): string;
+    /**
+     * Parse a usage response body into the shared KeyUsage shape.
+     * Returns null when the body doesn't match this provider's contract.
+     */
+    parseUsageResponse(body: string): KeyUsage | null;
+    /**
+     * Extra headers this provider requires on upstream requests
+     * (e.g. CommandCode CLI-identity headers). Called per request;
+     * must not include Authorization (added by the proxy).
+     */
+    extraUpstreamHeaders?(): Record<string, string>;
+    /**
+     * Fetch this provider's live model catalog (OpenAI list shape).
+     * Returns null when unavailable — callers fall back to bundled data.
+     * Implementations must not require a valid key (catalogs are public).
+     */
+    fetchCatalog?(timeoutMs?: number): Promise<Array<Record<string, unknown>> | null>;
+    /**
+     * Structural model-id affinity check. Consulted BEFORE dispatching so a
+     * request naming a commandcode-only model (e.g. 'claude-*') is not sent
+     * with an opencode-go key (and vice versa).
+     */
+    modelAffinity(modelId: string): ModelAffinity;
+    /**
+     * Affinity by bare model name (without vendor prefix), e.g. 'ds-v4-flash'
+     * for 'deepseek/ds-v4-flash'. Providers whose catalogs use vendor-prefixed
+     * ids match the bare name against their catalog's last path segment;
+     * others return the same verdict as modelAffinity(id).
+     * Enables cross-provider aliasing so shared models rotate across all keys.
+     */
+    modelAffinityByName?(bareName: string): ModelAffinity;
+    /**
+     * Map a bare model name to this provider's native catalog id
+     * ('deepseek-v4-flash' → 'deepseek/deepseek-v4-flash'), or null when the
+     * catalog doesn't serve it. Backed by the provider's live catalog;
+     * providers with 1:1 naming may return the input unchanged.
+     */
+    resolveNativeId?(bareName: string): string | null;
+}
+/**
+ * Model → provider affinity.
+ *
+ * 'yes' = the model id is (almost certainly) served by this provider,
+ * 'no' = definitely not, 'maybe' = cannot be decided structurally — the
+ * proxy tries matching providers first and falls back to any available key.
+ * 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). */
+export interface KeyUsage {
+    usedPercent: number;
+    rollingPercent: number;
+    weeklyPercent: number;
+    monthlyPercent: number;
+    rollingResetsAt?: string;
+    weeklyResetsAt?: string;
+    monthlyResetsAt?: string;
+}

package/dist/providers/types.js

@@ -0,0 +1,10 @@
+/**
+ * types.ts — Provider abstraction for multi-provider API key support.
+ *
+ * A KeyProvider encapsulates everything saros needs to know about one
+ * upstream API platform: how to recognize its keys structurally, how to
+ * verify them with a cheap network ping (smoke test), where its usage
+ * endpoint lives, and how to parse its usage response shape.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/proxy-logic.d.ts

@@ -12,21 +12,37 @@
 interface ApiKey {
     label: string;
     key: string;
+    /** Provider id ('opencode-go' | 'commandcode' | future extensions). */
+    provider: string;
     enabled: boolean;
     consecutiveFailures: number;
     lastUsed: number | null;
     disabledAt: number | null;
+    /** Worst-window used percent (0-100) reported by the upstream usage API. */
+    usagePercent: number | null;
+    /** Smooth weighted round-robin state (nginx-style). */
+    currentWeight: number;
 }
 /** Read-only projection returned to callers — cannot mutate internal state. */
 export interface KeySnapshot {
     label: string;
     key: string;
+    /** Provider this key belongs to (set at state creation from config). */
+    provider: string;
 }
 /** Tracks a single HTTP request's key usage through its lifecycle. */
 interface RequestContext {
     requestId: string;
     triedKeys: string[];
     currentKey: KeySnapshot | null;
+    /**
+     * Provider filter fixed at selection time (model affinity / @suffix pin).
+     * Failover re-applies it so a pinned commandcode request never fails over
+     * to an opencode-go key that cannot serve the (already rewritten) model id.
+     */
+    providerFilter?: (provider: string) => boolean;
+    /** True when the model is provider-pinned (@suffix) — tier-3 cross-provider fallback disabled. */
+    pinned?: boolean;
 }
 export interface ProxyState {
     keys: ApiKey[];
@@ -34,51 +50,56 @@ export interface ProxyState {
     circuitBreakerThreshold: number;
     circuitBreakerCooldownMs: number;
     activeRequests: Map<string, RequestContext>;
-}
-/**
- * Usage data for a single account, scraped from the OpenCode-Go workspace.
- * All values are percentages (0-100). null means no data for that window.
- */
-export interface UsageInfo {
-    rolling: number | null;
-    weekly: number | null;
-    monthly: number | null;
-}
-/**
- * Optional parameters for usage-gated key selection.
- */
-export interface KeySelectionOptions {
-    usageMap?: Map<string, UsageInfo>;
-    usageThreshold?: number;
+    /**
+     * Optional model→provider affinity resolver: (providerId, modelId) →
+     * 'yes' | 'no' | 'maybe'. Wired from the provider registry at app setup;
+     * absence disables affinity routing (single-provider behavior).
+     */
+    affinityResolver?: (provider: string, modelId: string) => 'yes' | 'no' | 'maybe';
 }
 /**
  * Error classification for HTTP responses.
- * - KeyFault: the API key should be penalised (invalid, revoked, rate-limited, server fault)
+ * - KeyFault: the API key should be penalised (invalid, revoked, quota exhausted)
  * - RequestFault: the request itself is bad — no key penalisation
  * - ServerFault: transient server issue — key penalised (normal circuit-breaker)
+ * - NetworkFault: timeout / connection error — no key penalisation. The
+ *   upstream base URL is shared by every key, so network-level failures are
+ *   not a per-key fault; disabling keys for them caused total-blackout
+ *   lockups ("all keys unavailable") when the upstream hung. Failover still
+ *   tries the next key for this request.
  */
-export type ErrorType = 'KeyFault' | 'RequestFault' | 'ServerFault';
+export type ErrorType = 'KeyFault' | 'RequestFault' | 'ServerFault' | 'NetworkFault';
 export declare function createProxyState(keys: Array<{
     label: string;
     key: string;
+    provider?: string;
 }>, options?: {
     circuitBreakerThreshold?: number;
     circuitBreakerCooldownMs?: number;
 }): ProxyState;
+/**
+ * Update per-key usage data (worst-window used percent, 0-100).
+ * Keys absent from the map keep their previous value.
+ */
+export declare function updateKeyUsage(state: ProxyState, usage: Map<string, number>): void;
 /**
  * Obtain a key for a new (or in-flight) request.
  * Creates a RequestContext if one does not already exist for this requestId.
  * Skips keys that have already been tried for this request AND keys booked
  * by any other active request.
+ *
+ * When a modelId is supplied and some providers claim it (modelAffinity
+ * 'yes'), keys of other providers are only used after the preferred pool is
+ * exhausted (including its booked-share tier).
  */
-export declare function selectKeyForRequest(state: ProxyState, requestId: string, options?: KeySelectionOptions): KeySnapshot | null;
+export declare function selectKeyForRequest(state: ProxyState, requestId: string, modelId?: string): KeySnapshot | null;
 /**
  * Failover: record the current key of this request as failed and pick the next
  * available key.  The caller should also call markKeyFailed() with the
  * appropriate ErrorType; this function only manages the request-context
  * tracking (adds the current key to triedKeys).
  */
-export declare function failoverRequest(state: ProxyState, requestId: string, options?: KeySelectionOptions): KeySnapshot | null;
+export declare function failoverRequest(state: ProxyState, requestId: string): KeySnapshot | null;
 /**
  * Complete a request: if successful, mark the current key as succeeded;
  * always clean up the request context.
@@ -87,7 +108,8 @@ export declare function completeRequest(state: ProxyState, requestId: string, su
 /**
  * Mark a key as failed according to the error type (C2).
  * - KeyFault / ServerFault: penalise the key (KeyFault disables immediately)
- * - RequestFault: no penalisation (bad request, not bad key)
+ * - 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;
 /**
@@ -101,7 +123,9 @@ export declare function markKeySucceeded(state: ProxyState, keyLabel: string): v
  *  401               → KeyFault  (invalid/revoked key — immediate disable)
  *  429               → ServerFault (transient rate-limit — incremental circuit breaker)
  *  500 / 502 / 503   → KeyFault if body mentions quota/balance, else ServerFault
- *  400 / 404 / 422   → RequestFault (bad request — don't penalise the key)
+ *  400 / 403 / 404 / 422 → RequestFault (bad request or permission denial —
+ *                      don't penalise the key; 403 MODEL_NOT_IN_PLAN is a plan
+ *                      restriction, found live on commandcode)
  *  everything else   → ServerFault
  */
 export declare function classifyHttpError(status: number, _body?: string): ErrorType;

package/dist/proxy-logic.js

@@ -18,10 +18,13 @@ export function createProxyState(keys, options) {
         keys: keys.map((k) => ({
             label: k.label,
             key: k.key,
+            provider: k.provider ?? 'opencode-go',
             enabled: true,
             consecutiveFailures: 0,
             lastUsed: null,
             disabledAt: null,
+            usagePercent: null,
+            currentWeight: 0,
         })),
         currentIndex: 0,
         circuitBreakerThreshold: options?.circuitBreakerThreshold ?? 3,
@@ -37,7 +40,7 @@ export function createProxyState(keys, options) {
  * (Keeps mutation paths through markKeyFailed / markKeySucceeded.)
  */
 function toSnapshot(key) {
-    return { label: key.label, key: key.key };
+    return { label: key.label, key: key.key, provider: key.provider };
 }
 /**
  * Internal: check whether a key is available (enabled & under threshold).
@@ -60,86 +63,6 @@ function isKeyAvailable(state, key) {
     }
     return false;
 }
-/**
- * Check if a key is available based on usage data.
- * A key is unavailable if ANY of its usage windows >= threshold.
- *
- * @param usage - The usage data for this key's account (null = no data = available)
- * @param threshold - The usage threshold (1-100)
- * @returns true if the key is available (usage below threshold or no data)
- */
-function isKeyAvailableByUsage(usage, threshold) {
-    if (usage === null)
-        return true; // no data = don't block
-    return ((usage.rolling === null || usage.rolling < threshold) &&
-        (usage.weekly === null || usage.weekly < threshold) &&
-        (usage.monthly === null || usage.monthly < threshold));
-}
-/**
- * Internal: when all circuit-breaker-available keys are over the usage
- * threshold, fall back to the key with the lowest maximum usage across
- * all windows. If a key has no usage data, it is preferred immediately.
- */
-function findFallbackKey(state, usageMap) {
-    let best = null;
-    let bestMaxUsage = Infinity;
-    for (const key of state.keys) {
-        if (!isKeyAvailable(state, key))
-            continue;
-        const usage = usageMap.get(key.label);
-        if (!usage) {
-            // No usage data = best possible – take it immediately
-            key.lastUsed = Date.now();
-            return toSnapshot(key);
-        }
-        const maxUsage = Math.max(usage.rolling ?? 0, usage.weekly ?? 0, usage.monthly ?? 0);
-        if (maxUsage < bestMaxUsage) {
-            bestMaxUsage = maxUsage;
-            best = key;
-        }
-    }
-    if (best) {
-        best.lastUsed = Date.now();
-        return toSnapshot(best);
-    }
-    return null;
-}
-/**
- * Internal: apply usage-gating to an exclusion set, then attempt to find
- * the next available key.  Falls back to findFallbackKey if all
- * circuit-breaker-available keys are over the usage threshold.
- *
- * Shared by selectKeyForRequest and failoverRequest — extracts the ~90%
- * identical usage-gating logic that was previously copy-pasted (PR-5).
- *
- * @param excludeLabels  Mutable set; usage-over-threshold labels are added.
- * @returns A key snapshot, or null if no key is available.
- */
-function selectKeyWithUsageFallback(state, excludeLabels, options) {
-    // Exclude keys whose account usage exceeds the threshold
-    if (options?.usageMap && options?.usageThreshold !== undefined) {
-        const threshold = options.usageThreshold;
-        for (const key of state.keys) {
-            const usage = options.usageMap.get(key.label) ?? null;
-            if (!isKeyAvailableByUsage(usage, threshold)) {
-                excludeLabels.add(key.label);
-            }
-        }
-    }
-    let snapshot = findNextKey(state, excludeLabels);
-    // Fallback: all circuit-breaker-available keys are over threshold
-    if (!snapshot && options?.usageMap) {
-        const fallback = findFallbackKey(state, options.usageMap);
-        if (fallback) {
-            const idx = state.keys.findIndex((k) => k.label === fallback.label);
-            if (idx !== -1) {
-                state.currentIndex = (idx + 1) % state.keys.length;
-            }
-            snapshot = fallback;
-        }
-    }
-    return snapshot;
-}
 /**
  * Internal: return the set of key labels that are currently *in use* by
  * active requests (C4 double-booking avoidance).
@@ -163,36 +86,128 @@ function buildBookedLabels(state) {
  * Internal: find the next available key, skipping:
  *  - disabled / under-cooldown keys
  *  - labels in `excludeLabels`
- * Advances the round-robin index and returns a read-only snapshot.
+ *
+ * Selection strategy (smooth weighted round-robin, nginx-style):
+ *  - When usage data is known for the candidates, keys with more remaining
+ *    quota are proportionally preferred. E.g. key X at 30% used and key Y at
+ *    70% used receive ~70%/30% of requests — exact proportions over a cycle,
+ *    not random sampling.
+ *  - Without usage data (or when every candidate is exhausted), falls back to
+ *    plain round-robin ordering.
  */
-function findNextKey(state, excludeLabels) {
+function findNextKey(state, excludeLabels, providerFilter) {
     const n = state.keys.length;
     if (n === 0)
         return null;
+    const candidates = [];
     for (let i = 0; i < n; i++) {
-        const idx = (state.currentIndex + i) % n;
-        const key = state.keys[idx];
+        const key = state.keys[(state.currentIndex + i) % n];
         if (excludeLabels.has(key.label))
             continue;
+        if (providerFilter && !providerFilter(key.provider))
+            continue;
         if (!isKeyAvailable(state, key))
             continue;
-        // Advance past the selected key
-        state.currentIndex = (idx + 1) % n;
-        key.lastUsed = Date.now();
-        return toSnapshot(key);
+        candidates.push(key);
+    }
+    if (candidates.length === 0)
+        return null;
+    const picked = pickWeighted(state, candidates);
+    state.currentIndex = (state.keys.indexOf(picked) + 1) % n;
+    picked.lastUsed = Date.now();
+    return toSnapshot(picked);
+}
+/**
+ * Internal: smooth weighted round-robin over the candidates.
+ * Falls back to the first candidate (round-robin order) when usage data is
+ * missing for any candidate or when no candidate has remaining capacity.
+ */
+function pickWeighted(state, candidates) {
+    const known = candidates.filter((k) => k.usagePercent !== null);
+    if (known.length === 0)
+        return candidates[0];
+    let weights = candidates.map((k) => Math.max(0, 100 - (k.usagePercent ?? 0)));
+    // Keys missing usage data get the median of the known weights — neutral,
+    // so one flaky key no longer disables weighting for the whole pool.
+    const sorted = known.map((k) => 100 - (k.usagePercent ?? 0)).sort((a, b) => a - b);
+    const median = sorted[Math.floor(sorted.length / 2)] ?? 0;
+    weights = weights.map((w, i) => (candidates[i].usagePercent === null ? median : w));
+    const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+    if (totalWeight === 0)
+        return candidates[0];
+    let best = candidates[0];
+    let bestWeight = -Infinity;
+    for (let i = 0; i < candidates.length; i++) {
+        candidates[i].currentWeight += weights[i];
+        if (candidates[i].currentWeight > bestWeight) {
+            bestWeight = candidates[i].currentWeight;
+            best = candidates[i];
+        }
+    }
+    best.currentWeight -= totalWeight;
+    return best;
+}
+/**
+ * Update per-key usage data (worst-window used percent, 0-100).
+ * Keys absent from the map keep their previous value.
+ */
+export function updateKeyUsage(state, usage) {
+    for (const key of state.keys) {
+        const percent = usage.get(key.label);
+        if (typeof percent === 'number')
+            key.usagePercent = percent;
     }
-    return null;
 }
 // ---------------------------------------------------------------------------
 // Request-Scoped Key Tracking (C4)
 // ---------------------------------------------------------------------------
+/** Parse a trailing '@provider' suffix from a model id ('x@cc' → 'cc'). */
+function parseModelSuffix(modelId) {
+    if (!modelId)
+        return null;
+    const at = modelId.lastIndexOf('@');
+    if (at <= 0 || at === modelId.length - 1)
+        return null;
+    return modelId.slice(at + 1);
+}
+/**
+ * Resolve the provider-preference predicate for a request.
+ *
+ * Rule: exclude providers whose verdict is definitively 'no' for the model
+ * (e.g. claude-* on opencode-go). Everything else — 'yes' AND 'maybe' —
+ * serves the request, so genuinely shared models rotate across ALL their
+ * keys regardless of which catalog loaded first. When no provider says 'no'
+ * the filter is undefined (legacy any-key behavior).
+ */
+function makeProviderFilter(state, modelId) {
+    if (!modelId)
+        return undefined;
+    const resolver = state.affinityResolver;
+    if (!resolver)
+        return undefined;
+    const excluded = new Set();
+    for (const key of state.keys) {
+        if (excluded.has(key.provider))
+            continue;
+        if (resolver(key.provider, modelId) === 'no') {
+            excluded.add(key.provider);
+        }
+    }
+    if (excluded.size === 0)
+        return undefined;
+    return (provider) => !excluded.has(provider);
+}
 /**
  * Obtain a key for a new (or in-flight) request.
  * Creates a RequestContext if one does not already exist for this requestId.
  * Skips keys that have already been tried for this request AND keys booked
  * by any other active request.
+ *
+ * When a modelId is supplied and some providers claim it (modelAffinity
+ * 'yes'), keys of other providers are only used after the preferred pool is
+ * exhausted (including its booked-share tier).
  */
-export function selectKeyForRequest(state, requestId, options) {
+export function selectKeyForRequest(state, requestId, modelId) {
     // If context already exists, return the already-assigned current key
     const existing = state.activeRequests.get(requestId);
     if (existing) {
@@ -201,18 +216,27 @@ export function selectKeyForRequest(state, requestId, options) {
     // Create new context and pick a fresh key
     const ctx = { requestId, triedKeys: [], currentKey: null };
     state.activeRequests.set(requestId, ctx);
+    const providerFilter = makeProviderFilter(state, modelId);
+    ctx.providerFilter = providerFilter;
+    ctx.pinned = Boolean(parseModelSuffix(modelId));
     // Tier 1: prefer a key not booked by another active request (spread load)
     const excludeLabels = new Set(ctx.triedKeys);
     const booked = buildBookedLabels(state);
     for (const label of booked) {
         excludeLabels.add(label);
     }
-    let snapshot = selectKeyWithUsageFallback(state, excludeLabels, options);
-    // Tier 2: all healthy keys are booked — share one via round-robin.
-    // Better to share a key than return 503 when concurrent requests
-    // outnumber the key pool.
+    let snapshot = findNextKey(state, excludeLabels, providerFilter);
+    // Tier 2: all healthy preferred keys are booked — share one via
+    // round-robin. Better to share a key than return 503 when concurrent
+    // requests outnumber the key pool.
     if (!snapshot) {
-        snapshot = selectKeyWithUsageFallback(state, new Set(ctx.triedKeys), options);
+        snapshot = findNextKey(state, new Set(ctx.triedKeys), providerFilter);
+    }
+    // Tier 3: preferred providers exhausted → fall back to any provider
+    // (pinned requests exempt: a @provider suffix or messages-only model
+    // cannot be served by other providers at all).
+    if (!snapshot && providerFilter && !ctx.pinned) {
+        snapshot = findNextKey(state, new Set(ctx.triedKeys));
     }
     ctx.currentKey = snapshot;
     return snapshot;
@@ -223,7 +247,7 @@ export function selectKeyForRequest(state, requestId, options) {
  * appropriate ErrorType; this function only manages the request-context
  * tracking (adds the current key to triedKeys).
  */
-export function failoverRequest(state, requestId, options) {
+export function failoverRequest(state, requestId) {
     const ctx = state.activeRequests.get(requestId);
     if (!ctx)
         return null;
@@ -231,18 +255,25 @@ export function failoverRequest(state, requestId, options) {
     if (ctx.currentKey) {
         ctx.triedKeys.push(ctx.currentKey.label);
     }
-    // Tier 1: prefer a key not tried AND not booked by another request
+    // The provider preference was fixed when the request context was created;
+    // failover re-applies it so cross-provider failover can't pick a key that
+    // cannot serve the (possibly rewritten) model id.
+    const filter = ctx.providerFilter;
     const excludeLabels = new Set(ctx.triedKeys);
     const booked = buildBookedLabels(state);
     for (const label of booked) {
         excludeLabels.add(label);
     }
-    let snapshot = selectKeyWithUsageFallback(state, excludeLabels, options);
-    // Tier 2: all remaining healthy keys are booked — share one.
+    let snapshot = findNextKey(state, excludeLabels, filter);
+    // Tier 2: all remaining healthy preferred keys are booked — share one.
     // Still respects per-request triedKeys (don't re-use a key this
     // request already failed on).
     if (!snapshot) {
-        snapshot = selectKeyWithUsageFallback(state, new Set(ctx.triedKeys), options);
+        snapshot = findNextKey(state, new Set(ctx.triedKeys), filter);
+    }
+    // Tier 3: exhausted → any provider, unless the model is provider-pinned.
+    if (!snapshot && !ctx.pinned) {
+        snapshot = findNextKey(state, new Set(ctx.triedKeys));
     }
     ctx.currentKey = snapshot;
     return snapshot;
@@ -266,10 +297,11 @@ export function completeRequest(state, requestId, success) {
 /**
  * Mark a key as failed according to the error type (C2).
  * - KeyFault / ServerFault: penalise the key (KeyFault disables immediately)
- * - RequestFault: no penalisation (bad request, not bad key)
+ * - RequestFault / NetworkFault: no penalisation (bad request, or network
+ *   trouble that is not the key's fault)
  */
 export function markKeyFailed(state, keyLabel, errorType) {
-    if (errorType === 'RequestFault')
+    if (errorType === 'RequestFault' || errorType === 'NetworkFault')
         return;
     const key = state.keys.find((k) => k.label === keyLabel);
     if (!key)
@@ -313,15 +345,23 @@ export function markKeySucceeded(state, keyLabel) {
  *  401               → KeyFault  (invalid/revoked key — immediate disable)
  *  429               → ServerFault (transient rate-limit — incremental circuit breaker)
  *  500 / 502 / 503   → KeyFault if body mentions quota/balance, else ServerFault
- *  400 / 404 / 422   → RequestFault (bad request — don't penalise the key)
+ *  400 / 403 / 404 / 422 → RequestFault (bad request or permission denial —
+ *                      don't penalise the key; 403 MODEL_NOT_IN_PLAN is a plan
+ *                      restriction, found live on commandcode)
  *  everything else   → ServerFault
  */
 export function classifyHttpError(status, _body) {
-    if (status === 401)
+    if (status === 401) {
+        // opencode-go returns 401 ModelError for UNKNOWN MODELS (verified live:
+        // a Model gpt-5.5 is not supported, with a valid key). That is a request
+        // fault — penalising it would disable every key as the pool rotates.
+        if (_body && /ModelError|not supported/i.test(_body))
+            return 'RequestFault';
         return 'KeyFault';
+    }
     if (status === 429)
         return 'ServerFault';
-    if (status === 400 || status === 404 || status === 422)
+    if (status === 400 || status === 403 || status === 404 || status === 422)
         return 'RequestFault';
     if (status === 500 || status === 502 || status === 503) {
         // Server errors: if the body hints at a quota/balance issue treat as KeyFault