@a-t-h-i/bot-lobby 0.6.7 → 0.6.8

package/src/classifier/knowledge.ts

@@ -0,0 +1,158 @@
+/**
+ * Relevant knowledge. An agent's knowledge, standards and decisions are put in
+ * its prompt, not looked up, so a gate ("does this step need the knowledge
+ * base?") would have to guess before the agent knows what it needs, and a wrong
+ * "no" is silent. What Jev does safely instead is the ranking the keyword
+ * selector does badly: when a file is longer than the prompt has room for, Jev
+ * judges each of its sections against the step (one yes/no per section) and the
+ * ones that bear on it stay. A file that fits goes in whole and costs nothing.
+ *
+ * Whatever is left out is said so, with the file's path, so an agent that does
+ * need it reads the rest itself. Any failure, timeout or switch-off keeps the
+ * keyword selection, which is what agents got before.
+ */
+import { basename } from "node:path";
+import { score, selectRelevant, splitSections, tokenize, type KnowledgeInput, type KnowledgeSelection } from "../knowledge/selector.ts";
+import type { Classifier } from "./classifier.ts";
+import { noul, yesOf, type SystemOneRequest } from "./client.ts";
+import { clip } from "./limits.ts";
+
+/** How many characters of each knowledge file a prompt has room for. */
+export const KNOWLEDGE_BUDGET_CHARS = 4000;
+/** A section is judged on its first characters; the whole section is kept when it stays. */
+export const SECTION_EXCERPT_CHARS = 700;
+/** Sections judged per file; a longer file is narrowed by keywords first. */
+export const MAX_SECTIONS = 60;
+/** The step waits this long for Jev, then goes with keywords. */
+export const KNOWLEDGE_BUDGET_MS = 1500;
+
+/** The three files a prompt carries: `knowledge`, `standards` and `decisions`. */
+export type KnowledgeSlice = keyof KnowledgeSelection;
+export type KnowledgePaths = Partial<Record<KnowledgeSlice, string>>;
+
+export interface SectionCall {
+  request: SystemOneRequest;
+  /** The section each question key stands for, by index into the file's sections. */
+  keys: Map<string, number>;
+}
+
+/** One request that asks about each candidate section of a file. */
+export function sectionRequest(task: string, sections: readonly string[], candidates: readonly number[]): SectionCall {
+  const entries: Record<string, string> = {};
+  const questions: SystemOneRequest["questions"] = {};
+  const keys = new Map<string, number>();
+  candidates.forEach((index, position) => {
+    const key = `s${position + 1}`;
+    entries[key] = clip(sections[index]!, SECTION_EXCERPT_CHARS);
+    questions[key] = noul(`Does \`sections.${key}\` hold a fact, rule or decision that an agent doing \`task\` should have in front of it? Yes when it bears on the code, files, conventions or choices the task touches; no when it is about something else or only shares words with it.`);
+    keys.set(key, index);
+  });
+  return { request: { state: { task: clip(task, 3000), sections: entries }, questions }, keys };
+}
+
+/** The sections to judge: all of them, or the `MAX_SECTIONS` that share the most words with the task. */
+export function candidateSections(task: string, sections: readonly string[]): number[] {
+  const all = sections.map((_, index) => index);
+  if (sections.length <= MAX_SECTIONS) return all;
+  const tokens = tokenize(task);
+  const scored = all.map((index) => ({ index, hits: score(sections[index]!, tokens) }));
+  scored.sort((a, b) => b.hits - a.hits || b.index - a.index);
+  return scored.slice(0, MAX_SECTIONS).map((entry) => entry.index).sort((a, b) => a - b);
+}
+
+/** What was kept of a file: its text and how many of its sections that was. */
+export interface Kept {
+  text: string;
+  kept: number;
+  total: number;
+}
+
+/**
+ * The most relevant sections that fit `budget`, in the order of the file. A
+ * section too long to fit on its own is cut to fit when nothing else is kept.
+ */
+export function keepSections(sections: readonly string[], relevance: ReadonlyMap<number, number>, floor: number, budget: number): Kept {
+  const wanted = [...relevance].filter(([, value]) => value >= floor).sort((a, b) => b[1] - a[1] || a[0] - b[0]);
+  const chosen: number[] = [];
+  const texts = new Map<number, string>();
+  let used = 0;
+  for (const [index] of wanted) {
+    const text = sections[index]!;
+    if (used + text.length <= budget) {
+      chosen.push(index);
+      texts.set(index, text);
+      used += text.length + 2;
+    } else if (chosen.length === 0) {
+      chosen.push(index);
+      texts.set(index, clip(text, budget));
+      used = budget;
+    }
+  }
+  chosen.sort((a, b) => a - b);
+  return { text: chosen.map((index) => texts.get(index)!).join("\n\n").trim(), kept: chosen.length, total: sections.length };
+}
+
+/** The line that tells an agent what it was not given, and where all of it is. */
+export function leftOutNote(kept: Kept, name: string, path?: string): string {
+  const where = path ? ` The whole file is ${path}.` : "";
+  return kept.kept === 0
+    ? `_No section of ${name} bears on this step (${kept.total} sections).${where}_`
+    : `_Kept ${kept.kept} of ${kept.total} sections of ${name} for this step.${where}_`;
+}
+
+/** Picks what an agent's prompt carries of its knowledge files. */
+export interface KnowledgePicker {
+  select(task: string, files: KnowledgeInput, options?: { signal?: AbortSignal; paths?: KnowledgePaths }): Promise<KnowledgeSelection>;
+}
+
+const SLICES: readonly KnowledgeSlice[] = ["knowledge", "standards", "decisions"];
+
+/**
+ * Jev's picks for one file over the budget, or undefined when it cannot judge
+ * (off, failed, out of time, no key): the caller then uses keywords.
+ */
+async function rank(classifier: Classifier, task: string, content: string, budget: number, options: { signal?: AbortSignal }): Promise<{ kept: Kept; sections: string[]; ms: number } | undefined> {
+  const sections = splitSections(content.trim());
+  if (sections.length < 2) return undefined;
+  const call = sectionRequest(task, sections, candidateSections(task, sections));
+  const result = await classifier.ask("knowledge", call.request, { ...(options.signal ? { signal: options.signal } : {}), timeoutMs: Math.min(classifier.config.timeoutMs, KNOWLEDGE_BUDGET_MS) });
+  if (!result) return undefined;
+  const relevance = new Map<number, number>();
+  for (const [key, index] of call.keys) {
+    const value = yesOf(result.answers, key);
+    if (value !== undefined) relevance.set(index, value);
+  }
+  // An answer to none of the questions says nothing: keywords decide.
+  if (relevance.size === 0) return undefined;
+  return { kept: keepSections(sections, relevance, classifier.config.thresholds.knowledgeRelevantAt, budget), sections, ms: result.ms };
+}
+
+/**
+ * A picker on Jev. Files that fit the prompt are untouched; a longer one keeps
+ * the sections Jev judges to bear on the step, with a note of what was left
+ * out. Standards are the exception to an empty result: they are rules for all
+ * work, so when Jev sees none that applies the keyword selection stands.
+ */
+export function knowledgePicker(classifier: Classifier, log?: (text: string) => void, budget = KNOWLEDGE_BUDGET_CHARS): KnowledgePicker {
+  return {
+    async select(task, files, options = {}) {
+      const plain = (kind: KnowledgeSlice) => selectRelevant(task, files[kind] ?? "", budget);
+      const picked = await Promise.all(SLICES.map(async (kind): Promise<string> => {
+        const content = files[kind] ?? "";
+        if (content.trim().length <= budget || !task.trim() || !classifier.enabled("knowledge")) return plain(kind);
+        try {
+          const ranked = await rank(classifier, task, content, budget, options.signal ? { signal: options.signal } : {});
+          if (!ranked) return plain(kind);
+          const path = options.paths?.[kind];
+          const name = path ? basename(path) : kind;
+          if (ranked.kept.kept === 0 && kind === "standards") return plain(kind);
+          log?.(`knowledge: kept ${ranked.kept.kept} of ${ranked.kept.total} sections of ${name} · ${ranked.ms} ms`);
+          return [ranked.kept.text, leftOutNote(ranked.kept, name, path)].filter(Boolean).join("\n\n");
+        } catch {
+          return plain(kind);
+        }
+      }));
+      return { knowledge: picked[0]!, standards: picked[1]!, decisions: picked[2]! };
+    },
+  };
+}

