@a-t-h-i/bot-lobby 0.6.39 → 0.6.41

package/src/master/scout-cache.ts

@@ -0,0 +1,70 @@
+/**
+ * Scout findings kept for reuse. A scout asked the same thing (same domain,
+ * same instruction, same task) on a work tree that has not changed since it
+ * last answered gives the same answer, so the engine hands the oracle the
+ * earlier findings instead of running it again: after a crash and resume, or
+ * when the oracle repeats a question. Any change to the tree (a commit, an
+ * edit, a new file) makes every cached answer stale.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Domain } from "../schemas/agent.ts";
+import type { ScoutOutcome } from "./master.ts";
+
+interface CachedScout {
+  version: 1;
+  tree: string;
+  at: string;
+  outcome: ScoutOutcome;
+}
+
+/** Cached answers older than this are dropped when the next one is written. */
+export const SCOUT_CACHE_DAYS = 7;
+
+export function scoutCacheDir(dataDir: string): string {
+  return join(dataDir, "cache", "scouts");
+}
+
+/** The question a scout is asked, as a file name. */
+export function scoutKey(domain: Domain, instruction: string, taskText: string): string {
+  return createHash("sha256").update(JSON.stringify([domain, instruction.trim(), taskText.trim()])).digest("hex").slice(0, 32);
+}
+
+/** The earlier answer to this question on this tree, marked with when it was taken; undefined when there is none or the tree changed. */
+export function readCachedScout(dataDir: string, key: string, tree: string): ScoutOutcome | undefined {
+  try {
+    const cached = JSON.parse(readFileSync(join(scoutCacheDir(dataDir), `${key}.json`), "utf8")) as Partial<CachedScout>;
+    if (cached.version !== 1 || cached.tree !== tree || !cached.outcome?.usable || !cached.at) return undefined;
+    return { ...cached.outcome, reused: cached.at };
+  } catch {
+    return undefined;
+  }
+}
+
+function pruneScoutCache(dir: string, now: number): void {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    try {
+      if (now - statSync(path).mtimeMs > SCOUT_CACHE_DAYS * 86_400_000) rmSync(path, { force: true });
+    } catch {
+      // Gone already.
+    }
+  }
+}
+
+/** Keep a usable answer for this question on this tree; failures are ignored (the cache only saves time). */
+export function writeCachedScout(dataDir: string, key: string, tree: string, outcome: ScoutOutcome, now = new Date()): void {
+  if (!outcome.usable) return;
+  const dir = scoutCacheDir(dataDir);
+  try {
+    mkdirSync(dir, { recursive: true });
+    pruneScoutCache(dir, now.getTime());
+    const path = join(dir, `${key}.json`);
+    const { reused: _reused, ...fresh } = outcome;
+    writeFileSync(`${path}.tmp`, JSON.stringify({ version: 1, tree, at: now.toISOString(), outcome: fresh } satisfies CachedScout));
+    renameSync(`${path}.tmp`, path);
+  } catch {
+    // Without the cache the scout just runs next time.
+  }
+}

package/src/master/synthesis.ts

@@ -1,4 +1,5 @@
 import type { Domain } from "../schemas/agent.ts";
+import type { RelevantFile } from "../schemas/findings.ts";
 import { truncate } from "../text.ts";
 import type { ScoutOutcome } from "./master.ts";
 
@@ -34,16 +35,23 @@ export function detectSharedFiles(outcomes: ScoutOutcome[]): { path: string; dom
     .map(([path, domains]) => ({ path, domains: [...domains] }));
 }
 
