@a-t-h-i/bot-lobby 0.6.79 → 0.7.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 (58) hide show
  1. package/THIRD_PARTY_NOTICES.md +0 -1
  2. package/package.json +1 -1
  3. package/prompts/lobby-chat.md +1 -1
  4. package/prompts/master.md +15 -2
  5. package/prompts/panel.md +4 -4
  6. package/prompts/planner.md +2 -2
  7. package/prompts/worker.md +6 -1
  8. package/src/ask/tool.ts +1 -1
  9. package/src/classifier/effort.ts +5 -0
  10. package/src/classifier/files.ts +7 -0
  11. package/src/classifier/knowledge.ts +88 -0
  12. package/src/classifier/lobby.ts +1 -1
  13. package/src/desk/board-client.ts +1 -1
  14. package/src/desk/board.ts +1 -1
  15. package/src/execution/assignment.ts +77 -1
  16. package/src/execution/delegation.ts +80 -27
  17. package/src/execution/verification.ts +216 -0
  18. package/src/knowledge/catalog-tools.ts +1 -1
  19. package/src/knowledge/catalogue.ts +21 -6
  20. package/src/knowledge/compactor.ts +212 -5
  21. package/src/knowledge/oracle-digest.ts +2 -2
  22. package/src/knowledge/paths.ts +9 -0
  23. package/src/knowledge/repo-map.ts +1 -0
  24. package/src/knowledge/retrieval.ts +8 -2
  25. package/src/knowledge/store.ts +68 -14
  26. package/src/lobby/chat-agents.ts +57 -8
  27. package/src/lobby/feed.ts +2 -2
  28. package/src/lobby/knowledge.ts +3 -3
  29. package/src/lobby/pi-commands.ts +1 -1
  30. package/src/lobby/planner.ts +6 -6
  31. package/src/lobby/prompts.ts +2 -2
  32. package/src/lobby/runtime.ts +4 -4
  33. package/src/lobby/service.ts +88 -51
  34. package/src/master/master.ts +87 -14
  35. package/src/master/scout-prefetch.ts +14 -1
  36. package/src/pi/commands.ts +28 -10
  37. package/src/pi/events.ts +21 -10
  38. package/src/pi/owner.ts +21 -3
  39. package/src/pi/start-task.ts +9 -6
  40. package/src/pi/switch-pending.ts +24 -0
  41. package/src/pi/tools.ts +14 -0
  42. package/src/roles/worker.ts +33 -3
  43. package/src/schemas/configuration.ts +9 -0
  44. package/src/schemas/task.ts +18 -0
  45. package/src/schemas/verification.ts +38 -0
  46. package/src/state/metrics.ts +32 -2
  47. package/src/webui/api/knowledge.ts +1 -1
  48. package/src/webui/api/tasks.ts +1 -1
  49. package/src/webui/dev/fake-service.ts +7 -7
  50. package/src/workflow/track.ts +65 -3
  51. package/src/workflow/workflow.ts +142 -17
  52. package/webui/dist/assets/{CodeSurface-DZdLN-w3.js → CodeSurface-FHm02AXI.js} +1 -1
  53. package/webui/dist/assets/{TerminalView-CRwPTCho.js → TerminalView-Be3q2ej_.js} +1 -1
  54. package/webui/dist/assets/{index-CiUnrnfa.js → index-B_7Iioqo.js} +45 -45
  55. package/webui/dist/assets/index-DPP8sEwW.css +2 -0
  56. package/webui/dist/build.json +59 -59
  57. package/webui/dist/index.html +2 -2
  58. package/webui/dist/assets/index-CTNZ-wc_.css +0 -2
package/src/pi/owner.ts CHANGED
@@ -137,7 +137,7 @@ export interface AutoTrack {
137
137
  stalled: boolean;
138
138
  }
139
139
 
