@a-t-h-i/bot-lobby 0.6.38 → 0.6.40

package/src/classifier/files.ts

@@ -14,7 +14,7 @@
  */
 import { execFile } from "node:child_process";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { open, readdir, stat } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { dataRoot } from "../state/project.ts";
@@ -36,6 +36,10 @@ export interface FileScope {
 export interface IndexedFile {
   path: string;
   excerpt: string;
+  /** What the file says it is for: its opening comment (a Markdown file's first heading), one line; "" when it says nothing. */
+  purpose?: string;
+  /** The top-level names it declares or exports (a Markdown file's headings), in file order. */
+  symbols?: string[];
 }
 
 export interface LikelyFile {
@@ -122,9 +126,12 @@ const COMMENT = /^(\/\/|\/\*|\*|#(?![!#])|"""|'''|<!--|--\s|;)/;
  * signatures (headings for Markdown), then its imports; the first lines when
  * none of those exist.
  */
-export function excerptOf(path: string, text: string, max = EXCERPT_CHARS): string {
-  const lines = text.split(/\r?\n/).slice(0, 600);
-  const markdown = /\.(md|mdx|markdown|rst|txt)$/i.test(path);
+function isMarkdown(path: string): boolean {
+  return /\.(md|mdx|markdown|rst|txt)$/i.test(path);
+}
+
+/** The words of a file's opening comment, a line each (at most four); none for Markdown or code that starts without one. */
+function leadComment(lines: readonly string[], markdown: boolean): string[] {
   const lead: string[] = [];
   for (const line of lines) {
     const trimmed = line.trim();
@@ -134,10 +141,17 @@ export function excerptOf(path: string, text: string, max = EXCERPT_CHARS): stri
     }
     if (trimmed.startsWith("#!")) continue;
     if (markdown || !COMMENT.test(trimmed)) break;
-    const words = trimmed.replace(/^(\/\*+|\*+\/?|\/\/+|#+|"""|'''|<!--|--|;+)\s*/, "").replace(/\*\/$|-->$/, "").trim();
+    const words = trimmed.replace(/^(\/\*+|\*+\/?|\/\/+|#+|"""|'''|<!--|--|;+)\s*/, "").replace(/\*\/$|-->$|"""$|'''$/, "").trim();
     if (words) lead.push(words);
     if (lead.length >= 4) break;
   }
+  return lead;
+}
+
+export function excerptOf(path: string, text: string, max = EXCERPT_CHARS): string {
+  const lines = text.split(/\r?\n/).slice(0, 600);
+  const markdown = isMarkdown(path);
+  const lead = leadComment(lines, markdown);
   const signatures: string[] = [];
   const imports: string[] = [];
   for (const line of lines) {
@@ -155,10 +169,68 @@ export function excerptOf(path: string, text: string, max = EXCERPT_CHARS): stri
   return clip(body, max);
 }
 
+const PURPOSE_CHARS = 120;
+
+/** What a file says it is for, in one line: the first sentence of its opening comment, or a Markdown file's first heading; "" for a licence header or none. */
+export function purposeOf(path: string, text: string): string {
+  const lines = text.split(/\r?\n/).slice(0, 80);
+  if (isMarkdown(path)) {
+    const heading = lines.map((line) => /^#{1,3}\s+(.+?)\s*#*\s*$/.exec(line.trim())?.[1]).find(Boolean);
+    return heading ? clip(heading, PURPOSE_CHARS) : "";
+  }
+  const lead = leadComment(lines, false).join(" ").replace(/^@(?:file|fileoverview|module)\s+/i, "");
+  if (!lead || /copyright|licen[cs]e|spdx-|eslint-|@ts-|prettier-ignore|biome-ignore|^use strict/i.test(lead)) return "";
+  const sentence = /^(.+?[.!?])(?:\s|$)/.exec(lead)?.[1] ?? lead;
+  return clip(sentence, PURPOSE_CHARS);
+}
+
+/** Top-level declarations by language; each pattern's groups are the names. Indented (nested) code is left out. */
+const SYMBOL_PATTERNS: readonly RegExp[] = [
+  /^export\s+(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function\*?|class|interface|type|const\s+enum|enum|const|let|var|namespace)\s+([A-Za-z_$][\w$]*)/,
+  /^(?:async\s+)?def\s+([A-Za-z]\w*)/,
+  /^class\s+([A-Za-z]\w*)/,
+  /^func\s+(?:\([^)]*\)\s*)?([A-Za-z]\w*)/,
+  /^type\s+([A-Z]\w*)\s+(?:struct|interface|func|map|\[|\w)/,
+  /^pub(?:\([\w:]+\))?\s+(?:async\s+)?(?:unsafe\s+)?(?:fn|struct|enum|trait|type|const|static|mod)\s+([A-Za-z_]\w*)/,
+  /^(?:module|def)\s+([A-Za-z_][\w:.]*[?!]?)/,
+  /^(?:public\s+|internal\s+|open\s+|export\s+)?(?:abstract\s+|final\s+|sealed\s+|data\s+|static\s+)*(?:class|interface|enum|record|struct|object|protocol)\s+([A-Za-z_]\w*)/,
+];
+/** Plain top-level functions and classes, for a script that exports nothing. */
+const LOCAL_PATTERNS: readonly RegExp[] = [/^(?:async\s+)?function\*?\s+([A-Za-z_$][\w$]*)/, /^(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)\s*=>|function)/];
+export const MAX_SYMBOLS = 12;
+
+/** The top-level names a file declares or exports, in order, at most `max`; a Markdown file's section headings. */
+export function symbolsOf(path: string, text: string, max = MAX_SYMBOLS): string[] {
+  const lines = text.split(/\r?\n/);
+  const found = new Set<string>();
+  const add = (name: string | undefined) => {
+    const clean = name?.trim();
+    if (clean && found.size < max && !clean.startsWith("_")) found.add(clean);
+  };
+  if (isMarkdown(path)) {
+    for (const line of lines) add(/^##\s+(.+?)\s*#*\s*$/.exec(line)?.[1]?.slice(0, 60));
+    return [...found];
+  }
+  for (const line of lines) {
+    if (found.size >= max) break;
+    const named = /^export\s*(?:type\s*)?\{([^}]*)\}/.exec(line);
+    if (named) for (const part of named[1]!.split(",")) add(part.split(/\s+as\s+/).pop()?.replace(/^type\s+/, ""));
+    else if (/^export\s+default\s+(?!(?:async\s+)?(?:function|class)\s+[A-Za-z_$])/.test(line)) add("default");
+    else for (const pattern of SYMBOL_PATTERNS) add(pattern.exec(line)?.[1]);
+  }
+  // A script that exports nothing still has its functions; a test's helpers are not worth naming.
+  if (found.size === 0 && /\.(c|m)?(j|t)sx?$/i.test(path) && !/(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.\w+$/i.test(path)) {
+    for (const line of lines) for (const pattern of LOCAL_PATTERNS) add(pattern.exec(line)?.[1]);
+  }
+  return [...found];
+}
+
 interface CacheEntry {
   mtimeMs: number;
   size: number;
   excerpt: string;
+  purpose?: string;
+  symbols?: string[];
 }
 
 interface CacheFile {
@@ -222,22 +294,17 @@ async function walkFiles(cwd: string): Promise<string[]> {
   return found.slice(0, MAX_FILES);
 }
 
-async function readHead(path: string): Promise<string | undefined> {
-  const handle = await open(path, "r");
-  try {
-    const buffer = Buffer.alloc(HEAD_BYTES);
-    const { bytesRead } = await handle.read(buffer, 0, HEAD_BYTES, 0);
-    const head = buffer.subarray(0, bytesRead);
-    return head.includes(0) ? undefined : head.toString("utf8");
-  } finally {
-    await handle.close();
-  }
+/** A text file's opening 8 KB (for its excerpt) and all of it (for its names); undefined for a binary file. */
+async function readText(path: string): Promise<{ head: string; text: string } | undefined> {
+  const buffer = await readFile(path);
+  const head = buffer.subarray(0, HEAD_BYTES);
+  return head.includes(0) ? undefined : { head: head.toString("utf8"), text: buffer.toString("utf8") };
 }
 
 /**
- * The repository's files with their excerpts. Unchanged files come from the
- * cache (same size and modification time); new or changed ones are read
- * (their first 8 KB) and the cache is rewritten.
+ * The repository's files with their excerpts, purposes and names. Unchanged
+ * files come from the cache (same size and modification time); new or
+ * changed ones are read and the cache is rewritten.
  */
 export async function indexFiles(scope: FileScope, exclude: readonly string[] = []): Promise<IndexedFile[]> {
   const listed = (await gitFiles(scope.cwd)) ?? (await walkFiles(scope.cwd));
@@ -255,11 +322,12 @@ export async function indexFiles(scope: FileScope, exclude: readonly string[] =
         const info = await stat(join(scope.cwd, path));
         if (!info.isFile() || info.size > MAX_FILE_BYTES) return undefined;
         const hit = cached[path];
-        if (hit && hit.mtimeMs === info.mtimeMs && hit.size === info.size) return [path, hit];
-        const head = await readHead(join(scope.cwd, path));
-        if (head === undefined) return undefined;
+        // An entry from before files had names is read again once.
+        if (hit && hit.mtimeMs === info.mtimeMs && hit.size === info.size && Array.isArray(hit.symbols)) return [path, hit];
+        const read = await readText(join(scope.cwd, path));
+        if (read === undefined) return undefined;
         changed = true;
-        return [path, { mtimeMs: info.mtimeMs, size: info.size, excerpt: excerptOf(path, head) }];
+        return [path, { mtimeMs: info.mtimeMs, size: info.size, excerpt: excerptOf(path, read.head), purpose: purposeOf(path, read.head), symbols: symbolsOf(path, read.text) }];
       } catch {
         return undefined;
       }
@@ -267,7 +335,7 @@ export async function indexFiles(scope: FileScope, exclude: readonly string[] =
     for (const entry of entries) {
       if (!entry) continue;
       next[entry[0]] = entry[1];
-      indexed.push({ path: entry[0], excerpt: entry[1].excerpt });
+      indexed.push({ path: entry[0], excerpt: entry[1].excerpt, purpose: entry[1].purpose ?? "", symbols: entry[1].symbols ?? [] });
     }
   }
   if (changed) writeCache(scope, next);

package/src/classifier/instance.ts

@@ -13,11 +13,13 @@ import { scriptPicker } from "./scripts.ts";
 import type { ScriptPicker } from "../scripts/pick.ts";
 import { registerJevProvider, type KeySource, type KeyStatus } from "./hosts.ts";
 import { fileHinter, type FileHinter, type FileScope } from "./files.ts";
+import { withRepoMap } from "../knowledge/repo-map.ts";
 import { knowledgePicker, type KnowledgePicker } from "./knowledge.ts";
 import { lobbyFeed } from "../lobby/feed.ts";
 import { triageLine, triageWithContext } from "./triage.ts";
 import type { TaskTriage } from "../schemas/task.ts";
 import { effortRouter, type EffortRouter } from "./effort.ts";
+import { engineAnswer, engineClassifiers, type EngineAnswer, type EngineModel, type Registry } from "./models.ts";
 
 interface Binding {
   cwd: string;
@@ -25,6 +27,8 @@ interface Binding {
   configDir: string;
   keys: KeySource;
   status: (piProvider: string) => KeyStatus | undefined;
+  engine: EngineAnswer;
+  registry: Registry;
   notify?: (message: string, level: "info" | "warning" | "error") => void;
 }
 
@@ -35,6 +39,10 @@ export function classifier(): Classifier {
   instance ??= new Classifier({
     config: () => loadConfig().classifier,
     keys: async (piProvider) => binding?.keys(piProvider),
+    engine: (ref, request, options) => {
+      if (!binding) throw new Error(`${ref} is not reachable before a pi session starts`);
+      return binding.engine(ref, request, options);
+    },
     metrics: (record) => {
       if (binding) appendMetrics(binding.root, binding.configDir, [record]);
     },
@@ -43,9 +51,13 @@ export function classifier(): Classifier {
   return instance;
 }
 
-/** Likely files for agents working in a tree, with what was found logged to the lobby's activity feed. */
+/**
+ * Likely files for agents working in a tree, with what was found logged to the
+ * lobby's activity feed, and the repository map while `workflow.repoMap` is on.
+ */
 export function hintsFor(scope: FileScope): FileHinter {
-  return fileHinter(classifier(), scope, (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
+  const hinter = fileHinter(classifier(), scope, (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
+  return withRepoMap(hinter, scope, () => ({ on: loadConfig().workflow.repoMap, exclude: classifier().config.exclude }));
 }
 
 /** Relevant knowledge and shared scripts for agents, with what Jev kept and matched logged to the lobby's activity feed. */
@@ -84,6 +96,24 @@ export function keyStatus(piProvider: string): KeyStatus | undefined {
   return binding?.status(piProvider);
 }
 
+let classifierModels: EngineModel[] = [];
+
+/** Refresh the list of classifier models pi can call with its logins (it is read from the network). */
+async function refreshClassifierModels(): Promise<void> {
+  if (!binding) return;
+  try {
+    classifierModels = await engineClassifiers(binding.registry);
+  } catch {
+    // Keep the last list: the picker still offers chat models and custom ids.
+  }
+}
+
+/** The classifier models pi can call with the logins it holds (Jev on each host, clef, d1, …); refreshed as it is read. */
+export function availableClassifiers(): EngineModel[] {
+  void refreshClassifierModels();
+  return classifierModels;
+}
+
 /** Register the `typesafe` login entry and bind the classifier to each session's key store. */
 export function registerClassifier(pi: ExtensionAPI, configDir: string): void {
   registerJevProvider(pi);
@@ -93,6 +123,8 @@ export function registerClassifier(pi: ExtensionAPI, configDir: string): void {
       root: detectProjectRoot(ctx.cwd, configDir),
       configDir,
       keys: (piProvider) => ctx.modelRegistry.getApiKeyForProvider(piProvider),
+      registry: ctx.modelRegistry,
+      engine: engineAnswer(ctx.modelRegistry),
       status: (piProvider) => {
         try {
           return ctx.modelRegistry.getProviderAuthStatus(piProvider);
@@ -103,5 +135,6 @@ export function registerClassifier(pi: ExtensionAPI, configDir: string): void {
       // Subagents have nobody to tell; their runs still land in the metrics.
       ...(ctx.hasUI && !isSubagentProcess() ? { notify: (message: string, level: "info" | "warning" | "error") => ctx.ui.notify(message, level) } : {}),
     };
+    if (!isSubagentProcess()) void refreshClassifierModels();
   });
 }

package/src/classifier/models.ts

@@ -0,0 +1,115 @@
+/**
+ * The classifier's model when it is not Jev on a host: whatever
+ * `classifier.engine` names (`provider/id`), looked up in pi's own model
+ * registry, so it is called with the logins pi already holds (an OpenAI or
+ * Anthropic account, an API key, OpenRouter, …). A classifier model (Jev,
+ * Cloudflare's clef, Liquid's d1, Upstage's solar-decide, …) answers through
+ * pi's `classify`; a chat model answers the same questions as JSON (see
+ * `chat.ts`).
+ */
+import { clampThinkingLevel, type Api, type ClassifierApi, type ClassifierContext, type ClassifierModel, type Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Answer, SystemOneRequest, SystemOneResponse } from "./client.ts";
+import { chatClassify } from "./chat.ts";
+
+export type Registry = Pick<ExtensionContext["modelRegistry"], "find" | "findOfType" | "classify" | "streamSimple" | "getAvailableOfType">;
+
+/** One model the classifier can use, as the settings picker lists it. */
+export interface EngineModel {
+  id: string;
+  label: string;
+  kind: "classifier" | "chat";
+}
+
+export interface AnswerOptions {
+  signal?: AbortSignal;
+  timeoutMs: number;
+  /** A chat model gets at least this long: it writes its answers, a classifier model only scores them. */
+  chatTimeoutMs: number;
+}
+
+/** Answers a request with the model `ref` names; throws when pi has no such model or the call fails. */
+export type EngineAnswer = (ref: string, request: SystemOneRequest, options: AnswerOptions) => Promise<SystemOneResponse>;
+
+/** `provider/id` split at the first slash (ids may hold more: `openrouter/liquid/d1`). */
+export function splitRef(ref: string): { provider: string; id: string } | undefined {
+  const slash = ref.indexOf("/");
+  if (slash <= 0 || slash === ref.length - 1) return undefined;
+  return { provider: ref.slice(0, slash), id: ref.slice(slash + 1) };
+}
+
+/** pi's `bool` answers are Jev's `noul`; the rest carry over as they are. */
+function fromPi(answers: Record<string, unknown>): Record<string, Answer> {
+  const out: Record<string, Answer> = {};
+  for (const [key, answer] of Object.entries(answers)) {
+    const value = answer as { type?: string; probability?: number };
+    out[key] = value.type === "bool" ? { type: "noul", noul: value.probability ?? 0 } : (answer as Answer);
+  }
+  return out;
+}
+
+/** Jev's request as pi's classifier context: `noul` questions are `bool` there, everything else is sent as it is. */
+function toPi(request: SystemOneRequest): ClassifierContext {
+  return {
+    state: request.state,
+    questions: Object.fromEntries(Object.entries(request.questions).map(([key, question]) => [key, question.type === "noul" ? { ...question, type: "bool" } : question])),
+  } as unknown as ClassifierContext;
+}
+
+async function classifyWith(registry: Registry, model: ClassifierModel<ClassifierApi>, request: SystemOneRequest, options: AnswerOptions): Promise<SystemOneResponse> {
+  const result = await registry.classify(model, toPi(request), { timeoutMs: options.timeoutMs, ...(options.signal ? { signal: options.signal } : {}) });
+  if (result.stopReason !== "stop") throw new Error(result.errorMessage || (result.stopReason === "aborted" ? "cancelled" : "the classifier failed"));
+  return {
+    model: `${model.provider}/${result.model || model.id}`,
+    answers: fromPi(result.answers as Record<string, unknown>),
+    ...(result.usage ? { usage: { input_tokens: result.usage.input, output_tokens: result.usage.output } } : {}),
+  };
+}
+
+/** The least thinking a model allows: none when it can switch it off. */
+function leastThinking(model: Model<Api>): "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined {
+  if (!model.reasoning) return undefined;
+  const level = clampThinkingLevel(model, "off");
+  return level === "off" ? undefined : level;
+}
+
+async function chatWith(registry: Registry, model: Model<Api>, request: SystemOneRequest, options: AnswerOptions): Promise<SystemOneResponse> {
+  const reasoning = leastThinking(model);
+  const timeoutMs = Math.max(options.timeoutMs, options.chatTimeoutMs);
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => controller.abort(new Error(`timed out after ${timeoutMs} ms`)), timeoutMs);
+  try {
+    return await chatClassify(request, async ({ system, user, maxTokens }) => {
+      const stream = registry.streamSimple(model, { systemPrompt: system, messages: [{ role: "user", content: user, timestamp: Date.now() }] }, { maxTokens, signal: controller.signal, ...(reasoning ? { reasoning } : {}) });
+      const aborted = new Promise<never>((_, reject) => controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true }));
+      const reply = await Promise.race([stream.result(), aborted]);
+      if (reply.stopReason === "error" || reply.stopReason === "aborted") throw new Error(reply.errorMessage || `the model stopped (${reply.stopReason})`);
+      const text = reply.content.filter((part) => part.type === "text").map((part) => part.text).join("");
+      return { text, model: `${model.provider}/${model.id}`, usage: { input_tokens: reply.usage.input, output_tokens: reply.usage.output } };
+    }, Boolean(reasoning));
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+/** Answers with pi's registry: a classifier model natively, else a chat model through a JSON prompt. */
+export function engineAnswer(registry: Registry): EngineAnswer {
+  return async (ref, request, options) => {
+    const parts = splitRef(ref);
+    if (!parts) throw new Error(`"${ref}" is not a provider/model reference`);
+    const classifierModel = registry.findOfType("classifier", parts.provider, parts.id);
+    if (classifierModel) return classifyWith(registry, classifierModel, request, options);
+    const chatModel = registry.find(parts.provider, parts.id);
+    if (chatModel) return chatWith(registry, chatModel, request, options);
+    throw new Error(`pi has no model ${ref}: pick one you are signed in to in Settings → Classifier`);
+  };
+}
+
+/** The classifier models pi can call with the logins it holds, as the settings picker lists them. */
+export async function engineClassifiers(registry: Registry): Promise<EngineModel[]> {
+  const models = await registry.getAvailableOfType("classifier");
+  return models.map((model) => ({ id: `${model.provider}/${model.id}`, label: model.name && model.name !== model.id ? model.name : `${model.provider}/${model.id}`, kind: "classifier" as const }));
+}

package/src/execution/git.ts

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
-import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
 import { promisify } from "node:util";
 import { truncate } from "../text.ts";
 
@@ -31,6 +32,48 @@ export async function headCommit(cwd: string): Promise<string | undefined> {
   }
 }
 
+/** A path with its links resolved (git reports real paths), or as it is when it does not exist. */
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/** Changed files stat'ed at most for a tree's state; past this the status text alone stands for them. */
+const MAX_STATED = 2000;
+
+/**
+ * A fingerprint of the work tree: HEAD, and each changed or untracked file's
+ * status, size and modification time, leaving out paths under `ignore`
+ * (bot-lobby's own data). Two equal fingerprints mean nothing in the tree
+ * changed in between; undefined outside git.
+ */
+export async function treeState(cwd: string, ignore: readonly string[] = []): Promise<string | undefined> {
+  try {
+    const top = await git(cwd, ["rev-parse", "--show-toplevel"]);
+    const head = (await headCommit(top)) ?? "";
+    const { stdout } = await run("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: top, maxBuffer: MAX_BUFFER });
+    const skipped = ignore.map((dir) => relative(top, realPath(dir))).filter((dir) => dir && !dir.startsWith("..")).map((dir) => `${dir.split("\\").join("/")}/`);
+    const entries = stdout.split("\0").filter((entry) => entry.length > 3 && !skipped.some((dir) => entry.slice(3).startsWith(dir)));
+    const hash = createHash("sha1").update(head);
+    entries.forEach((entry, index) => {
+      hash.update(`\0${entry}`);
+      if (index >= MAX_STATED) return;
+      try {
+        const info = statSync(join(top, entry.slice(3)));
+        hash.update(`\0${info.size}:${info.mtimeMs}`);
+      } catch {
+        hash.update("\0gone");
+      }
+    });
+    return hash.digest("hex");
+  } catch {
+    return undefined;
+  }
+}
+
 /** The repository's top folder, or undefined (no git, not a repository). */
 export async function repositoryTop(cwd: string): Promise<string | undefined> {
   try {
@@ -214,3 +257,66 @@ export async function addedLines(top: string, base: string | undefined, files: r
     return undefined;
   }
 }
+
+/** Longest first line a commit message may have. */
+export const MAX_COMMIT_SUBJECT = 72;
+/** Most lines a commit message may add below its first. */
+export const MAX_COMMIT_BODY_LINES = 3;
+
+/**
+ * A commit message kept short: one first line of at most
+ * `MAX_COMMIT_SUBJECT` characters, then, after a blank line, at most
+ * `MAX_COMMIT_BODY_LINES` short lines. Throws saying what is too long.
+ */
+export function commitMessage(text: string): string {
+  const lines = text.replace(/\r\n?/g, "\n").trim().split("\n").map((line) => line.trimEnd());
+  const subject = lines[0]?.trim() ?? "";
+  if (!subject) throw new Error("the commit message is empty");
+  if (subject.length > MAX_COMMIT_SUBJECT) throw new Error(`the commit message's first line is ${subject.length} characters; keep it to ${MAX_COMMIT_SUBJECT} or fewer, saying what changed`);
+  const body = lines.slice(1).filter((line) => line.trim().length > 0);
+  if (body.length > MAX_COMMIT_BODY_LINES) throw new Error(`the commit message has ${body.length} lines below its first; keep it to ${MAX_COMMIT_BODY_LINES} or fewer`);
+  if (body.some((line) => line.trim().length > MAX_COMMIT_SUBJECT)) throw new Error(`keep each line of the commit message to ${MAX_COMMIT_SUBJECT} characters or fewer`);
+  return body.length > 0 ? `${subject}\n\n${body.map((line) => line.trim()).join("\n")}` : subject;
+}
+
+/** `git status` of `files` (relative to `top`): each changed path with its two-letter code, a rename's old path beside its new one. */
+async function statusOf(top: string, files: readonly string[]): Promise<Array<{ path: string; code: string }>> {
+  if (files.length === 0) return [];
+  const { stdout } = await run("git", ["status", "--porcelain", "-z", "--untracked-files=all", "--", ...files], { cwd: top, maxBuffer: MAX_BUFFER });
+  const entries = stdout.split("\0");
+  const out: Array<{ path: string; code: string }> = [];
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index]!;
+    if (entry.length < 4) continue;
+    const code = entry.slice(0, 2);
+    out.push({ path: entry.slice(3), code });
+    if (/[RC]/.test(code) && entries[index + 1]) out.push({ path: entries[++index]!, code: "D " });
+  }
+  return out;
+}
+
+/** Which of `files` (relative to `top`) have changes git has not committed, with a rename's old path beside its new one. */
+export async function uncommitted(top: string, files: readonly string[]): Promise<string[]> {
+  return [...new Set((await statusOf(top, files)).map((entry) => entry.path))];
+}
+
+/**
+ * Commit `files` (relative to `top`) as they stand, and nothing else: what
+ * else is staged stays staged. The commit, or undefined when none of them
+ * has anything to commit. Throws with git's reason when it refuses (a hook).
+ */
+export async function commitFiles(top: string, files: readonly string[], message: string): Promise<{ commit: string; files: string[] } | undefined> {
+  const status = await statusOf(top, files);
+  const dirty = [...new Set(status.map((entry) => entry.path))];
+  if (dirty.length === 0) return undefined;
+  // Only what the working tree holds beyond the index needs adding; a staged deletion is no longer there to add.
+  const unstaged = [...new Set(status.filter((entry) => entry.code[1] !== " ").map((entry) => entry.path))];
+  try {
+    if (unstaged.length > 0) await run("git", ["add", "-A", "--", ...unstaged], { cwd: top, maxBuffer: MAX_BUFFER });
+    await run("git", ["commit", "-q", "-m", message, "--", ...dirty], { cwd: top, maxBuffer: MAX_BUFFER });
+  } catch (error) {
+    const failure = error as { stderr?: string; stdout?: string; message: string };
+    throw new Error(truncate((failure.stderr || failure.stdout || failure.message).trim(), 600));
+  }
+  return { commit: await git(top, ["rev-parse", "HEAD"]), files: dirty };
+}

package/src/index.ts

@@ -20,6 +20,7 @@ import { registerFreshContext } from "./pi/fresh-context.ts";
 import { registerAskTool } from "./ask/tool.ts";
 import { registerWebTools } from "./web/tools.ts";
 import { registerExcalidrawTools } from "./excalidraw/tools.ts";
+import { registerToolBudget } from "./pi/tool-budget.ts";
 
 export default function (pi: ExtensionAPI): void {
   registerAgentPermissions(pi);
@@ -54,4 +55,6 @@ export default function (pi: ExtensionAPI): void {
   if (isSubagentProcess()) registerDeskClient(pi);
   // Subagents look files up with the classifier (the engine allows the tool only while file hints are on).
   if (isSubagentProcess()) registerClassifierTools(pi);
+  // A subagent given a tool budget (scouts) is warned, then refused, so it reports instead of searching on.
+  if (isSubagentProcess()) registerToolBudget(pi);
 }

package/src/knowledge/file-notes.ts

@@ -0,0 +1,104 @@
+/**
+ * What scouts learned about files, kept across tasks. Each scout's Relevant
+ * Files (`path:lines — why it matters`) are recorded with a hash of the
+ * file's content, and the repository map shows a note again only while the
+ * file is unchanged, so a later agent starts from what an earlier one found
+ * instead of searching for it again. A changed file's note is never shown:
+ * it may no longer be true.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import type { Domain } from "../schemas/agent.ts";
+import type { RelevantFile } from "../schemas/findings.ts";
+
+export interface FileNote {
+  note: string;
+  /** The lines it is about (`12-40`), when the scout gave them. */
+  lines?: string;
+  /** sha1 of the file's content when the note was taken. */
+  hash: string;
+  domain: Domain;
+  at: string;
+}
+
+interface NotesFile {
+  version: 1;
+  files: Record<string, FileNote>;
+}
+
+/** Most notes kept; the oldest go first. */
+export const MAX_NOTES = 2000;
+const MAX_NOTE_CHARS = 240;
+/** Files larger than this are not hashed (the index skips them too). */
+const MAX_HASHED_BYTES = 256 * 1024;
+
+export function fileNotesPath(dataDir: string): string {
+  return join(dataDir, "cache", "file-notes.json");
+}
+
+export function readFileNotes(dataDir: string): Record<string, FileNote> {
+  try {
+    const parsed = JSON.parse(readFileSync(fileNotesPath(dataDir), "utf8")) as Partial<NotesFile>;
+    return parsed.version === 1 && parsed.files && typeof parsed.files === "object" ? parsed.files : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeFileNotes(dataDir: string, files: Record<string, FileNote>): void {
+  const path = fileNotesPath(dataDir);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(`${path}.tmp`, JSON.stringify({ version: 1, files } satisfies NotesFile));
+    renameSync(`${path}.tmp`, path);
+  } catch {
+    // Notes are an optimisation; without them agents search as before.
+  }
+}
+
+/** A file's content hash, or undefined when it is missing, not a file or too large. */
+export async function contentHash(cwd: string, path: string): Promise<string | undefined> {
+  try {
+    const full = join(cwd, path);
+    const info = await stat(full);
+    if (!info.isFile() || info.size > MAX_HASHED_BYTES) return undefined;
+    return createHash("sha1").update(await readFile(full)).digest("hex");
+  } catch {
+    return undefined;
+  }
+}
+
+/** A reported path relative to the tree (`./a.ts`, `/abs/tree/a.ts` → `a.ts`); undefined outside it. */
+export function treePath(cwd: string, path: string): string | undefined {
+  const plain = path.trim().replace(/^\.\//, "");
+  if (!plain) return undefined;
+  const rel = isAbsolute(plain) ? relative(cwd, plain) : plain;
+  return !rel || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split("\\").join("/");
+}
+
+/** Record a scout's Relevant Files as notes, each with its file's current hash; files that are not there are skipped. */
+export async function recordFileNotes(dataDir: string, cwd: string, domain: Domain, files: readonly RelevantFile[], now = new Date()): Promise<number> {
+  const entries = await Promise.all(files.filter((file) => file.reason.trim()).map(async (file): Promise<[string, FileNote] | undefined> => {
+    const path = treePath(cwd, file.path);
+    const hash = path ? await contentHash(cwd, path) : undefined;
+    if (!path || !hash) return undefined;
+    const note = file.reason.trim().replace(/\s+/g, " ").slice(0, MAX_NOTE_CHARS);
+    return [path, { note, ...(file.lines ? { lines: file.lines } : {}), hash, domain, at: now.toISOString() }];
+  }));
+  const fresh = entries.filter((entry): entry is [string, FileNote] => entry !== undefined);
+  if (fresh.length === 0) return 0;
+  const notes = { ...readFileNotes(dataDir), ...Object.fromEntries(fresh) };
+  const kept = Object.entries(notes).sort((a, b) => b[1].at.localeCompare(a[1].at)).slice(0, MAX_NOTES);
+  writeFileNotes(dataDir, Object.fromEntries(kept));
+  return fresh.length;
+}
+
+/** The notes for `paths` whose file is unchanged since the note was taken. */
+export async function currentNotes(dataDir: string, cwd: string, paths: readonly string[]): Promise<Map<string, FileNote>> {
+  const notes = readFileNotes(dataDir);
+  const wanted = paths.filter((path) => notes[path]);
+  const hashes = await Promise.all(wanted.map((path) => contentHash(cwd, path)));
+  return new Map(wanted.filter((path, index) => hashes[index] === notes[path]!.hash).map((path) => [path, notes[path]!]));
+}