saros-proxy 0.7.4 → 0.10.0

package/dist/providers/index.d.ts

@@ -0,0 +1,43 @@
+import type { KeyProvider, ProviderId, SmokeResult } from './types.js';
+export * from './types.js';
+export { inferProvider, type KeyEntry } from './infer.js';
+export { opencodeGoProvider, parseOpencodeUsage } from './opencode-go.js';
+export { commandcodeProvider, commandcodeClientHeaders, resolveClientVersion, parsePlanId, COMMANDCODE_BASE_URL, COMMANDCODE_BILLING_PATH, } from './commandcode.js';
+/** Get a provider by id. */
+export declare function getProvider(id: ProviderId): KeyProvider | undefined;
+/** All registered providers. */
+export declare function allProviders(): readonly KeyProvider[];
+/** Structural validity: at least one provider accepts the format. */
+export declare function isPlausibleKey(key: string): boolean;
+export interface KeyIdentification {
+    /** Provider the key belongs to, or null when unknown/invalid. */
+    provider: ProviderId | null;
+    /** 'unverified' when only the prefix matched (no definitive ping). */
+    confidence: 'verified' | 'unverified' | 'invalid' | 'unknown';
+    /** Per-provider smoke results (diagnostics for the TUI). */
+    attempts: SmokeResult[];
+}
+/**
+ * Identify which provider a key belongs to.
+ *
+ * Decision tree:
+ * 1. Providers whose prefix says 'no' are skipped entirely.
+ * 2. Remaining candidates are smoke-tested in parallel.
+ * 3. First 'valid' wins (definitive positive).
+ * 4. All candidates 'invalid' → the key is rejected.
+ * 5. Only inconclusive 'error' results → unknown (network problem).
+ * 6. No candidates at all → prefix not recognized by any provider.
+ *
+ * When `verify: false`, skips the network and returns the prefix-level
+ * answer ('unverified') — used by config validation where offline tolerance
+ * is required.
+ */
+export declare function identifyKey(key: string, options?: {
+    verify?: boolean;
+    timeoutMs?: number;
+}): Promise<KeyIdentification>;
+/**
+ * Extract candidate API keys from arbitrary pasted text (TUI drop-a-key
+ * flow). Matches oc_sk_, user_ and sk- tokens of plausible length; dedupes.
+ */
+export declare function extractKeys(text: string): string[];

package/dist/providers/index.js

@@ -0,0 +1,75 @@
+/**
+ * index.ts — Provider registry and key identification.
+ *
+ * identifyKey() classifies a pasted key by pinging candidate providers in
+ * parallel: a 200 is a definitive positive, a 401/403 a definitive negative,
+ * network errors are inconclusive. Handles the sk- collision between
+ * opencode-go and commandcode empirically.
+ */
+import { opencodeGoProvider } from './opencode-go.js';
+import { commandcodeProvider } from './commandcode.js';
+export * from './types.js';
+export { inferProvider } from './infer.js';
+export { opencodeGoProvider, parseOpencodeUsage } from './opencode-go.js';
+export { commandcodeProvider, commandcodeClientHeaders, resolveClientVersion, parsePlanId, COMMANDCODE_BASE_URL, COMMANDCODE_BILLING_PATH, } from './commandcode.js';
+const ALL_PROVIDERS = [opencodeGoProvider, commandcodeProvider];
+/** Get a provider by id. */
+export function getProvider(id) {
+    return ALL_PROVIDERS.find((p) => p.id === id);
+}
+/** All registered providers. */
+export function allProviders() {
+    return ALL_PROVIDERS;
+}
+/** Structural validity: at least one provider accepts the format. */
+export function isPlausibleKey(key) {
+    return ALL_PROVIDERS.some((p) => p.quickMatch(key) !== 'no');
+}
+/** Providers whose quickMatch does not rule the key out. */
+function candidates(key) {
+    return ALL_PROVIDERS.filter((p) => p.quickMatch(key) !== 'no');
+}
+/**
+ * Identify which provider a key belongs to.
+ *
+ * Decision tree:
+ * 1. Providers whose prefix says 'no' are skipped entirely.
+ * 2. Remaining candidates are smoke-tested in parallel.
+ * 3. First 'valid' wins (definitive positive).
+ * 4. All candidates 'invalid' → the key is rejected.
+ * 5. Only inconclusive 'error' results → unknown (network problem).
+ * 6. No candidates at all → prefix not recognized by any provider.
+ *
+ * When `verify: false`, skips the network and returns the prefix-level
+ * answer ('unverified') — used by config validation where offline tolerance
+ * is required.
+ */
+export async function identifyKey(key, options) {
+    const cands = candidates(key);
+    if (cands.length === 0) {
+        return { provider: null, confidence: 'unknown', attempts: [] };
+    }
+    if (options?.verify === false) {
+        const unique = new Set(cands.map((c) => c.id));
+        const provider = unique.size === 1 ? cands[0].id : null;
+        return { provider, confidence: 'unverified', attempts: [] };
+    }
+    const attempts = await Promise.all(cands.map((c) => c.smokeTest(key, options?.timeoutMs)));
+    const valid = attempts.find((a) => a.status === 'valid');
+    if (valid) {
+        return { provider: valid.provider, confidence: 'verified', attempts };
+    }
+    if (attempts.every((a) => a.status === 'invalid')) {
+        return { provider: null, confidence: 'invalid', attempts };
+    }
+    return { provider: null, confidence: 'unknown', attempts };
+}
+/**
+ * Extract candidate API keys from arbitrary pasted text (TUI drop-a-key
+ * flow). Matches oc_sk_, user_ and sk- tokens of plausible length; dedupes.
+ */
+export function extractKeys(text) {
+    const matches = text.match(/(?:oc_sk_|user_|sk-)[A-Za-z0-9_-]{16,}/g) ?? [];
+    return [...new Set(matches)];
+}
+//# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

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

