llm-relay 0.80.0 → 0.82.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/dist/backend.d.ts +43 -3
  2. package/dist/backend.js +0 -0
  3. package/dist/backend.js.map +1 -1
  4. package/dist/candidate-runner.d.ts +45 -9
  5. package/dist/candidate-runner.js +55 -22
  6. package/dist/candidate-runner.js.map +1 -1
  7. package/dist/catalog.d.ts +49 -0
  8. package/dist/catalog.js +18 -0
  9. package/dist/catalog.js.map +1 -1
  10. package/dist/circuit-breaker.d.ts +118 -1
  11. package/dist/circuit-breaker.js +96 -1
  12. package/dist/circuit-breaker.js.map +1 -1
  13. package/dist/cli.d.ts +3 -0
  14. package/dist/cli.js +23 -3
  15. package/dist/cli.js.map +1 -1
  16. package/dist/config/routing-parser.d.ts +1 -1
  17. package/dist/config/routing-parser.js +27 -1
  18. package/dist/config/routing-parser.js.map +1 -1
  19. package/dist/config-edit.js +70 -16
  20. package/dist/config-edit.js.map +1 -1
  21. package/dist/config-types.d.ts +62 -6
  22. package/dist/config-types.js +1 -1
  23. package/dist/config-types.js.map +1 -1
  24. package/dist/dashboard/.vite/manifest.json +2 -2
  25. package/dist/dashboard/assets/index-B2UQHoym.js +74 -0
  26. package/dist/dashboard/assets/index-DFEP3XPr.css +1 -0
  27. package/dist/dashboard/index.html +2 -2
  28. package/dist/dispatch-lane-stats.d.ts +59 -5
  29. package/dist/dispatch-lane-stats.js +96 -29
  30. package/dist/dispatch-lane-stats.js.map +1 -1
  31. package/dist/dispatch.d.ts +143 -1
  32. package/dist/dispatch.js +260 -98
  33. package/dist/dispatch.js.map +1 -1
  34. package/dist/lane-affinity.d.ts +8 -0
  35. package/dist/lane-affinity.js +10 -0
  36. package/dist/lane-affinity.js.map +1 -1
  37. package/dist/log.d.ts +16 -0
  38. package/dist/log.js +1 -0
  39. package/dist/log.js.map +1 -1
  40. package/dist/mcp/agy-quota-log.d.ts +37 -0
  41. package/dist/mcp/agy-quota-log.js +68 -0
  42. package/dist/mcp/agy-quota-log.js.map +1 -0
  43. package/dist/mcp/job-archive.d.ts +55 -0
  44. package/dist/mcp/job-archive.js +151 -0
  45. package/dist/mcp/job-archive.js.map +1 -0
  46. package/dist/mcp/lane-runner.d.ts +108 -5
  47. package/dist/mcp/lane-runner.js +93 -4
  48. package/dist/mcp/lane-runner.js.map +1 -1
  49. package/dist/mcp/readonly-boundary.d.ts +46 -0
  50. package/dist/mcp/readonly-boundary.js +119 -0
  51. package/dist/mcp/readonly-boundary.js.map +1 -1
  52. package/dist/mcp/server.d.ts +132 -8
  53. package/dist/mcp/server.js +267 -68
  54. package/dist/mcp/server.js.map +1 -1
  55. package/dist/openai-request.d.ts +8 -0
  56. package/dist/openai-request.js +33 -9
  57. package/dist/openai-request.js.map +1 -1
  58. package/dist/pacing.d.ts +125 -0
  59. package/dist/pacing.js +83 -0
  60. package/dist/pacing.js.map +1 -0
  61. package/dist/ping/cadence.d.ts +57 -0
  62. package/dist/ping/cadence.js +58 -0
  63. package/dist/ping/cadence.js.map +1 -1
  64. package/dist/refusal-interpretation.d.ts +24 -0
  65. package/dist/refusal-interpretation.js +10 -1
  66. package/dist/refusal-interpretation.js.map +1 -1
  67. package/dist/responses-request.d.ts +14 -1
  68. package/dist/responses-request.js +21 -4
  69. package/dist/responses-request.js.map +1 -1
  70. package/dist/routes/admin.d.ts +8 -0
  71. package/dist/routes/admin.js +122 -35
  72. package/dist/routes/admin.js.map +1 -1
  73. package/dist/routes/messages.d.ts +2 -0
  74. package/dist/routes/messages.js +7 -3
  75. package/dist/routes/messages.js.map +1 -1
  76. package/dist/routes/openai-front.d.ts +1 -0
  77. package/dist/routes/openai-front.js +7 -3
  78. package/dist/routes/openai-front.js.map +1 -1
  79. package/dist/server.d.ts +4 -0
  80. package/dist/server.js +28 -4
  81. package/dist/server.js.map +1 -1
  82. package/dist/setup-claude.d.ts +2 -2
  83. package/dist/setup-claude.js +3 -3
  84. package/dist/stream-commit.d.ts +65 -0
  85. package/dist/stream-commit.js +150 -8
  86. package/dist/stream-commit.js.map +1 -1
  87. package/dist/target-facts.js +3 -0
  88. package/dist/target-facts.js.map +1 -1
  89. package/dist/telemetry.d.ts +9 -1
  90. package/dist/telemetry.js +1 -1
  91. package/dist/telemetry.js.map +1 -1
  92. package/package.json +1 -1
  93. package/scripts/install-skill.mjs +2 -2
  94. package/skills/llm-relay/SKILL.md +5 -3
  95. package/skills/llm-relay/references/dispatch-lanes.md +8 -2
  96. package/dist/dashboard/assets/index-Bqtx14ES.css +0 -1
  97. package/dist/dashboard/assets/index-CetZdLCA.js +0 -74
