@falkenslab/agent-kit 0.14.0 → 0.16.0

package/dist/core/session.js

@@ -9,6 +9,11 @@ import { createPlanGate } from "./hooks/planGate.js";
 import { createHumanApprovalServer } from "./tools/humanApproval.js";
 import { createManualLoginServer } from "./tools/manualLogin.js";
 import { createSaveToSourcesServer } from "./tools/saveToSources.js";
+import { createTimeServer } from "./tools/time.js";
+import { TODO_TOOL } from "./todos.js";
+import { createModeControl } from "./modeControl.js";
+import { createFileKnowledgeStore } from "./fileKnowledgeStore.js";
+import { createKnowledgeServer } from "./tools/knowledgeTools.js";
 import { allowAnyMcpTool } from "./mcpPermissions.js";
 import { knowledgePluginRoot, knowledgePromptSection } from "./knowledge.js";
 import { replyLanguageInstruction } from "./language.js";
@@ -53,24 +58,38 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // (`knowledgeDir`) or for original files (`sourcesDir`) — there is no separate "context"
     // folder: material the user provides is just more of `sourcesDir`.
     const includeFileTools = Boolean(config.knowledgeDir || config.sourcesDir);
-    const fileTools = includeFileTools ? ["Read", "Write", "Edit", "Glob", "Grep"] : [];
+    // The built-in knowledge base (rules in the system prompt + its skills/commands as a plugin) needs
+    // somewhere to keep the wiki, so it follows `knowledgeDir`; `spec.knowledgeBase: false` opts out.
+    const includeKnowledgeBase = Boolean(config.knowledgeDir) && spec.knowledgeBase !== false;
+    // By default the agent reaches it only through the `knowledge_*` tools, over a store, never
+    // with the file tools (ADR-024); `spec.knowledgeTools: "files"` keeps the file tools on it.
+    const knowledgeViaStore = includeKnowledgeBase && (spec.knowledgeTools ?? "store") === "store";
+    const notesDir = knowledgeViaStore ? undefined : config.knowledgeDir;
+    const extraDirs = config.extraWritableDirs ?? [];
+    // With the store, the file tools are only for the originals (reading) and the extra writable
+    // folders; without either, none.
+    const fileTools = !includeFileTools
+        ? []
+        : !knowledgeViaStore
+            ? ["Read", "Write", "Edit", "Glob", "Grep"]
+            : [...(config.sourcesDir || extraDirs.length ? ["Read", "Glob", "Grep"] : []), ...(extraDirs.length ? ["Write", "Edit"] : [])];
     // Where Write/Edit may act and Grep may search (see hooks/fileScopeGate.ts): the
     // project's own folders, never the whole cwd — which would include whatever else the
     // project directory holds (the user's config...). `sourcesDir` is searchable but
     // deliberately NOT writable: originals stay as obtained, and the only way to add to it is
     // the `save_to_sources` tool (which never overwrites).
-    const writableDirs = [config.knowledgeDir, ...(config.extraWritableDirs ?? [])].filter((d) => Boolean(d));
-    const searchableDirs = [config.knowledgeDir, config.sourcesDir, ...(config.extraWritableDirs ?? [])].filter((d) => Boolean(d));
+    const writableDirs = [notesDir, ...extraDirs].filter((d) => Boolean(d));
+    const searchableDirs = [notesDir, config.sourcesDir, ...extraDirs].filter((d) => Boolean(d));
     const readOnlyDirs = config.sourcesDir ? [config.sourcesDir] : [];
     // Skills/commands/plugins are a separate concern from the file tools: an agent that
     // wants a plugin-provided skill/command but has no notes or sources folder shouldn't have
     // to invent one just to get `cwd`/`skills: "all"`/`plugins` wired up. Gated on either
     // signal, not on `pluginRoots` alone, so an agent with file tools keeps getting the SDK's
     // own project-level `.claude/skills`/`.claude/commands` discovery.