package/src/classifier/review.ts

@@ -0,0 +1,146 @@
+/**
+ * Jev's quick read of a pull request, for the Git tab: how big the change is,
+ * how likely it is risky, to break callers, to touch security-sensitive code
+ * or to change behaviour without tests, and what kind of change it is — in
+ * one call, in a moment, without writing a word. It is a triage, not a review:
+ * it says whether a full review by an agent is worth its tokens.
+ */
+import type { Classifier } from "./classifier.ts";
+import { choice, choiceOf, noul, score, scoreOf, yesOf, type SystemOneRequest } from "./client.ts";
+import { clip } from "./limits.ts";
+import { TRIAGE_SIZES } from "./triage.ts";
+import type { TriageSize } from "../schemas/task.ts";
+
+const SIZE_LEVELS = [
+  "trivial: a one-line or mechanical change (a rename, a typo, a version bump)",
+  "small: a few files in one area, following an existing pattern",
+  "medium: several files or two areas, with some design decisions",
+  "large: a cross-cutting change, a new subsystem, a migration or an architecture change",
+];
+
+const KINDS: Record<string, string> = {
+  feature: "New capability or behaviour",
+  bugfix: "Existing behaviour was wrong and is fixed",
+  refactor: "Restructures code without changing behaviour",
+  tests: "Adds or fixes tests only",
+  docs: "Documentation only",
+  dependency: "Upgrades or changes dependencies",
+  chore: "Configuration, build, tooling or cleanup",
+};
+
+/** The pull request as Jev reads it. */
+export interface PullInput {
+  title: string;
+  body: string;
+  /** Changed files with their line counts, e.g. `src/a.ts (+12 −3)`. */
+  files: readonly string[];
+  diff: string;
+}
+
+/** What Jev made of a pull request. */
+export interface PullRead {
+  size: TriageSize;
+  sizeConfidence: number;
+  /** Probabilities of yes, 0 to 1. */
+  risky: number;
+  breaking: number;
+  security: number;
+  testsMissing: number;
+  kind?: string;
+  kindProbability?: number;
+  model: string;
+  ms: number;
+}
+
+/** Characters of diff sent: the rest is what the agent's review is for. */
+export const READ_DIFF_CHARS = 80_000;
+
+export function pullRequest(input: PullInput): SystemOneRequest {
+  return {
+    state: {
+      title: clip(input.title, 300),
+      description: clip(input.body, 3000),
+      changed_files: clip(input.files.join("\n"), 4000),
+      diff: clip(input.diff, READ_DIFF_CHARS),
+    },
+    questions: {
+      size: score("How big is the change in `diff`, judged by what it would take to review and verify?", SIZE_LEVELS),
+      risky: noul(
+        "Could merging `diff` break existing behaviour or cause harm: data loss, corrupted state, wrong results, concurrency bugs, performance cliffs, or an outage?",
+        "Yes: there is a plausible way this breaks something that works today.",
+        "No: it is low-risk, well contained, or purely additive.",
+      ),
+      breaking: noul(
+        "Does `diff` change a public API, a config or file format, a database schema or a command-line interface in a way that breaks existing callers or users?",
+        "Yes: something outside this change has to adapt.",
+        "No: existing callers and data keep working as they are.",
+      ),
+      security: noul(
+        "Does `diff` touch authentication, authorisation, secrets, input validation, cryptography, or other security-sensitive code?",
+        "Yes: a mistake here could be a vulnerability.",
+        "No: nothing in it is security-relevant.",
+      ),
+      tests_missing: noul(
+        "Does `diff` change behaviour without adding or updating tests that cover the change?",
+        "Yes: the behaviour changes and no test in the diff covers it.",
+        "No: it adds or updates tests for what it changes, or it changes no behaviour.",
+      ),
+      kind: choice("What kind of change is `diff`?", KINDS),
+    },
+  };
+}
+
+/** Jev's read of a pull request, or undefined when the classifier is off or fails. */
+export async function readPull(classifier: Classifier, input: PullInput, signal?: AbortSignal): Promise<PullRead | undefined> {
+  if (!classifier.enabled("review")) return undefined;
+  const result = await classifier.ask("review", pullRequest(input), signal ? { signal } : {});
+  if (!result) return undefined;
+  const size = scoreOf(result.answers, "size");
+  if (!size) return undefined;
+  const kind = choiceOf(result.answers, "kind");
+  return {
+    size: TRIAGE_SIZES[Math.max(0, Math.min(TRIAGE_SIZES.length - 1, size.level))]!,
+    sizeConfidence: size.confidence,
+    risky: yesOf(result.answers, "risky") ?? 0,
+    breaking: yesOf(result.answers, "breaking") ?? 0,
+    security: yesOf(result.answers, "security") ?? 0,
+    testsMissing: yesOf(result.answers, "tests_missing") ?? 0,
+    ...(kind ? { kind: kind.choice, kindProbability: kind.probability } : {}),
+    model: result.model,
+    ms: result.ms,
+  };
+}
+
+const CONCERN = 0.5;
+
+/** The concerns worth a look, most likely first, as words. */
+export function concerns(read: PullRead): string[] {
+  const found: Array<[number, string]> = [
+    [read.risky, "risky"],
+    [read.security, "touches security"],
+    [read.breaking, "may break callers"],
+    [read.testsMissing, "no tests for the change"],
+  ];
+  return found.filter(([probability]) => probability >= CONCERN).sort((a, b) => b[0] - a[0]).map(([, words]) => words);
+}
+
+/** Whether a full review by an agent is worth its tokens: a concern, or a change too big to skim. */
+export function worthReview(read: PullRead): boolean {
+  return concerns(read).length > 0 || read.size === "large";
+}
+
+/** One line: `medium · bugfix · risky 0.71, no tests for the change 0.64 → worth a full review`. */
+export function readLine(read: PullRead): string {
+  const kind = read.kind ? ` · ${read.kind}` : "";
+  const flagged = concerns(read);
+  const figures = [
+    ["risky", read.risky],
+    ["security", read.security],
+    ["breaking", read.breaking],
+    ["tests missing", read.testsMissing],
+  ] as const;
+  const detail = flagged.length > 0
+    ? figures.filter(([, probability]) => probability >= CONCERN).sort((a, b) => b[1] - a[1]).map(([name, probability]) => `${name} ${probability.toFixed(2)}`).join(", ")
+    : "nothing stands out";
+  return `${read.size}${kind} · ${detail} → ${worthReview(read) ? "worth a full review" : "looks routine"}`;
+}