@@ -1,10 +1,13 @@
1
1
  import { DEFAULT_MCP_MAX_WAIT_MS } from "../config-types.js";
2
2
  import { isToolUseBlock } from "../anthropic.js";
3
- import { formatAttemptBudget, formatLaneStats } from "../dispatch.js";
3
+ import { formatAttemptBudget, formatLaneStats, isPassThroughSpec, LANE_UNRELIABLE_STREAK, mcpPassThroughReason } from "../dispatch.js";
4
+ import { laneOfRung } from "../lane-manifest.js";
4
5
  import { estimateTokensFromCharacters } from "../metadata.js";
5
6
  import { DEFAULT_LANE_TIMEOUT_MS, DEFAULT_MAX_DEPTH, DEPTH_ENV, EMPTY_OUTPUT_REASON, LaneJobStore, SKIPPED_LANE_STATUS, attemptWasTried, classifyDispatchedResult, classifyLaneAttempt, checkCwd, currentDepth, defaultAnswerFetch, defaultLaneSpawner, isContentEmpty, readRelayAnnouncements, relayLoopbackUrl, } from "./lane-runner.js";
6
- import { readOnlyVerdict } from "./readonly-boundary.js";
7
+ import { readOnlyInvoke, readOnlyVerdict } from "./readonly-boundary.js";
8
+ import { agyQuotaStatement } from "./agy-quota-log.js";
7
9
  import { nullJobJournal } from "./job-journal.js";
10
+ import { nullJobArchive } from "./job-archive.js";
8
11
  import { RPC_INTERNAL_ERROR, RPC_INVALID_PARAMS, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, encodeMessage, errorResponse, isJsonRpcNotification, isJsonRpcRequest, logStderr, negotiateProtocolVersion, resultResponse, splitMessages, } from "./protocol.js";
9
12
  export const MCP_SERVER_NAME = "llm-relay";
10
13
  export const DEFAULT_ANSWER_MAX_TOKENS = 4096;
@@ -14,8 +17,9 @@ export const MCP_INSTRUCTIONS = "Use dispatch from every MCP host — Claude, Co
14
17
  "Reach for it on your own, without being asked. Offload a task when it is self-contained and " +
15
18
  "its result is a conclusion you can check: a broad code search, a file-by-file sweep, a " +
16
19
  "survey, a draft, a long summary, a second opinion. Keep in this session whatever needs your " +
17
- "own conversation context or edits you must supervise. The default lane is free capacity, so " +
18
- "offloading spends no subscription quota and saves this session's context. On Windows it " +
20
+ "own conversation context or edits you must supervise. The default lane is the relay's model " +
21
+ "pool: offloading spends none of this session's subscription quota and saves its context (the " +
22
+ "pool may spend the owner's paid provider credits, such as DeepSeek). On Windows it " +
19
23
  "centralizes hidden child creation, closes stdin so headless agents do not stall, and applies " +
20
24
  "each lane's configured timeouts. Prefer it over launching an agent alias from a shell. A " +
21
25
  "third-party CLI observed creating visible descendants must be disabled until reverified. " +
@@ -23,9 +27,12 @@ export const MCP_INSTRUCTIONS = "Use dispatch from every MCP host — Claude, Co
23
27
  "Desktop rejects that child model before reaching the relay and ignores its custom provider. " +
24
28
  "Call dispatch instead. If this MCP server is unavailable, run `llm-relay dispatch " +
25
29
  "--next-command -t <task>` and follow its returned command or target; do not guess from the host.\n\n" +
26
- "Do not switch lanes by hand. If a lane is slow or silent, dispatch moves to the next one " +
27
- "itself and prefers the lane that answered on your next call. When it reports that every lane " +
28
- "was tried, do the work here — re-dispatching the same task picks the same lanes.\n\n" +
30
+ "Let dispatch choose the lane. If a lane is slow or silent, dispatch moves to the next one " +
31
+ "itself and prefers the lane that answered on your next call. Follow the advice at the end of a " +
32
+ "reply: when it says a lane was stopped while it was still working, dispatch again with that " +
33
+ "lane named so it can finish; when it says every lane ran and failed, do the work here — " +
34
+ "re-dispatching the same task picks the same lanes. To run one specific model instead of the " +
35
+ "ladder (for example deepseek/deepseek-flash or pool/high), pass model.\n\n" +
29
36
  "Pass mode: \"answer\" for a question, draft, summary, or second opinion that needs no file " +
30
37
  "access — for a relay lane it posts straight to this relay's own /v1/messages with no spawned " +
