llm-relay 0.80.0 → 0.82.0

package/dist/dispatch.d.ts

@@ -2,6 +2,7 @@ import type { Config, LadderRung } from "./config-types.js";
 import type { HostRoutingState } from "./host-routing.js";
 import type { ContextWindowSource, ResolvedContextWindow } from "./metadata.js";
 import { type LaneManifest } from "./lane-manifest.js";
+import { type DispatchMode } from "./dispatch-lane-stats.js";
 /**
  * The dispatch ladder: which LANE a host agent should hand a delegated task to, in what order,
  * and what to do when one is spent.
@@ -40,6 +41,15 @@ export declare const MAX_EXHAUSTED_MS: number;
  */
 export type DispatchOutcome = "rate_limited" | "quota_exhausted";
 export declare const OUTCOME_DEFAULT_MS: Record<DispatchOutcome, number>;
+/** The ceiling a RAISED budget stops at — the same one-hour ceiling `attemptMs` is bounded by. */
+export declare const MAX_ATTEMPT_BUDGET_MS = 3600000;
+/**
+ * Own failures in a row after which a lane cannot be relied on to answer. `runWalk` will not stop
+ * an earlier lane that is still working in order to reach lanes that are all past this streak.
+ */
+export declare const LANE_UNRELIABLE_STREAK = 3;
+/** Own failures in a row after which a lane is ordered behind the lanes that have none. */
+export declare const FAILING_LANE_STREAK = 5;
 export type LaneState = "ready" | "exhausted" | "disabled" | "not-servable";
 /**
  * Advisory per-lane execution stats for one ladder rung: how often this config took the lane
@@ -90,6 +100,7 @@ export declare function formatAttemptBudget(budget: {
     basis: "history" | "floor" | "clamped";
     samples: number;
     quantileMs?: number;
+    raisedBy?: number;
 }): string;
 export interface DispatchLane {
     id: string;
@@ -232,6 +243,16 @@ export interface DispatchLane {
          * came to read and `ms` is not it. Never a guess: absent unless a quantile was computed.
          */
         quantileMs?: number;