-    // The built-in knowledge base (rules in the system prompt + its skills/commands as a plugin) needs
-    // somewhere to keep the wiki, so it follows `knowledgeDir`; `spec.knowledgeBase: false` opts out.
-    const includeKnowledgeBase = Boolean(config.knowledgeDir) && spec.knowledgeBase !== false;
-    const pluginRoots = [...spec.pluginRoots(config), ...(includeKnowledgeBase ? [knowledgePluginRoot()] : [])];
+    const pluginRoots = [...spec.pluginRoots(config), ...(includeKnowledgeBase ? [knowledgePluginRoot(knowledgeViaStore ? "tools" : "files")] : [])];
+    const knowledgeStore = knowledgeViaStore && config.knowledgeDir
+        ? (spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(config.knowledgeDir, { pageTypes: spec.knowledgePageTypes, sourcesDir: config.sourcesDir }))
+        : undefined;
     const includeSkillsAndPlugins = includeFileTools || pluginRoots.length > 0;
     const skillTools = includeSkillsAndPlugins ? ["Skill"] : [];
     // Whatever opt-in subagents `spec` wants for this config, or undefined if none apply.
@@ -97,7 +116,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
     const sdkOptions = {
         systemPrompt: withReplyLine(includeKnowledgeBase && config.knowledgeDir
-            ? `${spec.buildSystemPrompt(config)}\n\n${knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir)}`
+            ? `${spec.buildSystemPrompt(config)}\n\n${knowledgePromptSection(config.projectDir, config.knowledgeDir, config.sourcesDir, { tools: knowledgeViaStore, pageTypes: knowledgeStore?.types() })}`
             : spec.buildSystemPrompt(config)),
         // Not the SDK's default (every source): "user" hands the agent the runner's own Claude
         // Code configuration, and its `language` setting outranked the agent's prompt.
@@ -118,8 +137,10 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         // "Skill" has to be listed explicitly: with an explicit `tools` list the SDK loads the
         // skills (they show up in the init message) but doesn't offer the tool to invoke them,
         // so the model ends up looking for SKILL.md files by hand (confirmed empirically).
-        tools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
-        allowedTools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
+        // TodoWrite: the SDK's task list for long jobs, in every session (the chats show the list
+        // instead of the calls; see todos.ts). Accepted in an explicit list (confirmed empirically).
+        tools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
+        allowedTools: [...fileTools, ...skillTools, "WebFetch", "WebSearch", TODO_TOOL, ...(includeSubagentTools ? ["Agent", "Bash"] : [])],
         // Every mcp__* tool (whatever spec.buildMcpServers() registers, approvals/manualLogin
         // when enabled below, sourceFiles, and any server a project's own .mcp.json
         // declares) is approved generically here rather than listed one by one — see
@@ -145,7 +166,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 // SDK's own official skills (pdf/docx), the project's own custom ones, and the
                 // plugin-provided built-ins below. A spec's own list gets the knowledge base's
                 // skills added, so it only names its own.
-                skills: skillList(spec.skills, includeKnowledgeBase),
+                skills: skillList(spec.skills, includeKnowledgeBase ? (knowledgeViaStore ? "tools" : "files") : null),
                 plugins: pluginRoots.map((pluginPath) => ({ type: "local", path: pluginPath, skipMcpDiscovery: true })),
             }
             : {}),
@@ -154,15 +175,47 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         ...(subagentDefinitions ? { agents: subagentDefinitions } : {}),
         mcpServers: {
             ...spec.buildMcpServers(config, runDir),
-            ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts) } : {}),
+            ...(includeApprovalTool ? { approvals: createHumanApprovalServer(runDir, spec.humanApprovalTexts, { modeControl }) } : {}),
             ...(manualInterventionTexts ? { manualLogin: createManualLoginServer(runDir, manualInterventionTexts) } : {}),