31
38
  "harness, so it answers faster. Use the default agent mode when the lane must read or edit " +
@@ -35,11 +42,13 @@ const TOOLS = [
35
42
  {
36
43
  name: "dispatch",
37
44
  title: "Dispatch a task to another agent",
38
- description: "Hand a whole task to the best available agent lane (a free model pool, or a peer agent CLI " +
45
+ description: "Hand a whole task to the best available agent lane (a relay model pool, or a peer agent CLI " +
39
46
  "such as Codex or Antigravity) and return its answer. Reach for this without being asked " +
40
47
  "whenever a task is self-contained and its result is a conclusion you can check — a broad " +
41
48
  "code search, a file-by-file sweep, a survey, a draft, a second opinion — because the " +
42
- "default lane is free capacity and it saves this session's context. Picks the lane from " +
49
+ "default lane spends none of this session's subscription quota and saves its context. " +
50
+ "Pass model to run one specific model (a routing spec such as deepseek/deepseek-flash or " +
51
+ "pool/high) as its own lane, with no walk. Otherwise it picks the lane from " +
43
52
  "the configured ladder unless you name one, and WALKS that ladder for you: a lane that does " +
44
53
  "not answer inside its budget is stopped and the next one is started, and the lane that " +
45
54
  "answers is preferred next time. Runs the lane correctly — working directory, " +
@@ -90,6 +99,12 @@ const TOOLS = [
90
99
  type: "string",
91
100
  description: "Force a specific ladder rung by id instead of taking the ladder's own order.",
92
101
  },
102
+ model: {
103
+ type: "string",
104
+ description: "Run ONE specific model instead of the ladder: a routing spec such as " +
105
+ "deepseek/deepseek-flash, openrouter/<model> or pool/high. It runs as its own lane with " +
106
+ "no walk, in either mode. Cannot be combined with lane.",
107
+ },
93
108
  cwd: {
94
109
  type: "string",
95
110
  description: "Agent mode only: absolute directory to run the lane in. Defaults to this server's working directory.",
@@ -110,7 +125,11 @@ const TOOLS = [
110
125
  "rather than trusting the task text to say \"do not edit\": a measured read-only lane " +
111
126
  "committed and pushed the caller's in-progress files, and another silently reverted a " +
112
127
  "staged one. Pass cwd pointing at a separate checkout, or use mode \"answer\", which " +
113
- "spawns no harness and cannot touch the filesystem at all.",
128
+ "spawns no harness and cannot touch the filesystem at all. It ALSO binds the lane's " +
129
+ "TOOLS: a claude lane runs with only Read/Glob/Grep/WebFetch/WebSearch under " +
130
+ "--permission-mode dontAsk, a codex lane runs under --sandbox read-only, and a lane " +
131
+ "whose CLI offers no read-only binding (opencode, agy) is skipped with the reason " +
132
+ "rather than run unbound.",
114
133
  },
115
134
  },
116
135
  required: ["task"],
@@ -217,6 +236,43 @@ function isFailureStatus(status) {
217
236
  }
218
237
  }
219
238
  }
