llm-relay 0.67.0 → 0.68.1

package/dist/cli.d.ts

@@ -2,6 +2,7 @@
 import { splitSpec, type Config } from "./config.js";
 import { type Candidate, type CandidateAvailability } from "./candidates.js";
 import { type DispatchView } from "./dispatch.js";
+import type { DispatchedQuotaReport } from "./mcp/lane-runner.js";
 import { ModelCatalog } from "./catalog.js";
 import { type CommandEffect } from "./self-update.js";
 import { type KeysCliDependencies } from "./keys-cli.js";
@@ -130,6 +131,17 @@ export declare function runKeysEnable(credential?: string | undefined, deps?: Ke
 export declare function runKeysExport(deps?: KeysCliDependencies): Promise<void>;
 export declare function runKeysImport(importPath?: string | undefined, deps?: KeysCliDependencies): Promise<void>;
 export declare function runKeysUnlock(deps?: KeysCliDependencies): Promise<void>;
+export interface TelemetryDeps {
+    readonly loadConfig?: () => Config;
+    readonly request?: (cfg: Config) => Promise<unknown | null>;
+    readonly localReport?: (cfg: Config) => unknown;
+    readonly write?: (text: string) => void;
+}
+/** Print telemetry from the live relay when available, falling back to the local snapshot. */
+export declare function runTelemetry(deps?: TelemetryDeps): Promise<void>;
+export type DispatchReportRequest = (cfg: Config, path: string, init: RequestInit) => Promise<unknown | null>;
+/** Forward positive MCP lane quota evidence to the live relay's authenticated control route. */
+export declare function reportMcpExhaustion(cfg: Config, report: DispatchedQuotaReport, request?: DispatchReportRequest): Promise<void>;
 /** Render a normalized listener address as an HTTP URL, including required IPv6 brackets. */
 export declare function proxyUrl(cfg: Pick<Config, "host" | "port">, path: string): string;
 export declare const CLI_COMMAND_NAMES: ReadonlySet<string>;
@@ -159,6 +171,8 @@ export declare const CLI_COMMAND_NAMES: ReadonlySet<string>;
 export declare const ARITY_EXEMPT: ReadonlySet<string>;
 /** The commands this guard bounds — exported for the drift test, not for dispatch. */
 export declare const ARITY_GUARDED_COMMANDS: readonly string[];
+/** Return a bounded, value-free diagnostic for an option not accepted by this command/action. */
+export declare function commandOptionError(argv: readonly string[]): string | null;
 export declare function commandArityError(positionals: readonly string[]): string | null;
 /** Clear process-local routing cooldowns through the protected live control plane only. */
 export declare function runCooldowns(_action: string | undefined, _spec: string | undefined): Promise<void>;

package/dist/cli.js

@@ -176,6 +176,7 @@ ${formatTextTable([
     ["llm-relay keys | keys check | check-keys", "Check every configured credential slot."],
     ["llm-relay keys <action> ...", "action: add|list|rotate|revoke|remove|disable|enable|export|import|unlock."],
     ["llm-relay pools [--probe]", "List members; --probe tests each deployment once."],
+    ["llm-relay pools list | pools <name> | pools show <name> [--json]", "List pool names or one pool's effective members."],
     ["llm-relay pools <action> <name> [<spec>...]", "action: set|add|remove|delete."],
     ["llm-relay routing <action> ...", "action: show|get|default|tier|subagent|sort|benchmark|set|unset|answered."],
     ["llm-relay route <action> ...", "Alias for routing."],
@@ -191,7 +192,7 @@ ${formatTextTable([
     ["llm-relay candidates [-p <name>]", "Compare deployment x credential-slot targets."],
     ["llm-relay cost [--window <w>] [--by <d>] [--include-repair]", "Summarise spend from the local accounting ledger."],
     ["llm-relay eligibility", "What backends said about themselves; refusals awaiting interpretation."],
-    ["llm-relay eligibility <propose|accept> <n> [--sig <digest>] --class <kind> --scope <scope>", "Scopes: attempt | group | deployment | credential | provider | model. --sig pins the item across queue reorderings."],
+    ["llm-relay eligibility <propose|accept|reject> <n> [--sig <digest>] --class <kind> --scope <scope>", "Scopes: attempt | group | deployment | credential | provider | model. --sig pins the item across queue reorderings."],
     ["llm-relay eligibility ... --scope group --members <id,id,...> [--all-credentials]", "Groups default to the current credential slot; the flag explicitly widens them."],
     ["llm-relay eligibility ... --cost-class free|paid|unknown", "Cover only deployments of that cost class, resolved live from catalog prices."],
     ["eligibility scope breadth", "credential = current credential slot; provider = all credentials for that provider."],
@@ -800,6 +801,26 @@ async function tryServer(cfg, path, init) {
         return null;
     }
 }
+export async function runTelemetry(deps = {}) {
+    const cfg = (deps.loadConfig ?? loadOrExit)();
+    const live = await (deps.request ?? ((config) => tryServer(config, "/telemetry")))(cfg);
+    const report = live ?? (deps.localReport ? deps.localReport(cfg) : getTelemetryReport(cfg, globalCircuitBreaker));
+    (deps.write ?? ((text) => process.stdout.write(text)))(`${JSON.stringify(report, null, 2)}\n`);
+}
+export async function reportMcpExhaustion(cfg, report, request = tryServer) {
+    const live = await request(cfg, "/dispatch", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            exhausted: report.laneId,
+            ...(report.tier ? { tier: report.tier } : {}),
+            outcome: report.outcome,
+            ...(report.retryAfterMs !== undefined ? { retryAfterMs: report.retryAfterMs } : {}),
+        }),
+    });
+    if (live === null)
+        throw new Error("no proxy running — quota report not recorded");
+}
 export function proxyUrl(cfg, path) {
     const host = cfg.host.includes(":") ? `[${cfg.host}]` : cfg.host;
     return `http://${host}:${cfg.port}${path}`;
@@ -846,6 +867,69 @@ const COMMAND_ARITY = {
 };
 export const ARITY_EXEMPT = new Set(["keys", "cooldowns", "help", "version"]);
 export const ARITY_GUARDED_COMMANDS = Object.keys(COMMAND_ARITY);
+const CLI_OPTIONS = {
+    proxy: ["--config", "--default", "--mode", "--listen", "--ping"],
+    onboard: ["--config", "--import", "--force"],
+    setup: [],
+    "check-keys": ["--config"],
+    models: ["--config", "--provider", "--refresh"],
+    ping: ["--config", "--provider", "--ping"],
+    dashboard: ["--config"],
+    telemetry: ["--config"],
+    offload: ["--config", "--scope"],
+    lanes: ["--config", "--probe"],
+    dispatch: ["--config", "--task", "--exhausted", "--outcome", "--retry-after-ms", "--after", "--lane", "--tier", "--client", "--host", "--shell", "--next-command", "--json"],
+    eligibility: ["--config", "--sig", "--class", "--rationale", "--scope", "--members", "--all-credentials", "--reset-field", "--reset-ms", "--cost-class"],
+    candidates: ["--config", "--provider"],
+    cost: ["--window", "--by", "--include-repair", "--json"],
+    pools: ["--config", "--probe", "--json"],
+    routing: ["--config", "--clear"],
+    route: ["--config", "--clear"],
+    config: ["--config"],
+    "delegate-gate": ["--repo", "--fix"],
+    mcp: ["--config"],
+};
+const ACTION_OPTIONS = {
+    offload: { on: ["--config", "--scope"], off: ["--config", "--scope"], enable: ["--config", "--scope"], disable: ["--config", "--scope"], status: ["--config"] },
+    pools: {
+        list: ["--config", "--json", "--probe"], show: ["--config", "--json"],
+        set: ["--config", "--include", "--free", "--effort"], add: ["--config", "--include", "--free", "--effort"],
+        remove: ["--config", "--include", "--free", "--effort"], delete: ["--config"], rm: ["--config"],
+    },
+    eligibility: {
+        status: ["--config"], reject: ["--config", "--sig"],
+        propose: ["--config", "--sig", "--class", "--rationale", "--scope", "--members", "--all-credentials", "--reset-field", "--reset-ms", "--cost-class"],
+        accept: ["--config", "--sig", "--class", "--scope", "--members", "--all-credentials", "--reset-field", "--reset-ms", "--cost-class"],
+    },
+    routing: {
+        tier: ["--config", "--clear"], subagent: ["--config", "--clear"],
+        show: ["--config"], get: ["--config"], default: ["--config"], sort: ["--config"],
+        benchmark: ["--config"], set: ["--config"], unset: ["--config"], answered: ["--config"],
+    },
+};
+export function commandOptionError(argv) {
+    const hasHelp = argv.slice(2).some((a) => a === "--help" || a === "-h" || a === "--version" || a === "-v");
+    if (hasHelp)
+        return null;
+    const positionals = getPositionalArgs([...argv]);
+    const command = positionals[0] ?? "proxy";
+    if (command === "keys" || command === "cooldowns" || command === "help" || command === "version")
+        return null;
+    const base = CLI_OPTIONS[command];
+    if (!base)
+        return null;
+    const action = positionals[1];
+    const actionOptions = ACTION_OPTIONS[command];
+    const allowed = actionOptions
+        ? actionOptions[action ?? ""] ?? (action === undefined ? base : ["--config", "--json"])
+        : base;
+    const aliases = expandFlagAliases([...allowed]);
+    for (const flag of parseCliArgs([...argv]).flags) {
+        if (!aliases.has(flag))
+            return `llm-relay ${command}: unsupported option`;
+    }
+    return null;
+}
 export function commandArityError(positionals) {
     const name = positionals[0];
     if (name === undefined)
@@ -1273,6 +1357,18 @@ function writeAbandonedShare(report, write) {
         `${formatTextTable(rows)}\n` +
         `The totals above are what the answers you received cost. Add this table for what the requests cost.\n`);
 }
+function writeCoveredPeriod(from, to, generatedAt, write) {
+    write(from === null ? `Covering everything up to ${to} (UTC).\n` : `Covering ${from} → ${to} (UTC).\n`);
+    const end = Date.parse(to);
+    const now = Date.parse(generatedAt);
+    if (!Number.isFinite(end) || !Number.isFinite(now))
+        return;
+    const minutes = Math.floor((now - end) / 60_000);
+    if (minutes < 1)
+        return;
+    write(`The window ends on a bucket boundary, so the most recent ${minutes} ` +
+        `${minutes === 1 ? "minute is" : "minutes are"} not counted.\n`);
+}
 function renderCostReport(report, write) {
     if (report.coverage === "empty") {
         write("No accounting data yet.\n\nThe relay records per-request usage under ~/.llm-relay/usage/ once it serves\ntraffic through configured providers. Run the proxy, send a request, then retry.\n");
@@ -1285,6 +1381,7 @@ function renderCostReport(report, write) {
     const rows = costTableRows(report);
     const repairDeclinedByWindow = report.includeRepair && report.repair === null && report.window === "lifetime";
     write(`llm-relay cost — ${report.window}${report.includeRepair && !repairDeclinedByWindow ? ", repair included" : ""}\n`);
+    writeCoveredPeriod(report.from, report.to, report.generatedAt, write);
     if (repairDeclinedByWindow) {
         write("The lifetime window cannot prove the serve/repair split; use a day-bounded window (--window 1h|24h|7d|30d) for the repair share.\n");
     }
@@ -1491,6 +1588,7 @@ export async function runMcp() {
         buildView: (o) => resolveDispatchView({ ...o, cfg }),
         ...(allowedRoots ? { allowedRoots } : {}),
         version: currentVersion(),
+        reportExhaustion: (report) => reportMcpExhaustion(cfg, report),
         write: (chunk) => process.stdout.write(chunk),
     });
     const stop = () => {
@@ -2654,6 +2752,12 @@ export function main() {
         process.stdout.write(`${currentVersion()}\n`);
         process.exit(0);
     }
+    const optionError = commandOptionError(process.argv);
+    if (optionError !== null) {
+        process.stderr.write(`${optionError}\n`);
+        process.exit(1);
+        return;
+    }
     const arityError = commandArityError(positionals);
     if (arityError !== null) {
         process.stderr.write(`${arityError}\n`);
@@ -2698,9 +2802,10 @@ export function main() {
         return;
     }
     if (arg2 === "telemetry") {
-        const cfg = loadOrExit();
-        const report = getTelemetryReport(cfg, globalCircuitBreaker);
-        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        void runTelemetry().catch((e) => {
+            process.stderr.write(`llm-relay telemetry: ${e.message}\n`);
+            process.exit(1);
+        });
         return;
     }
     if (arg2 === "check-keys") {
@@ -2917,14 +3022,22 @@ export function classifyCommand(argv) {
         case "dashboard":
             return "read-only";
         case "delegate-gate":
-            return "read-only";
+            return argv.some((a) => a === "--fix" || a === "-fix") ? "mutating" : "read-only";
         case "mcp":
             return "read-only";
+        case "dispatch":
+            return argv.some((a) => a === "--exhausted" || a === "-x") ? "mutating" : "read-only";
         default:
             return "read-only";
     }
 }
 export async function run() {
+    const optionError = commandOptionError(process.argv);
+    if (optionError !== null) {
+        process.stderr.write(`${optionError}\n`);
+        process.exit(1);
+        return;
+    }
     const command = rawCliCommand(process.argv);
     if (command === "cooldowns")
         parseCooldownClearArgs(process.argv);