llm-relay 0.71.1 → 0.72.0

package/dist/cli.d.ts

@@ -3,6 +3,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 type { DispatchedTelemetryReport } from "./dispatch-lane-stats.js";
 import { ModelCatalog } from "./catalog.js";
 import { type CommandEffect } from "./self-update.js";
 import { type KeysCliDependencies } from "./keys-cli.js";
@@ -154,6 +155,14 @@ 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>;
+/**
+ * Forward one MCP lane-execution report to the live relay's `POST /dispatch/telemetry`.
+ *
+ * ⚠ Asymmetry with `reportMcpExhaustion` is deliberate: it throws because a lost quota
+ * report changes routing; a lost telemetry row changes only a ledger, so this is
+ * best-effort — false when no proxy answered, and it NEVER throws.
+ */
+export declare function reportMcpTelemetry(cfg: Config, report: DispatchedTelemetryReport, request?: DispatchReportRequest): Promise<boolean>;
 /** 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>;
@@ -227,6 +236,12 @@ export interface CostCommandDependencies {
     readonly exit?: (code: number) => never;
     /** Overrides the store directory; defaults to the production `~/.llm-relay/usage/`. */
     readonly usageDir?: string;
+    /**
+     * Loads the relay config for the `--by model` lane-id footnote. Defaults to the live
+     * `loadOrExit`; tests inject a config holding the ladder under test. Read ONLY when
+     * `--by model` is asked — every other dimension must keep working config-less.
+     */
+    readonly loadConfig?: () => Config;
 }
 /**
  * `llm-relay cost` — the C1 roll-up (open-decisions-2026-08-16.md C1): what did this
@@ -287,6 +302,13 @@ export type WireDispatchView = Omit<DispatchView, "host"> & {
 };
 /** Normalize structured output from an older live proxy before exposing it to this host. */
 export declare function normalizeDispatchCommands(view: WireDispatchView, platform?: NodeJS.Platform): DispatchView;
+/**
+ * Substitute `{task}` placeholder into lane arguments and set `view.task`.
+ * Applied locally so dispatch view queries never need to send arbitrary task text in HTTP query strings.
+ */
+export declare function substituteTaskInView(view: DispatchView, task: string | undefined): DispatchView;
+/** Safely reload configuration from disk without exiting if unreadable. */
+export declare function loadConfigSafely(): Config | null;
 /** Which shell's literal-quoting rules a rendered command line is written for. */
 export type RenderShell = "sh" | "pwsh";
 /** Human name for the shell a line was quoted for. Precise on purpose — see `quoteArg`. */

package/dist/cli.js

@@ -14,7 +14,7 @@ import { CREDENTIAL_LABEL_PATTERN, makeCredentialId } from "./credential-id.js";
 import { providerCredentialSlots, slotAllowsModel } from "./credential-fleet.js";
 import { loadLaneManifest, rosterIsStale, verifyModel } from "./lane-manifest.js";
 import { probeLanes } from "./lane-probe.js";
-import { buildDispatch, normalizeCliCommand, restoreExhaustedRows, specContextWindow, CONTEXT_TOKEN } from "./dispatch.js";
+import { buildDispatch, allLadderRungs, normalizeCliCommand, restoreExhaustedRows, specContextWindow, CONTEXT_TOKEN, TASK_TOKEN, formatLaneStats } from "./dispatch.js";
 import { McpDispatchServer } from "./mcp/server.js";
 import { loadExhaustedRows } from "./dispatch-exhaustion-persistence.js";
 import { detectHostRouting, parseHostRoutingState } from "./host-routing.js";
@@ -851,6 +851,19 @@ export async function reportMcpExhaustion(cfg, report, request = tryServer) {
     if (live === null)
         throw new Error("no proxy running — quota report not recorded");
 }