-            ...(config.sourcesDir ? { sourceFiles: createSaveToSourcesServer(runDir, config.sourcesDir, spec.saveToSourcesDescription) } : {}),
+            // The sources folder's tools (tools/saveToSources.ts); asking a person (request_file,
+            // retire_source) only where there is one.
+            ...(config.sourcesDir
+                ? {
+                    sourceFiles: createSaveToSourcesServer(runDir, config.sourcesDir, spec.saveToSourcesDescription, {
+                        knowledgeDir: config.knowledgeDir,
+                        projectDir: config.projectDir,
+                        interactive: mode !== "autonomous",
+                    }),
+                }
+                : {}),
+            // The knowledge base's own tools, over its store (tools/knowledgeTools.ts, ADR-024).
+            ...(knowledgeStore
+                ? {
+                    knowledge: createKnowledgeServer(knowledgeStore, {
+                        runDir,
+                        interactive: mode !== "autonomous",
+                        sourcesDir: config.sourcesDir,
+                        projectDir: config.projectDir,
+                        knowledgeDir: config.knowledgeDir,
+                    }),
+                }
+                : {}),
+            // The date and date arithmetic, in every session and mode: only reads (tools/time.ts).
+            time: createTimeServer(config.timeZone),
         },
         hooks: {
             PreToolUse: [
                 { hooks: [transcriptLogger.preToolUse] },
                 ...(includeFileTools
-                    ? [{ hooks: [createFileScopeGate({ projectDir: config.projectDir, writableDirs, searchableDirs, readOnlyDirs, deniedPaths: config.deniedPaths ?? [] })] }]
+                    ? [{ hooks: [createFileScopeGate({
+                                    projectDir: config.projectDir,
+                                    writableDirs,
+                                    searchableDirs,
+                                    readOnlyDirs,
+                                    deniedPaths: config.deniedPaths ?? [],
+                                    ...(knowledgeViaStore && config.knowledgeDir ? { toolOnlyDirs: [{ dir: config.knowledgeDir, instead: "the knowledge_* tools" }] } : {}),
+                                }),
+                            ] }]
                     : []),
                 // Registered wherever the approval tool is, and asking only while the current mode is
                 // "interactive": a guided session can switch to interactive and back (ModeControl).
@@ -193,67 +246,19 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             PostToolUse: [{ hooks: [transcriptLogger.postToolUse] }],
         },
     };
-    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language };
+    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, ...(knowledgeStore ? { knowledgeStore } : {}) };
 }
