Skip to content

Commit 08b2562

Browse files
claudeJorisPaarde
authored andcommitted
feat(routing): capacity facts per pool and a deterministic dispatcher
Routing is a lookup, so it runs in code and costs no tokens. Two new libs and two scripts, no dependencies, same fail-closed house style as the collector. collector/lib/routing.js derives one capacity fact per pool from the published snapshot. Cursor's verdict comes from its capacity meters only: on-demand spend sat at 98% of its cap on 2026-08-31 while included capacity was under 30%, and reading that as "full" would push every repo task to a paid lane for nothing. Claude takes the highest of session and weekly; usage-credits is spend, not a rate limit, so it does not drive the verdict. No verdict is stored. The file carries facts plus each pool's own measuredAt and maxAgeMinutes, and verdictForPool computes the verdict against a clock at read time -- a stored verdict would age inside the file the same way a fresh generatedAt over old values did. The rule is asymmetric on purpose: ok needs a fresh measurement, full may be set by an observed quota error regardless of any measurement, and anything stale or unmeasurable degrades to low. Being wrong toward caution costs a little paid capacity; being wrong toward optimism costs a run that dies halfway. collector/lib/lanes.js is the table alone, with no dispatch in it, so it survives block/buzz#3871 shipping an agent-invocation step. scripts/route.js measures first and decides second, retries the next lane on a quota error, and writes a runlog outside the repo -- task text can name clients and data/ is published. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01QGnBRDZEryL5UVgKAzNZqp
1 parent 0712125 commit 08b2562

7 files changed

Lines changed: 1299 additions & 1 deletion

File tree

‎collector/lib/lanes.js‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
/**
2+
* The routing table: which pools may run which kind of task, in what order.
3+
*
4+
* Kept deliberately separate from dispatch (scripts/route.js). Buzz has no
5+
* agent-invocation step today (block/buzz#3871 is open), so we dispatch
6+
* ourselves; when that ships, the dispatch half can be deleted and this table
7+
* stays as-is.
8+
*
9+
* No external deps.
10+
*/
11+
12+
/** Quality a pool is trusted with. `max` means real reasoning work. */
13+
export const POOL_QUALITY = Object.freeze({
14+
local: ["cheap"],
15+
sail: ["cheap", "normal"],
16+
cursor: ["cheap", "normal", "max"],
17+
claude: ["cheap", "normal", "max"],
18+
openai: ["cheap", "normal", "max"],
19+
openrouter: ["cheap", "normal", "max"],
20+
});
21+
22+
export const QUALITIES = Object.freeze(["cheap", "normal", "max"]);
23+
24+
/**
25+
* Ordered pool preference per task type. First entry is the intended home;
26+
* the rest are overflow. Paid pools come last so a metered pool with room is
27+
* always preferred, even when it is only `low`.
28+
*/
29+
export const LANES = Object.freeze({
30+
code: ["cursor", "openai", "openrouter"],
31+
review: ["claude", "openai", "openrouter"],
32+
research: ["claude", "openai", "openrouter"],
33+
classify: ["local", "cursor", "openrouter"],
34+
digest: ["local", "claude", "openrouter"],
35+
bulk: ["sail", "openrouter"],
36+
});
37+
38+
export const TASK_TYPES = Object.freeze(Object.keys(LANES));
39+
40+
/**
41+
* Validate a task before it can be routed. Fail closed: an unroutable task is
42+
* an error, never a silent default to the most expensive lane.
43+
* @param {unknown} raw
44+
* @returns {{ ok: boolean, errors: string[] }}
45+
*/
46+
export function validateTask(raw) {
47+
const errors = [];
48+
if (!raw || typeof raw !== "object") {
49+
return { ok: false, errors: ["task must be an object"] };
50+
}
51+
const t = /** @type {Record<string, unknown>} */ (raw);
52+
if (typeof t.id !== "string" || !t.id.trim()) {
53+
errors.push("task.id must be a non-empty string");
54+
}
55+
if (typeof t.type !== "string" || !TASK_TYPES.includes(t.type)) {
56+
errors.push(`task.type must be one of: ${TASK_TYPES.join(", ")}`);
57+
}
58+
if (typeof t.quality !== "string" || !QUALITIES.includes(t.quality)) {
59+
errors.push(`task.quality must be one of: ${QUALITIES.join(", ")}`);
60+
}
61+
if (typeof t.prompt !== "string" || !t.prompt.trim()) {
62+
errors.push("task.prompt must be a non-empty string");
63+
}
64+
if (t.deadline != null && typeof t.deadline !== "string") {
65+
errors.push("task.deadline must be an ISO string or omitted");
66+
}
67+
return { ok: errors.length === 0, errors };
68+
}
69+
70+
/**
71+
* Candidate pools for a task: the lane order, filtered by quality.
72+
* @param {{type: string, quality: string}} task
73+
*/
74+
export function candidatesFor(task) {
75+
const lane = LANES[task.type] || [];
76+
return lane.filter((pool) =>
77+
(POOL_QUALITY[pool] || []).includes(task.quality),
78+
);
79+
}
80+
81+
/**
82+
* Choose a pool for a task given current verdicts.
83+
*
84+
* Two passes: take the first candidate that is `ok`, else the first that is
85+
* `low` or `unknown`, else the first paid pool. Same task plus same verdicts
86+
* always yields the same pool — no randomness, no time-of-day behaviour beyond
87+
* what the verdicts already encode.
88+
*
89+
* @param {{type: string, quality: string}} task
90+
* @param {Record<string, {verdict: string, reason?: string}>} verdicts
91+
* @returns {{pool: string|null, agent: string|null, reason: string, considered: object[]}}
92+
*/
93+
export function pickPool(task, verdicts, pools = {}) {
94+
const candidates = candidatesFor(task);
95+
const considered = candidates.map((pool) => ({
96+
pool,
97+
verdict: verdicts[pool]?.verdict ?? "unknown",
98+
reason: verdicts[pool]?.reason ?? "No verdict for this pool.",
99+
}));
100+
101+
if (candidates.length === 0) {
102+
return {
103+
pool: null,
104+
agent: null,
105+
reason: `No pool is allowed to run ${task.type} at quality ${task.quality}.`,
106+
considered,
107+
};
108+
}
109+
110+
const pass = (want) =>
111+
candidates.find((pool) => want.includes(verdicts[pool]?.verdict));
112+
113+
const chosen =
114+
pass(["ok"]) || pass(["low", "unknown"]) || pass(["paid"]) || null;
115+
116+
if (!chosen) {
117+
return {
118+
pool: null,
119+
agent: null,
120+
reason:
121+
"Every candidate pool is full. Nothing dispatched — refill credits or wait for a reset.",
122+
considered,
123+
};
124+
}
125+
126+
const verdict = verdicts[chosen]?.verdict;
127+
const why = verdicts[chosen]?.reason || "";
128+
const rank =
129+
verdict === "ok"
130+
? "first choice with room"
131+
: verdict === "paid"
132+
? "last resort: every metered pool was full or unusable"
133+
: "no pool had full room; best remaining";
134+
return {
135+
pool: chosen,
136+
agent: pools[chosen]?.agent ?? null,
137+
reason: `${chosen} (${verdict}) — ${rank}. ${why}`.trim(),
138+
considered,
139+
};
140+
}

0 commit comments

Comments
 (0)