+        /**
+         * How many times the budget was DOUBLED because the walk abandoned this lane since its last
+         * success (`LaneStats.abandonedSinceSuccess`). Present only when above zero.
+         *
+         * ⚠ It exists because an abandoned run leaves no duration sample, so a window fed only by runs
+         * that finished inside the budget can never show that the lane needed longer — the floor lock
+         * measured on 2026-09-10 (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §3b). Each abandonment
+         * doubles the next budget, capped at `MAX_ATTEMPT_BUDGET_MS`; one success resets the count.
+         */
+        raisedBy?: number;
     };
     /**
      * This lane recently failed to answer inside the budget a dispatch walk gave it, so ready lanes
@@ -253,6 +274,44 @@ export interface DispatchLane {
         until: string;
         reason: string;
     };
+    /**
+     * The lane's usual time to ANSWER in the requested mode: median and 80th percentile of the
+     * durations in the window its budget was read from — since 2026-09-10 only a COMPLETED run adds
+     * one, and `restoreLaneStatsRows` empties an older window that provably holds anything else.
+     * Present only when that window holds a duration. A poll renders it (`describeJob` in `mcp/server.ts`), so a caller can tell a slow
+     * lane from a stuck one — 23 of the 182 unanswered dispatches in the 2026-09-10 transcript sweep
+     * ended with the caller simply no longer polling.
+     */
+    timeToAnswer?: {
+        medianMs: number;
+        p80Ms: number;
+        samples: number;
+        mode: DispatchMode | null;
+    };
+    /**
+     * Own failures (`failed` or `timed_out`, never a walk abandonment) in a row, read from the same
+     * window as the budget. Present only when above zero.
+     *
+     * ⚠ Evidence the walk reads: a later lane on a streak of `LANE_UNRELIABLE_STREAK` or more cannot
+     * be relied on to answer, so the walk does not stop an earlier lane that is still working in
+     * order to reach it (`runWalk`). Measured 2026-09-10: the walk stopped `free-pool` at 90 s to try
+     * `opencode-muse-spark` (0 of 12), `agy-claude-opus` (0 of 34) and `anthropic` (0 of 21).
+     */
+    recentFailures?: number;
+    /**
+     * Set at `FAILING_LANE_STREAK` own failures in a row: the lane is ordered behind every lane that
+     * has none, the same band as a walk demotion, until it answers again. Demoted, never dropped.
+     */
+    failing?: {
+        streak: number;
+        reason: string;
+    };
+    /**
+     * Not a ladder rung: built for ONE dispatch from a caller-named `model`. Never reported to
+     * `/dispatch/telemetry`, which knows only ladder lane ids; its HTTP traffic is metered by the
+     * relay's own pipeline anyway.
+     */
+    adHoc?: true;
 }
 export interface DispatchView {
     /** Selected tier-specific ladder, or null when using the legacy single ladder. */
@@ -328,6 +387,27 @@ export interface DispatchOptions {
      * existed. Never guess a number here: see `specContextWindow`.
      */
     publishedContextWindow?: (spec: string) => ResolvedContextWindow | null;
+    /**
+     * WHO is asking, when that changes what can run. `"mcp"` is the `llm-relay mcp` server: it runs
+     * lanes itself and has no `Agent` tool, so a pass-through relay rung — one that forwards the
+     * caller's own Anthropic credential — can never run there. It comes back `unreachable`, never as a
+     * lane the walk tries and fails in 0 s (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §4).
+     * Absent ⇒ exactly the behaviour before this existed.
+     */
+    requester?: "mcp";
+    /**
+     * The mode the caller will run lanes in, so each lane's budget comes from runs of the SAME mode
+     * (`attemptBudget`). Absent ⇒ the mode-less legacy window, as before this existed.
+     */
+    mode?: DispatchMode;
+    /**
+     * A routing spec (`deepseek/deepseek-flash`, `pool/high`, …) to run as its OWN one-lane view
+     * instead of the ladder. Validated against the configured providers and pools: an unknown spec
+     * yields no lane and a reason. `dispatch` could not name a model before 2026-09-10, so agents that
+     * had to use DeepSeek wrote their own HTTP calls to the relay
+     * (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §7).
+     */
+    model?: string;
 }
 /**
  * Report a rung spent (quota gone, rate-limited, CLI missing). Rungs sharing a `quota` bucket
@@ -339,6 +419,25 @@ export interface DispatchOptions {
 export declare function markExhausted(cfg: Config, id: string, ttlMs?: number, tier?: string): boolean;
 /** Clear one rung's cooldown, or every cooldown for this config when no id is given. */
 export declare function clearExhausted(cfg: Config, id?: string, tier?: string): void;
+/**
+ * What a tier-scoped ladder lookup found: the tier the ladder resolved to (`null` for the legacy
+ * single ladder), the rung when the id names one ON THAT LADDER, and — when `routing.ladders`
+ * exists but holds no ladder under the requested name — that name, so a caller can say so.
+ */
+export interface LadderRungLookup {
+    tier: string | null;
+    rung: LadderRung | undefined;
+    missingTier: string | undefined;
+}
+/**
+ * The tier-scoped rung lookup — the ONE resolution `markExhausted`, `clearExhausted` and the
+ * operator pin in `routes/admin.ts` share. It answers with the SAME `(tier, rung)` pair
+ * `buildDispatch` annotates a view with (`selectLadder` on both sides), which is what makes a
+ * pin recorded through it land where the next `GET /dispatch` reads. ⚠ Distinct from
+ * `findLadderRung`, which is tier-AGNOSTIC (a telemetry report names a lane, not a tier); a
+ * memory or a cooldown written here is keyed by tier, so the lookup must be too.
+ */
+export declare function lookupLadderRung(cfg: Config, laneId: unknown, tier?: string): LadderRungLookup;
 /**
  * One exported/persisted cooldown row: the raw map key (`rung:<id>` / `quota:<name>`) and its
  * absolute expiry in epoch ms. The KEY travels, not the rung, because a bucket outlives any one
@@ -408,6 +507,18 @@ export declare const CONTEXT_TOKEN = "{contextWindow}";
 export declare function specContextWindow(spec: string, cfg: Config, published: (spec: string) => ResolvedContextWindow | null): (ResolvedContextWindow & {
     unknownMembers: number;
 }) | null;
+/**
+ * Does `spec` reach only the caller's own pass-through vendor (`reachableWithoutRelay`)? Exported
+ * for the MCP server, which filters such a lane out of a walk itself when its view came from a
+ * daemon older than `requester=mcp` — a version-skew guard, because the daemon started at logon
+ * routinely runs older code than a freshly spawned MCP process.
+ */
+export declare function isPassThroughSpec(spec: string, cfg: Config): boolean;
+/**
+ * Why the MCP server cannot run a pass-through rung — the ONE wording, used for the `unreachable`
+ * verdict here and by the MCP server's own fallback text, so the two never disagree.
+ */
+export declare function mcpPassThroughReason(spec: string): string;
 /**
  * Resolve command names whose Windows shell semantics differ from their POSIX spelling.
  *
@@ -418,6 +529,28 @@ export declare function specContextWindow(spec: string, cfg: Config, published:
  * deliberately narrow: explicit paths and every other configured command remain authoritative.
  */
 export declare function normalizeCliCommand(command: string, platform?: NodeJS.Platform): string;
+/**
+ * Where the windowless-console launcher lives, if the operator has installed one.
+ *
+ * Not shipped by this package or by any of its installers (verified: no `lane-launch.ps1` exists
+ * anywhere under this repository) — it is a hand-maintained artifact documented in CLAUDE.md's AGY
+ * lane notes and `docs/agy-popup-fix-2026-09-07.md`. So absence is the ORDINARY case on a fresh
+ * machine and on every non-Windows host, not a misconfiguration to warn about. Resolved through the
+ * same config-kind XDG base every other operator-authored artifact under this directory uses
+ * (`state-paths.ts`), so an XDG override on the config side moves this alongside `config.json`
+ * itself — matching where every hand-authored `cli` ladder rung already points its own `-File`
+ * argument. (`state-paths.ts` stays the one module naming the XDG variables directly, per
+ * `test/state-paths.test.ts` — this reaches them only through `relayStatePath`.)
+ *
+ * Deliberately the ONE impure seam in this module (the `buildDispatch`/`platform` precedent): every
+ * function below it stays pure over a caller-resolved `launcherPath: string | null`. ⚠ Guarded like
+ * `winenv.ts`/`os-keyring.ts`/`lane-runner.ts`'s default spawner: under vitest, a caller that omits
+ * `exists` gets `null` unconditionally rather than the real filesystem — a suite must never depend
+ * on whether THIS machine happens to have the launcher installed (it does), which is exactly what
+ * broke `routes/admin.ts` and `cli.ts`'s own call sites (neither injects a seam) before this guard
+ * existed. A test that wants the real check injects `exists` itself, same as every seam above it.
+ */
+export declare function resolveLaneLauncherPath(platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;
 /**
  * Every rung across EVERY ladder the config declares — each tiered ladder, then the legacy
  * single ladder. The ONE ladder walk: `POST /dispatch/telemetry` (unknown-lane 400) and the
@@ -433,7 +566,16 @@ export declare function allLadderRungs(cfg: Config): LadderRung[];
  * shared lookup both branches mean — one walk, not two.
  */
 export declare function findLadderRung(cfg: Config, laneId: string): LadderRung | undefined;
-export declare function buildDispatch(cfg: Config, rawOpts?: DispatchOptions, platform?: NodeJS.Platform): DispatchView;
+/**
+ * Render a caller-supplied id for a `reason` string. The reason is reflected back verbatim in the
+ * JSON response AND printed to a terminal by `llm-relay dispatch`, so echoing raw caller input let
+ * a `?lane=` carrying ESC sequences rewrite the operator's terminal, and an arbitrarily long one
+ * bloat a response about a lane that does not exist. Control characters go, and the echo is capped
+ * — enough to recognise your own typo, not a channel. Exported for `routes/admin.ts`, whose
+ * `POST /dispatch` 400s echo a caller-supplied lane id or tier under the same rule.
+ */
+export declare function describeId(id: string): string;
+export declare function buildDispatch(cfg: Config, rawOpts?: DispatchOptions, platform?: NodeJS.Platform, launcherPath?: string | null): DispatchView;
 export declare const AUTO_TIERS: readonly ["low", "medium", "high", "xhigh"];
 export type AutoTier = (typeof AUTO_TIERS)[number];
 export declare function normalizeAutoTier(tier?: string | null): string;