saros-proxy 0.7.4 → 0.9.0

package/dist/providers/infer.js

@@ -0,0 +1,13 @@
+/**
+ * Infer the provider for a key entry.
+ * Explicit `provider` field wins; 'user_' keys are commandcode; everything
+ * else plausible defaults to opencode-go (back-compat with every existing
+ * config.yaml).
+ */
+export function inferProvider(entry) {
+    if (entry.provider === 'commandcode' || entry.provider === 'opencode-go') {
+        return entry.provider;
+    }
+    return entry.key.startsWith('user_') ? 'commandcode' : 'opencode-go';
+}
+//# sourceMappingURL=infer.js.map

package/dist/providers/infer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer.js","sourceRoot":"","sources":["../../src/providers/infer.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAe;IAC3C,IAAI,KAAK,CAAC,QAAQ,KAAK,aAAa,IAAI,KAAK,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACzE,OAAO,KAAK,CAAC,QAAQ,CAAC;IACxB,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC;AACvE,CAAC"}

package/dist/providers/opencode-go.d.ts

@@ -0,0 +1,4 @@
+import type { KeyProvider, KeyUsage } from './types.js';
+/** Parse opencode-go usage JSON (moved from usage-client.ts). */
+export declare function parseOpencodeUsage(body: string): KeyUsage | null;
+export declare const opencodeGoProvider: KeyProvider;

package/dist/providers/opencode-go.js

@@ -0,0 +1,179 @@
+/**
+ * opencode-go.ts — KeyProvider adapter for the OpenCode-Go API (opencode.ai).
+ *
+ * Keys: `sk-` prefix (shared with commandcode → 'maybe'), ≥ 20 chars.
+ * Usage: GET /zen/go/v1/usage with Bearer = the key itself.
+ */
+import { API_KEY_PREFIX, MIN_KEY_LENGTH, USAGE_PATH, } from '../constants.js';
+/** Bare-name index of the live opencode-go catalog. */
+let catalogCache = null;
+/** Ensures the background refresh fires at most once per process. */
+let refreshStarted = false;
+/**
+ * Fetch the public opencode-go model list and index it. The endpoint needs
+ * no auth (verified live); failures keep the previous cache.
+ */
+async function refreshCatalog(baseUrl, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${baseUrl.replace(/\/$/, '')}${USAGE_PATH.replace(/\/usage$/, '/models')}`, {
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return false;
+        const body = (await res.json());
+        if (!Array.isArray(body.data))
+            return false;
+        const bareNames = new Set();
+        for (const entry of body.data) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const id = entry.id;
+            if (typeof id !== 'string' || !id)
+                continue;
+            bareNames.add(id.toLowerCase());
+            const last = id.split('/').pop() ?? id;
+            if (last)
+                bareNames.add(last.toLowerCase());
+        }
+        catalogCache = { bareNames };
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parsePercent(window) {
+    const percent = window?.percent;
+    if (typeof percent !== 'number' || !Number.isFinite(percent))
+        return 0;
+    return Math.min(100, Math.max(0, percent));
+}
+/** Parse opencode-go usage JSON (moved from usage-client.ts). */
+export function parseOpencodeUsage(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    const usage = parsed?.usage;
+    if (!usage || typeof usage !== 'object')
+        return null;
+    const rolling = parsePercent(usage.rolling);
+    const weekly = parsePercent(usage.weekly);
+    const monthly = parsePercent(usage.monthly);
+    return {
+        rollingPercent: rolling,
+        weeklyPercent: weekly,
+        monthlyPercent: monthly,
+        usedPercent: Math.max(rolling, weekly, monthly),
+        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,
+    };
+}
+export const opencodeGoProvider = {
+    id: 'opencode-go',
+    displayName: 'OpenCode Go',
+    baseUrl: 'https://opencode.ai',
+    chatBasePath: '/zen/go/v1',
+    quickMatch(key) {
+        // sk- is shared with commandcode → never a definitive 'yes'.
+        return key.startsWith(API_KEY_PREFIX) && key.length >= MIN_KEY_LENGTH
+            ? 'maybe'
+            : 'no';
+    },
+    async smokeTest(key, timeoutMs = 10_000) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${this.baseUrl}${USAGE_PATH}`, {
+                headers: { Authorization: `Bearer ${key}` },
+                signal: controller.signal,
+            });
+            if (res.ok) {
+                return { provider: this.id, status: 'valid', httpStatus: res.status };
+            }
+            // 401/403 = definitive rejection; 5xx/429 = inconclusive
+            const definitive = res.status === 401 || res.status === 403;
+            return {
+                provider: this.id,
+                status: definitive ? 'invalid' : 'error',
+                httpStatus: res.status,
+                detail: definitive ? 'upstream rejected the key' : 'upstream unavailable',
+            };
+        }
+        catch (err) {
+            return {
+                provider: this.id,
+                status: 'error',
+                detail: err instanceof Error ? err.message : String(err),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+    usagePath() {
+        return USAGE_PATH;
+    },
+    parseUsageResponse(body) {
+        return parseOpencodeUsage(body);
+    },
+    /**
+     * Affinity via the live catalog when loaded; 'maybe' before the first
+     * fetch resolves (non-committal, keeps the key as rotation fallback).
+     */
+    modelAffinity(modelId) {
+        if (!catalogCache) {
+            if (!refreshStarted) {
+                refreshStarted = true;
+                void refreshCatalog(this.baseUrl, 5_000);
+            }
+            return 'maybe';
+        }
+        const bare = (modelId.split('/').pop() ?? modelId).toLowerCase();
+        return catalogCache.bareNames.has(bare) ? 'yes' : 'no';
+    },
+    /** Same verdict as modelAffinity — the catalog index is already bare-name based. */
+    modelAffinityByName(bareName) {
+        if (!catalogCache) {
+            if (!refreshStarted) {
+                refreshStarted = true;
+                void refreshCatalog(this.baseUrl, 5_000);
+            }
+            return 'maybe';
+        }
+        return catalogCache.bareNames.has(bareName.toLowerCase()) ? 'yes' : 'no';
+    },
+    /** opencode-go ids are already bare (1:1 naming) — the input passes through. */
+    resolveNativeId(bareName) {
+        return catalogCache?.bareNames.has(bareName.toLowerCase()) ? bareName : null;
+    },
+    /** Public catalog endpoint (no auth required, verified live). */
+    async fetchCatalog(timeoutMs = 5_000) {
+        const ok = await refreshCatalog(this.baseUrl, timeoutMs);
+        if (!ok)
+            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')}`);
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            return Array.isArray(body.data)
+                ? body.data
+                : null;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+//# sourceMappingURL=opencode-go.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -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;