140
- /** Everything a workflow step changes, cheaply: two equal fingerprints mean the oracle made no progress. */
140
+ /** Everything a workflow step changes, cheaply: two equal fingerprints mean the orchestrator made no progress. */
141
141
  export function taskFingerprint(task: Task): string {
142
142
  return [
143
143
  task.state,
@@ -185,7 +185,7 @@ export function driveAuto(): boolean {
185
185
  state.auto = step.track;
186
186
  if (step.stalledNow) {
187
187
  listener?.({ kind: "stalled", taskId: task.id });
188
- state.ctx.ui.notify(`bot-lobby: auto mode — the oracle made no progress on ${task.id} after ${MAX_IDLE_NUDGES} nudges; it needs you.`, "warning");
188
+ state.ctx.ui.notify(`bot-lobby: auto mode — the orchestrator made no progress on ${task.id} after ${MAX_IDLE_NUDGES} nudges; it needs you.`, "warning");
189
189
  }
190
190
  if (!step.nudge) return false;
191
191
  state.pi.sendUserMessage(autoNudge(task));
@@ -214,7 +214,7 @@ export function toggleOwnAuto(): string {
214
214
  if (!live(task)) return "no active task in this session — auto mode applies to a task";
215
215
  const on = !isAutoMode(state.root, state.configDir, task.id);
216
216
  setAuto(state.root, state.configDir, task.id, on, state.ctx.sessionManager.getSessionId());
217
- return on ? `auto mode on for ${task.id}: the oracle drives it to completion without asking you` : `auto mode off for ${task.id}: the oracle asks you again`;
217
+ return on ? `auto mode on for ${task.id}: the orchestrator drives it to completion without asking you` : `auto mode off for ${task.id}: the orchestrator asks you again`;
218
218
  }
219
219
 
220
220
  /** Whether a finished turn was stopped by the user (its last reply was aborted). */
@@ -254,6 +254,24 @@ export function ownerTick(): void {
254
254
  }
255
255
  }
256
256
 
257
+ /**
258
+ * Hold the owner's clock while this window switches sessions, so no comment,
259
+ * message or auto-mode nudge starts a turn in the session being left (its
260
+ * background copy delivers them instead). The returned function restarts the
261
+ * clock should the switch not happen; a switch that lands starts a new one.
262
+ */
263
+ export function pauseOwner(): () => void {
264
+ const state = owner;
265
+ if (!state?.timer) return () => {};
266
+ clearInterval(state.timer);
267
+ state.timer = undefined;
268
+ return () => {
269
+ if (owner !== state || state.timer) return;
270
+ state.timer = setInterval(() => ownerTick(), OWNER_POLL_MS);
271
+ state.timer.unref?.();
272
+ };
273
+ }
274
+
257
275
  function stop(): void {
258
276
  if (owner?.timer) clearInterval(owner.timer);
259
277
  if (owner) {
@@ -7,7 +7,7 @@ import { existsSync } from "node:fs";
7
7
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
8
8
  import { createTask, taskRequest, type Task, type TaskTrack, type TaskTriage, type TrackPath } from "../schemas/task.ts";
9
9
  import type { Domain } from "../schemas/agent.ts";
10
- import { chooseTrack, qaRequired, rosterWords, trackLine, trackSummary } from "../workflow/track.ts";
10
+ import { chooseTrack, fastPathRecord, qaRequired, rosterWords, trackLine, trackSummary } from "../workflow/track.ts";
11
11
  import { prefetchScouts, startFromAgreedPlan } from "../workflow/workflow.ts";
12
12
  import { workflowDeps } from "./tools.ts";
13
13
  import { lobbyFeed } from "../lobby/feed.ts";
@@ -165,8 +165,11 @@ export async function startTask(pi: ExtensionAPI, ctx: ExtensionContext, configD
165
165
  // The classifier's read of the request (when it is on) reaches the Master's very first turn.
166
166
  const triage = options.triaged ? options.triage : await triageFor({ cwd: ctx.cwd, root, configDir }, request);
167
167
  if (triage) task.triage = triage;
168
- // How serious the request reads: who takes part, and whether it takes the fast track or the full workflow.
169
- task.track = chooseTrack(request, triage, { fastTrack: config.workflow.fastTrack, ...(options.track ? { forced: options.track } : {}), ...(options.approvedPlan ? { approvedPlan: true } : {}), ...(options.panel ? { planPanel: options.panel } : {}) });
168
+ // Effort selects the fast path; genuine risk and ambiguity still veto it.
169
+ const makeDeps = () => workflowDeps(ctx, configDir, undefined, undefined);
170
+ const effort = await makeDeps().effort?.score(request).catch(() => undefined);
171
+ task.track = chooseTrack(request, triage, { effort, fastTrack: config.workflow.fastTrack, ...(options.track ? { forced: options.track } : {}), ...(options.approvedPlan ? { approvedPlan: true } : {}), ...(options.panel ? { planPanel: options.panel } : {}) });
172
+ task.fastPath = fastPathRecord(request, task.track, effort);
170
173
  lobbyFeed.log("LOBBY", trackLine(task.track), "info");
171
174
  // An agreed plan is the task's plan: it goes straight to delegating its steps.
172
175
  if (options.approvedPlan && options.plan) startFromAgreedPlan(task, options.plan, taskDirFor(root, configDir, task.id));
@@ -180,12 +183,12 @@ export async function startTask(pi: ExtensionAPI, ctx: ExtensionContext, configD
180
183
  ctx.ui.notify(`bot-lobby ${task.id} started`, "info");
181
184
  // The oracle takes the task on with a clean context: nothing said before the kickoff is sent to its model.
182
185
  if (freshContextOn()) markContext(pi, { kind: "start", taskId: task.id, at: Date.now() });
183
- // The full workflow scouts first: start it now, so the findings are on their way while the oracle reads the request.
186
+ // The full workflow scouts first: start it now, so the findings are on their way while the orchestrator reads the request.
184
187
  // It is only a head start: anything that stops it leaves the oracle to scout as before.
185
188
  let scouting: Domain[] = [];
186
- try { scouting = prefetchScouts(task, config, () => workflowDeps(ctx, configDir, undefined, undefined)); }
189
+ try { scouting = prefetchScouts(task, config, makeDeps, effort); }
187
190
  catch { scouting = []; }
188
- if (scouting.length > 0) lobbyFeed.log("LOBBY", `${task.id}: scouting ${scouting.join(", ")} while the oracle reads the request`, "info");
191
+ if (scouting.length > 0) lobbyFeed.log("LOBBY", `${task.id}: scouting ${scouting.join(", ")} while the orchestrator reads the request`, "info");
189
192
  // A kickoff while pi is still busy (another turn) queues behind it instead of throwing.
190
193
  pi.sendUserMessage(kickoff(task, { fastTrack: config.workflow.fastTrack, cwd: taskCwd(task, ctx.cwd), scouting }), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
191
194
  return task;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * A session switch the lobby asked for and `/bot-lobby switch` has not run
3
+ * yet. The lobby gets this window ready to leave (its owner clock held, a
4
+ * hand-off to the background noted) before pi runs the command; when the
5
+ * command does not switch after all, it undoes that here.
6
+ */
7
+ let undo: (() => void) | undefined;
8
+
9
+ /** Note how to undo a switch the lobby got ready for. */
10
+ export function switchPending(fn: () => void): void {
11
+ undo = fn;
12
+ }
13
+
14
+ /** The switch landed: nothing to undo. */
15
+ export function switchLanded(): void {
16
+ undo = undefined;
17
+ }
18
+
19
+ /** The switch did not happen: undo what the lobby got ready. */
20
+ export function switchFailed(): void {
21
+ const fn = undo;
22
+ undo = undefined;
23
+ fn?.();
24
+ }
package/src/pi/tools.ts CHANGED
@@ -26,6 +26,19 @@ import {
26
26
  type WorkflowResult,
27
27
  } from "../workflow/workflow.ts";
28
28
 
29
+ export const ContextPackSchema = Type.Object({
30
+ version: Type.Literal(1),
31
+ files: Type.Array(Type.Object({
32
+ path: Type.String({ minLength: 1 }),
33
+ ranges: Type.Optional(Type.Array(Type.Tuple([Type.Integer({ minimum: 1 }), Type.Integer({ minimum: 1 })]), { description: "[start, end] line ranges with 1 <= start <= end" })),
34
+ fingerprint: Type.Optional(Type.String({ minLength: 1, description: "content hash at pack-build time; dispatch refreshes stale entries" })),
35
+ snippet: Type.Optional(Type.String({ maxLength: 2000, description: "bounded excerpt, current at pack-build time" })),
36
+ }, { additionalProperties: false })),
37
+ invariants: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
38
+ priorWork: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
39
+ verification: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
40
+ }, { additionalProperties: false, description: "Reusable worker context, rendered once into the initial prompt; at most 24,000 characters serialized" });
41
+
29
42
  export const WorkerAssignmentSchema = Type.Object({
30
43
  id: Type.String({ minLength: 1 }),
31
44
  revision: Type.Integer({ minimum: 1 }),
@@ -49,6 +62,7 @@ export const WorkerAssignmentSchema = Type.Object({
49
62
  requested: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
50
63
  }, { additionalProperties: false })),
51
64
  discoveryLimit: Type.Optional(Type.Integer({ minimum: 0 })),
65
+ contextPack: Type.Optional(ContextPackSchema),
52
66
  }, { additionalProperties: false });
53
67
 
54
68
  const OrchestrateSchema = Type.Object({
@@ -1,4 +1,4 @@
1
- import type { AssignmentExpansionRequest, WorkerAssignment } from "../execution/assignment.ts";
1
+ import type { AssignmentExpansionRequest, ContextPack, ContextPackFile, WorkerAssignment } from "../execution/assignment.ts";
2
2
  import type { Domain, RoleSpec } from "../schemas/agent.ts";
3
3
  import type { Blocker } from "../schemas/task.ts";
4
4
  import type { FileChange, KnowledgeProposal, ScriptProposal, WorkerResult } from "../schemas/findings.ts";
@@ -183,18 +183,48 @@ export function parseWorkerResult(domain: Domain, raw: string, now = new Date().
183
183
  };
184
184
  }
185
185
 
186
+ /** One pack file as a prompt bullet: path, line ranges, fingerprint and its bounded snippet, once. */
187
+ function packFileBlock(file: ContextPackFile): string {
188
+ const ranges = file.ranges?.length ? ` lines ${file.ranges.map(([start, end]) => `${start}-${end}`).join(", ")}` : "";
189
+ const fingerprint = file.fingerprint ? ` · fingerprint ${file.fingerprint}` : "";
190
+ const snippet = file.snippet ? `\n\n \`\`\`\n${file.snippet.split("\n").map((line) => ` ${line}`).join("\n")}\n \`\`\`` : "";
191
+ return `- ${file.path}${ranges}${fingerprint}${snippet}`;
192
+ }
193
+
194
+ /**
195
+ * The context pack as the worker's prompt carries it: one clean rendering of
196
+ * paths with line ranges, fingerprints, snippets, invariants, prior work and
197
+ * verification — never a JSON dump beside a prose copy. Dispatch appends what
198
+ * it refreshed, so the worker knows which entries are newer than the pack.
199
+ */
200
+ export function contextPackBlock(pack: ContextPack, refreshed: readonly string[] = []): string {
201
+ return [
202
+ "## Context pack",
203
+ `Version ${pack.version}. Entries were current at dispatch (paths, line ranges, content fingerprints, bounded snippets); what dispatch refreshed is named below.`,
204
+ ...pack.files.map(packFileBlock),
205
+ pack.invariants?.length ? `Invariants that must hold:\n${pack.invariants.map((entry) => `- ${entry}`).join("\n")}` : "",
206
+ pack.priorWork?.length ? `Prior work already landed:\n${pack.priorWork.map((entry) => `- ${entry}`).join("\n")}` : "",
207
+ `Verification this pack requires of you:\n${pack.verification.map((entry) => `- ${entry}`).join("\n")}`,
208
+ refreshed.length ? `Refreshed at dispatch: ${refreshed.join("; ")}.` : "",
209
+ "Trust pack entries for files you only reference; re-read a packed file solely when you will edit it, reading just the needed line range, and make independent reads in one batch instead of sequential re-discovery.",
210
+ ].filter(Boolean).join("\n\n");
211
+ }
212
+
186
213
  /** Assignment-specific content belongs in the user instruction, not the shared system prefix. */
187
214
  export function assignmentPrompt(assignment: WorkerAssignment): string {
215
+ const { contextPack, ...rest } = assignment;
188
216
  return [
189
217
  "## Validated master assignment",
190
- JSON.stringify(assignment, null, 2),
218
+ // A pack is rendered once below; the JSON dump must not repeat it.
219
+ JSON.stringify(contextPack ? rest : assignment, null, 2),
191
220
  "Actions are numbered and authoritative. Begin with assigned files; paths and purposes are provided, not file bodies.",
192
221
  "Read current contents before editing; re-read after file handover. Reference paths are read-only. Only edit/create paths authorize changes.",
193
222
  `Discovery allowance: ${assignment.discoveryLimit ?? 2} total targeted lookups. Each nested or batched discovery call counts separately; retries and revisions do not reset consumed allowance. Assigned-file reads and assigned verification are exempt. Shell discovery follows the same limit.`,
194
223
  "Discovery never authorizes editing a newly found file. Tools listed here are a replacement selection intersected with existing grants; an empty list grants no tools. Codemode does not grant unselected nested or MCP tools.",
195
224
  "If files, tools, discovery allowance or decisions are missing, report each expansion request under Notes as a standalone JSON object (optionally in a json fence), with exactly these keys: {\"kind\":\"files|tools|discovery|decision\",\"reason\":\"why needed\",\"requested\":[\"exact path, tool, allowance or decision\"]}. Continue unaffected work; do not expand permissions yourself.",
196
225
  "Report completed work and evidence, outstanding needs, and one Brief Check per verification criterion. Reference-only work may succeed without edits; do not make artificial changes. Every changed file still requires verification.",
197
- ].join("\n\n");
226
+ ...(contextPack ? [contextPackBlock(contextPack)] : []),
227
+ ].filter(Boolean).join("\n\n");
198
228
  }
199
229
 
200
230
  /** Report contract deviations so the Master does not accept unverified work. */
@@ -107,6 +107,8 @@ export interface WorkflowConfig {
107
107
  readOnlyOnScoutModel: boolean;
108
108
  /** The QA gate reviews with a clean context: the request, plan, board contracts and diff, not the workers' own accounts of their work. */
109
109
  cleanReview: boolean;
110
+ /** One combined budget, in characters, for everything a prompt injects as knowledge per role (standards, knowledge, decisions, bookmarks, scripts). */
111
+ knowledgeStartupBudget: number;
110
112
  }
111
113
 
112
114
  /**
@@ -285,6 +287,7 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
285
287
  prefetchScout: true,
286
288
  readOnlyOnScoutModel: true,
287
289
  cleanReview: true,
290
+ knowledgeStartupBudget: 8000,
288
291
  },
289
292
  lint: { mode: "advise", command: "", extensions: [], timeoutMs: 2 * 60 * 1000 },
290
293
  knowledge: {
@@ -403,6 +406,11 @@ function flag(value: unknown, fallback: boolean): boolean {
403
406
  return typeof value === "boolean" ? value : fallback;
404
407
  }
405
408
 
409
+ /** A whole number of characters for the combined startup knowledge budget; anything smaller than 1,000 or not a whole number keeps the default. */
410
+ function startupBudgetChars(value: unknown, fallback: number): number {
411
+ return typeof value === "number" && Number.isInteger(value) && value >= 1000 ? value : fallback;
412
+ }
413
+
406
414
  function normalizeLobby(value: unknown): LobbyConfig {
407
415
  const source = value as { planningPanel?: unknown; startOn?: unknown; panels?: unknown; keys?: unknown; maxPlanningRounds?: unknown; web?: unknown } | undefined;
408
416
  const defaults = DEFAULT_CONFIG.lobby;
@@ -509,6 +517,7 @@ export function resolveConfig(partial: unknown): BotLobbyConfig {
509
517
  workflow.prefetchScout = workflow.prefetchScout !== false;
510
518
  workflow.readOnlyOnScoutModel = workflow.readOnlyOnScoutModel !== false;
511
519
  workflow.cleanReview = workflow.cleanReview !== false;
520
+ workflow.knowledgeStartupBudget = startupBudgetChars(workflow.knowledgeStartupBudget, DEFAULT_CONFIG.workflow.knowledgeStartupBudget);
512
521
  workflow.gitIsolation = isGitIsolation(workflow.gitIsolation) ? workflow.gitIsolation : DEFAULT_CONFIG.workflow.gitIsolation;
513
522
  // Agent time limits are gone: a config file that still names them is cleaned on its next save.
514
523
  // So are quick fixes: the lobby chat does that work now.
@@ -1,5 +1,6 @@
1
1
  import type { WorkerAssignment, AssignmentExpansionRequest } from "../execution/assignment.ts";
2
2
  import type { LintReport } from "./lint.ts";
3
+ import type { VerificationReport } from "./verification.ts";
3
4
  import type { Domain, Role } from "./agent.ts";
4
5
  import type { Delivery } from "../delivery/types.ts";
5
6
  import type { TaskCheckpoint } from "../state/checkpoint.ts";
@@ -182,6 +183,19 @@ export interface QaRiskAssessment {
182
183
  /** How much process a task gets: the fast track for a small, clear, low-risk change, the full workflow for the rest. */
183
184
  export type TrackPath = "fast" | "full";
184
185
 
186
+ /** Why a fast-track task is single-worker work, and what would end it. */
187
+ export interface FastPathRecord {
188
+ /** The effort/size/risk rationale that made it fast, as the reading recorded it. */
189
+ basis: string;
190
+ risk: "none" | "low" | "medium" | "high";
191
+ /** The evidence behind the risk level, when the reading found any. */
192
+ riskEvidence?: string;
193
+ /** The one implementation domain that owns the work, when the reading names it. */
194
+ owner?: Domain;
195
+ /** When genuine risk promoted the task off the single-worker path. */
196
+ promotedAt?: string;
197
+ }
198
+
185
199
  /** Who can take part in a task: the three domains and the researcher. */
186
200
  export type TrackMember = Domain | "researcher";
187
201
 
@@ -324,6 +338,8 @@ export interface Task {
324
338
  triage?: TaskTriage;
325
339
  /** The task's track; absent on tasks created before tracks, which take the full workflow. */
326
340
  track?: TaskTrack;
341
+ /** The single-worker fast path's persisted decision; absent on tasks that are not single-worker work. */
342
+ fastPath?: FastPathRecord;
327
343
  /** Files already changed when the first worker started: the QA gate reads them as pre-existing, not as this task's work. */
328
344
  baseline?: ChangeBaseline;
329
345
  /** Review rounds the user granted past `workflow.maxReviewIterations`. */
@@ -334,6 +350,8 @@ export interface Task {
334
350
  git?: TaskGit;
335
351
  /** The lint gate's last report on the files this task's agents touched. */
336
352
  lint?: LintReport;
353
+ /** Final verification's last report: the engine-run checks completion required. */
354
+ verification?: VerificationReport;
337
355
  /** The last read of what the built change warrants of QA, taken as the QA gate starts. */
338
356
  qaRisk?: QaRiskAssessment;
339
357
  /** Set only by the user: the work is accepted with the lint errors it has, so the task may complete. */
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Final verification: the engine-run checks a task must pass before its work
3
+ * is committed and it is called complete (see workflow.ts handleComplete).
4
+ * Like the lint gate, a result is a check the engine ran, never an agent's
5
+ * word; and a recorded pass is reused only while everything it covered —
6
+ * sources, configuration, dependencies, commands and environment — is
7
+ * unchanged. Missing, stale, failed, cancelled and unavailable results are
8
+ * never passes.
9
+ */
10
+
11
+ export type VerifyState = "pass" | "fail" | "unavailable" | "cancelled";
12
+
13
+ export interface VerifyResult {
14
+ /** The check's id: `typecheck`, `test`, `web:build`, `web:check`. */
15
+ id: string;
16
+ state: VerifyState;
17
+ at: string;
18
+ ms: number;
19
+ /** The check's inputs, command and environment as they stood: an equal key means an equal result. */
20
+ fingerprint: string;
21
+ /** A pass taken from the previous report rather than re-run. */
22
+ reused?: boolean;
23
+ /** One line; on a failure, what to do about it. */
24
+ summary: string;
25
+ /** The tail of what the check printed when it failed or could not run. */
26
+ output?: string;
27
+ }
28
+
29
+ export interface VerificationReport {
30
+ at: string;
31
+ /** passing: every applicable check passed; failing: any did not. */
32
+ state: "passing" | "failing";
33
+ /** Every result's id and fingerprint: equal key means an equal report. */
34
+ fingerprint: string;
35
+ results: VerifyResult[];
36
+ /** Why nothing was applicable, when nothing was (no scripts to run). */
37
+ note?: string;
38
+ }
@@ -6,13 +6,14 @@
6
6
  * lines per project; reads keep the newest `MAX_READ` records.
7
7
  */
8
8
  import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync } from "node:fs";
9
+ import { randomUUID } from "node:crypto";
9
10
  import { dirname, join } from "node:path";
10
11
  import type { AgentRun } from "../schemas/findings.ts";
11
12
  import type { RunLogEntry, Task } from "../schemas/task.ts";
12
13
  import { dataRoot } from "./project.ts";
13
14
 
14
- /** `chat`: an agent answering in the lobby chat; `quickfix` is kept so older logs still read. */
15
- export const METRIC_KINDS = ["master", "scout", "worker", "reviewer", "researcher", "chat", "quickfix", "planner", "panel", "classifier"] as const;
15
+ /** `chat`: an agent answering in the lobby chat; `quickfix` is kept so older logs still read; `avoided`: a launch the fast path refused or skipped. */
16
+ export const METRIC_KINDS = ["master", "scout", "worker", "reviewer", "researcher", "chat", "quickfix", "planner", "panel", "classifier", "avoided"] as const;
16
17
  export type MetricKind = (typeof METRIC_KINDS)[number];
17
18
 
18
19
  export type MetricStatus = "success" | "failed" | "cancelled" | "timeout";
@@ -40,6 +41,10 @@ export interface MetricRecord {
40
41
  routedFrom?: string;
41
42
  /** Classifier calls: what the decision spared (seat runs skipped, questions answered). */
42
43
  saved?: number;
44
+ /** Worker runs dispatched with a context pack: the rendered pack's size in characters. */
45
+ contextChars?: number;
46
+ /** Final verification: how many of its checks reused a recorded pass. */
47
+ cacheHits?: number;
43
48
  }
44
49
 
45
50
  /** What the classifier did and spared, for the Metrics tab. */
@@ -210,10 +215,20 @@ function finalStatus(status: AgentRun["status"]): MetricStatus {
210
215
  return status === "running" ? "failed" : status;
211
216
  }
212
217
 
218
+ /** Rendered context-pack sizes by run id, noted at dispatch and consumed when the run is recorded. */
219
+ const runContextChars = new Map<string, number>();
220
+
221
+ /** Record the rendered context-pack size for one worker run, so its metric record carries it. */
222
+ export function noteRunContextChars(runId: string, chars: number): void {
223
+ runContextChars.set(runId, Math.max(0, Math.round(chars)));
224
+ }
225
+
213
226
  /** A finished subagent run as a metric record. */
214
227
  export function metricFromRun(run: AgentRun): MetricRecord {
215
228
  const agent = run.role === "researcher" ? "RESEARCH" : AGENT_NAMES[run.domain] ?? run.domain.toUpperCase();
216
229
  const turns = run.turns ?? run.usage?.turns;
230
+ const contextChars = runContextChars.get(run.runId);
231
+ runContextChars.delete(run.runId);
217
232
  return {
218
233
  id: run.runId,
219
234
  kind: run.role,
@@ -229,6 +244,7 @@ export function metricFromRun(run: AgentRun): MetricRecord {
229
244
  taskId: run.taskId,
230
245
  ...(run.stalled ? { stalled: true } : {}),
231
246
  ...(run.routedFrom ? { routedFrom: run.routedFrom } : {}),
247
+ ...(contextChars !== undefined ? { contextChars } : {}),
232
248
  };
233
249
  }
234
250
 
@@ -253,6 +269,20 @@ export function metricFromLog(entry: RunLogEntry, taskId: string): MetricRecord
253
269
  };
254
270
  }
255
271
 
272
+ /** A launch the fast path refused or skipped: no agent ran, so it cost no time and no tokens. */
273
+ export function avoidedLaunchRecord(taskId: string, description: string): MetricRecord {
274
+ return {
275
+ id: randomUUID(),
276
+ kind: "avoided",
277
+ agent: "ENGINE",
278
+ status: "success",
279
+ startedAt: new Date().toISOString(),
280
+ durationMs: 0,
281
+ taskId,
282
+ purpose: description,
283
+ };
284
+ }
285
+
256
286
  /** Records from the log plus every task's run log, deduplicated by id (the log wins). */
257
287
  export function collectMetrics(logged: readonly MetricRecord[], tasks: readonly Task[]): MetricRecord[] {
258
288
  const byId = new Map<string, MetricRecord>();
@@ -19,7 +19,7 @@ export function knowledgeAsk(body: { text: string; attachments?: string[] }, ctx
19
19
  if (!body.text.trim() && !body.attachments?.length) fail(400, "bad_request", "type a question first");
20
20
  const busy = ctx.service.masterBusy();
21
21
  ctx.service.askKnowledge(withAttachments(body.text, body.attachments, undefined, ctx.service.projectRoot?.()));
22
- return { notice: busy ? "question queued — the oracle answers after its current turn" : "the oracle is checking project knowledge" };
22
+ return { notice: busy ? "question queued — the orchestrator answers after its current turn" : "the orchestrator is checking project knowledge" };
23
23
  }
24
24
 
25
25
  /** The terminal's stale-entry refusal, as `KnowledgeBook` words it. */
@@ -248,7 +248,7 @@ export function tasksAuto(body: { taskId: string; on: boolean }, ctx: ApiContext
248
248
  if (TERMINAL_STATES.includes((task as Task).state)) fail(400, "bad_request", `${body.taskId} is ${(task as Task).state}; auto mode applies to a task under way`);
249
249
  ctx.service.setAuto(body.taskId, body.on);
250
250
  const id = body.taskId;
251
- return { notice: body.on ? `auto mode on — the oracle drives ${id} to completion without asking` : `auto mode off — the oracle asks you again on ${id}`, on: body.on };
251
+ return { notice: body.on ? `auto mode on — the orchestrator drives ${id} to completion without asking` : `auto mode off — the orchestrator asks you again on ${id}`, on: body.on };
252
252
  }
253
253
 
254
254
  /** Leave a message for a task's oracle; blank text is a no-op notice. */
@@ -299,7 +299,7 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
299
299
  toOracle: (text: string) => {
300
300
  const command = parseLobbyCommand(text);
301
301
  if (command?.command === "plan") return { notice: "planning on the Plan tab", open: "plan" as const };
302
- if (command) return "starting a task — the oracle takes it from here";
302
+ if (command) return "starting a task — the orchestrator takes it from here";
303
303
  const mention = parseMention(text);
304
304
  if (mention && mention.agent !== "master") {
305
305
  const source = CHAT_AGENT_SOURCES[mention.agent];
@@ -344,7 +344,7 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
344
344
  comment: (taskId: string, text: string) => {
345
345
  const entry = { id: `C-mock-${(commentSeq += 1)}`, taskId, text, by: fixture.status.sessionId, createdAt: new Date().toISOString(), status: "open" };
346
346
  comments.set(taskId, [...(comments.get(taskId) ?? []), entry]);
347
- return "comment sent to the oracle — it will amend the plan";
347
+ return "comment sent to the orchestrator — it will amend the plan";
348
348
  },
349
349
  editComment: (taskId: string, commentId: string, text: string) => {
350
350
  const existing = (comments.get(taskId) ?? []).find((entry) => entry.id === commentId);
@@ -389,8 +389,8 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
389
389
  if (on) auto.add(taskId);
390
390
  else auto.delete(taskId);
391
391
  },
392
- sendToTask: (taskId: string, _text: string) => (tasks.some((task) => (task as { id: string }).id === taskId) ? `sent — the session driving ${taskId} passes it to its oracle` : `no task ${taskId}`),
393
- sendToSession: (_sessionId: string, _text: string) => "sent — that session passes it to its oracle within a few seconds",
392
+ sendToTask: (taskId: string, _text: string) => (tasks.some((task) => (task as { id: string }).id === taskId) ? `sent — the session driving ${taskId} passes it to its orchestrator` : `no task ${taskId}`),
393
+ sendToSession: (_sessionId: string, _text: string) => "sent — that session passes it to its orchestrator within a few seconds",
394
394
  skipTaskStep: async (taskId: string, step: number, text: string, reason: string) => {
395
395
  const task = tasks.find((entry) => (entry as { id: string }).id === taskId) as { id: string; skippedSteps?: Array<{ text: string; reason: string; at: string }>; decisions?: Array<{ domain: string; text: string; createdAt: string }> } | undefined;
396
396
  if (!task) throw new Error(`no task ${taskId}`);
@@ -398,7 +398,7 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
398
398
  task.skippedSteps = [...(task.skippedSteps ?? []), { text, reason: reason.trim(), at }];
399
399
  task.decisions = [...(task.decisions ?? []), { domain: "master", text: `The user skipped step ${step + 1} ("${text}") from the Tasks screen. Reason: ${reason.trim()}`, createdAt: at }];
400
400
  lobbyTopics.bump("tasks");
401
- return { notice: `step ${step + 1} skipped; the oracle has been told` };
401
+ return { notice: `step ${step + 1} skipped; the orchestrator has been told` };
402
402
  },
403
403
  resumeTask: async (taskId: string) => {
404
404
  const task = tasks.find((entry) => (entry as { id: string }).id === taskId) as { id: string; title: string; paused?: boolean; ownerSessionId?: string } | undefined;
@@ -552,9 +552,9 @@ function mockLedger(view: { agent: string; file: string; entries: Array<Record<s
552
552
  return {
553
553
  pins: [{ agent, file, entry: first, at: iso(3 * day) }],
554
554
  events: [
555
- { id: "ev1", agent, file, entry: first, by: "Oracle", what: "wrote this while planning the offline mock", source: "Planning · offline mock", at: iso(9 * day) },
555
+ { id: "ev1", agent, file, entry: first, by: "Orchestrator", what: "wrote this while planning the offline mock", source: "Planning · offline mock", at: iso(9 * day) },
556
556
  { id: "ev2", agent, file, entry: first, by: "you", what: "edited it", before: "- Mock everything the page needs.", at: iso(3 * day) },
557
- { id: "ev3", agent, file, entry: second, by: "Oracle", what: "saved this from a chat with you", source: "Chat with you", at: iso(14 * day) },
557
+ { id: "ev3", agent, file, entry: second, by: "Orchestrator", what: "saved this from a chat with you", source: "Chat with you", at: iso(14 * day) },
558
558
  { id: "ev4", agent, file, entry: third, by: "Backend", what: "wrote this while working on task T-mock-1", source: "Task T-mock-1", at: iso(2 * day) },
559
559
  ],
560
560
  proposals: [
@@ -13,7 +13,9 @@
13
13
  * `action=track`; the user can force either path with `--fast` or `--full`.
14
14
  * Once work is under way a track only gets stricter.
15
15
  */
16
- import type { Task, TaskTrack, TaskTriage, TrackMember, TrackPath, TriageSize } from "../schemas/task.ts";
16
+ import type { Task, TaskTrack, TaskTriage, TrackMember, TrackPath, TriageSize, FastPathRecord } from "../schemas/task.ts";
17
+ import type { Domain } from "../schemas/agent.ts";
18
+ import { effortBasis, type EffortScore } from "../classifier/effort.ts";
17
19
 
18
20
  export const TRACK_MEMBERS: readonly TrackMember[] = ["designer", "backend", "qa", "researcher"];
19
21
 
@@ -271,6 +273,8 @@ const SOLO_YES = 0.7;
271
273
  export interface TrackOptions {
272
274
  /** `workflow.fastTrack`: false puts every task on the full workflow. */
273
275
  fastTrack: boolean;
276
+ /** Estimated work, independent of request length or file counts. */
277
+ effort?: EffortScore;
274
278
  /** The user's `--fast` or `--full`. */
275
279
  forced?: TrackPath;
276
280
  /** The task follows a plan agreed in the planning panel. */
@@ -304,7 +308,10 @@ export function chooseTrack(request: string, triage: TaskTriage | undefined, opt
304
308
  const source: TaskTrack["source"] = triage ? "classifier" : "rules";
305
309
  // A self-contained build (one file, one page) needs no survey or plan round even when it is rich.
306
310
  const selfContained = Boolean(rules.solo) || (triage?.solo ?? 0) >= SOLO_YES;
307
- const fast = (size === "trivial" || size === "small" || (size === "medium" && selfContained)) && !rules.risk && !unclear;
311
+ const estimated = options.effort && options.effort.confidence >= SIZE_CONFIDENCE;
312
+ const manageable = estimated ? options.effort!.level !== "complex" : size === "trivial" || size === "small" || (size === "medium" && selfContained);
313
+ if (estimated) reasons.push(effortBasis(options.effort)!);
314
+ const fast = manageable && !rules.risk && !unclear;
308
315
  const [path, why, by]: [TrackPath, string[], TaskTrack["source"]] = options.forced
309
316
  ? [options.forced, [`the user asked for the ${options.forced === "fast" ? "fast track" : "full workflow"}`], "user"]
310
317
  : options.approvedPlan
@@ -353,6 +360,61 @@ export function satOut(task: Task, member: TrackMember): boolean {
353
360
  return Boolean(task.track?.satOut?.includes(member));
354
361
  }
355
362
 
363
+ /* ------------------------------------------------------------ the single-worker fast path */
364
+
365
+ /** The builders a task's work may belong to. */
366
+ const BUILD_DOMAINS: readonly TrackMember[] = ["designer", "backend"];
367
+
368
+ /**
369
+ * The single-worker fast-path record for a task on the fast track, from the
370
+ * reading that chose the track: why it is fast (basis: the effort/size/risk
371
+ * rationale the reading already recorded), how risky it read (risk), and the
372
+ * one domain that owns the work (owner). Undefined when the track is not
373
+ * single-worker work: not fast, more than one builder, or QA on the roster
374
+ * (the change needs tests, so more than one agent takes part).
375
+ */
376
+ export function fastPathRecord(request: string, track: TaskTrack, effort?: EffortScore): FastPathRecord | undefined {
377
+ if (track.path !== "fast") return undefined;
378
+ const builders = track.roster.filter((member): member is Domain => BUILD_DOMAINS.includes(member));
379
+ if (track.roster.includes("qa") || builders.length > 1) return undefined;
380
+ const risk = readRequest(request).risk;
381
+ const basis = [effortBasis(effort), ...(track.reasons ?? [])].filter(Boolean).join("; ");
382
+ return {
383
+ basis: basis || "fast track",
384
+ risk: risk ? "medium" : "none",
385
+ ...(risk ? { riskEvidence: `the request reads as serious: touches ${risk}` } : {}),
386
+ ...(builders.length === 1 ? { owner: builders[0] } : {}),
387
+ };
388
+ }
389
+
390
+ /** A fast-track task with an unpromoted low-risk record: one worker carries it, end to end. */
391
+ export function singleWorker(task: Task): boolean {
392
+ const fast = task.fastPath;
393
+ return task.track?.path === "fast" && !!fast && (fast.risk === "none" || fast.risk === "low") && !fast.promotedAt;
394
+ }
395
+
396
+ const RISK_ORDER = ["none", "low", "medium", "high"] as const;
397
+
398
+ /**
399
+ * End the single-worker path for a task whose work turned out riskier than
400
+ * its request read: the record keeps the level and the evidence, the track
401
+ * goes full with the QA gate, and every fast-path bypass lifts. Returns true
402
+ * when it promoted; false when there was nothing to promote.
403
+ */
404
+ export function promoteFastPath(task: Task, risk: "medium" | "high", evidence: string, now = new Date().toISOString()): boolean {
405
+ const fast = task.fastPath;
406
+ const track = task.track;
407
+ if (!fast || !track || fast.promotedAt) return false;
408
+ if (RISK_ORDER.indexOf(risk) > RISK_ORDER.indexOf(fast.risk)) fast.risk = risk;
409
+ fast.riskEvidence = evidence;
410
+ fast.promotedAt = now;
411
+ track.path = "full";
412
+ track.reasons = [...track.reasons, `risk promotion: ${evidence}`].slice(-8);
413
+ track.roster = parseRoster([...track.roster, "qa"]);
414
+ track.at = now;
415
+ return true;
416
+ }
417
+
356
418
  /* ------------------------------------------------------------ what a track asks of the engine */
357
419
 
358
420
  export function onFastTrack(task: Task): boolean {
@@ -405,7 +467,7 @@ export function builtSomething(task: Task): boolean {
405
467
  /* ------------------------------------------------------------ words */
406
468
 
407
469
  export function rosterWords(roster: readonly TrackMember[]): string {
408
- return roster.length > 0 ? roster.map((member) => MEMBER_LABELS[member]).join(", ") : "the one domain that owns the files (the oracle picks)";
470
+ return roster.length > 0 ? roster.map((member) => MEMBER_LABELS[member]).join(", ") : "the one domain that owns the files (the orchestrator picks)";
409
471
  }
410
472
 
411
473
  /** The track in one line, for the oracle's context and `/bot-lobby status`. */