package/dist/providers/infer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * infer.ts — Synchronous provider inference for config-time decisions.
+ *
+ * Config loading must never block on network I/O, so the provider for each
+ * key is inferred structurally here ('user_' → commandcode; 'oc_sk_' and
+ * 'sk-' → opencode-go, the legacy default). The authoritative, empirical
+ * answer comes from identifyKey() (async, network) — the setup wizard uses it
+ * and persists the result as an explicit `provider` field in config.yaml.
+ */
+import type { ProviderId } from './types.js';
+export interface KeyEntry {
+    label: string;
+    key: string;
+    /** Explicit provider from config.yaml; wins over inference when present. */
+    provider?: ProviderId;
+}
+/**
+ * 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 declare function inferProvider(entry: KeyEntry): ProviderId;

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,190 @@
+/**
+ * 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, OPENCODE_GO_KEY_PREFIX, 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) {
+        if (key.length < MIN_KEY_LENGTH)
+            return 'no';
+        // oc_sk_ is minted only by OpenCode → definitive.
+        if (key.startsWith(OPENCODE_GO_KEY_PREFIX))
+            return 'yes';
+        // sk- is shared with commandcode → never a definitive 'yes'.
+        return key.startsWith(API_KEY_PREFIX) ? '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);
+    },
+    // Verified live (2026-09-20): the zen endpoint accepts
+    // stream_options.include_usage and every chunk carries a `usage` key
+    // (null until the final chunk, which reports the real counts).
+    supportsStreamUsage: true,
+    // Required by opencode.ai/docs/go ("Send a stable session ID in
+    // x-opencode-session for each conversation"); enforced live — chat
+    // requests without it fail with 400 MissingSessionID.
+    sessionHeader: 'x-opencode-session',
+    /**
+     * 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,135 @@
+/**
+ * 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;
+    /**
+     * True when the provider accepts OpenAI's `stream_options.include_usage`
+     * and reports token counts for streamed responses. The proxy then asks
+     * for usage explicitly on streaming requests (unless the client set the
+     * option itself), so per-key token accounting stays accurate.
+     * Providers that reject unknown body fields must leave this unset.
+     */
+    readonly supportsStreamUsage?: boolean;
+    /**
+     * Header this provider uses to identify one conversation (upstream
+     * routing + prompt-cache optimization). saros forwards a client-supplied
+     * value untouched and derives a stable one from the conversation when the
+     * client sends none — some harnesses only send it on a subset of their
+     * request paths, and the upstream rejects the rest outright
+     * (OpenCode Go: 400 `MissingSessionID`).
+     */
+    readonly sessionHeader?: string;
+    /**
+     * 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"}