package/src/execution/workspace.ts

@@ -0,0 +1,185 @@
+/**
+ * Where a task's work lives in git. A task can get a branch of its own
+ * (`branch`: created and checked out in the working folder) or a worktree of
+ * its own (`worktree`: a second checkout on that branch, which every agent of
+ * the task runs in, so tasks never trample each other's files). Both are named
+ * after the task. Every failure comes back as one readable line and the task
+ * simply runs without isolation: git being unusable must never stop a task.
+ */
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import type { TaskGit } from "../schemas/task.ts";
+import { dataRoot } from "../state/project.ts";
+
+const run = promisify(execFile);
+const TIMEOUT_MS = 30_000;
+
+/** Runs git in a folder; resolves with trimmed stdout, rejects with git's own message. */
+export type GitRunner = (cwd: string, args: readonly string[]) => Promise<string>;
+
+export const runGit: GitRunner = async (cwd, args) => {
+  try {
+    const { stdout } = await run("git", [...args], { cwd, timeout: TIMEOUT_MS, maxBuffer: 10 * 1024 * 1024, windowsHide: true });
+    return stdout.trim();
+  } catch (error) {
+    const failure = error as { stderr?: string; message: string; code?: unknown };
+    // A missing git binary reads as that, not as a spawn error.
+    if (failure.code === "ENOENT") throw new Error("git is not installed");
+    throw new Error(firstLine(failure.stderr) || firstLine(failure.message) || "git failed");
+  }
+};
+
+function firstLine(text: string | undefined): string {
+  return text?.split("\n").find((line) => line.trim())?.trim().replace(/^(fatal|error):\s*/i, "") ?? "";
+}
+
+/** Where a task's worktrees live: `<project>/<configDir>/bot-lobby/worktrees`. */
+export function worktreesRoot(root: string, configDir: string): string {
+  return join(dataRoot(root, configDir), "worktrees");
+}
+
+/** A branch name git accepts, made from a task's friendly name (which already is one, bar odd characters). */
+export function branchName(name: string): string {
+  const cleaned = name
+    .trim()
+    .replace(/[\s~^:?*[\\]+/g, "-")
+    .replace(/@\{/g, "-")
+    .replace(/\.{2,}/g, ".")
+    .replace(/\/{2,}/g, "/")
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .replace(/^[-./]+|[-./]+$/g, "")
+    .replace(/\.lock$/i, "");
+  return cleaned || "task";
+}
+
+/** The first of `name`, `name-2`, `name-3`… that no branch (local or remote) already uses. */
+async function freeBranch(git: GitRunner, top: string, name: string): Promise<string> {
+  const base = branchName(name);
+  for (let suffix = 1; suffix < 100; suffix += 1) {
+    const candidate = suffix === 1 ? base : `${base}-${suffix}`;
+    const taken = await git(top, ["for-each-ref", "--count=1", "--format=%(refname)", `refs/heads/${candidate}`, `refs/remotes/*/${candidate}`]).catch(() => "");
+    if (!taken) return candidate;
+  }
+  throw new Error(`every branch name like ${base} is taken`);
+}
+
+/** Keep the worktrees out of `git add -A` in the main checkout (a local exclude; nothing is committed). */
+async function excludeWorktrees(git: GitRunner, top: string, root: string, configDir: string): Promise<void> {
+  try {
+    const inside = relative(top, worktreesRoot(root, configDir));
+    if (!inside || inside.startsWith("..") || isAbsolute(inside)) return;
+    const file = resolve(top, await git(top, ["rev-parse", "--git-path", "info/exclude"]));
+    const line = `/${inside.split(sep).join("/")}/`;
+    const current = existsSync(file) ? readFileSync(file, "utf8") : "";
+    if (current.split("\n").some((entry) => entry.trim() === line)) return;
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, `${current && !current.endsWith("\n") ? "\n" : ""}# bot-lobby: one worktree per task\n${line}\n`);
+  } catch {
+    // Only a convenience: a read-only .git leaves the worktrees showing as untracked.
+  }
+}
+
+export interface WorkspaceRequest {
+  /** The folder the task starts from (the session's working folder). */
+  cwd: string;
+  root: string;
+  configDir: string;
+  /** The task's friendly name: the branch takes it. */
+  name: string;
+  mode: "branch" | "worktree";
+  git?: GitRunner;
+}
+
+/**
+ * Give a task its branch (or worktree and branch). Returns what was made, or
+ * one line saying why not (not a repository, no commits for a worktree, a
+ * failed checkout); the task then runs without.
+ */
+export async function createWorkspace(request: WorkspaceRequest): Promise<TaskGit | string> {
+  const git = request.git ?? runGit;
+  let top: string;
+  try {
+    top = await git(request.cwd, ["rev-parse", "--show-toplevel"]);
+  } catch {
+    return "this folder is not a git repository";
+  }
+  const [current, head] = await Promise.all([
+    git(top, ["branch", "--show-current"]).catch(() => ""),
+    git(top, ["rev-parse", "--verify", "HEAD"]).catch(() => ""),
+  ]);
+  let branch: string;
+  try {
+    branch = await freeBranch(git, top, request.name);
+    await git(top, ["check-ref-format", "--branch", branch]);
+  } catch (error) {
+    return `no valid branch name for ${request.name} — ${(error as Error).message}`;
+  }
+  const from = current || (head ? `detached at ${head.slice(0, 7)}` : undefined);
+  const base = { branch, ...(from ? { from } : {}), ...(head ? { base: head } : {}) };
+  if (request.mode === "branch") {
+    try {
+      await git(top, ["checkout", "-b", branch]);
+    } catch (error) {
+      return `could not create branch ${branch} — ${(error as Error).message}`;
+    }
+    return { mode: "branch", ...base };
+  }
+  if (!head) return "a worktree needs at least one commit to start from; commit first, or use a branch";
+  const path = join(worktreesRoot(request.root, request.configDir), branch);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    await git(top, ["worktree", "add", "-b", branch, path, head]);
+  } catch (error) {
+    return `could not create a worktree for ${branch} — ${(error as Error).message}`;
+  }
+  await excludeWorktrees(git, top, request.root, request.configDir);
+  return { mode: "worktree", ...base, path };
+}
+
+/** The folder a task's agents run in: its worktree when it has one, otherwise where the session works. */
+export function taskCwd(task: { git?: TaskGit }, cwd: string): string {
+  return task.git?.mode === "worktree" && task.git.path ? task.git.path : cwd;
+}
+
+/** Why a task's worktree cannot be used (it was removed), or undefined when it is there or the task has none. */
+export function missingWorktree(task: { git?: TaskGit }): string | undefined {
+  const git = task.git;
+  if (git?.mode !== "worktree" || !git.path || existsSync(git.path)) return undefined;
+  return `the worktree ${git.path} of branch ${git.branch} is gone. Restore it with: git worktree add ${JSON.stringify(git.path)} ${git.branch}`;
+}
+
+/** The line that tells the oracle where the task's work lives; empty for a task without isolation. */
+export function gitLine(git: TaskGit | undefined): string {
+  if (!git) return "";
+  const from = git.from ? ` (from ${git.from})` : "";
+  if (git.mode === "branch") return `Git: this task works on its own branch ${git.branch}${from}, checked out in the working folder. Commit there; never switch branches.`;
+  return [
+    `Git: this task works in its own worktree ${git.path} on branch ${git.branch}${from}. Every agent runs there.`,
+    `Your own tools run in the main checkout, so look at the task's files under ${git.path} (git -C ${JSON.stringify(git.path)} diff --stat), and never edit outside it.`,
+    "Uncommitted changes in the main checkout are not in the worktree.",
+  ].join(" ");
+}
+
+/** What the lobby's title shows: the repository (or folder) and the branch checked out in it. */
+export interface WorkspaceInfo {
+  name: string;
+  branch?: string;
+}
+
+/** Repository (or folder) name and branch of a working folder; a folder outside git has only its name. */
+export async function describeWorkspace(cwd: string, git: GitRunner = runGit): Promise<WorkspaceInfo> {
+  let top: string;
+  try {
+    top = await git(cwd, ["rev-parse", "--show-toplevel"]);
+  } catch {
+    return { name: basename(cwd) || cwd };
+  }
+  const name = basename(top) || top;
+  const branch = await git(top, ["branch", "--show-current"]).catch(() => "");
+  if (branch) return { name, branch };
+  // Detached (or an unborn branch): the commit, when there is one.
+  const head = await git(top, ["rev-parse", "--short", "HEAD"]).catch(() => "");
+  return head ? { name, branch: `detached ${head}` } : { name };
+}