+export async function reportMcpTelemetry(cfg, report, request = tryServer) {
+    try {
+        const live = await request(cfg, "/dispatch/telemetry", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(report),
+        });
+        return live !== null;
+    }
+    catch {
+        return false;
+    }
+}
 export function proxyUrl(cfg, path) {
     const host = cfg.host.includes(":") ? `[${cfg.host}]` : cfg.host;
     return `http://${host}:${cfg.port}${path}`;
@@ -1318,7 +1331,17 @@ export async function runCostCommand(dependencies = {}) {
             write(JSON.stringify(report, null, 2) + "\n");
             return;
         }
-        renderCostReport(report, write);
+        let cliLaneIds;
+        if (by === "model") {
+            try {
+                const cfg = (dependencies.loadConfig ?? loadOrExit)();
+                cliLaneIds = new Set(allLadderRungs(cfg).filter((rung) => rung.kind === "cli").map((rung) => rung.id));
+            }
+            catch {
+                cliLaneIds = undefined;
+            }
+        }
+        renderCostReport(report, write, cliLaneIds === undefined ? {} : { cliLaneIds });
     }
     finally {
         store.close();
@@ -1399,7 +1422,7 @@ function writeCoveredPeriod(from, to, generatedAt, write) {
     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) {
+function renderCostReport(report, write, opts = {}) {
     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");
         return;
@@ -1416,6 +1439,17 @@ function renderCostReport(report, write) {
         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");
     }
     write(`${formatTextTable(rows)}\n`);
+    if (report.by === "client" && report.rows.some((row) => row.key === "mcp-dispatch")) {
+        write("mcp-dispatch rows are the estimated dispatch envelope (task text + lane output), not the lane's provider consumption, which the relay cannot see; they are unpriced.\n");
+    }
+    if (report.by === "model" && opts.cliLaneIds !== undefined) {
+        const laneKeys = [...new Set(report.rows
+                .map((row) => row.key)
+                .filter((key) => opts.cliLaneIds.has(key) || opts.cliLaneIds.has(key.slice(key.indexOf("/") + 1))))].sort();
+        if (laneKeys.length > 0) {
+            write(`Rows keyed by cli lane id (${laneKeys.join(", ")}) are the estimated dispatch envelope (task text + lane output), not the lane's provider consumption, which the relay cannot see; they are unpriced.\n`);
+        }
+    }
     writeRepairShare(report, write);
     writeAbandonedShare(report, write);
     if (report.coverage === "partial") {
@@ -1457,6 +1491,42 @@ export function normalizeDispatchCommands(view, platform = process.platform) {
         next: view.next ? normalizeLane(view.next) : null,
     };
 }
+export function substituteTaskInView(view, task) {
+    if (!task)
+        return view;
+    const substituteArgs = (args) => args.map((a) => a.split(TASK_TOKEN).join(task));
+    const substituteLane = (lane) => {
+        if (!lane.invoke)
+            return lane;
+        return {
+            ...lane,
+            invoke: {
+                ...lane.invoke,
+                args: substituteArgs(lane.invoke.args),
+            },
+        };
+    };
+    return {
+        ...view,
+        task,
+        ladder: view.ladder.map(substituteLane),
+        next: view.next ? substituteLane(view.next) : null,
+    };
+}
+export function loadConfigSafely() {
+    try {
+        const configPath = resolveConfigPath();
+        const overrides = {
+            routeDefault: argValue("--default", "-d"),
+            mode: argValue("--mode", "-m"),
+            listen: argValue("--listen", "-l"),
+        };
+        return loadConfig(configPath, overrides);
+    }
+    catch {
+        return null;
+    }
+}
 export const SHELL_LABEL = {
     sh: "sh/bash",
     pwsh: "PowerShell 7+ (pwsh)",
@@ -1580,8 +1650,6 @@ ${lane} — ${entry.models.length} models, probed ${entry.probedAt} via \`${entr
 export async function resolveDispatchView(opts) {
     const cfg = opts.cfg ?? loadOrExit();
     const qs = new URLSearchParams();
-    if (opts.task)
-        qs.set("task", opts.task);
     if (opts.lane)
         qs.set("lane", opts.lane);
     if (opts.tier)
@@ -1599,16 +1667,20 @@ export async function resolveDispatchView(opts) {
     const liveRaw = (await tryServer(cfg, `/dispatch?${qs}`));
     const live = liveRaw !== null && liveRaw.host === "bypassed" ? liveRaw : null;
     restoreExhaustedRows(cfg, loadExhaustedRows());
-    return normalizeDispatchCommands(live ??
-        buildDispatch(cfg, {
-            ...(opts.task ? { task: opts.task } : {}),
-            ...(opts.lane ? { lane: opts.lane } : {}),
-            ...(opts.tier ? { tier: opts.tier } : {}),
-            ...(opts.client ? { client: opts.client } : {}),
-            host: "bypassed",
-            publishedContextWindow: cachedContextWindow,
-            manifest: loadLaneManifest(),
-        }));
+    if (live !== null) {
+        const view = normalizeDispatchCommands(live);
+        return substituteTaskInView({ ...view, source: "daemon" }, opts.task);
+    }
+    const fallbackCfg = loadConfigSafely() ?? cfg;
+    const fallbackView = normalizeDispatchCommands(buildDispatch(fallbackCfg, {
+        ...(opts.lane ? { lane: opts.lane } : {}),
+        ...(opts.tier ? { tier: opts.tier } : {}),
+        ...(opts.client ? { client: opts.client } : {}),
+        host: "bypassed",
+        publishedContextWindow: cachedContextWindow,
+        manifest: loadLaneManifest(),
+    }));
+    return substituteTaskInView({ ...fallbackView, source: "local-fallback" }, opts.task);
 }
 export async function runMcp() {
     const cfg = loadOrExit();
@@ -1619,6 +1691,7 @@ export async function runMcp() {
         ...(allowedRoots ? { allowedRoots } : {}),
         version: currentVersion(),
         reportExhaustion: (report) => reportMcpExhaustion(cfg, report),
+        reportTelemetry: (report) => { void reportMcpTelemetry(cfg, report); },
         write: (chunk) => process.stdout.write(chunk),
     });
     const stop = () => {
@@ -1693,8 +1766,6 @@ export async function runDispatch(arg) {
         await recordSpentDispatchLane(cfg, spent, { tier, client, outcome, retryAfterMs });
     }
     const qs = new URLSearchParams();
-    if (task)
-        qs.set("task", task);
     if (lane)
         qs.set("lane", lane);
     if (after)
@@ -1725,9 +1796,8 @@ export async function runDispatch(arg) {
     const staleProxy = hostStale || windowStale;
     const live = staleProxy ? null : liveRaw;
     restoreExhaustedRows(cfg, loadExhaustedRows());
-    const view = normalizeDispatchCommands(live ??
+    const rawView = normalizeDispatchCommands(live ??
         buildDispatch(cfg, {
-            ...(task ? { task } : {}),
             ...(lane ? { lane } : {}),
             ...(after ? { after } : {}),
             ...(tier ? { tier } : {}),
@@ -1737,6 +1807,7 @@ export async function runDispatch(arg) {
             publishedContextWindow: cachedContextWindow,
             manifest: loadLaneManifest(),
         }));
+    const view = substituteTaskInView(rawView, task);
     if (hasFlag("--json")) {
         process.stdout.write(JSON.stringify(view, null, 2) + "\n");
         return;
@@ -1799,6 +1870,8 @@ export async function runDispatch(arg) {
         }
         if (l.note)
             process.stdout.write(`   note: ${l.note}\n`);
+        if (l.stats)
+            process.stdout.write(`   ${formatLaneStats(l.stats)}\n`);
     }
     if (renderedCli) {
         process.stdout.write(`\ncli lines are quoted for ${SHELL_LABEL[shell]} — the task is a single argument (--shell to change)\n`);