-/** The knowledge plugin's skills, as the SDK names a plugin's skills ("plugin:skill"). */
-const KNOWLEDGE_SKILLS = ["knowledge-pages", "knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`);
-function skillList(skills, includeKnowledgeBase) {
+export { createModeControl, togglePlanMode } from "./modeControl.js";
+/** The knowledge plugin's skills, as the SDK names a plugin's skills ("plugin:skill"): the tools variant has no page templates skill (knowledge_create gives them). */
+const KNOWLEDGE_SKILLS = {
+    tools: ["knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`),
+    files: ["knowledge-pages", "knowledge-ingest", "knowledge-query", "knowledge-lint"].map((skill) => `knowledge:${skill}`),
+};
+function skillList(skills, knowledgeVariant) {
     if (skills === undefined || skills === "all")
         return "all";
-    return includeKnowledgeBase ? [...new Set([...skills, ...KNOWLEDGE_SKILLS])] : skills;
-}
-/** A `ModeControl` starting at `initial` (`buildSessionOptions()` returns one for its session). */
-export function createModeControl(initial) {
-    let current = initial;
-    // The mode the model was last told about: a session starting in plan mode tells it with
-    // the first message, since the system prompt doesn't say.
-    let told = initial === "plan" ? undefined : initial;
-    const switchable = initial === "autonomous" ? ["autonomous"] : ["guided", "interactive", "plan"];
-    return {
-        get mode() {
-            return current;
-        },
-        switchable,
-        set(next) {
-            if (!switchable.includes(next))
-                return false;
-            current = next;
-            return true;
-        },
-        takeNotice() {
-            const before = told;
-            told = current;
-            if (current === "plan" && before !== "plan")
-                return PLAN_MODE_ENTERED;
-            if (current !== "plan" && before === "plan")
-                return PLAN_MODE_LEFT;
-            return undefined;
-        },
-    };
-}
-// The mode each session was in when `/plan` took it into plan mode, to go back to.
-const modeBeforePlan = new WeakMap();
-/**
- * What the chats' `/plan` does: switches `control` into plan mode, or, when it's already
- * there, back to the mode it was entered from ("guided" if it started in plan mode). Returns
- * the new mode, or `null` when this session can't be in plan mode (an autonomous one).
- */
-export function togglePlanMode(control) {
-    if (!control.switchable.includes("plan"))
-        return null;
-    if (control.mode === "plan") {
-        const back = modeBeforePlan.get(control) ?? "guided";
-        control.set(back);
-        return back;
-    }
-    modeBeforePlan.set(control, control.mode);
-    control.set("plan");
-    return "plan";
+    return knowledgeVariant ? [...new Set([...skills, ...KNOWLEDGE_SKILLS[knowledgeVariant]])] : skills;
 }
-// What the model reads on a plan-mode switch, in English like the rest of what it reads
-// (ADR-019); tagged so a resumed conversation doesn't show it as the human's words (runs.ts).
-const PLAN_MODE_ENTERED = "<system-reminder>The user switched to plan mode. Only read, research and plan: nothing can be changed (files, tools that modify something) until they switch out of it. When the plan is ready, present it and wait for them.</system-reminder>";
-const PLAN_MODE_LEFT = "<system-reminder>The user left plan mode: you can carry out the plan now.</system-reminder>";
 /**
  * User message queue backed by a single long-lived generator, for any multi-turn
  * (chat-shaped) caller of `query()`.

package/dist/core/sources.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The sources folder's bookkeeping: originals stay files (ADR-024), and the kit keeps a
+ * manifest next to them (`.agent-kit/sources.json`, inside `sourcesDir`, where the agent's
+ * file tools can't write) with each original's hash, size and provenance, the version it
+ * replaces, and the hash it had when a summary page first pointed to it. From that it tells
+ * new, ingested, changed and missing originals apart, refuses duplicates, and retires an
+ * original into `.agent-kit/retired/` instead of deleting it.
+ */
+export declare const KIT_DIR = ".agent-kit";
+/** Where an original came from. */
+export type SourceOrigin = {
+    kind: "run";
+    from: string;
+} | {
+    kind: "url";
+    from: string;
+} | {
+    kind: "person";
+    from: string;
+}
+/** Copied in by hand: first seen by `listSources()`. */
+ | {
+    kind: "manual";
+};
+export interface SourceEntry {
+    hash: string;
+    size: number;
+    /** For hashing a file again only when it changed. */
+    mtimeMs: number;
+    addedAt: string;
+    origin: SourceOrigin;
+    /** The original this one is a new version of (a path relative to `sourcesDir`). */
+    replaces?: string;
+    /** The page this one was generated from (a web page's markdown, from its HTML). */
+    derivedFrom?: string;
+    /** The hash when a summary page first pointed to it: a different hash now means it changed after its ingest. */
+    ingestedHash?: string;
+}
+export interface RetiredSource {
+    path: string;
+    movedTo: string;
+    retiredAt: string;
+    why: "wrong" | "replaced";
+    reason: string;
+    replacedBy?: string;
+    entry?: SourceEntry;
+}
+export interface SourceManifest {
+    version: 1;
+    files: Record<string, SourceEntry>;
+    retired: RetiredSource[];
+}
+export type SourceStatus = "new" | "ingested" | "changed" | "missing" | "present";
+export interface SourceListing {
+    path: string;
+    status: SourceStatus;
+    type: string;
+    size?: number;
+    pages?: number;
+    slides?: number;
+    origin?: SourceOrigin;
+    replaces?: string;
+    /** The summary pages that point to it (paths relative to the project). */
+    summaries: string[];
+}
+export declare function hashFile(file: string): Promise<string>;
+/** Resolves `candidate` against `base`; the absolute path only if it stays inside it. */
+export declare function resolveWithin(base: string, candidate: string): string | undefined;
+export declare function loadManifest(sourcesDir: string): Promise<SourceManifest>;
+export declare function saveManifest(sourcesDir: string, manifest: SourceManifest): Promise<void>;
+/** Every original under `sourcesDir` (paths relative to it), leaving out hidden files and folders (the kit's own among them). */
+export declare function scanSources(sourcesDir: string): Promise<string[]>;
+/** The summary pages (knowledge base layout: `summaries/*.md`) by the absolute path of the original their frontmatter `file:` points to. */
+export declare function summariesByOriginal(knowledgeDir: string): Promise<Map<string, string[]>>;
+/** Pages of a PDF, read from its page tree without a parser; undefined when it can't tell (e.g. compressed object streams). */
+export declare function pdfPageCount(bytes: Buffer): number | undefined;
+/** Slides of a PPTX, from the file names in the zip (stored uncompressed). */
+export declare function pptxSlideCount(bytes: Buffer): number | undefined;
+/**
+ * Every original with its status, recording in the manifest the ones copied in by hand and,
+ * the first time a summary page points to one, its hash at ingest. Without a knowledge
+ * folder there's no ingest to compare with: originals are "present".
+ */
+export declare function listSources(sourcesDir: string, knowledgeDir: string | undefined, projectDir: string): Promise<SourceListing[]>;
+export interface AddedSource {
+    /** Where it is, relative to `sourcesDir`. */
+    path: string;
+    /** An identical file was already there: nothing was copied. */
+    duplicateOf?: string;
+}
+/**
+ * Adds `file` (an absolute path) to `sourcesDir` at `destination` (a folder: under `extra.name`,
+ * or the file's own name): never overwriting, and
+ * not at all if an identical file is already there (its path is returned). `replaces`
+ * records it as a new version of an original already in the folder.
+ */
+export declare function addSource(sourcesDir: string, file: string, destination: string, origin: SourceOrigin, extra?: {
+    replaces?: string;
+    derivedFrom?: string;
+    name?: string;
+}): Promise<AddedSource>;
+/** What retiring an original did to its summary pages (paths relative to the project). */
+export interface RetireResult {
+    movedTo: string;
+    summaries: {
+        page: string;
+        marked: "retired" | "superseded";
+        supersededBy?: string;
+    }[];
+}
+/**
+ * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder)
+ * and records why. Its summary pages are marked: retired if the original was wrong (what it
+ * taught was wrong), superseded if it was replaced, pointing to the replacement's summary
+ * when there is one.
+ */
+export declare function retireSource(sourcesDir: string, knowledgeDir: string | undefined, projectDir: string, source: string, why: "wrong" | "replaced", reason: string, replacedBy?: string): Promise<RetireResult>;
+/**
+ * Records `source` (relative to `sourcesDir`) as ingested now, with its current hash: a
+ * summary page was just written from it, so "changed" means changed after this.
+ */
+export declare function recordIngest(sourcesDir: string, source: string): Promise<void>;

package/dist/core/sources.js

@@ -0,0 +1,312 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { copyFile, mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * The sources folder's bookkeeping: originals stay files (ADR-024), and the kit keeps a
+ * manifest next to them (`.agent-kit/sources.json`, inside `sourcesDir`, where the agent's
+ * file tools can't write) with each original's hash, size and provenance, the version it
+ * replaces, and the hash it had when a summary page first pointed to it. From that it tells
+ * new, ingested, changed and missing originals apart, refuses duplicates, and retires an
+ * original into `.agent-kit/retired/` instead of deleting it.
+ */
+export const KIT_DIR = ".agent-kit";
+const MANIFEST = "sources.json";
+const RETIRED_DIR = "retired";
+const posix = (p) => p.split(path.sep).join("/");
+// The model can call several tools at once: everything that reads and writes a folder's
+// manifest runs one at a time per folder, or a parallel call would lose another's entry.
+const locks = new Map();
+function serialized(sourcesDir, work) {
+    const key = path.resolve(sourcesDir);
+    const result = (locks.get(key) ?? Promise.resolve()).then(work, work);
+    locks.set(key, result.catch(() => undefined));
+    return result;
+}
+const now = () => new Date().toISOString();
+export async function hashFile(file) {
+    return createHash("sha256").update(await readFile(file)).digest("hex");
+}
+/** Resolves `candidate` against `base`; the absolute path only if it stays inside it. */
+export function resolveWithin(base, candidate) {
+    const resolved = path.isAbsolute(candidate) ? path.resolve(candidate) : path.resolve(base, candidate);
+    const relative = path.relative(base, resolved);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)) ? resolved : undefined;
+}
+export async function loadManifest(sourcesDir) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(sourcesDir, KIT_DIR, MANIFEST), "utf8"));
+        return { version: 1, files: parsed.files ?? {}, retired: parsed.retired ?? [] };
+    }
+    catch {
+        return { version: 1, files: {}, retired: [] };
+    }
+}
+export async function saveManifest(sourcesDir, manifest) {
+    await mkdir(path.join(sourcesDir, KIT_DIR), { recursive: true });
+    await writeFile(path.join(sourcesDir, KIT_DIR, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+/** Every original under `sourcesDir` (paths relative to it), leaving out hidden files and folders (the kit's own among them). */
+export async function scanSources(sourcesDir) {
+    const found = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.isFile())
+                found.push(posix(path.relative(sourcesDir, full)));
+        }
+    }
+    await walk(sourcesDir);
+    return found.sort();
+}
+/** An entry for `file`, reusing the recorded hash when its size and modification time haven't changed. */
+async function freshEntry(file, known, origin) {
+    const info = await stat(file);
+    if (known && known.size === info.size && known.mtimeMs === info.mtimeMs)
+        return known;
+    return { ...(known ?? { addedAt: now(), origin }), hash: await hashFile(file), size: info.size, mtimeMs: info.mtimeMs };
+}
+/** The original a frontmatter `file:` value points to (a relative path or a markdown link), resolved from the page's folder. */
+function linkedFile(value, pageDir) {
+    const link = /\]\(([^)]+)\)/.exec(value)?.[1] ?? value.trim().replace(/^["']|["']$/g, "");
+    if (!link || /^[a-z]+:\/\//i.test(link))
+        return undefined;
+    return path.resolve(pageDir, decodeURI(link));
+}
+/** The summary pages (knowledge base layout: `summaries/*.md`) by the absolute path of the original their frontmatter `file:` points to. */
+export async function summariesByOriginal(knowledgeDir) {
+    const byOriginal = new Map();
+    const dir = path.join(knowledgeDir, "summaries");
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return byOriginal;
+    }
+    for (const name of names.filter((n) => n.endsWith(".md"))) {
+        const page = path.join(dir, name);
+        const text = await readFile(page, "utf8");
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
+        const value = /^file:\s*(.+)$/m.exec(frontmatter)?.[1];
+        const original = value ? linkedFile(value, dir) : undefined;
+        if (original)
+            byOriginal.set(path.normalize(original), [...(byOriginal.get(path.normalize(original)) ?? []), page]);
+    }
+    return byOriginal;
+}
+/** Pages of a PDF, read from its page tree without a parser; undefined when it can't tell (e.g. compressed object streams). */
+export function pdfPageCount(bytes) {
+    const text = bytes.toString("latin1");
+    const counts = [...text.matchAll(/\/Type\s*\/Pages\b[^>]*?\/Count\s+(\d+)/g)].map((m) => Number(m[1]));
+    const reversed = [...text.matchAll(/\/Count\s+(\d+)[^>]*?\/Type\s*\/Pages\b/g)].map((m) => Number(m[1]));
+    const fromTree = Math.max(0, ...counts, ...reversed);
+    if (fromTree > 0)
+        return fromTree;
+    const pages = text.match(/\/Type\s*\/Page(?![s\w])/g)?.length ?? 0;
+    return pages > 0 ? pages : undefined;
+}
+/** Slides of a PPTX, from the file names in the zip (stored uncompressed). */
+export function pptxSlideCount(bytes) {
+    const names = new Set(bytes.toString("latin1").match(/ppt\/slides\/slide\d+\.xml/g) ?? []);
+    return names.size > 0 ? names.size : undefined;
+}
+const typeOf = (file) => path.extname(file).slice(1).toLowerCase() || "file";
+/**
+ * Every original with its status, recording in the manifest the ones copied in by hand and,
+ * the first time a summary page points to one, its hash at ingest. Without a knowledge
+ * folder there's no ingest to compare with: originals are "present".
+ */
+export function listSources(sourcesDir, knowledgeDir, projectDir) {
+    return serialized(sourcesDir, () => listSourcesNow(sourcesDir, knowledgeDir, projectDir));
+}
+async function listSourcesNow(sourcesDir, knowledgeDir, projectDir) {
+    const manifest = await loadManifest(sourcesDir);
+    const summaries = knowledgeDir ? await summariesByOriginal(knowledgeDir) : new Map();
+    const files = await scanSources(sourcesDir);
+    const listing = [];
+    for (const rel of files) {
+        const full = path.join(sourcesDir, rel);
+        const entry = await freshEntry(full, manifest.files[rel], { kind: "manual" });
+        const pagesOf = summaries.get(path.normalize(full)) ?? [];
+        let status = "present";
+        if (knowledgeDir) {
+            if (pagesOf.length === 0)
+                status = "new";
+            else {
+                entry.ingestedHash ??= entry.hash;
+                status = entry.ingestedHash === entry.hash ? "ingested" : "changed";
+            }
+        }
+        manifest.files[rel] = entry;
+        const type = typeOf(rel);
+        const counts = type === "pdf" || type === "pptx"
+            ? await readFile(full).then((bytes) => (type === "pdf" ? { pages: pdfPageCount(bytes) } : { slides: pptxSlideCount(bytes) }))
+            : {};
+        listing.push({
+            path: rel,
+            status,
+            type,
+            size: entry.size,
+            ...counts,
+            origin: entry.origin,
+            ...(entry.replaces ? { replaces: entry.replaces } : {}),
+            summaries: pagesOf.map((page) => posix(path.relative(projectDir, page))),
+        });
+    }
+    for (const [rel, entry] of Object.entries(manifest.files)) {
+        if (!files.includes(rel))
+            listing.push({ path: rel, status: "missing", type: typeOf(rel), origin: entry.origin, summaries: [] });
+    }
+    await saveManifest(sourcesDir, manifest);
+    return listing;
+}
+/**
+ * Adds `file` (an absolute path) to `sourcesDir` at `destination` (a folder: under `extra.name`,
+ * or the file's own name): never overwriting, and
+ * not at all if an identical file is already there (its path is returned). `replaces`
+ * records it as a new version of an original already in the folder.
+ */
+export function addSource(sourcesDir, file, destination, origin, extra = {}) {
+    return serialized(sourcesDir, () => addSourceNow(sourcesDir, file, destination, origin, extra));
+}
+async function addSourceNow(sourcesDir, file, destination, origin, extra) {
+    // A folder ("books/", or one that exists) means: inside it, under the file's own name.
+    const isFolder = /[/\\]$/.test(destination) || (await stat(path.join(sourcesDir, destination)).catch(() => null))?.isDirectory();
+    if (isFolder)
+        destination = path.join(destination, extra.name ?? path.basename(file));
+    const target = resolveWithin(sourcesDir, destination);
+    if (!target || posix(path.relative(sourcesDir, target)).split("/").some((part) => part.startsWith("."))) {
+        throw new Error(`"${destination}" isn't a path inside sources/ (hidden folders are the kit's).`);
+    }
+    const manifest = await loadManifest(sourcesDir);
+    if (extra.replaces) {
+        const old = resolveWithin(sourcesDir, extra.replaces);
+        if (!old || !(await stat(old).catch(() => null)))
+            throw new Error(`"${extra.replaces}" isn't an original in sources/, so it can't be replaced.`);
+    }
+    const hash = await hashFile(file);
+    for (const rel of await scanSources(sourcesDir)) {
+        const entry = await freshEntry(path.join(sourcesDir, rel), manifest.files[rel], { kind: "manual" });
+        manifest.files[rel] = entry;
+        if (entry.hash === hash) {
+            await saveManifest(sourcesDir, manifest);
+            return { path: rel, duplicateOf: rel };
+        }
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    try {
+        await copyFile(file, target, constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new Error(`"${destination}" already exists in sources/: originals are never overwritten. Pick another name${extra.replaces ? "" : ", or pass `replaces` for a new version"}.`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    const rel = posix(path.relative(sourcesDir, target));
+    const info = await stat(target);
+    manifest.files[rel] = {
+        hash,
+        size: info.size,
+        mtimeMs: info.mtimeMs,
+        addedAt: now(),
+        origin,
+        ...(extra.replaces ? { replaces: posix(path.relative(sourcesDir, resolveWithin(sourcesDir, extra.replaces))) } : {}),
+        ...(extra.derivedFrom ? { derivedFrom: extra.derivedFrom } : {}),
+    };
+    await saveManifest(sourcesDir, manifest);
+    return { path: rel };
+}
+/** Adds frontmatter fields and a notice under the frontmatter of a markdown page. */
+async function markPage(page, fields, notice) {
+    const text = await readFile(page, "utf8");
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    const lines = Object.entries(fields).map(([key, value]) => `${key}: ${value}`);
+    const updated = match
+        ? `---\n${match[1].split(/\r?\n/).filter((line) => !Object.keys(fields).some((key) => line.startsWith(`${key}:`))).concat(lines).join("\n")}\n---\n\n> ${notice}\n\n${text.slice(match[0].length).replace(/^\s+/, "")}`
+        : `---\n${lines.join("\n")}\n---\n\n> ${notice}\n\n${text}`;
+    await writeFile(page, updated);
+}
+/**
+ * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder)
+ * and records why. Its summary pages are marked: retired if the original was wrong (what it
+ * taught was wrong), superseded if it was replaced, pointing to the replacement's summary
+ * when there is one.
+ */
+export function retireSource(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
+    return serialized(sourcesDir, () => retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy));
+}
+async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
+    const full = resolveWithin(sourcesDir, source);
+    if (!full || !(await stat(full).catch(() => null))?.isFile())
+        throw new Error(`"${source}" isn't an original in sources/.`);
+    const rel = posix(path.relative(sourcesDir, full));
+    if (rel.split("/").some((part) => part.startsWith(".")))
+        throw new Error(`"${source}" is one of the kit's own files.`);
+    const replacement = replacedBy ? resolveWithin(sourcesDir, replacedBy) : undefined;
+    if (replacedBy && (!replacement || !(await stat(replacement).catch(() => null))))
+        throw new Error(`"${replacedBy}" isn't an original in sources/.`);
+    const summaries = knowledgeDir ? await summariesByOriginal(knowledgeDir) : new Map();
+    const manifest = await loadManifest(sourcesDir);
+    const stamp = now();
+    const movedTo = posix(path.join(KIT_DIR, RETIRED_DIR, `${stamp.replace(/[:.]/g, "-")}-${path.basename(rel)}`));
+    await mkdir(path.join(sourcesDir, KIT_DIR, RETIRED_DIR), { recursive: true });
+    await rename(full, path.join(sourcesDir, movedTo));
+    manifest.retired.push({
+        path: rel,
+        movedTo,
+        retiredAt: stamp,
+        why,
+        reason,
+        ...(replacement ? { replacedBy: posix(path.relative(sourcesDir, replacement)) } : {}),
+        ...(manifest.files[rel] ? { entry: manifest.files[rel] } : {}),
+    });
+    delete manifest.files[rel];
+    await saveManifest(sourcesDir, manifest);
+    const date = stamp.slice(0, 10);
+    const replacementSummary = replacement ? summaries.get(path.normalize(replacement))?.[0] : undefined;
+    const result = { movedTo, summaries: [] };
+    for (const page of summaries.get(path.normalize(full)) ?? []) {
+        if (why === "wrong") {
+            await markPage(page, { status: "retired", retired: date }, `Retired on ${date}: its original was wrong (${reason}). Don't rely on what it says.`);
+            result.summaries.push({ page: posix(path.relative(projectDir, page)), marked: "retired" });
+        }
+        else {
+            const link = replacementSummary ? posix(path.relative(path.dirname(page), replacementSummary)) : undefined;
+            await markPage(page, { status: "superseded", superseded: date, ...(link ? { superseded_by: link } : {}) }, `Superseded on ${date}: its original was replaced (${reason})${link ? `; see [the new summary](${link})` : ""}.`);
+            result.summaries.push({ page: posix(path.relative(projectDir, page)), marked: "superseded", ...(replacementSummary ? { supersededBy: posix(path.relative(projectDir, replacementSummary)) } : {}) });
+        }
+    }
+    return result;
+}
+/**
+ * Records `source` (relative to `sourcesDir`) as ingested now, with its current hash: a
+ * summary page was just written from it, so "changed" means changed after this.
+ */
+export function recordIngest(sourcesDir, source) {
+    return serialized(sourcesDir, async () => {
+        const full = resolveWithin(sourcesDir, source);
+        if (!full || !(await stat(full).catch(() => null))?.isFile())
+            return;
+        const rel = posix(path.relative(sourcesDir, full));
+        const manifest = await loadManifest(sourcesDir);
+        const entry = await freshEntry(full, manifest.files[rel], { kind: "manual" });
+        entry.ingestedHash = entry.hash;
+        manifest.files[rel] = entry;
+        await saveManifest(sourcesDir, manifest);
+    });
+}