package/src/knowledge/edit.ts

@@ -0,0 +1,109 @@
+/**
+ * Knowledge files as entries the user can pick, edit, add and delete from the
+ * Knowledge tab. An entry is what reads as one item: a heading, a bullet with
+ * its wrapped and nested lines, or a paragraph. Everything here is pure text
+ * in, text out; the tab finds an entry again by its exact text (and which of
+ * several identical ones it is), so an edit made after the file changed on
+ * disk is refused rather than landing on the wrong line.
+ */
+
+export type EntryKind = "heading" | "bullet" | "text";
+
+export interface KnowledgeEntry {
+  /** The entry's lines exactly as the file has them. */
+  text: string;
+  /** First line, and the line after the last (indexes into the file's lines). */
+  start: number;
+  end: number;
+  kind: EntryKind;
+  /** Which of the entries with this same text it is (0 for the first). */
+  occurrence: number;
+}
+
+const HEADING = /^#{1,6}\s/;
+const BULLET = /^(?:[-*+]|\d+[.)])\s+\S/;
+
+/** The entries of a knowledge file, in order; blank lines separate them and belong to none. */
+export function parseEntries(content: string): KnowledgeEntry[] {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  const found: Array<{ start: number; end: number; kind: EntryKind }> = [];
+  let current: { start: number; end: number; kind: EntryKind } | undefined;
+  const close = () => {
+    if (current) found.push(current);
+    current = undefined;
+  };
+  lines.forEach((line, index) => {
+    if (!line.trim()) return close();
+    if (HEADING.test(line)) {
+      close();
+      found.push({ start: index, end: index + 1, kind: "heading" });
+      return;
+    }
+    if (BULLET.test(line)) {
+      close();
+      current = { start: index, end: index + 1, kind: "bullet" };
+      return;
+    }
+    // A wrapped or indented line joins the item above it; anything else starts a paragraph.
+    if (current) current.end = index + 1;
+    else current = { start: index, end: index + 1, kind: "text" };
+  });
+  close();
+  const seen = new Map<string, number>();
+  return found.map(({ start, end, kind }) => {
+    const text = lines.slice(start, end).join("\n");
+    const occurrence = seen.get(text) ?? 0;
+    seen.set(text, occurrence + 1);
+    return { text, start, end, kind, occurrence };
+  });
+}
+
+/** The entry with this exact text (the `occurrence`-th one), or undefined when the file no longer has it. */
+export function findEntry(content: string, text: string, occurrence = 0): KnowledgeEntry | undefined {
+  return parseEntries(content).find((entry) => entry.text === text && entry.occurrence === occurrence);
+}
+
+function linesOf(content: string): string[] {
+  const text = content.replace(/\r\n/g, "\n").replace(/\n+$/, "");
+  return text ? text.split("\n") : [];
+}
+
+/** `text` as a bullet: its first line after `- `, the rest indented under it; text that already is a bullet or heading stays as written. */
+export function bulletOf(text: string): string {
+  const trimmed = text.replace(/^\s*\n+|\s+$/g, "");
+  if (!trimmed.trim()) return "";
+  if (BULLET.test(trimmed) || HEADING.test(trimmed)) return trimmed;
+  const [first = "", ...rest] = trimmed.split("\n");
+  return [`- ${first}`, ...rest.map((line) => (line.trim() ? `  ${line.trimStart()}` : ""))].join("\n");
+}
+
+/** The file with `entry` replaced by `text`, exactly as written (a blank text removes it). */
+export function replaceEntry(content: string, entry: KnowledgeEntry, text: string): string {
+  const body = text.replace(/\s+$/, "");
+  if (!body.trim()) return removeEntry(content, entry);
+  const lines = linesOf(content);
+  lines.splice(entry.start, entry.end - entry.start, ...body.split("\n"));
+  return `${lines.join("\n")}\n`;
+}
+
+/** The file without `entry`; the blank line it leaves doubled up is dropped with it. */
+export function removeEntry(content: string, entry: KnowledgeEntry): string {
+  const lines = linesOf(content);
+  lines.splice(entry.start, entry.end - entry.start);
+  const before = lines[entry.start - 1];
+  const after = lines[entry.start];
+  if (entry.start < lines.length && after !== undefined && !after.trim() && (before === undefined || !before.trim())) lines.splice(entry.start, 1);
+  else if (entry.start >= lines.length && lines.length > 0 && !lines[lines.length - 1]!.trim()) lines.pop();
+  return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+
+/** The file with a new bullet after `entry` (at the end without one); after a paragraph it gets a blank line first. */
+export function insertAfter(content: string, entry: KnowledgeEntry | undefined, text: string): string {
+  const added = bulletOf(text);
+  if (!added.trim()) return content;
+  const lines = linesOf(content);
+  const at = entry ? entry.end : lines.length;
+  const addition = entry?.kind === "text" || (!entry && lines.length > 0 && lines[lines.length - 1]!.trim() && !BULLET.test(lines[lines.length - 1]!)) ? ["", ...added.split("\n")] : added.split("\n");
+  lines.splice(at, 0, ...addition);
+  return `${lines.join("\n")}\n`;
+}