llm-relay 0.80.0 → 0.82.0

package/dist/mcp/server.d.ts

@@ -22,9 +22,11 @@
  */
 import type { Config } from "../config.js";
 import type { DispatchView } from "../dispatch.js";
-import type { DispatchedTelemetryReport } from "../dispatch-lane-stats.js";
-import { type AnswerFetch, type LaneSpawner, type DispatchedQuotaReport } from "./lane-runner.js";
+import type { DispatchedTelemetryReport, DispatchMode } from "../dispatch-lane-stats.js";
+import { type AnswerFetch, type LaneJob, type LaneSpawner, type DispatchedQuotaReport } from "./lane-runner.js";
+import { type AgyLogSnapshot } from "./agy-quota-log.js";
 import { type JobJournal } from "./job-journal.js";
+import { type JobArchive } from "./job-archive.js";
 export declare const MCP_SERVER_NAME = "llm-relay";
 /** `max_tokens` for an answer-mode call when the caller names none. */
 export declare const DEFAULT_ANSWER_MAX_TOKENS = 4096;
@@ -37,6 +39,13 @@ export type DispatchViewBuilder = (opts: {
     task: string | undefined;
     tier: string | undefined;
     lane: string | undefined;
+    /**
+     * How this dispatch will run its lanes, so the relay hands back budgets measured in the SAME mode
+     * (`DispatchMode`). Absent from `dispatch_lanes`, which runs nothing.
+     */
+    mode?: DispatchMode | undefined;
+    /** A routing spec to run as its own one-lane view instead of the ladder (`dispatch`'s `model`). */
+    model?: string | undefined;
 }) => Promise<DispatchView>;
 export interface McpServerDeps {
     config: Config;
@@ -74,6 +83,24 @@ export interface McpServerDeps {
      * real one, so a host-launched server can report the jobs a previous instance died holding.
      */
     journal?: JobJournal;
+    /**
+     * The finished-job archive. Absent ⇒ `nullJobArchive`, which keeps nothing. `cli.ts` passes the
+     * real one, so a job that ENDED before a restart still answers `dispatch_result` afterwards and
+     * job ids continue past the highest one the previous process minted (`job-archive.ts`).
+     */
+    archive?: JobArchive;
+    /**
+     * The llm-relay version INSTALLED on disk now, read fresh on each call — or null when unknown.
+     * When it differs from `version` (the code this process started with), every tool reply says so:
+     * the Claude desktop app keeps one MCP process alive across sessions and releases, and on
+     * 2026-09-10 two processes from before v0.78.0 were still serving old code with no sign of it.
+     */
+    installedVersion?: () => string | null;
+    /**
+     * AGY's log, read after an AGY lane ends or is stopped, so a quota death AGY stated only in its
+     * log still reaches the relay (`agy-quota-log.ts`). Absent ⇒ never read.
+     */
+    readAgyLog?: () => AgyLogSnapshot | null;
     write: (chunk: string) => void;
 }
 /**
@@ -108,6 +135,16 @@ export type ResolvedWaitMs = {
     refusal: string;
 };
 export declare function resolveWaitMs(requested: unknown, ceiling: number): ResolvedWaitMs;
+/**
+ * A RUNNING spawned attempt's output so far: how long the lane has been silent, or how much it has
+ * written and how long ago. Null for anything else — a finished job, or an answer-mode call, which
+ * has no output stream and must not read as "silent".
+ *
+ * ⚠ The zero-output line says why silence alone proves nothing: `claude -p` buffers its whole
+ * answer until exit. Without that, a caller reading "silent for 300 s" on the free pool would cancel
+ * a healthy run — the false failure the backlog item names as worse than an honest slow status.
+ */
+export declare function describeActivity(job: LaneJob, now: number): string | null;
 /**
  * What a caller is told when the walk tried every lane it had and none of them answered.
  *
@@ -132,9 +169,24 @@ export declare const LANE_LADDER_EXHAUSTED_ADVICE: string;
  * (found by adversarial review, 2026-09-06). Both of its sentences were then false: lanes remained,
  * and "it would pick the same lanes" is wrong precisely because the walk has just DEMOTED every
  * lane it tried, so the next dispatch reorders around them. Telling an autonomous caller to stop
- * delegating, on a false premise, abandons free capacity that was never contacted.
+ * delegating, on a false premise, abandons capacity that was never contacted.
  */
 export declare const LANE_LADDER_PARTIAL_ADVICE: string;
+/**
+ * What a caller is told when the walk STOPPED a lane at its time budget and nothing answered after.
+ *
+ * ⚠ The stopped lane did not fail: it was still working when the walk moved on. So "every dispatch
+ * lane has now been tried" was false there, and it ended the caller's use of dispatch for a task the
+ * stopped lane would have finished (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §5). A NAMED lane
+ * runs with no budget, so this names the call that lets it finish.
+ */
+export declare function laneStoppedAdvice(laneId: string): string;
+/**
+ * What a caller is told when it NAMED the lane or the model and that one lane did not answer. Only
+ * that lane ran, so "every dispatch lane has now been tried" would be false — measured 2026-09-10 on
+ * jobs 0023 and 0024, which each ran one forced lane and were told to stop delegating.
+ */
+export declare const FORCED_LANE_ADVICE: string;
 export declare class McpDispatchServer {
     private readonly deps;
     private readonly jobs;
@@ -173,18 +225,51 @@ export declare class McpDispatchServer {
      * takes the loop down. Resolves after the source ends AND every handler it started has settled.
      */
     serve(source: AsyncIterable<string>): Promise<void>;
-    /** Kill every running child. Wired to process exit so nothing is orphaned. */
+    /**
+     * Kill every running child, then flush the finished-job archive. Wired to process exit so nothing
+     * is orphaned and nothing the archive still owes to disk is lost on a graceful stop (a hard kill
+     * is covered by the archive's eager terminal writes — `job-archive.ts`).
+     */
     shutdown(): void;
     private send;
     private handleLine;
     private route;
     private initialize;
     private callTool;
+    private runTool;
+    /**
+     * Append a notice to a tool reply when this process runs OLDER code than the version installed on
+     * disk. The Claude desktop app keeps one MCP process alive across sessions and releases, and on
+     * 2026-09-10 two processes from before v0.78.0 were still serving old code with nothing to say so.
+     * Only a plain one-block text reply is touched; anything else passes through unchanged. A version
+     * that cannot be read is unknown, and unknown adds nothing.
+     */
+    private withVersionNotice;
     private toolLanes;
     private toolStatus;
     private toolResult;
     private toolCancel;
     private toolDispatch;
+    /**
+     * The lanes this dispatch will try, best first, and how many selectable lanes it leaves untried.
+     *
+     * `view.order` is the ONE definition of selection order (`dispatch.ts`). With the walk turned off
+     * — or with a view that carries no order — this collapses to EXACTLY the pre-walk behaviour: the
+     * single lane the view named as `next`, tried once, with no attempt budget.
+     *
+     * ⚠ The `Array.isArray` test is a VERSION SKEW guard, not defensive noise. `buildView` reaches the
+     * running daemon over HTTP, and a daemon started before this field existed answers without it — an
+     * MCP child upgraded ahead of a long-running daemon is the normal state on a machine that starts
+     * the relay at logon and leaves it up for days. Reading `.length` off `undefined` there would throw
+     * on EVERY dispatch, turning a new optional field into a total outage.
+     *
+     * ⚠ A second skew guard: a daemon older than `requester=mcp` still offers a pass-through rung as
+     * ready, and this process can never run one (`mcpPassThroughReason`). Such a lane is dropped from an
+     * UNFORCED walk here; a caller who named it still reaches it and reads why it cannot run.
+     */
+    private walkOrder;
+    /** A pass-through relay lane — one this process cannot run (`walkOrder`). Never throws. */
+    private isPassThroughLane;
     /**
      * Try each lane in turn until one answers. THE JOB IS THE WALK.
      *
@@ -199,6 +284,16 @@ export declare class McpDispatchServer {
      * with it. Only a caller error ends the walk early — see `refusal` on `LaneAttemptOutcome`.
      */
     private runWalk;
+    /**
+     * Does the lane at position `i` run with NO attempt budget? The last lane does — there is nowhere
+     * to move to. So does a lane whose later lanes are all unlikely to answer: each is on a streak of
+     * `LANE_UNRELIABLE_STREAK` own failures or more, or marked `failing`. Stopping a lane that may
+     * still answer in order to reach those trades an answer for a near-certain failure — measured
+     * 2026-09-10, when the walk stopped `free-pool` at 90 s to try lanes that had answered 0 of 12,
+     * 0 of 34 and 0 of 21 runs (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §1). A lane with no
+     * record counts as reliable: unmeasured is no opinion, never a failure.
+     */
+    private budgetWithheld;
     /**
      * A `cli` rung whose configured `maxConcurrent` this MCP server process has already reached for
      * — SKIP it for this walk rather than starting a competing process. Records the skip as an
@@ -211,6 +306,18 @@ export declare class McpDispatchServer {
      * always `null`, so this returns `false` for one without needing a `kind` check of its own.
      */
     private skipIfAtConcurrencyCap;
+    /**
+     * For a read-only dispatch, the invocation this lane will be spawned with — its own CLI's
+     * read-only tool binding (`readOnlyInvoke`) — or a SKIP when its CLI offers none. Recorded exactly
+     * like a concurrency-cap skip: an attempt in the walk's own record, `lanesNotTried` grown so the
+     * terminal advice is PARTIAL rather than EXHAUSTED, nothing spawned, no telemetry, no demotion —
+     * a lane the relay declined to run unbound has not failed.
+     *
+     * Not consulted at all for an ordinary dispatch, for an answer-mode relay call (no harness, so
+     * nothing to bind), or for a lane with no invocation (the existing "cannot be run from here" path
+     * reports that on its own).
+     */
+    private bindReadOnlyOrSkip;
     /**
      * Run ONE lane, optionally bounded by an attempt budget. Returns what happened; never throws.
      *
@@ -236,10 +343,27 @@ export declare class McpDispatchServer {
      */
     private startLane;
     /**
-     * Forward one lane-execution report after an agent-mode job reaches a terminal state.
-     * Never a RELAY-kind answer-mode job (the daemon's HTTP pipeline already accounts it —
-     * finding F3); a `cli`-kind rung dispatched with `mode: "answer"` spawns like agent mode
-     * and IS forwarded. A cancelled job is discarded, never reported.
+     * Settle a spawned lane's run. A quota death the lane states — in its own output, or for an AGY
+     * lane in AGY's own log — is reported to the relay; a content-empty answer is a failure.
+     *
+     * ⚠ It also runs for a lane the walk STOPPED: the killed child still settles here, so a death AGY
+     * stated only in its log reaches the relay although the walk has moved on. The outcome itself is
+     * discarded in that case — `runOneLane` already returned `abandoned`.
+     */
+    private settleSpawnedRun;
+    /**
+     * The quota death an AGY lane stated only in AGY's own log (`agy-quota-log.ts`). AGY retries a
+     * spent quota in silence, so a lane stopped by the walk or by its own timeout printed nothing, and
+     * the death reached the relay only when a run happened to last its whole length
+     * (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §4). Undefined unless the lane is AGY, names its
+     * model, and the log is provably this run's — `agyQuotaStatement` refuses everything else.
+     */
+    private agyLogReport;
+    /**
+     * Forward one lane-execution report per ATTEMPT, for both lane kinds: the daemon records the
+     * lane's stats and routing memory from these, and skips the ledger row for a `relay` lane on its
+     * own because the HTTP pipeline already accounts it. Never for a cancelled job, and never for an
+     * ad-hoc lane (`DispatchLane.adHoc`), which the daemon has no rung to record against.
      *
      * Fire-and-forget by design: the reporter is never awaited on the response path, and a
      * throwing or rejecting reporter is swallowed after ONE metadata-only stderr line (lane id