llm-relay 0.8.4 → 0.10.0

package/dist/key-checker.js

@@ -1,20 +1,132 @@
 import { fetchProviderQuota } from "./ping/quota.js";
 import { candidateEnvNames } from "./authEnv.js";
-/** Pre-flight check all configured provider API keys. */
+import { splitSpec } from "./config.js";
+/**
+ * Per-request cap for key checking. Independent of a provider's own `timeoutMs`, which is
+ * sized for real completions (minutes) — a status command must stay answerable even when a
+ * configured host is black-holing connections.
+ */
+const KEY_CHECK_TIMEOUT_MS = 45_000;
+function withTimeout() {
+    return typeof AbortSignal?.timeout === "function" ? { signal: AbortSignal.timeout(KEY_CHECK_TIMEOUT_MS) } : {};
+}
+/**
+ * Does this endpoint actually require credentials? Probed by calling it with none.
+ * A 401/403 means the earlier authenticated 200 was real evidence about the key.
+ * Anything else means the endpoint is public and tells us nothing.
+ * On a network error we assume it IS gated — never downgrade a working key on a blip.
+ */
+async function isAuthGated(url, fetchFn) {
+    try {
+        const bare = await fetchFn(url, { method: "GET", headers: { "Content-Type": "application/json" }, ...withTimeout() });
+        return bare.status === 401 || bare.status === 403;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Ask an endpoint that definitely needs the key: a 1-token completion.
+ *
+ * `modelId` should be a REAL id from the provider's own catalogue. A throwaway id like
+ * "probe" looks tidy but is unreliable: some providers reject the unknown model with a 401
+ * (reported as a bad key when the key was fine) and others stall routing it until the
+ * request times out. Both turn a healthy provider into a false alarm — the same class of
+ * bug as the false VALID this check exists to fix, just pointing the other way.
+ */
+async function probeAuthenticated(p, apiKey, fetchFn, modelId) {
+    const isOpenAi = p.kind === "openai";
+    const url = isOpenAi ? `${p.base}/chat/completions` : `${p.base}/v1/messages`;
+    const headers = { "Content-Type": "application/json" };
+    if (p.authHeader === "x-api-key" || p.kind === "anthropic") {
+        headers["x-api-key"] = apiKey;
+        headers["anthropic-version"] = "2023-06-01";
+    }
+    else {
+        headers["authorization"] = apiKey.startsWith("Bearer ") ? apiKey : `Bearer ${apiKey}`;
+    }
+    const body = JSON.stringify({
+        model: modelId,
+        max_tokens: 1,
+        messages: [{ role: "user", content: "hi" }],
+    });
+    try {
+        const r = await fetchFn(url, { method: "POST", headers, body, ...withTimeout() });
+        if (r.status === 429) {
+            return { status: "rate_limited", httpStatus: 429, message: "Rate limited or quota exhausted (HTTP 429)" };
+        }
+        if (r.status !== 401 && r.status !== 403) {
+            // 2xx, or a 400/404 rejecting the request on its contents — either way it got past auth.
+            return { status: "valid", httpStatus: r.status, message: "Key verified (authenticated probe)" };
+        }
+        // A 401/403 is ambiguous: the key may be bad, OR the key may be fine and simply not
+        // entitled to this particular model (premium tiers are common in a free-tier roster, and
+        // the catalogue lists them alongside the free ones). Send the SAME request anonymously:
+        // if the answer changes, the credential demonstrably did something and the wall is about
+        // the model, not the key. If it does not change, we have learned nothing and must say so
+        // rather than accuse a working key.
+        const anon = await fetchFn(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            ...withTimeout(),
+        });
+        if (anon.status !== r.status) {
+            return {
+                status: "valid",
+                httpStatus: r.status,
+                message: `Key authenticated (HTTP ${r.status} is the probe model not being available on this plan)`,
+            };
+        }
+        return {
+            status: "unverified",
+            httpStatus: r.status,
+            message: `Could not confirm — /models is public and the probe model answers HTTP ${r.status} with or without the key`,
+        };
+    }
+    catch (e) {
+        return { status: "unreachable", httpStatus: undefined, message: `Network error: ${e.message}` };
+    }
+}
+/** First model id this config routes to each provider, across pools, tiers and default. */
+function routedModelsByProvider(cfg) {
+    const out = new Map();
+    const raw = [
+        ...Object.values(cfg.routing.pools ?? {}),
+        ...Object.values(cfg.routing.tiers ?? {}),
+        cfg.routing.default,
+    ];
+    for (const entry of raw) {
+        for (const spec of Array.isArray(entry) ? entry : entry ? [entry] : []) {
+            const { provider, model } = splitSpec(spec);
+            if (model && !out.has(provider))
+                out.set(provider, model);
+        }
+    }
+    return out;
+}
+/**
+ * Pre-flight check all configured provider API keys.
+ *
+ * Providers are checked CONCURRENTLY. A rich config can declare a dozen-plus providers, and
+ * one unreachable host (a local daemon that isn't running) must not add its whole timeout to
+ * everyone else's wait — checked serially that turns a status command into a minutes-long one.
+ * Result order still follows config order.
+ */
 export async function validateProviderKeys(cfg, fetchFn = fetch) {
-    const results = [];
-    for (const [name, p] of Object.entries(cfg.providers)) {
+    const entries = Object.entries(cfg.providers);
+    const routed = routedModelsByProvider(cfg);
+    const checkOne = async ([name, p]) => {
         const envVarName = p.authEnv;
         const apiKey = envVarName ? process.env[envVarName] : undefined;
         if (envVarName && !apiKey) {
-            results.push({
+            return {
                 provider: name,
                 authEnv: envVarName,
                 hasEnvKey: false,
                 status: "missing_env",
                 message: `No key found — set ${candidateEnvNames(name, envVarName).slice(0, 4).join(" or ")}`,
-            });
-            continue;
+            };
         }
         try {
             // 1. Fetch quota if applicable
@@ -30,19 +142,19 @@ export async function validateProviderKeys(cfg, fetchFn = fetch) {
                     headers["authorization"] = apiKey.startsWith("Bearer ") ? apiKey : `Bearer ${apiKey}`;
                 }
             }
-            const resp = await fetchFn(url, { method: "GET", headers });
+            const resp = await fetchFn(url, { method: "GET", headers, ...withTimeout() });
             if (resp.status === 401 || resp.status === 403) {
-                results.push({
+                return {
                     provider: name,
                     authEnv: envVarName,
                     hasEnvKey: true,
                     status: "invalid_key",
                     httpStatus: resp.status,
                     message: `Authentication failed (HTTP ${resp.status})`,
-                });
+                };
             }
             else if (resp.status === 429) {
-                results.push({
+                return {
                     provider: name,
                     authEnv: envVarName,
                     hasEnvKey: true,
@@ -50,22 +162,56 @@ export async function validateProviderKeys(cfg, fetchFn = fetch) {
                     httpStatus: 429,
                     message: "Rate limited or quota exhausted (HTTP 429)",
                     quotaPercent: quota.quotaPercent,
-                });
+                };
             }
             else if (resp.ok || resp.status === 400 || resp.status === 404 || resp.status === 405) {
                 // 200 OK or endpoint-level expected response (e.g. GET on /messages returning 405 Method Not Allowed)
                 let modelsCount;
+                let firstModelId;
                 if (resp.ok && url.endsWith("/models")) {
                     try {
                         const body = (await resp.json());
-                        if (Array.isArray(body.data))
+                        if (Array.isArray(body.data)) {
                             modelsCount = body.data.length;
+                            const first = body.data.find((m) => typeof m?.id === "string");
+                            if (first)
+                                firstModelId = first.id;
+                        }
                     }
                     catch {
                         /* ignore JSON parse */
                     }
                 }
-                results.push({
+                // A 200 from /models only proves the KEY works if that endpoint is actually
+                // auth-gated. Several providers (OpenRouter among them) serve it publicly, so a
+                // revoked key still returns the full catalogue and this check reported VALID while
+                // every real request 401'd. Re-probe WITHOUT the key: if it still succeeds, the
+                // endpoint proved nothing and we must ask an authenticated endpoint instead.
+                // Needs a real model id to probe with; without one, escalation is less reliable
+                // than the listing we already have, so keep the listing verdict.
+                // Prefer a model this config actually ROUTES to the provider over the catalogue's
+                // first entry. Free-tier rosters list premium models the key legitimately cannot
+                // touch, and probing one of those produces a 401/403 that says nothing about the
+                // key. The routed model is both the one the user cares about and the one most
+                // likely to be reachable on their plan.
+                const probeModel = routed.get(name) ?? firstModelId;
+                if (resp.ok && apiKey && url.endsWith("/models") && probeModel) {
+                    const gated = await isAuthGated(url, fetchFn);
+                    if (!gated) {
+                        const verdict = await probeAuthenticated(p, apiKey, fetchFn, probeModel);
+                        return {
+                            provider: name,
+                            authEnv: envVarName,
+                            hasEnvKey: true,
+                            status: verdict.status,
+                            httpStatus: verdict.httpStatus,
+                            message: verdict.message,
+                            quotaPercent: quota.quotaPercent,
+                            modelsFound: modelsCount,
+                        };
+                    }
+                }
+                return {
                     provider: name,
                     authEnv: envVarName,
                     hasEnvKey: true,
@@ -74,29 +220,29 @@ export async function validateProviderKeys(cfg, fetchFn = fetch) {
                     message: "Key verified & healthy",
                     quotaPercent: quota.quotaPercent,
                     modelsFound: modelsCount,
-                });
+                };
             }
             else {
-                results.push({
+                return {
                     provider: name,
                     authEnv: envVarName,
                     hasEnvKey: true,
                     status: "unreachable",
                     httpStatus: resp.status,
                     message: `Provider returned HTTP ${resp.status}`,
-                });
+                };
             }
         }
         catch (e) {
-            results.push({
+            return {
                 provider: name,
                 authEnv: envVarName,
                 hasEnvKey: true,
                 status: "unreachable",
                 message: `Network error: ${e.message}`,
-            });
+            };
         }
-    }
-    return results;
+    };
+    return Promise.all(entries.map(checkOne));
 }
 //# sourceMappingURL=key-checker.js.map

package/dist/key-checker.js.map

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

package/dist/pool-health.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pool liveness probing — `llm-relay pools [--probe]`.
+ *
+ * Nothing used to detect a dead pool member. A model can be listed in a provider's catalogue
+ * and still refuse every request (de-listed behind the scenes, gated to a paid tier, or
+ * routed to a function that no longer exists), so config-time validation cannot see it. The
+ * observed failure mode: a pool whose top-ranked member 404'd on every call while the pool
+ * looked healthy, leaving offload running on a single live model with failover that existed
+ * only on paper.
+ *
+ * The only trustworthy signal is a real completion, so that is what `--probe` sends.
+ */
+import type { Config } from "./config.js";
+export type MemberVerdict = "live" | "empty" | "auth" | "rate_limited" | "missing" | "error";
+export interface MemberHealth {
+    pool: string;
+    spec: string;
+    verdict: MemberVerdict;
+    httpStatus?: number | undefined;
+    latencyMs?: number | undefined;
+    detail?: string | undefined;
+}
+/** Verdicts that mean "this member will never answer until someone changes something". */
+export declare const DEAD_VERDICTS: ReadonlySet<MemberVerdict>;
+/**
+ * Send one real completion to a single pool member.
+ *
+ * `maxTokens` defaults to 400 rather than a token or two because reasoning models spend
+ * their budget thinking: at a low cap they return a 200 with EMPTY content, which reads as
+ * a broken model when it is only a truncated one.
+ */
+export declare function probeMember(pool: string, spec: string, cfg: Config, fetchFn?: typeof fetch, maxTokens?: number, now?: () => number): Promise<MemberHealth>;
+/** Pull assistant text out of either an OpenAI or an Anthropic shaped response. */
+export declare function extractContent(raw: string): string;
+/** Probe every member of every pool. Concurrency-limited so a wide config can't fan out unbounded. */
+export declare function probeAllPools(cfg: Config, fetchFn?: typeof fetch, concurrency?: number): Promise<MemberHealth[]>;

package/dist/pool-health.js

@@ -0,0 +1,108 @@
+import { splitSpec } from "./config.js";
+/** Verdicts that mean "this member will never answer until someone changes something". */
+export const DEAD_VERDICTS = new Set(["missing", "auth"]);
+function authHeaders(p, apiKey) {
+    const headers = { "Content-Type": "application/json" };
+    if (!apiKey)
+        return headers;
+    if (p.authHeader === "x-api-key" || p.kind === "anthropic") {
+        headers["x-api-key"] = apiKey;
+        headers["anthropic-version"] = "2023-06-01";
+    }
+    else {
+        headers["authorization"] = apiKey.startsWith("Bearer ") ? apiKey : `Bearer ${apiKey}`;
+    }
+    return headers;
+}
+/**
+ * Send one real completion to a single pool member.
+ *
+ * `maxTokens` defaults to 400 rather than a token or two because reasoning models spend
+ * their budget thinking: at a low cap they return a 200 with EMPTY content, which reads as
+ * a broken model when it is only a truncated one.
+ */
+export async function probeMember(pool, spec, cfg, fetchFn = fetch, maxTokens = 400, now = Date.now) {
+    const { provider, model } = splitSpec(spec);
+    const p = cfg.providers[provider];
+    if (!p) {
+        return { pool, spec, verdict: "missing", detail: `no provider "${provider}" configured` };
+    }
+    const apiKey = p.authEnv ? process.env[p.authEnv] : undefined;
+    if (p.authEnv && !apiKey) {
+        return { pool, spec, verdict: "auth", detail: `${p.authEnv} is not set` };
+    }
+    const isOpenAi = p.kind === "openai";
+    const url = isOpenAi ? `${p.base}/chat/completions` : `${p.base}/v1/messages`;
+    const body = JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        messages: [{ role: "user", content: "Reply with exactly: OK" }],
+    });
+    const started = now();
+    try {
+        const r = await fetchFn(url, { method: "POST", headers: authHeaders(p, apiKey), body });
+        const latencyMs = now() - started;
+        if (r.status === 401 || r.status === 403) {
+            return { pool, spec, verdict: "auth", httpStatus: r.status, latencyMs, detail: `HTTP ${r.status}` };
+        }
+        if (r.status === 429) {
+            return { pool, spec, verdict: "rate_limited", httpStatus: 429, latencyMs, detail: "HTTP 429" };
+        }
+        if (r.status === 404 || r.status === 400) {
+            return { pool, spec, verdict: "missing", httpStatus: r.status, latencyMs, detail: `HTTP ${r.status} — model not servable` };
+        }
+        if (!r.ok) {
+            return { pool, spec, verdict: "error", httpStatus: r.status, latencyMs, detail: `HTTP ${r.status}` };
+        }
+        const text = await r.text();
+        const content = extractContent(text);
+        if (content.trim().length === 0) {
+            return { pool, spec, verdict: "empty", httpStatus: r.status, latencyMs, detail: "200 but no content" };
+        }
+        return { pool, spec, verdict: "live", httpStatus: r.status, latencyMs };
+    }
+    catch (e) {
+        return { pool, spec, verdict: "error", latencyMs: now() - started, detail: e.message };
+    }
+}
+/** Pull assistant text out of either an OpenAI or an Anthropic shaped response. */
+export function extractContent(raw) {
+    try {
+        const j = JSON.parse(raw);
+        const openai = j.choices?.[0]?.message?.content;
+        if (typeof openai === "string")
+            return openai;
+        if (Array.isArray(j.content)) {
+            return j.content
+                .filter((b) => b?.type === "text" && typeof b.text === "string")
+                .map((b) => b.text)
+                .join("");
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return "";
+}
+/** Probe every member of every pool. Concurrency-limited so a wide config can't fan out unbounded. */
+export async function probeAllPools(cfg, fetchFn = fetch, concurrency = 4) {
+    const jobs = [];
+    for (const [pool, members] of Object.entries(cfg.routing.pools ?? {})) {
+        for (const spec of members)
+            jobs.push({ pool, spec });
+    }
+    const out = new Array(jobs.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(concurrency, jobs.length)) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= jobs.length)
+                return;
+            const job = jobs[i];
+            out[i] = await probeMember(job.pool, job.spec, cfg, fetchFn);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}
+//# sourceMappingURL=pool-health.js.map

package/dist/pool-health.js.map

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

package/dist/server.js

@@ -12,6 +12,7 @@ import { ModelCatalog } from "./catalog.js";
 import { buildRegistry } from "./registry.js";
 import { buildCandidates } from "./candidates.js";
 import { offloadState, setOffload } from "./offload.js";
+import { buildDispatch, markExhausted, clearExhausted } from "./dispatch.js";
 import { toolSchemaMap } from "./anthropic.js";
 import { PingLoop } from "./ping/cadence.js";
 import { recordModelCall } from "./ping/runtime-telemetry.js";
@@ -152,6 +153,43 @@ async function handle(req, res, cfg, h) {
         h.logger.write(baseLog(started, path, model, false, false, 200, "skipped"));
         return;
     }
+    // The dispatch ladder: which lane the host should hand a delegated task to next. GET reads
+    // (with ?lane= to override, ?after= to walk past a spent rung, ?task= to get a runnable
+    // command); POST reports a rung spent so the next read walks past it. The relay decides the
+    // ORDER and never executes a cli rung itself — spawning agents is the host's job.
+    if ((req.method === "GET" || req.method === "POST") && pathname === "/dispatch") {
+        if (req.method === "POST") {
+            const body = (reqJson ?? {});
+            const ttlMs = typeof body.ttlMs === "number" ? body.ttlMs : undefined;
+            if (typeof body.clear === "string") {
+                clearExhausted(cfg, body.clear);
+            }
+            else if (body.clear === true) {
+                clearExhausted(cfg);
+            }
+            else if (typeof body.exhausted === "string") {
+                if (!markExhausted(cfg, body.exhausted, ttlMs)) {
+                    failClosed(res, 400, `POST /dispatch: no lane "${body.exhausted}" in routing.ladder`);
+                    h.logger.write(baseLog(started, path, model, false, false, 400, "skipped"));
+                    return;
+                }
+            }
+            else {
+                failClosed(res, 400, `POST /dispatch needs {"exhausted":"<lane>"} or {"clear":"<lane>"|true}`);
+                h.logger.write(baseLog(started, path, model, false, false, 400, "skipped"));
+                return;
+            }
+        }
+        const view = buildDispatch(cfg, {
+            ...(pickQuery(path, "task") ? { task: pickQuery(path, "task") } : {}),
+            ...(pickQuery(path, "lane") ? { lane: pickQuery(path, "lane") } : {}),
+            ...(pickQuery(path, "after") ? { after: pickQuery(path, "after") } : {}),
+        });
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify(view, null, 2));
+        h.logger.write(baseLog(started, path, model, false, false, 200, "skipped"));
+        return;
+    }
     if (req.method === "GET" && pathname === "/telemetry") {
         const report = getTelemetryReport(cfg, globalCircuitBreaker);
         res.writeHead(200, { "content-type": "application/json" });