239
+ function formatTimeToAnswer(t) {
240
+ const s = (ms) => (ms === null ? "n/a" : `${Math.round(ms / 1000)}s`);
241
+ const inMode = t.mode ? `, ${t.mode} mode` : "";
242
+ const runs = `${t.samples} run${t.samples === 1 ? "" : "s"} on record${inMode}`;
243
+ return `usually answers in: median ${s(t.medianMs)}, p80 ${s(t.p80Ms)} (${runs})`;
244
+ }
245
+ function runningTimeToAnswer(job) {
246
+ if (job.status !== "running")
247
+ return null;
248
+ return job.expected
249
+ ? formatTimeToAnswer(job.expected)
250
+ : "usually answers in: not known (no completed run on record for this lane)";
251
+ }
252
+ export function describeActivity(job, now) {
253
+ if (job.status !== "running" || job.activity === undefined)
254
+ return null;
255
+ const a = job.activity;
256
+ const s = (ms) => `${Math.max(0, Math.round(ms / 1000))}s`;
257
+ if (a.lastOutputAt === null) {
258
+ return (`output: none yet — silent for ${s(now - a.attemptStartedAt)} since this lane started ` +
259
+ "(a lane that buffers its answer until exit, such as claude -p, is silent while it works)");
260
+ }
261
+ return (`output: ${a.stdoutBytes + a.stderrBytes} bytes so far (stdout ${a.stdoutBytes}, stderr ${a.stderrBytes}); ` +
262
+ `last output ${s(now - a.lastOutputAt)} ago`);
263
+ }
264
+ function laneEvidenceBits(lane) {
265
+ const bits = [];
266
+ if (lane.adHoc)
267
+ bits.push("(named by model, not a ladder rung)");
268
+ if (lane.timeToAnswer)
269
+ bits.push(formatTimeToAnswer(lane.timeToAnswer));
270
+ if (lane.failing)
271
+ bits.push(`failing: ${lane.failing.reason}`);
272
+ else if (lane.recentFailures)
273
+ bits.push(`${lane.recentFailures} own failure${lane.recentFailures === 1 ? "" : "s"} in a row`);
274
+ return bits;
275
+ }
220
276
  function describeJob(job, now) {
221
277
  const elapsed = Math.round(((job.endedAt ?? now) - job.startedAt) / 1000);
222
278
  const head = [
@@ -243,6 +299,16 @@ function describeJob(job, now) {
243
299
  head.push(`degraded: ${job.relay.degraded}`);
244
300
  if (job.dispatchSource === "fallback")
245
301
  head.push("dispatch-source: local-fallback (daemon unreachable)");
302
+ if (job.restored === true)
303
+ head.push("record: restored from disk — this job ended before the llm-relay MCP server last restarted");
304
+ if (job.readOnly)
305
+ head.push(`read-only: ${job.readOnly.binding}`);
306
+ const usually = runningTimeToAnswer(job);
307
+ if (usually !== null)
308
+ head.push(usually);
309
+ const output = describeActivity(job, now);
310
+ if (output !== null)
311
+ head.push(output);
246
312
  if (job.process?.survivors.length) {
247
313
  head.push(`owned processes STILL RUNNING after ${job.id} ended: ${job.process.survivors.join(", ")} ` +
248
314
  "(relay-started, not reaped)");
@@ -256,6 +322,25 @@ export const LANE_LADDER_EXHAUSTED_ADVICE = "Every dispatch lane has now been tr
256
322
  export const LANE_LADDER_PARTIAL_ADVICE = "Lanes remain untried: this dispatch stopped at its maxLanes bound. Call dispatch again to "
257
323
  + "reach them — the lanes above are now demoted, so it will pick different ones — or do the "
258
324
  + "work in this session.";
325
+ export function laneStoppedAdvice(laneId) {
326
+ return (`The walk stopped lane "${laneId}" at its time budget while it was still working — it did not ` +
327
+ `fail. To let it finish, call dispatch again with lane: "${laneId}" and the same tier and mode (a ` +
328
+ "named lane runs with no budget, only its own timeout), or do the work in this session.");
329
+ }
330
+ export const FORCED_LANE_ADVICE = "Only the lane you named was tried, and it did not answer. Call dispatch without lane or model to "
331
+ + "let the walk try the other lanes, or do the work in this session.";
332
+ function terminalAdvice(job) {
333
+ if (job.walkEnabled !== true)
334
+ return "";
335
+ if (job.forcedLane === true)
336
+ return `\n\n${FORCED_LANE_ADVICE}`;
337
+ const stopped = job.attempts.find((a) => a.status === "abandoned");
338
+ if (stopped !== undefined)
339
+ return `\n\n${laneStoppedAdvice(stopped.laneId)}`;
340
+ if (job.lanesNotTried)
341
+ return `\n\n${LANE_LADDER_PARTIAL_ADVICE}`;
342
+ return `\n\n${LANE_LADDER_EXHAUSTED_ADVICE}`;
343
+ }
259
344
  function describeAttempts(job) {
260
345
  if (job.attempts.length === 0 && !job.lanesNotTried)
261
346
  return "";
@@ -276,13 +361,7 @@ function jobAnswer(job, now) {
276
361
  && job.status !== "cancelled"
277
362
  && job.attempts.length > 0
278
363
  && job.attempts.every((a) => a.status !== "completed");
279
- const exhausted = !nothingAnswered
280
- ? ""
281
- : job.walkEnabled !== true
282
- ? ""
283
- : job.lanesNotTried
284
- ? `\n\n${LANE_LADDER_PARTIAL_ADVICE}`
285
- : `\n\n${LANE_LADDER_EXHAUSTED_ADVICE}`;
364
+ const exhausted = nothingAnswered ? terminalAdvice(job) : "";
286
365
  if (job.status === "running") {
287
366
  return `${header}\n\nStill running. Poll dispatch_status, then call dispatch_result.`;
288
367
  }
@@ -326,6 +405,16 @@ function attemptReason(status, outcome, elapsedMs, budgetMs) {
326
405
  const _never = status;
327
406
  return String(_never);
328
407
  }
408
+ function flagValue(args, flag) {
409
+ const i = args.indexOf(flag);
410
+ if (i >= 0 && i + 1 < args.length)
411
+ return args[i + 1] ?? null;
412
+ const joined = args.find((a) => a.startsWith(`${flag}=`));
413
+ return joined === undefined ? null : joined.slice(flag.length + 1);
414
+ }
415
+ function laneAnswered(r) {
416
+ return r.code === 0 && !r.timedOut && !isContentEmpty(r.stdout);
417
+ }
329
418
  function applyLaneEnv(base, deltas) {
330
419
  const env = { ...base };
331
420
  for (const [name, value] of Object.entries(deltas ?? {})) {
@@ -350,6 +439,7 @@ function laneSummary(lane, inFlight) {
350
439
  bits.push(lane.note);
351
440
  if (lane.attemptBudget)
352
441
  bits.push(formatAttemptBudget(lane.attemptBudget));
442
+ bits.push(...laneEvidenceBits(lane));
353
443
  if (lane.maxConcurrent !== null && lane.maxConcurrent !== undefined) {
354
444
  bits.push(`in flight: ${inFlight} of ${lane.maxConcurrent}`);
355
445
  }
@@ -375,7 +465,7 @@ export class McpDispatchServer {
375
465
  buffer = "";
376
466
  constructor(deps) {
377
467
  this.deps = deps;
378
- this.jobs = new LaneJobStore(deps.journal ?? nullJobJournal);
468
+ this.jobs = new LaneJobStore(deps.journal ?? nullJobJournal, deps.archive ?? nullJobArchive);
379
469
  this.spawn = deps.spawn ?? defaultLaneSpawner;
380
470
  this.fetchImpl = deps.fetch ?? defaultAnswerFetch;
381
471
  this.now = deps.now ?? Date.now;
@@ -401,6 +491,7 @@ export class McpDispatchServer {
401
491
  }
402
492
  shutdown() {
403
493
  this.jobs.cancelAll();
494
+ this.jobs.flush();
404
495
  }
405
496
  send(message) {
406
497
  this.deps.write(encodeMessage(message));
@@ -462,6 +553,9 @@ export class McpDispatchServer {
462
553
  if (typeof name !== "string") {
463
554
  throw Object.assign(new Error("tools/call requires a tool name"), { code: RPC_INVALID_PARAMS });
464
555
  }
556
+ return this.withVersionNotice(await this.runTool(name, args));
557
+ }
558
+ async runTool(name, args) {
465
559
  switch (name) {
466
560
  case "dispatch":
467
561
  return this.toolDispatch(args);
@@ -477,6 +571,26 @@ export class McpDispatchServer {
477
571
  return textResult(`unknown tool: ${name}`, true);
478
572
  }
479
573
  }
574
+ withVersionNotice(result) {
575
+ const running = this.deps.version;
576
+ const installed = (() => {
577
+ try {
578
+ return this.deps.installedVersion?.() ?? null;
579
+ }
580
+ catch {
581
+ return null;
582
+ }
583
+ })();
584
+ if (!running || !installed || running === installed)
585
+ return result;
586
+ const r = result;
587
+ const block = r?.content?.[0];
588
+ if (!r || !block || block.type !== "text" || typeof block.text !== "string")
589
+ return result;
590
+ const notice = `\n\n⚠ This llm-relay MCP server process runs v${running}, but v${installed} is installed. ` +
591
+ "Restart the host's llm-relay MCP connection, or the host, to use the installed code.";
592
+ return { ...r, content: [{ ...block, text: block.text + notice }, ...(r.content?.slice(1) ?? [])] };
593
+ }
480
594
  async toolLanes(args) {
481
595
  const view = await this.deps.buildView({
482
596
  task: undefined,
@@ -528,22 +642,25 @@ export class McpDispatchServer {
528
642
  return textResult(`dispatch refused: already ${depth} levels deep (max ${this.maxDepth}). ` +
529
643
  "Do the work here rather than delegating further.", true);
530
644
  }
531
- const view = await this.deps.buildView({
532
- task,
533
- tier: readString(args, "tier"),
534
- lane: readString(args, "lane"),
535
- });
645
+ const lane = readString(args, "lane");
646
+ const model = readString(args, "model");
647
+ if (lane !== undefined && model !== undefined) {
648
+ return textResult("dispatch takes lane or model, not both: lane names a ladder rung, model names a routing spec", true);
649
+ }
650
+ const mode = readMode(args);
651
+ const view = await this.deps.buildView({ task, tier: readString(args, "tier"), lane, mode, model });
536
652
  if (!view.next) {
537
653
  return textResult(`No lane is available. ${view.reason}`, true);
538
654
  }
655
+ const forced = lane !== undefined || model !== undefined;
539
656
  const declared = this.deps.config.routing?.dispatchWalk;
540
657
  const walk = declared !== undefined && declared.enabled ? declared : null;
541
- const order = Array.isArray(view.order) ? view.order : [];
542
- const ordered = walk !== null && order.length > 0 ? order.slice(0, walk.maxLanes) : [view.next.id];
658
+ const { ordered, notTried } = this.walkOrder(view, walk, forced, view.next.id);
543
659
  const opts = {
544
- mode: readMode(args),
660
+ mode,
545
661
  cwd: readString(args, "cwd") ?? this.cwd(),
546
662
  depth,
663
+ readOnly: args["readOnly"] === true,
547
664
  tier: view.tier ?? undefined,
548
665
  timeoutMs: readNumber(args, "timeoutMs") ?? DEFAULT_LANE_TIMEOUT_MS,
549
666
  attemptMs: walk !== null ? walk.attemptMs : null,
@@ -553,7 +670,7 @@ export class McpDispatchServer {
553
670
  dispatchSource: view.source === "local-fallback" ? "fallback" : "daemon",
554
671
  };
555
672
  const readOnlyVerdictResult = readOnlyVerdict({
556
- readOnly: args["readOnly"] === true,
673
+ readOnly: opts.readOnly,
557
674
  mode: opts.mode,
558
675
  cwd: opts.cwd,
559
676
  callerRoot: this.cwd(),
@@ -562,10 +679,7 @@ export class McpDispatchServer {
562
679
  return textResult(readOnlyVerdictResult.refusal, true);
563
680
  const first = view.ladder.find((l) => l.id === ordered[0]) ?? view.next;
564
681
  const job = this.jobs.create(first.id, first.spec, opts.cwd, opts.dispatchSource);
565
- this.jobs.noteWalkScope(job.id, {
566
- enabled: walk !== null,
567
- lanesNotTried: Math.max(0, order.length - ordered.length),
568
- });
682
+ this.jobs.noteWalkScope(job.id, { enabled: walk !== null, lanesNotTried: notTried, forced });
569
683
  const ceiling = this.deps.config.routing?.mcp?.maxWaitMs ?? DEFAULT_MCP_MAX_WAIT_MS;
570
684
  const waitMs = resolveWaitMs(args["waitMs"], ceiling);
571
685
  if ("refusal" in waitMs)
@@ -576,6 +690,22 @@ export class McpDispatchServer {
576
690
  });
577
691
  return this.awaitOrPoll(job.id, settled, waitMs.waitMs, waitMs.clamped ? { requested: waitMs.requested, ceiling } : undefined);
578
692
  }
693
+ walkOrder(view, walk, forced, nextId) {
694
+ const runnable = (id) => forced || !this.isPassThroughLane(view.ladder.find((l) => l.id === id));
695
+ const order = (Array.isArray(view.order) ? view.order : []).filter(runnable);
696
+ const ordered = walk !== null && order.length > 0 ? order.slice(0, walk.maxLanes) : [order[0] ?? nextId];
697
+ return { ordered, notTried: Math.max(0, order.length - ordered.length) };
698
+ }
699
+ isPassThroughLane(lane) {
700
+ if (lane?.kind !== "relay" || lane.spec === undefined)
701
+ return false;
702
+ try {
703
+ return isPassThroughSpec(lane.spec, this.deps.config);
704
+ }
705
+ catch {
706
+ return false;
707
+ }
708
+ }
579
709
  async runWalk(jobId, view, laneIds, task, opts) {
580
710
  for (let i = 0; i < laneIds.length; i++) {
581
711
  if (this.jobs.get(jobId)?.status !== "running")
@@ -586,11 +716,17 @@ export class McpDispatchServer {
586
716
  continue;
587
717
  if (this.skipIfAtConcurrencyCap(jobId, lane))
588
718
  continue;
589
- this.jobs.setCurrentLane(jobId, lane.id, lane.spec);
719
+ const readOnly = this.bindReadOnlyOrSkip(jobId, lane, opts);
720
+ if (readOnly.skipped)
721
+ continue;
722
+ this.jobs.setCurrentLane(jobId, lane.id, lane.spec, lane.timeToAnswer);
723
+ if (readOnly.bound !== undefined)
724
+ this.jobs.noteReadOnly(jobId, lane.id, readOnly.bound.binding);
590
725
  const isLast = i === laneIds.length - 1;
726
+ const noBudget = this.budgetWithheld(view, laneIds, i);
591
727
  const startedAt = this.now();
592
728
  const budgetMs = lane.attemptBudget?.ms ?? opts.attemptMs;
593
- const outcome = await this.runOneLane(jobId, lane, task, opts, isLast ? null : budgetMs);
729
+ const outcome = await this.runOneLane(jobId, lane, task, opts, noBudget ? null : budgetMs, readOnly.bound?.invoke);
594
730
  const elapsedMs = Math.max(0, this.now() - startedAt);
595
731
  if (this.jobs.get(jobId)?.status === "cancelled")
596
732
  return "done";
@@ -602,7 +738,7 @@ export class McpDispatchServer {
602
738
  abandoned: outcome.abandoned,
603
739
  semanticFailure: outcome.semanticFailure,
604
740
  });
605
- const reason = attemptReason(status, outcome, elapsedMs, isLast ? null : budgetMs);
741
+ const reason = attemptReason(status, outcome, elapsedMs, noBudget ? null : budgetMs);
606
742
  this.jobs.recordAttempt(jobId, {
607
743
  laneId: lane.id,
608
744
  spec: lane.spec,
@@ -610,7 +746,15 @@ export class McpDispatchServer {
610
746
  elapsedMs,
611
747
  ...(reason === undefined ? {} : { reason }),
612
748
  });
613
- this.forwardTelemetry(jobId, { taskLength: task.length, laneId: lane.id, kind: lane.kind, spec: lane.spec, tier: opts.tier }, outcome.run.stdout.length, { status, wallClockMs: elapsedMs, exitCode: outcome.run.code });
749
+ this.forwardTelemetry(jobId, {
750
+ taskLength: task.length,
751
+ laneId: lane.id,
752
+ kind: lane.kind,
753
+ spec: lane.spec,
754
+ tier: opts.tier,
755
+ requestedMode: opts.mode,
756
+ adHoc: lane.adHoc === true,
757
+ }, outcome.run.stdout.length, { status, wallClockMs: elapsedMs, exitCode: outcome.run.code });
614
758
  if (status === "completed" || isLast) {
615
759
  this.jobs.complete(jobId, outcome.run, status === "completed" ? undefined : (outcome.semanticFailure ?? reason), outcome.relay);
616
760
  return "done";
@@ -619,13 +763,20 @@ export class McpDispatchServer {
619
763
  const attempts = this.jobs.get(jobId)?.attempts ?? [];
620
764
  const ran = attempts.filter((a) => attemptWasTried(a.status)).length;
621
765
  const allSkipped = attempts.length > 0 && ran === 0;
766
+ const skipReasons = [...new Set(attempts.filter((a) => !attemptWasTried(a.status)).map((a) => a.reason ?? "skipped"))];
622
767
  this.jobs.fail(jobId, allSkipped
623
- ? "every remaining lane in the selection order is at its maxConcurrent cap"
768
+ ? `every lane in the selection order was skipped before it ran: ${skipReasons.join("; ")}`
624
769
  : ran === 0
625
770
  ? "no lane in the dispatch ladder matched the selection order"
626
771
  : `no lane answered, and the ladder no longer holds the remaining lanes in the selection order (${ran} tried)`);
627
772
  return "done";
628
773
  }
774
+ budgetWithheld(view, laneIds, i) {
775
+ return !laneIds.slice(i + 1).some((id) => {
776
+ const later = view.ladder.find((l) => l.id === id);
777
+ return later !== undefined && later.failing === undefined && (later.recentFailures ?? 0) < LANE_UNRELIABLE_STREAK;
778
+ });
779
+ }
629
780
  skipIfAtConcurrencyCap(jobId, lane) {
630
781
  if (lane.maxConcurrent === null || lane.maxConcurrent === undefined)
631
782
  return false;
@@ -642,8 +793,28 @@ export class McpDispatchServer {
642
793
  this.jobs.noteSkippedLane(jobId);
643
794
  return true;
644
795
  }
645
- async runOneLane(jobId, lane, task, opts, budgetMs) {
646
- const started = this.startLane(jobId, lane, task, opts);
796
+ bindReadOnlyOrSkip(jobId, lane, opts) {
797
+ if (!opts.readOnly)
798
+ return { skipped: false };
799
+ if (opts.mode === "answer" && lane.kind === "relay")
800
+ return { skipped: false };
801
+ if (lane.invoke === undefined)
802
+ return { skipped: false };
803
+ const verdict = readOnlyInvoke(lane.invoke);
804
+ if (verdict.ok)
805
+ return { skipped: false, bound: { invoke: verdict.invoke, binding: verdict.binding } };
806
+ this.jobs.recordAttempt(jobId, {
807
+ laneId: lane.id,
808
+ spec: lane.spec,
809
+ status: SKIPPED_LANE_STATUS,
810
+ elapsedMs: 0,
811
+ reason: `lane "${lane.id}" skipped: ${verdict.reason}`,
812
+ });
813
+ this.jobs.noteSkippedLane(jobId);
814
+ return { skipped: true };
815
+ }
816
+ async runOneLane(jobId, lane, task, opts, budgetMs, invoke) {
817
+ const started = this.startLane(jobId, lane, task, opts, invoke);
647
818
  if ("refusal" in started)
648
819
  return { run: emptyRun(), abandoned: false, refusal: started.refusal };
649
820
  this.jobs.registerProcess(jobId, started);
@@ -667,7 +838,7 @@ export class McpDispatchServer {
667
838
  started.kill();
668
839
  return { run: emptyRun(), abandoned: true };
669
840
  }
670
- startLane(jobId, lane, task, opts) {
841
+ startLane(jobId, lane, task, opts, invokeOverride) {
671
842
  if (opts.mode === "answer" && lane.kind === "relay") {
672
843
  if (!lane.spec) {
673
844
  return {
@@ -693,52 +864,79 @@ export class McpDispatchServer {
693
864
  const cwdCheck = checkCwd(opts.cwd, this.deps.allowedRoots);
694
865
  if (!cwdCheck.ok)
695
866
  return { refusal: `dispatch refused: ${cwdCheck.reason}` };
696
- const invoke = lane.invoke;
867
+ const invoke = invokeOverride ?? lane.invoke;
697
868
  if (!invoke) {
869
+ const why = lane.unreachable ??
870
+ (lane.spec !== undefined && this.isPassThroughLane(lane)
871
+ ? mcpPassThroughReason(lane.spec)
872
+ : `it is a relay target (${lane.spec ?? "?"}) with no cliLane template configured`);
698
873
  return {
699
- result: Promise.resolve(failedOutcome(`Lane "${lane.id}" cannot be run from here: ${lane.unreachable ?? `it is a relay target (${lane.spec ?? "?"}) with no cliLane template configured`}.`)),
874
+ result: Promise.resolve(failedOutcome(`Lane "${lane.id}" cannot be run from here: ${why}.`)),
700
875
  kill: () => { },
701
876
  };
702
877
  }
703
878
  const env = applyLaneEnv(process.env, invoke.env);
704
879
  env[DEPTH_ENV] = String(opts.depth + 1);
880
+ const startedAt = this.now();
881
+ this.jobs.beginAttemptActivity(jobId, startedAt);
705
882
  let run;
706
883
  try {
707
- run = this.spawn(invoke.command, invoke.args, { env, cwd: opts.cwd, timeoutMs: opts.timeoutMs });
884
+ run = this.spawn(invoke.command, invoke.args, {
885
+ env,
886
+ cwd: opts.cwd,
887
+ timeoutMs: opts.timeoutMs,
888
+ onOutput: ({ stream, bytes }) => this.jobs.noteOutput(jobId, stream, bytes, this.now()),
889
+ });
708
890
  }
709
891
  catch (e) {
710
892
  return { result: Promise.resolve(failedOutcome(e.message)), kill: () => { } };
711
893
  }
712
- const result = run.result.then(async (r) => {
713
- if (this.jobs.get(jobId)?.status === "cancelled")
714
- return { run: r, abandoned: false };
715
- const report = classifyDispatchedResult({
716
- result: r,
717
- laneId: lane.id,
718
- tier: opts.tier,
719
- command: invoke.command,
720
- args: invoke.args,
721
- });
722
- let semanticFailure = report ? `lane reported ${report.outcome}` : undefined;
723
- let out = r;
724
- if (report) {
725
- try {
726
- await this.deps.reportExhaustion?.(report);
727
- }
728
- catch (e) {
729
- const detail = e instanceof Error ? e.message : String(e);
730
- semanticFailure = `${semanticFailure}; quota report failed: ${detail.slice(0, 500)}`;
731
- out = { ...r, stderr: `${r.stderr}${r.stderr ? "\n" : ""}${semanticFailure}` };
732
- }
894
+ const result = run.result.then((r) => this.settleSpawnedRun(jobId, lane, invoke, opts, startedAt, r));
895
+ return { result, kill: run.kill, ...(run.pids === undefined ? {} : { pids: run.pids }) };
896
+ }
897
+ async settleSpawnedRun(jobId, lane, invoke, opts, startedAt, r) {
898
+ if (this.jobs.get(jobId)?.status === "cancelled")
899
+ return { run: r, abandoned: false };
900
+ const report = classifyDispatchedResult({ result: r, laneId: lane.id, tier: opts.tier, command: invoke.command, args: invoke.args }) ??
901
+ (laneAnswered(r) ? undefined : this.agyLogReport(lane, invoke, opts, startedAt));
902
+ let semanticFailure = report ? `lane reported ${report.outcome}` : undefined;
903
+ let out = r;
904
+ if (report) {
905
+ try {
906
+ await this.deps.reportExhaustion?.(report);
733
907
  }
734
- if (semanticFailure === undefined && !out.timedOut && isContentEmpty(out.stdout)) {
735
- semanticFailure = EMPTY_OUTPUT_REASON;
908
+ catch (e) {
909
+ const detail = e instanceof Error ? e.message : String(e);
910
+ semanticFailure = `${semanticFailure}; quota report failed: ${detail.slice(0, 500)}`;
911
+ out = { ...r, stderr: `${r.stderr}${r.stderr ? "\n" : ""}${semanticFailure}` };
736
912
  }
737
- return { run: out, abandoned: false, ...(semanticFailure === undefined ? {} : { semanticFailure }) };
738
- });
739
- return { result, kill: run.kill };
913
+ }
914
+ if (semanticFailure === undefined && !out.timedOut && isContentEmpty(out.stdout)) {
915
+ semanticFailure = EMPTY_OUTPUT_REASON;
916
+ }
917
+ return { run: out, abandoned: false, ...(semanticFailure === undefined ? {} : { semanticFailure }) };
918
+ }
919
+ agyLogReport(lane, invoke, opts, startedAt) {
920
+ const read = this.deps.readAgyLog;
921
+ if (read === undefined || laneOfRung(invoke.command, invoke.args)?.lane !== "agy")
922
+ return undefined;
923
+ const model = flagValue(invoke.args, "--model");
924
+ if (model === null)
925
+ return undefined;
926
+ let statement;
927
+ try {
928
+ statement = agyQuotaStatement(read(), model, startedAt);
929
+ }
930
+ catch {
931
+ return undefined;
932
+ }
933
+ if (statement === null)
934
+ return undefined;
935
+ return { laneId: lane.id, tier: opts.tier, outcome: statement.outcome, retryAfterMs: statement.retryAfterMs };
740
936
  }
741
937
  forwardTelemetry(jobId, captured, outputChars, attempt) {
938
+ if (captured.adHoc)
939
+ return;
742
940
  const job = this.jobs.get(jobId);
743
941
  if (!job)
744
942
  return;
@@ -750,6 +948,7 @@ export class McpDispatchServer {
750
948
  kind: captured.kind,
751
949
  ...(captured.spec === undefined ? {} : { spec: captured.spec }),
752
950
  ...(captured.tier === undefined ? {} : { tier: captured.tier }),
951
+ mode: captured.requestedMode === "answer" && captured.kind === "relay" ? "answer" : "agent",
753
952
  wallClockMs: Math.max(0, attempt.wallClockMs),
754
953
  exitCode: attempt.exitCode,
755
954
  status: attempt.status,