+/** A relevant file as `path:lines — why`, the way a brief should point at it. */
+export function fileAnchor(file: RelevantFile, reasonChars = 140): string {
+  const anchor = file.lines ? `${file.path}:${file.lines}` : file.path;
+  return file.reason ? `${anchor} — ${truncate(file.reason, reasonChars)}` : anchor;
+}
+
 function describeOutcome(outcome: ScoutOutcome, rawLimit: number): string {
   const { result } = outcome;
+  const reused = outcome.reused ? `, reused from ${outcome.reused.slice(0, 16).replace("T", " ")} UTC: same question, tree unchanged` : "";
   const lines = [
-    `### ${result.domain} (${outcome.run.status}${outcome.usable ? "" : ", unusable"}) — confidence: ${result.confidence}`,
+    `### ${result.domain} (${outcome.run.status}${outcome.usable ? "" : ", unusable"}${reused}) — confidence: ${result.confidence}`,
     result.scope ? `Scope: ${result.scope}` : "",
     ...result.findings.slice(0, 12).map((finding) => `- ${finding}`),
     ...result.risks.slice(0, 5).map((risk) => `- RISK: ${risk}`),
     ...result.recommendations.slice(0, 5).map((rec) => `- REC: ${rec}`),
     result.relevantFiles.length > 0
-      ? `Files: ${result.relevantFiles.slice(0, 10).map((file) => file.path).join(", ")}`
+      ? `Files:\n${result.relevantFiles.slice(0, 10).map((file) => `- ${fileAnchor(file)}`).join("\n")}`
       : "",
     outcome.issues.length > 0 ? `Issues: ${outcome.issues.join("; ")}` : "",
     result.raw.trim() ? `Raw (truncated): ${truncate(result.raw.trim(), rawLimit)}` : "",

package/src/pi/model-settings.ts

@@ -47,7 +47,7 @@ interface EntryPatch {
 export function patchEntry(config: BotLobbyConfig, kind: SettingsKind, patch: EntryPatch): BotLobbyConfig {
   const next: BotLobbyConfig = { ...config, agents: { ...config.agents } };
   if (kind === "master") next.master = { ...config.master, ...patch } as AgentModelConfig;
-  else if (kind === "scout") next.scout = { model: patch.model ?? config.scout.model, timeoutMs: patch.timeoutMs ?? config.scout.timeoutMs };
+  else if (kind === "scout") next.scout = { ...config.scout, model: patch.model ?? config.scout.model, timeoutMs: patch.timeoutMs ?? config.scout.timeoutMs };
   else if (kind === "researcher") next.researcher = { ...config.researcher, ...patch } as AgentModelConfig;
   else if (kind === "quickfix") next.quickFix = { ...config.quickFix, ...patch } as AgentModelConfig;
   else if (kind === "planner") next.planner = { ...config.planner, ...patch } as AgentModelConfig;
@@ -83,10 +83,12 @@ export function prefillModels(config: BotLobbyConfig, sessionModel: string | und
   return { config: next, filled };
 }
 
-/** `on · OpenCode Zen · jev-1.13-free · key stored in pi`, for the settings menu and `/bot-lobby config`. */
+/** `on · OpenCode Zen · jev-1.13-free · key stored in pi` (or `on · openai/gpt-5-nano · your pi login`), for the settings menu and `/bot-lobby config`. */
 export function classifierSummary(config: BotLobbyConfig, status: StatusSource | undefined): string {
+  const state = config.classifier.enabled ? "on" : "off";
+  if (config.classifier.engine) return [state, config.classifier.engine, "your pi login"].join(" · ");
   const { host, model } = jevEndpoint(config.classifier, status);
   const via = config.classifier.provider === "auto" ? `${host.label} (auto)` : host.label;
-  return [config.classifier.enabled ? "on" : "off", via, model, `key ${describeKey(host, status)}`].join(" · ");
+  return [state, via, model, `key ${describeKey(host, status)}`].join(" · ");
 }
 

package/src/pi/tool-budget.ts

@@ -0,0 +1,66 @@
+/**
+ * A hard limit on a subagent's tool calls, enforced inside its own process so
+ * it holds on every provider and model. The engine sets the budget through
+ * `BOT_LOBBY_TOOL_BUDGET` (scouts get `scout.maxToolCalls`). At 60% the next
+ * tool result tells the agent to wrap up; past the limit every call is
+ * refused with the reason, so the agent writes its report with what it has.
+ * An agent that keeps calling anyway is stopped after a few refusals.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const TOOL_BUDGET_ENV = "BOT_LOBBY_TOOL_BUDGET";
+
+export interface ToolBudget {
+  /** The call after which the agent is told to wrap up. */
+  warnAt: number;
+  /** Calls past this are refused. */
+  max: number;
+}
+
+/** Refusals in a row after which the run is stopped rather than refused again. */
+export const MAX_REFUSALS = 5;
+
+/** The env that gives a subagent `max` tool calls; none for 0 (no limit). */
+export function toolBudgetEnv(max: number): Record<string, string> {
+  return max > 0 ? { [TOOL_BUDGET_ENV]: String(Math.round(max)) } : {};
+}
+
+export function parseToolBudget(value: string | undefined): ToolBudget | undefined {
+  const max = Number(value);
+  if (!value || !Number.isFinite(max) || max < 1) return undefined;
+  return { warnAt: Math.max(1, Math.round(max * 0.6)), max: Math.round(max) };
+}
+
+/** What the agent is told up front, in its workflow context. */
+export function toolBudgetNote(max: number): string {
+  const budget = parseToolBudget(String(max));
+  return budget ? `Tool budget: at most ${budget.max} tool calls. After ${budget.warnAt} you are told to wrap up; past ${budget.max} every call is refused and you report with what you have.` : "";
+}
+
+export function budgetWarning(used: number, budget: ToolBudget): string {
+  return `bot-lobby: ${used} of your ${budget.max} tool calls are used. Stop exploring: check only what your answer still needs, then write your report.`;
+}
+
+export function budgetRefusal(budget: ToolBudget): string {
+  return `bot-lobby: your ${budget.max} tool calls are spent, so this call was not run. Write your report now in the required format with what you have, and mark what you did not verify as an assumption.`;
+}
+
+/** Count the agent's own tool calls (not those a tool made for it), warn once, then refuse. */
+export function registerToolBudget(pi: ExtensionAPI, budget = parseToolBudget(process.env[TOOL_BUDGET_ENV])): void {
+  if (!budget) return;
+  let used = 0;
+  let refused = 0;
+  let warned = false;
+  pi.on("tool_call", (event) => {
+    if (event.parentToolCallId) return undefined;
+    used += 1;
+    if (used <= budget.max) return undefined;
+    refused += 1;
+    return { block: true, reason: budgetRefusal(budget), ...(refused >= MAX_REFUSALS ? { terminate: true } : {}) };
+  });
+  pi.on("tool_result", (event) => {
+    if (event.parentToolCallId || warned || used < budget.warnAt || used > budget.max) return undefined;
+    warned = true;
+    return { content: [...event.content, { type: "text" as const, text: budgetWarning(used, budget) }] };
+  });
+}

package/src/roles/markdown.ts

@@ -56,9 +56,17 @@ export function bullets(text: string | undefined): string[] {
     .filter((line) => line.length > 0);
 }
 
-/** Parse a `path — reason` bullet into its parts. */
-export function parseFileBullet(text: string): { path: string; reason: string } {
+/** Split a `path:12-40` (or `path#L12-L40`) anchor into the path and its lines. */
+function splitAnchor(anchor: string): { path: string; lines?: string } {
+  const match = /^(.+?)(?::|#L)(\d+)(?::\d+)?(?:\s*[-–]\s*L?(\d+)(?::\d+)?)?$/.exec(anchor);
+  if (!match) return { path: anchor };
+  return { path: match[1]!, lines: match[3] && match[3] !== match[2] ? `${match[2]}-${match[3]}` : match[2]! };
+}
+
+/** Parse a `path — reason` bullet (the path may carry lines: `path:12-40`) into its parts. */
+export function parseFileBullet(text: string): { path: string; lines?: string; reason: string } {
   const match = /^`?([^`\s]+)`?\s*(?:[—–]|--|-)\s*(.*)$/.exec(text);
-  if (match) return { path: match[1]!, reason: match[2]!.trim() };
-  return { path: text.trim(), reason: "" };
+  const [anchor, reason] = match ? [match[1]!, match[2]!.trim()] : [text.trim().replace(/^`|`$/g, ""), ""];
+  const { path, lines } = splitAnchor(anchor);
+  return lines ? { path, lines, reason } : { path, reason };
 }

package/src/roles/scout.ts

@@ -12,7 +12,8 @@ export const scoutSpec: RoleSpec = {
     "Respond with exactly these sections and nothing else:",
     "`## Scope`, `## Findings`, `## Relevant Files`, `## Existing Patterns`,",
     "`## Risks`, `## Recommendations`, `## Confidence`.",
-    "Use `- ` bullets. `## Relevant Files` entries are `- \\`path\\` — reason`.",
+    "Use `- ` bullets. `## Relevant Files` entries are `- \\`path:start-end\\` — reason`, with the lines of the code that matters",
+    "(`path:42` for one line, the bare `path` only when the whole file does), so the worker opens the exact place.",
     "`## Confidence` is exactly one of `High`, `Medium`, `Low`.",
     "Keep the whole response under 400 words. Report uncertainty; do not implement.",
     "An optional `## Pushback` (`**Request:**`, `**Reason:**`, optional `**Alternative:**`) flags a change you",

package/src/schemas/configuration.ts

@@ -38,6 +38,8 @@ export interface ScoutConfig {
   mcpTools?: string[];
   model: ModelRef;
   timeoutMs: number;
+  /** Tool calls a scout may make: it is told to wrap up at 60% and refused more past this, so it reports with what it has; 0 = no limit. */
+  maxToolCalls: number;
 }
 
 /** Subagent kinds with their own settings entry. */
@@ -91,6 +93,10 @@ export interface WorkflowConfig {
   routeQuickFixes: boolean;
   /** A new task gets a git branch or worktree of its own, named after it; `--branch` and `--worktree` decide for one task. */
   gitIsolation: GitIsolation;
+  /** Scouts, workers, quick fixes and the planner get the repository map: the layout and the files matching their step, with each file's purpose, names and unchanged scout notes. */
+  repoMap: boolean;
+  /** A scout asked the same thing again for the same task, on a tree that has not changed, reuses its findings instead of running. */
+  reuseScouts: boolean;
 }
 
 /**
@@ -206,9 +212,15 @@ export interface ClassifierThresholds {
   quickFixLargeAt: number;
 }
 
-/** The Jev classifier: a fast model for obvious decisions, so large models spend fewer tokens on them. */
+/** The classifier: a fast model for obvious decisions, so large models spend fewer tokens on them. */
 export interface ClassifierConfig {
   enabled: boolean;
+  /**
+   * The model that answers, as `provider/id`: any classifier model pi lists
+   * (Jev, Cloudflare's clef, Liquid's d1, …) or any chat model you are signed
+   * in to (OpenAI, Anthropic, Google, …). Empty calls Jev on `provider`.
+   */
+  engine: string;
   /** Where Jev is called; the key comes from pi's own key store for that host. */
   provider: JevHostName;
   /** A pinned Jev model; empty uses the host's default. */
@@ -250,7 +262,7 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     backend: { model: INHERIT_MODEL, thinking: DEFAULT_THINKING, instructions: "", timeoutMs: 15 * 60 * 1000 },
     qa: { model: INHERIT_MODEL, thinking: DEFAULT_THINKING, instructions: "", timeoutMs: 15 * 60 * 1000 },
   },
-  scout: { model: INHERIT_MODEL, timeoutMs: 8 * 60 * 1000 },
+  scout: { model: INHERIT_MODEL, timeoutMs: 8 * 60 * 1000, maxToolCalls: 30 },
   researcher: { model: INHERIT_MODEL, thinking: "low", instructions: "", timeoutMs: 10 * 60 * 1000 },
   quickFix: { model: INHERIT_MODEL, thinking: "low", instructions: "", timeoutMs: 10 * 60 * 1000 },
   planner: { model: INHERIT_MODEL, thinking: "high", instructions: "", timeoutMs: 5 * 60 * 1000 },
@@ -272,6 +284,8 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     briefCheck: true,
     routeQuickFixes: true,
     gitIsolation: "off",
+    repoMap: true,
+    reuseScouts: true,
   },
   lint: { mode: "advise", command: "", extensions: [], timeoutMs: 2 * 60 * 1000 },
   knowledge: {
@@ -292,6 +306,7 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
   },
   classifier: {
     enabled: false,
+    engine: "",
     provider: "auto",
     model: "",
     baseUrl: "",
@@ -346,6 +361,7 @@ function normalizeScout(override: Partial<ScoutConfig> | undefined): ScoutConfig
   return {
     model: typeof override?.model === "string" && override.model.trim() ? override.model : base.model,
     timeoutMs: positive(override?.timeoutMs) ?? base.timeoutMs,
+    maxToolCalls: typeof override?.maxToolCalls === "number" && Number.isFinite(override.maxToolCalls) && override.maxToolCalls >= 0 ? Math.round(override.maxToolCalls) : base.maxToolCalls,
     ...(mcpTools.length ? { mcpTools } : {}),
   };
 }
@@ -432,6 +448,7 @@ function normalizeClassifier(value: unknown): ClassifierConfig {
   const provider = typeof source.provider === "string" && (JEV_HOSTS as readonly string[]).includes(source.provider) ? source.provider as JevHostName : defaults.provider;
   return {
     enabled: flag(source.enabled, defaults.enabled),
+    engine: text(source.engine, defaults.engine).trim(),
     provider,
     model: text(source.model, defaults.model),
     baseUrl: text(source.baseUrl, defaults.baseUrl),
@@ -456,6 +473,8 @@ export function resolveConfig(partial: unknown): BotLobbyConfig {
   workflow.fastTrack = workflow.fastTrack !== false;
   workflow.briefCheck = workflow.briefCheck !== false;
   workflow.routeQuickFixes = workflow.routeQuickFixes !== false;
+  workflow.repoMap = workflow.repoMap !== false;
+  workflow.reuseScouts = workflow.reuseScouts !== false;
   workflow.gitIsolation = isGitIsolation(workflow.gitIsolation) ? workflow.gitIsolation : DEFAULT_CONFIG.workflow.gitIsolation;
   workflow.taskBudgetMinutes = typeof workflow.taskBudgetMinutes === "number" && workflow.taskBudgetMinutes > 0 ? Math.min(24 * 60, Math.round(workflow.taskBudgetMinutes)) : 0;
   const knowledge = { ...DEFAULT_CONFIG.knowledge, ...(src.knowledge as Partial<KnowledgeConfig> | undefined) };

package/src/schemas/findings.ts

@@ -3,6 +3,8 @@ import type { Blocker, Verdict } from "./task.ts";
 
 export interface RelevantFile {
   path: string;
+  /** The lines that matter (`42` or `12-40`), when the scout gave them as `path:12-40`. */
+  lines?: string;
   reason: string;
 }
 

package/src/webui/api/settings.ts

@@ -90,7 +90,8 @@ export function settingsGet(ctx: ApiContext): SettingsInfo {
     config = prefilled.config;
     pushNotice(`${prefilled.filled.map(kindLabel).join(", ")} now run on the session model; change them here any time.`);
   }
-  return { config: stripSecrets(config), models: ctx.service.models?.() ?? [] };
+  const classifiers = ctx.service.classifierModels?.() ?? [];
+  return { config: stripSecrets(config), models: ctx.service.models?.() ?? [], ...(classifiers.length > 0 ? { classifierModels: classifiers } : {}) };
 }
 
 /** The linters the project configures (its top and a few folders below), and whether each is installed. */

package/src/webui/dev/fake-service.ts

@@ -455,6 +455,7 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
     },
     configChanged: () => {},
     models: () => models.map((model) => ({ id: model.id, label: model.label, thinkingLevels: [...model.thinkingLevels] })),
+    classifierModels: () => [{ id: "opencode/jev-1.13-free", label: "Jev 1.13 (free)" }, { id: "openrouter/liquid/d1", label: "Liquid D1" }],
     issuesEnabled: () => fixture.status.issuesEnabled,
     workspace: () => ({ ...fixture.status.workspace }),
     zen: () => ({ ...(fixture.zen.task ? { task: { ...fixture.zen.task } } : {}), runs: [...fixture.zen.runs] }),

package/src/webui/protocol.ts

@@ -200,6 +200,14 @@ export interface SettingsLinter {
 export interface SettingsInfo {
   config: BotLobbyConfig;
   models: SettingsModelInfo[];
+  /** Classifier models pi can call with the logins it holds (Jev on each host, Cloudflare's clef, Liquid's d1, …). */
+  classifierModels?: SettingsClassifierModel[];
+}
+
+/** A classifier model for the classifier's picker: `provider/id` and its name. */
+export interface SettingsClassifierModel {
+  id: string;
+  label: string;
 }
 
 /** One message on the event stream (`GET /api/events`, server-sent events). */