@falkenslab/agent-kit 0.14.0 → 0.16.0

package/dist/core/extractText.js

@@ -0,0 +1,147 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Word, PowerPoint and Excel originals as markdown: the SDK's `Read` refuses DOCX and PPTX
+ * (confirmed empirically), and course material is often both. The libraries are optional
+ * peer dependencies of the kit (`mammoth` for DOCX, `fflate` to open PPTX and XLSX, which
+ * are zips of XML); without them the caller is told what to install.
+ */
+export const EXTRACTABLE = new Set(["docx", "pptx", "xlsx"]);
+/** The most rows of a sheet written out; the rest are counted. */
+const MAX_SHEET_ROWS = 200;
+export class MissingLibraryError extends Error {
+    library;
+    constructor(library, options) {
+        super(`Reading this format needs the optional "${library}" library: npm install ${library}`, options);
+        this.library = library;
+    }
+}
+async function load(library) {
+    try {
+        return (await import(library));
+    }
+    catch (error) {
+        throw new MissingLibraryError(library, { cause: error });
+    }
+}
+const decode = (xml) => xml
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&amp;/g, "&");
+/** The paragraphs of a DrawingML text body (slides and notes): each `<a:p>` its runs' `<a:t>` text. */
+function paragraphs(xml) {
+    return [...xml.matchAll(/<a:p\b[\s\S]*?<\/a:p>/g)]
+        .map((p) => [...p[0].matchAll(/<a:t>([\s\S]*?)<\/a:t>/g)].map((t) => decode(t[1])).join(""))
+        .map((text) => text.trim())
+        .filter(Boolean);
+}
+const text = (files, name) => (files[name] ? new TextDecoder().decode(files[name]) : undefined);
+async function unzip(file) {
+    const { unzipSync } = await load("fflate");
+    return unzipSync(new Uint8Array(await readFile(file)));
+}
+/** A slide deck: a section per slide (its title, text and speaker notes), from slide `from` to `to` (1-based). */
+async function pptx(file, from, to) {
+    const files = await unzip(file);
+    const slides = Object.keys(files)
+        .map((name) => /^ppt\/slides\/slide(\d+)\.xml$/.exec(name))
+        .filter((m) => Boolean(m))
+        .map((m) => Number(m[1]))
+        .sort((a, b) => a - b);
+    const first = Math.max(1, from ?? 1);
+    const last = Math.min(slides.length, to ?? slides.length);
+    const parts = [`# ${path.basename(file)}`, `${slides.length} slides${first > 1 || last < slides.length ? `; slides ${first} to ${last}` : ""}.`];
+    let images = 0;
+    for (const n of slides.slice(first - 1, last)) {
+        const xml = text(files, `ppt/slides/slide${n}.xml`) ?? "";
+        images += (xml.match(/<p:pic\b/g) ?? []).length;
+        const [title, ...body] = paragraphs(xml);
+        parts.push(`## Slide ${n}${title ? `: ${title}` : ""}`);
+        if (body.length)
+            parts.push(body.map((line) => `- ${line}`).join("\n"));
+        // A slide's notes are linked from its relationships; their slide-number placeholder is left out.
+        const rels = text(files, `ppt/slides/_rels/slide${n}.xml.rels`) ?? "";
+        const notesTarget = /Target="\.\.\/notesSlides\/(notesSlide\d+\.xml)"/.exec(rels)?.[1];
+        const notes = notesTarget ? paragraphs(text(files, `ppt/notesSlides/${notesTarget}`) ?? "").filter((line) => !/^\d+$/.test(line)) : [];
+        if (notes.length)
+            parts.push(`Speaker notes:\n${notes.map((line) => `> ${line}`).join("\n")}`);
+    }
+    if (images)
+        parts.push(`(${images} images left out.)`);
+    return `${parts.join("\n\n")}\n`;
+}
+/** The column index of a cell reference ("C7" → 2). */
+function columnOf(ref) {
+    let index = 0;
+    for (const letter of /^[A-Z]+/.exec(ref)?.[0] ?? "A")
+        index = index * 26 + letter.charCodeAt(0) - 64;
+    return index - 1;
+}
+const cell = (value) => value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+/** A workbook: a markdown table per sheet, capped in rows. */
+async function xlsx(file) {
+    const files = await unzip(file);
+    const shared = [...(text(files, "xl/sharedStrings.xml") ?? "").matchAll(/<si>([\s\S]*?)<\/si>/g)].map((si) => [...si[1].matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((t) => decode(t[1])).join(""));
+    const workbook = text(files, "xl/workbook.xml") ?? "";
+    const names = [...workbook.matchAll(/<sheet\b[^>]*name="([^"]*)"/g)].map((m) => decode(m[1]));
+    const sheets = Object.keys(files)
+        .map((name) => /^xl\/worksheets\/sheet(\d+)\.xml$/.exec(name))
+        .filter((m) => Boolean(m))
+        .map((m) => Number(m[1]))
+        .sort((a, b) => a - b);
+    const parts = [`# ${path.basename(file)}`];
+    for (const n of sheets) {
+        const xml = text(files, `xl/worksheets/sheet${n}.xml`) ?? "";
+        const rows = [...xml.matchAll(/<row\b[\s\S]*?<\/row>/g)].map((row) => {
+            const values = [];
+            for (const c of row[0].matchAll(/<c\b([^>]*?)(?:\/>|>([\s\S]*?)<\/c>)/g)) {
+                const attrs = c[1];
+                const ref = /r="([A-Z]+\d+)"/.exec(attrs)?.[1] ?? "";
+                const type = /t="(\w+)"/.exec(attrs)?.[1];
+                const raw = /<v>([\s\S]*?)<\/v>/.exec(c[2] ?? "")?.[1] ?? /<t[^>]*>([\s\S]*?)<\/t>/.exec(c[2] ?? "")?.[1] ?? "";
+                const value = type === "s" ? (shared[Number(raw)] ?? "") : decode(raw);
+                values[ref ? columnOf(ref) : values.length] = value;
+            }
+            return Array.from(values, (v) => cell(v ?? ""));
+        });
+        const filled = rows.filter((row) => row.some(Boolean));
+        parts.push(`## ${names[n - 1] ?? `Sheet ${n}`}`);
+        if (!filled.length) {
+            parts.push("(empty)");
+            continue;
+        }
+        const width = Math.max(...filled.map((row) => row.length));
+        const pad = (row) => `| ${Array.from({ length: width }, (_, i) => row[i] ?? "").join(" | ")} |`;
+        const shown = filled.slice(0, MAX_SHEET_ROWS);
+        parts.push([pad(shown[0]), `|${" --- |".repeat(width)}`, ...shown.slice(1).map(pad)].join("\n"));
+        if (filled.length > MAX_SHEET_ROWS)
+            parts.push(`(${filled.length - MAX_SHEET_ROWS} more rows.)`);
+    }
+    return `${parts.join("\n\n")}\n`;
+}
+/** A Word document: headings, paragraphs, lists and tables. */
+async function docx(file) {
+    const mammoth = await load("mammoth");
+    const { value: html } = await mammoth.convertToHtml({ path: file });
+    const images = (html.match(/<img\b/g) ?? []).length;
+    // Markdown with turndown (also optional); plain text without it.
+    const turndown = await load("turndown").catch(() => null);
+    const body = turndown
+        ? new turndown.default({ headingStyle: "atx" }).turndown(html.replace(/<img\b[^>]*>/g, ""))
+        : decode(html.replace(/<\/(p|h\d|li|tr)>/g, "\n").replace(/<[^>]+>/g, "")).trim();
+    return `# ${path.basename(file)}\n\n${body}\n${images ? `\n(${images} images left out.)\n` : ""}`;
+}
+/** An original's text as markdown; `from`/`to` pick slides of a deck. */
+export async function extractText(file, from, to) {
+    const type = path.extname(file).slice(1).toLowerCase();
+    if (type === "docx")
+        return docx(file);
+    if (type === "pptx")
+        return pptx(file, from, to);
+    if (type === "xlsx")
+        return xlsx(file);
+    throw new Error(`extract_text reads DOCX, PPTX and XLSX; for "${path.basename(file)}" use Read (PDFs, images, text).`);
+}

package/dist/core/fileKnowledgeStore.d.ts

@@ -0,0 +1,10 @@
+import { type KnowledgeStore, type PageType } from "./knowledgeStore.js";
+/** Options of `createFileKnowledgeStore()`. */
+export interface FileKnowledgeStoreOptions {
+    /** The agent's own page types, besides the kit's four. */
+    pageTypes?: readonly PageType[];
+    /** The sources folder: a summary's `file` field is given relative to it. */
+    sourcesDir?: string;
+}
+/** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
+export declare function createFileKnowledgeStore(knowledgeDir: string, options?: FileKnowledgeStoreOptions): KnowledgeStore;

package/dist/core/fileKnowledgeStore.js

@@ -0,0 +1,378 @@
+import { appendFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { BUILT_IN_PAGE_TYPES, isSlug, linkedIds, parseId, } from "./knowledgeStore.js";
+/**
+ * The kit's knowledge store over markdown files, in the layout the knowledge base always had
+ * (ADR-008): `index.md`, `log.md`, `overview.md` and a folder per page type (`summaries/`,
+ * `concepts/`...), or the root for a declared type with `dir: ""`. An existing knowledge base
+ * works as is. Links are stored as relative paths, so the files read well on their own, and
+ * returned as page ids; the index is rewritten after every change; backlinks are computed.
+ */
+const RESERVED = new Set(["index", "log", "overview"]);
+const posix = (p) => p.split(path.sep).join("/");
+const today = () => new Date().toISOString().slice(0, 10);
+function parse(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    const fields = new Map();
+    if (!match)
+        return { fields, body: text.replace(/^\s+/, "") };
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z_][\w-]*):\s?(.*)$/.exec(line);
+        if (kv)
+            fields.set(kv[1], kv[2].trim().replace(/^"(.*)"$/, "$1"));
+    }
+    return { fields, body: text.slice(match[0].length).replace(/^\s+/, "") };
+}
+function serialize(fields, body) {
+    const lines = [...fields].map(([key, value]) => `${key}: ${/[:#]/.test(value) && !/^\[.*\]$/.test(value) ? JSON.stringify(value) : value}`);
+    return `---\n${lines.join("\n")}\n---\n\n${body.replace(/^\s+/, "").replace(/\s*$/, "")}\n`;
+}
+/** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
+export function createFileKnowledgeStore(knowledgeDir, options = {}) {
+    const declared = options.pageTypes ?? [];
+    const types = [...BUILT_IN_PAGE_TYPES.filter((t) => !declared.some((d) => d.type === t.type)), ...declared];
+    const byType = new Map(types.map((t) => [t.type, t]));
+    const fileOf = (type, slug) => path.join(knowledgeDir, type.dir, `${slug}.md`);
+    async function readPage(type, slug) {
+        const file = fileOf(type, slug);
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch {
+            return null;
+        }
+        const { fields, body } = parse(text);
+        // At the root, a page belongs to the type its frontmatter says.
+        if (type.dir === "" && fields.get("type") !== type.type)
+            return null;
+        return { id: `${type.type}/${slug}`, type, slug, file, fields, body };
+    }
+    async function allPages() {
+        const pages = [];
+        for (const type of types) {
+            let names;
+            try {
+                names = await readdir(path.join(knowledgeDir, type.dir));
+            }
+            catch {
+                continue;
+            }
+            for (const name of names.filter((n) => n.endsWith(".md")).sort()) {
+                const slug = name.slice(0, -3);
+                if (type.dir === "" && RESERVED.has(slug))
+                    continue;
+                const page = await readPage(type, slug);
+                if (page)
+                    pages.push(page);
+            }
+        }
+        return pages;
+    }
+    async function find(id) {
+        const parsed = parseId(id);
+        const type = parsed && byType.get(parsed.type);
+        if (!parsed || !type)
+            throw new Error(`"${id}" isn't a page id: it's <type>/<slug>, with a type among ${types.map((t) => t.type).join(", ")}.`);
+        const page = await readPage(type, parsed.slug);
+        if (!page)
+            throw new Error(`There's no page "${id}". knowledge_search or knowledge_index finds the right one.`);
+        return page;
+    }
+    /** Links as ids → relative paths, from `file`. */
+    function toFile(markdown, file) {
+        return markdown.replace(/\]\(([a-z][a-z0-9-]*\/[a-z0-9]+(?:-[a-z0-9]+)*)(#[^)]*)?\)/g, (whole, id, anchor = "") => {
+            const parsed = parseId(id);
+            const type = parsed && byType.get(parsed.type);
+            if (!parsed || !type)
+                return whole;
+            return `](${posix(path.relative(path.dirname(file), fileOf(type, parsed.slug)))}${anchor})`;
+        });
+    }
+    /** Relative links to pages → ids. */
+    function fromFile(markdown, file, pagesByFile) {
+        return markdown.replace(/\]\(([^)\s:]+\.md)(#[^)]*)?\)/g, (whole, link, anchor = "") => {
+            const id = pagesByFile.get(path.normalize(path.resolve(path.dirname(file), decodeURI(link))));
+            return id ? `](${id}${anchor})` : whole;
+        });
+    }
+    const titleOf = (page) => page.fields.get("title") || /^#\s+(.+)$/m.exec(page.body)?.[1].trim() || page.slug;
+    function descriptionOf(page) {
+        const given = page.fields.get("description");
+        if (given)
+            return given;
+        const line = page.body
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .find((l) => l && !l.startsWith("#") && !l.startsWith(">") && !l.startsWith("-") && !l.startsWith("<"));
+        const sentence = (line ?? "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").split(/(?<=[.!?])\s/)[0];
+        return sentence.length > 140 ? `${sentence.slice(0, 139)}…` : sentence;
+    }
+    const statusOf = (page) => page.fields.get("status") || "active";
+    /** Checks every page first (types, slugs, ids, links among them or to existing pages), then writes them all. */
+    async function createPages(newPages) {
+        const ids = new Set();
+        const ready = [];
+        for (const { type: typeName, slug, title, content } of newPages) {
+            const type = byType.get(typeName);
+            if (!type)
+                throw new Error(`"${typeName}" isn't a page type: ${types.map((t) => t.type).join(", ")}.`);
+            if (!isSlug(slug))
+                throw new Error(`"${slug}" isn't a valid slug: lowercase ASCII words joined by hyphens, e.g. "spring-tides".`);
+            if (type.dir === "" && RESERVED.has(slug))
+                throw new Error(`"${slug}" is reserved.`);
+            const id = `${type.type}/${slug}`;
+            if (ids.has(id) || (await stat(fileOf(type, slug)).catch(() => null)))
+                throw new Error(`"${id}" already exists: edit it, or pick another slug.`);
+            ids.add(id);
+            const file = fileOf(type, slug);
+            const body = /^#\s/.test(content.trimStart()) ? content : `# ${title}\n\n${content}`;
+            ready.push({ id, type, slug, file, fields: new Map([["type", type.type], ["title", title]]), body });
+        }
+        for (const page of ready)
+            await linksResolve(page.body, page.id, ids);
+        for (const [i, page] of ready.entries()) {
+            const fields = newPages[i].fields ?? {};
+            page.body = toFile(page.body, page.file);
+            if (page.type.type === "summary" && !("ingested" in fields))
+                page.fields.set("ingested", today());
+            await applyFields(page, fields); // may refuse a summary's missing original, before anything is written
+        }
+        for (const page of ready) {
+            await mkdir(path.dirname(page.file), { recursive: true });
+            await writeFile(page.file, serialize(page.fields, page.body));
+        }
+        await writeIndex();
+        return [...ids];
+    }
+    /** Throws when a link points to a page that doesn't exist (nor is in `alsoCreating`). */
+    async function linksResolve(markdown, self, alsoCreating = new Set()) {
+        const missing = [];
+        for (const id of new Set(linkedIds(markdown))) {
+            if (id === self || alsoCreating.has(id))
+                continue;
+            const parsed = parseId(id);
+            const type = parsed && byType.get(parsed.type);
+            if (!type || !parsed || !(await readPage(type, parsed.slug)))
+                missing.push(id);
+        }
+        if (missing.length)
+            throw new Error(`These links point to pages that don't exist: ${missing.join(", ")}. Create them first, or link existing ones (knowledge_search).`);
+    }
+    /** A field given by the model, made ready to store: `file` (relative to sources/) becomes a link from the page. */
+    async function storedField(key, value, file) {
+        if (key !== "file" || !options.sourcesDir || /^[a-z]+:\/\//i.test(value))
+            return value;
+        const original = path.resolve(options.sourcesDir, value.replace(/^sources\//, ""));
+        if (!(await stat(original).catch(() => null))?.isFile())
+            throw new Error(`"${value}" isn't an original in sources/ (list_sources lists them).`);
+        return posix(path.relative(path.dirname(file), original));
+    }
+    async function applyFields(page, changes = {}) {
+        for (const [key, value] of Object.entries(changes)) {
+            if (key === "type")
+                continue;
+            if (value === null)
+                page.fields.delete(key);
+            else
+                page.fields.set(key, await storedField(key, value, page.file));
+        }
+        page.fields.set("updated", today());
+    }
+    async function save(page) {
+        await mkdir(path.dirname(page.file), { recursive: true });
+        await writeFile(page.file, serialize(page.fields, page.body));
+        await writeIndex();
+    }
+    /** The notice under the frontmatter of a superseded or retired page. */
+    const withNotice = (body, notice) => `> ${notice}\n\n${body.replace(/^> (Superseded|Retired) on [^\n]*\n\n/, "")}`;
+    async function indexText() {
+        const pages = (await allPages()).filter((p) => statusOf(p) !== "retired");
+        const lines = ["# Index", ""];
+        for (const type of types) {
+            const own = pages.filter((p) => p.type === type).sort((a, b) => titleOf(a).localeCompare(titleOf(b)));
+            if (!own.length)
+                continue;
+            lines.push(`## ${type.indexSection}`, "");
+            for (const page of own) {
+                const extras = (type.indexFields ?? []).filter((f) => page.fields.get(f)).map((f) => `${f}: ${page.fields.get(f)}`);
+                const status = statusOf(page) === "superseded" ? " (superseded)" : "";
+                lines.push(`- [${titleOf(page)}](${posix(path.relative(knowledgeDir, page.file))}) — ${descriptionOf(page)}${extras.length ? ` (${extras.join(", ")})` : ""}${status}`);
+            }
+            lines.push("");
+        }
+        return `${lines.join("\n").trimEnd()}\n`;
+    }
+    async function writeIndex() {
+        await mkdir(knowledgeDir, { recursive: true });
+        await writeFile(path.join(knowledgeDir, "index.md"), await indexText());
+    }
+    async function pagesByFile() {
+        const pages = await allPages();
+        return { pages, byFile: new Map(pages.map((p) => [path.normalize(p.file), p.id])) };
+    }
+    const normalize = (text) => text
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase();
+    return {
+        types: () => types,
+        async list() {
+            return (await allPages())
+                .filter((p) => statusOf(p) !== "retired")
+                .map((p) => ({ id: p.id, type: p.type.type, title: titleOf(p), description: descriptionOf(p), status: statusOf(p), fields: Object.fromEntries(p.fields) }));
+        },
+        async read(id) {
+            let page;
+            try {
+                page = await find(id);
+            }
+            catch {
+                return null;
+            }
+            const { pages, byFile } = await pagesByFile();
+            const linkedFrom = pages
+                .filter((p) => p.id !== page.id && linkedIds(fromFile(p.body, p.file, byFile)).includes(page.id))
+                .map((p) => p.id);
+            const fields = Object.fromEntries([...page.fields].filter(([key]) => key !== "type" && key !== "title"));
+            return { id: page.id, type: page.type.type, slug: page.slug, title: titleOf(page), fields, content: fromFile(page.body, page.file, byFile), linkedFrom };
+        },
+        async create(typeName, slug, title, content, fields = {}) {
+            return (await createPages([{ type: typeName, slug, title, content, fields }]))[0];
+        },
+        createMany: createPages,
+        async edit(id, oldText, newText, fields) {
+            const page = await find(id);
+            const { byFile } = await pagesByFile();
+            const current = fromFile(page.body, page.file, byFile);
+            const count = oldText ? current.split(oldText).length - 1 : 0;
+            if (count === 0)
+                throw new Error(`The text to replace isn't in "${id}" (as returned by knowledge_read, links as ids). Read it again.`);
+            if (count > 1)
+                throw new Error(`The text to replace appears ${count} times in "${id}": include more around it so it's unique.`);
+            await linksResolve(newText, id);
+            page.body = toFile(current.replace(oldText, () => newText), page.file);
+            await applyFields(page, fields);
+            await save(page);
+        },
+        async rewrite(id, content, fields) {
+            const page = await find(id);
+            await linksResolve(content, id);
+            page.body = toFile(/^#\s/.test(content.trimStart()) ? content : `# ${titleOf(page)}\n\n${content}`, page.file);
+            await applyFields(page, fields);
+            await save(page);
+        },
+        async supersede(id, by, reason) {
+            const page = await find(id);
+            const replacement = await find(by);
+            if (replacement.id === page.id)
+                throw new Error("A page can't supersede itself.");
+            const link = posix(path.relative(path.dirname(page.file), replacement.file));
+            page.fields.set("status", "superseded");
+            page.fields.set("superseded_by", link);
+            page.body = withNotice(page.body, `Superseded on ${today()}${reason ? ` (${reason})` : ""}: see [${titleOf(replacement)}](${link}).`);
+            await applyFields(page);
+            await save(page);
+        },
+        async retire(id, reason) {
+            const page = await find(id);
+            page.fields.set("status", "retired");
+            page.fields.set("retired", today());
+            page.body = withNotice(page.body, `Retired on ${today()}: ${reason}. Don't rely on what it says.`);
+            await applyFields(page);
+            await save(page);
+        },
+        async search(query, limit = 10) {
+            const terms = normalize(query)
+                .split(/[^a-z0-9]+/)
+                .filter((term) => term.length > 1);
+            if (!terms.length)
+                return [];
+            const hits = [];
+            const { pages, byFile } = await pagesByFile();
+            for (const page of pages) {
+                if (statusOf(page) === "retired")
+                    continue;
+                const title = normalize(titleOf(page));
+                const aliases = normalize(page.fields.get("aliases") ?? "");
+                const lines = fromFile(page.body, page.file, byFile)
+                    .split(/\r?\n/)
+                    .filter((line) => !/^#\s/.test(line));
+                let score = 0;
+                let snippet = "";
+                for (const term of terms) {
+                    if (title.includes(term))
+                        score += 5;
+                    if (aliases.includes(term))
+                        score += 4;
+                    for (const line of lines) {
+                        if (normalize(line).includes(term)) {
+                            score += 1;
+                            snippet ||= line.trim();
+                        }
+                    }
+                }
+                if (score > 0)
+                    hits.push({ id: page.id, title: titleOf(page), snippet: (snippet || descriptionOf(page)).slice(0, 200), score });
+            }
+            return hits
+                .sort((a, b) => b.score - a.score)
+                .slice(0, limit)
+                .map(({ id, title, snippet }) => ({ id, title, snippet }));
+        },
+        index: indexText,
+        async log(operation, what, pages = []) {
+            await mkdir(knowledgeDir, { recursive: true });
+            const file = path.join(knowledgeDir, "log.md");
+            const exists = await stat(file).catch(() => null);
+            const entry = `## [${today()}] ${operation} | ${what}\n${pages.length ? `- pages: ${pages.join(", ")}\n` : ""}`;
+            await appendFile(file, `${exists ? "\n" : "# Log\n\n"}${entry}`);
+        },
+        async check() {
+            await writeIndex(); // the one mechanical fix there is: an index.md out of date
+            const { pages, byFile } = await pagesByFile();
+            const known = new Map(pages.map((p) => [p.id, p]));
+            const inbound = new Map();
+            const report = { brokenLinks: [], orphans: [], linksToRetired: [], missingOriginals: [] };
+            for (const page of pages) {
+                if (statusOf(page) === "retired")
+                    continue;
+                const body = fromFile(page.body, page.file, byFile);
+                // Relative links to .md files that resolve to nothing are broken too.
+                for (const m of page.body.matchAll(/\]\(([^)\s:]+\.md)(?:#[^)]*)?\)/g)) {
+                    const target = path.normalize(path.resolve(path.dirname(page.file), decodeURI(m[1])));
+                    if (!byFile.has(target) && target.startsWith(path.normalize(knowledgeDir)))
+                        report.brokenLinks.push({ page: page.id, target: posix(path.relative(knowledgeDir, target)) });
+                }
+                for (const id of new Set(linkedIds(body))) {
+                    const target = known.get(id);
+                    if (!target)
+                        report.brokenLinks.push({ page: page.id, target: id });
+                    else if (statusOf(target) === "retired")
+                        report.linksToRetired.push({ page: page.id, target: id });
+                    if (id !== page.id)
+                        inbound.set(id, (inbound.get(id) ?? 0) + 1);
+                }
+                const file = page.fields.get("file");
+                if (file && !/^[a-z]+:\/\//i.test(file) && !(await stat(path.resolve(path.dirname(page.file), file)).catch(() => null))) {
+                    report.missingOriginals.push({ page: page.id, file });
+                }
+            }
+            report.orphans = pages
+                .filter((p) => statusOf(p) !== "retired" && p.type.type !== "summary" && p.type.type !== "synthesis" && !inbound.get(p.id))
+                .map((p) => p.id);
+            return report;
+        },
+        async overview() {
+            const file = path.join(knowledgeDir, "overview.md");
+            const text = await readFile(file, "utf8").catch(() => "");
+            return text ? fromFile(text, file, (await pagesByFile()).byFile) : "";
+        },
+        async writeOverview(content) {
+            await linksResolve(content);
+            const file = path.join(knowledgeDir, "overview.md");
+            await mkdir(knowledgeDir, { recursive: true });
+            await writeFile(file, `${toFile(content.trim(), file)}\n`);
+        },
+    };
+}

package/dist/core/hooks/fileScopeGate.d.ts

@@ -16,6 +16,14 @@ export interface FileScope {
     searchableDirs: string[];
     /** Never readable, searchable or writable. */
     deniedPaths: string[];
+    /**
+     * Reached only through the kit's own tools, never the file tools: the knowledge folder
+     * when the agent has the `knowledge_*` tools (ADR-024). The denial says what to use instead.
+     */
+    toolOnlyDirs?: {
+        dir: string;
+        instead: string;
+    }[];
 }
 /** Whether `candidate` is `base` itself or somewhere inside it (case-insensitive on Windows, like path.relative). */
 export declare function isWithin(base: string, candidate: string): boolean;

package/dist/core/hooks/fileScopeGate.js

@@ -15,6 +15,26 @@ function describeDirs(scope, dirs) {
 export function checkFileScope(scope, toolName, input) {
     const resolve = (value) => typeof value === "string" && value !== "" ? path.resolve(scope.projectDir, value) : undefined;
     const isDenied = (target) => scope.deniedPaths.some((denied) => isWithin(denied, target));
+    // The folder of the kit's own tools that `target` is in, if any.
+    const toolOnlyDirs = (scope.toolOnlyDirs ?? []).map((only) => ({ ...only, dir: path.resolve(scope.projectDir, only.dir) }));
+    const toolOnly = (target) => toolOnlyDirs.find(({ dir }) => isWithin(dir, target));
+    const viaTools = (shown, only) => `"${String(shown)}" is in ${path.relative(scope.projectDir, only.dir) || "."}/, which is reached only through ${only.instead}, not the file tools.`;
+    if (toolName === "Read" || toolName === "Write" || toolName === "Edit") {
+        const target = resolve(input.file_path);
+        const only = target && toolOnly(target);
+        if (only)
+            return viaTools(input.file_path, only);
+    }
+    if (toolName === "Grep" || toolName === "Glob") {
+        const target = resolve(input.path) ?? scope.projectDir;
+        const pattern = typeof input.pattern === "string" ? input.pattern : "";
+        // Where a search really starts: Grep's path, Glob's path plus the pattern's fixed folders
+        // ("sources/**" starts in sources/). From above the folder it would reach into it.
+        const start = toolName === "Glob" ? path.resolve(target, pattern.replace(/[^/\\]*[*?[{].*$/, "")) : target;
+        const only = toolOnly(start) ?? toolOnlyDirs.find(({ dir }) => isWithin(start, dir));
+        if (only)
+            return viaTools(input.path ?? pattern, only);
+    }
     switch (toolName) {
         case "Read": {
             const target = resolve(input.file_path);

package/dist/core/hooks/humanInput.d.ts

@@ -11,5 +11,23 @@ export type { ApprovalPrompt } from "../interaction.js";
  * Returns the answer lowercased and trimmed ("", "y", "n", "q"...).
  */
 export declare function askForDecision(runDir: string, prompt: ApprovalPrompt): Promise<string>;
+/**
+ * A free-text answer, through the port's `askText()` (or `askDecision()` when it has none)
+ * and the response file: trimmed, with its case kept.
+ */
+export declare function askForText(runDir: string, prompt: ApprovalPrompt): Promise<string>;
+/** What the person chose: the options they picked, and their own answer if they gave one. */
+export interface ChoiceAnswer {
+    chosen: string[];
+    other?: string;
+}
+/** Reads a raw choice answer (see `InteractionPort.askChoice()`) against `options`. */
+export declare function parseChoice(raw: string, options: readonly string[], multiple: boolean): ChoiceAnswer;
+/**
+ * A choice between `options`, through the port's `askChoice()` (or `askDecision()` with the
+ * options numbered in the prompt) and the response file, which takes the same answer: the
+ * numbers, or the person's own words.
+ */
+export declare function askForChoice(runDir: string, prompt: ApprovalPrompt, options: readonly string[], multiple?: boolean): Promise<ChoiceAnswer>;
 /** Like `askForDecision()`, for a manual-intervention checkpoint (see tools/manualLogin.ts). */
 export declare function askForManualIntervention(runDir: string, prompt: ApprovalPrompt): Promise<string>;

package/dist/core/hooks/humanInput.js

@@ -1,6 +1,7 @@
 import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import { getInteractionPort } from "../interaction.js";
+import { t } from "../messages/index.js";
 /**
  * Asks the human for a decision through two channels in parallel, whichever answers
  * first wins: (1) the installed `InteractionPort` (the keyboard, for a person running the
@@ -14,6 +15,33 @@ import { getInteractionPort } from "../interaction.js";
 export async function askForDecision(runDir, prompt) {
     return await raceWithResponseFile(runDir, (port, signal) => port.askDecision(prompt, signal));
 }
+/**
+ * A free-text answer, through the port's `askText()` (or `askDecision()` when it has none)
+ * and the response file: trimmed, with its case kept.
+ */
+export async function askForText(runDir, prompt) {
+    return await raceWithResponseFile(runDir, (port, signal) => (port.askText ? port.askText(prompt, signal) : port.askDecision(prompt, signal)), false);
+}
+/** Reads a raw choice answer (see `InteractionPort.askChoice()`) against `options`. */
+export function parseChoice(raw, options, multiple) {
+    const [first = "", ...rest] = raw.trim().split(/\r?\n/);
+    const isNumbers = /^\s*\d+(\s*,\s*\d+)*\s*$/.test(first);
+    const numbers = isNumbers ? first.split(",").map((n) => Number(n.trim())).filter((n) => n >= 1 && n <= options.length) : [];
+    const chosen = [...new Set(numbers)].slice(0, multiple ? undefined : 1).map((n) => options[n - 1]);
+    const other = (isNumbers ? rest : [first, ...rest]).join("\n").trim();
+    return other ? { chosen, other } : { chosen };
+}
+/**
+ * A choice between `options`, through the port's `askChoice()` (or `askDecision()` with the
+ * options numbered in the prompt) and the response file, which takes the same answer: the
+ * numbers, or the person's own words.
+ */
+export async function askForChoice(runDir, prompt, options, multiple = false) {
+    const raw = await raceWithResponseFile(runDir, (port, signal) => port.askChoice
+        ? port.askChoice(prompt, { options, multiple }, signal)
+        : port.askDecision({ ...prompt, lines: [...prompt.lines, ...options.map((option, i) => `${i + 1}. ${option}`)], question: t().choiceQuestion(multiple) }, signal), false);
+    return parseChoice(raw, options, multiple);
+}
 /** Like `askForDecision()`, for a manual-intervention checkpoint (see tools/manualLogin.ts). */
 export async function askForManualIntervention(runDir, prompt) {
     return await raceWithResponseFile(runDir, (port, signal) => port.askManualIntervention(prompt, signal));
@@ -21,7 +49,7 @@ export async function askForManualIntervention(runDir, prompt) {
 function never() {
     return new Promise(() => { });
 }
-async function raceWithResponseFile(runDir, ask) {
+async function raceWithResponseFile(runDir, ask, lowercase = true) {
     const responseFile = path.join(runDir, "approval-response.txt");
     await rm(responseFile, { force: true });
     let settled = false;
@@ -48,5 +76,5 @@ async function raceWithResponseFile(runDir, ask) {
     settled = true;
     controller.abort();
     await rm(responseFile, { force: true });
-    return raw.trim().toLowerCase();
+    return lowercase ? raw.trim().toLowerCase() : raw.trim();
 }