@falkenslab/agent-kit 0.17.0 → 0.18.0

package/dist/core/sources.js

@@ -5,10 +5,11 @@ 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.
+ * file tools can't write) with each original's hash, size, provenance, the version it replaces
+ * and when its content last changed. From that it refuses duplicates, tells present, missing
+ * and retired originals apart, and retires an original into `.agent-kit/retired/` instead of
+ * deleting it. It knows nothing of the knowledge base: each owns its data, and the model
+ * connects them through their tools (#30). Hashes never leave it.
  */
 export const KIT_DIR = ".agent-kit";
 const MANIFEST = "sources.json";
@@ -70,41 +71,20 @@ export async function scanSources(sourcesDir) {
     await walk(sourcesDir);
     return found.sort();
 }
-/** An entry for `file`, reusing the recorded hash when its size and modification time haven't changed. */
+/**
+ * An entry for `file`, reusing the recorded hash when its size and modification time haven't
+ * changed; `changedAt` moves only when the content (its hash) did. Entries from before
+ * `changedAt` existed take their `addedAt`.
+ */
 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;
+    const previous = known ? { ...known, changedAt: known.changedAt ?? known.addedAt } : undefined;
+    if (previous && previous.size === info.size && previous.mtimeMs === info.mtimeMs)
+        return previous;
+    const hash = await hashFile(file);
+    const stamp = now();
+    const base = previous ?? { addedAt: stamp, origin, changedAt: stamp };
+    return { ...base, hash, size: info.size, mtimeMs: info.mtimeMs, changedAt: previous && previous.hash === hash ? previous.changedAt : stamp };
 }
 /** 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) {
@@ -124,31 +104,19 @@ export function pptxSlideCount(bytes) {
 }
 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".
+ * Every original with its status and when its content last changed, recording in the manifest
+ * the ones copied in by hand; then the missing ones and the retired ones.
  */
-export function listSources(sourcesDir, knowledgeDir, projectDir) {
-    return serialized(sourcesDir, () => listSourcesNow(sourcesDir, knowledgeDir, projectDir));
+export function listSources(sourcesDir) {
+    return serialized(sourcesDir, () => listSourcesNow(sourcesDir));
 }
-async function listSourcesNow(sourcesDir, knowledgeDir, projectDir) {
+async function listSourcesNow(sourcesDir) {
     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"
@@ -156,18 +124,28 @@ async function listSourcesNow(sourcesDir, knowledgeDir, projectDir) {
             : {};
         listing.push({
             path: rel,
-            status,
+            status: "present",
             type,
+            changedAt: entry.changedAt,
             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: [] });
+            listing.push({ path: rel, status: "missing", type: typeOf(rel), origin: entry.origin });
+    }
+    for (const retired of manifest.retired) {
+        listing.push({
+            path: retired.path,
+            status: "retired",
+            type: typeOf(retired.path),
+            retiredAt: retired.retiredAt,
+            why: retired.why,
+            ...(retired.replacedBy ? { replacedBy: retired.replacedBy } : {}),
+        });
     }
     await saveManifest(sourcesDir, manifest);
     return listing;
@@ -219,11 +197,13 @@ async function addSourceNow(sourcesDir, file, destination, origin, extra) {
     }
     const rel = posix(path.relative(sourcesDir, target));
     const info = await stat(target);
+    const stamp = now();
     manifest.files[rel] = {
         hash,
         size: info.size,
         mtimeMs: info.mtimeMs,
-        addedAt: now(),
+        addedAt: stamp,
+        changedAt: stamp,
         origin,
         ...(extra.replaces ? { replaces: posix(path.relative(sourcesDir, resolveWithin(sourcesDir, extra.replaces))) } : {}),
         ...(extra.derivedFrom ? { derivedFrom: extra.derivedFrom } : {}),
@@ -231,26 +211,15 @@ async function addSourceNow(sourcesDir, file, destination, origin, extra) {
     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.
+ * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder) and
+ * records why. What was built from it (summary pages) is the knowledge base's to update: the
+ * model does it with its tools.
  */
-export function retireSource(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
-    return serialized(sourcesDir, () => retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy));
+export function retireSource(sourcesDir, source, why, reason, replacedBy) {
+    return serialized(sourcesDir, () => retireSourceNow(sourcesDir, source, why, reason, replacedBy));
 }
-async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
+async function retireSourceNow(sourcesDir, 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/.`);
@@ -260,7 +229,6 @@ async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why
     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)}`));
@@ -277,36 +245,5 @@ async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why
     });
     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);
-    });
+    return { movedTo };
 }

package/dist/core/tools/humanApproval.js

@@ -34,8 +34,8 @@ export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL
         };
     });
     const askHuman = tool("ask_human", "Ask the person to choose between options, in a panel, and get the answer in this same turn, instead of ending your turn with a written question. Use it when you need their decision to go on (which approach, which of several items). They can also type their own answer.", {
-        question: z.string().describe("The question, in one sentence, in the person's language"),
-        options: z.array(z.string()).min(2).max(8).describe("The options, short, in the person's language (2 to 8; an \"Other\" for their own answer is added)"),
+        question: z.string().describe("The question, in one sentence, in the language you reply in"),
+        options: z.array(z.string()).min(2).max(8).describe("The options, short, in the language you reply in (2 to 8; an \"Other\" for their own answer is added)"),
         multiple: z.boolean().optional().describe("Whether they can pick several (default: one)"),
     }, async (args) => {
         const answer = await askForChoice(runDir, { title: t().questionTitle, lines: [args.question] }, args.options, args.multiple ?? false);
@@ -46,7 +46,7 @@ export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL
         return ok(parts.length ? parts.join("\n") : "The person didn't answer. Go on with what you can, or ask in your reply.");
     });
     const control = options.modeControl;
-    const presentPlan = tool("present_plan", "In plan mode, when the plan is ready: show it to the person, who decides to run it (plan mode ends and you carry it out right away, in this turn), to keep planning (with a comment on what to change) or to cancel. Outside plan mode it's refused.", { plan: z.string().describe("The whole plan, in markdown, in the person's language: steps, what changes, what to check") }, async (args) => {
+    const presentPlan = tool("present_plan", "In plan mode, when the plan is ready: show it to the person, who decides to run it (plan mode ends and you carry it out right away, in this turn), to keep planning (with a comment on what to change) or to cancel. Outside plan mode it's refused.", { plan: z.string().describe("The whole plan, in markdown, in the language you reply in: steps, what changes, what to check") }, async (args) => {
         if (!control || control.mode !== "plan")
             return { ...ok("present_plan only works in plan mode: you aren't in it, so just go ahead."), isError: true };
         const choices = [t().runPlan, t().keepPlanning, t().cancelPlan];

package/dist/core/tools/knowledgeTools.d.ts

@@ -1,16 +1,16 @@
 import type { KnowledgeStore } from "../knowledgeStore.js";
+/**
+ * Text as the model meant it: a body that arrives with escaped newlines ("\\n") and no real
+ * one gets them back. A model sometimes double-escapes a long markdown argument, and the page
+ * would be stored as one line with literal "\n"s (found by a real session).
+ */
+export declare function unescapedText(text: string): string;
 /** Options of `createKnowledgeServer()`. */
 export interface KnowledgeToolsOptions {
     /** This run's folder (for the response file of `knowledge_retire`'s approval). */
     runDir: string;
     /** A person can be asked (not autonomous): adds `knowledge_retire`, which asks first. */
     interactive?: boolean;
-    /** The sources folder: summaries record their original's hash, and `knowledge_check` reports new, changed and missing originals. */
-    sourcesDir?: string;
-    /** The project root, for `list_sources`' paths. */
-    projectDir?: string;
-    /** The knowledge folder, for `list_sources`' ingest status. */
-    knowledgeDir?: string;
 }
 /** The `knowledge` MCP server over `store`. */
 export declare function createKnowledgeServer(store: KnowledgeStore, options: KnowledgeToolsOptions): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/core/tools/knowledgeTools.js

@@ -1,7 +1,5 @@
-import path from "node:path";
 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
-import { listSources, loadManifest, recordIngest } from "../sources.js";
 import { askForDecision } from "../hooks/humanInput.js";
 import { t } from "../messages/index.js";
 /**
@@ -21,6 +19,14 @@ async function attempt(work) {
         return fail(message(error));
     }
 }
+/**
+ * Text as the model meant it: a body that arrives with escaped newlines ("\\n") and no real
+ * one gets them back. A model sometimes double-escapes a long markdown argument, and the page
+ * would be stored as one line with literal "\n"s (found by a real session).
+ */
+export function unescapedText(text) {
+    return !text.includes("\n") && text.includes("\\n") ? text.replace(/\\r\\n|\\n/g, "\n").replace(/\\t/g, "\t") : text;
+}
 const OVERVIEW = "overview";
 const LOG = "log";
 /** The `knowledge` MCP server over `store`. */
@@ -31,20 +37,8 @@ export function createKnowledgeServer(store, options) {
     const fields = z
         .array(z.object({ name: z.string(), value: z.string().nullable() }))
         .optional()
-        .describe('Frontmatter fields to set (value null removes one), e.g. [{"name": "aliases", "value": "tide range, tidal range"}]; for a summary, "file" is its original relative to sources/');
+        .describe('Frontmatter fields to set (value null removes one), e.g. [{"name": "aliases", "value": "tide range, tidal range"}]; for a summary, "file" is its original as list_sources names it (its "ingested" is set for you)');
     const changes = (pairs) => pairs ? Object.fromEntries(pairs.map(({ name, value }) => [name, value])) : undefined;
-    /** A summary written from an original: record its hash, so "changed" means changed after this. */
-    async function ingested(id) {
-        if (!options.sourcesDir || !id.startsWith("summary/"))
-            return;
-        const page = await store.read(id);
-        const file = page?.fields.file;
-        if (!file || /^[a-z]+:\/\//i.test(file))
-            return;
-        const knowledgeDir = options.knowledgeDir;
-        const original = knowledgeDir ? path.resolve(knowledgeDir, "summaries", file) : path.resolve(options.sourcesDir, file);
-        await recordIngest(options.sourcesDir, path.relative(options.sourcesDir, original));
-    }
     const index = tool("knowledge_index", "The knowledge base's catalog: every page, one line each (title, id, what it is), by section. Start here, then read only the pages the task needs.", {}, async () => attempt(async () => (await store.list()).length ? await store.index() : "The knowledge base is empty."), { annotations: { readOnlyHint: true } });
     const search = tool("knowledge_search", "Find pages by words: in titles, aliases and content, best first, with the line that matched. Search before creating a page, so you don't duplicate one under another name.", { query: z.string().describe("Words to look for"), limit: z.number().int().positive().max(50).optional() }, async (args) => attempt(async () => {
         const hits = await store.search(args.query, args.limit ?? 10);
@@ -71,7 +65,7 @@ export function createKnowledgeServer(store, options) {
         .join("; ")}. Without content, returns the type's template: fill it and call again. Links to other pages are ids, [Bowline](concept/bowline), and must exist, or be created in the same call (\`also\`); the index is kept for you.`, {
         type: z.enum(typeNames),
         slug: z.string().describe('Lowercase ASCII words joined by hyphens, e.g. "spring-tides"'),
-        title: z.string().describe("The page's title, in the person's language"),
+        title: z.string().describe("The page's title, in the language you reply in"),
         content: z.string().optional().describe("The page's markdown body (under its title), following the type's template"),
         fields,
         also: z
@@ -87,34 +81,30 @@ export function createKnowledgeServer(store, options) {
     }, async (args) => attempt(async () => {
         const type = store.types().find((t) => t.type === args.type);
         if (!args.content)
-            return `Template for a ${type.type} page (${type.description}):\n\n${type.template}\n\nFill it in the person's language and call knowledge_create again with content.`;
+            return `Template for a ${type.type} page (${type.description}):\n\n${type.template}\n\nFill it in the language you reply in and call knowledge_create again with content.`;
         const ids = await store.createMany([
-            { type: args.type, slug: args.slug, title: args.title, content: args.content, fields: changes(args.fields) },
-            ...(args.also ?? []).map((page) => ({ ...page, fields: changes(page.fields) })),
+            { type: args.type, slug: args.slug, title: args.title, content: unescapedText(args.content), fields: changes(args.fields) },
+            ...(args.also ?? []).map((page) => ({ ...page, content: unescapedText(page.content), fields: changes(page.fields) })),
         ]);
-        for (const id of ids)
-            await ingested(id);
         return `Created ${ids.join(", ")}.`;
     }));
     const edit = tool("knowledge_edit", "Change one fragment of a page: oldText (exactly as knowledge_read returned it, unique in the page) becomes newText. Prefer it to rewriting a page.", { page: z.string(), oldText: z.string(), newText: z.string(), fields }, async (args) => attempt(async () => {
-        await store.edit(args.page, args.oldText, args.newText, changes(args.fields));
-        await ingested(args.page);
+        await store.edit(args.page, unescapedText(args.oldText), unescapedText(args.newText), changes(args.fields));
         return `Edited ${args.page}.`;
     }));
     const rewrite = tool("knowledge_rewrite", 'Replace a page\'s whole content, keeping its id and the links to it: for a page redone from a better source, or the "overview" (the living synthesis of the whole knowledge base). For small changes use knowledge_edit.', { page: z.string().describe('The page id, or "overview"'), content: z.string(), fields }, async (args) => attempt(async () => {
         if (args.page === OVERVIEW) {
-            await store.writeOverview(args.content);
+            await store.writeOverview(unescapedText(args.content));
             return "Rewrote the overview.";
         }
-        await store.rewrite(args.page, args.content, changes(args.fields));
-        await ingested(args.page);
+        await store.rewrite(args.page, unescapedText(args.content), changes(args.fields));
         return `Rewrote ${args.page}.`;
     }));
     const supersede = tool("knowledge_supersede", "Mark a page superseded by another one (it stays, with a notice pointing to the new one). Pages are never deleted or renamed.", { page: z.string(), by: z.string().describe("The page that replaces it"), reason: z.string().optional() }, async (args) => attempt(async () => {
         await store.supersede(args.page, args.by, args.reason);
         return `${args.page} is now superseded by ${args.by}. Repoint the links that should go to the new page.`;
     }));
-    const retire = tool("knowledge_retire", "Retire a page whose knowledge was wrong (e.g. learned from a wrong original), after the person approves: it leaves the index and the search but is kept. Then fix the pages that link to it (knowledge_check lists them).", { page: z.string(), reason: z.string().describe("Why, in one sentence, in the person's language") }, async (args) => attempt(async () => {
+    const retire = tool("knowledge_retire", "Retire a page whose knowledge was wrong (e.g. learned from a wrong original). It asks the person itself, with a panel: don't ask them first. Retired, it leaves the index and the search but is kept. Then fix the pages that link to it (knowledge_check lists them).", { page: z.string(), reason: z.string().describe("Why, in one sentence, in the language you reply in") }, async (args) => attempt(async () => {
         const page = await store.read(args.page);
         if (!page)
             throw new Error(`There's no page "${args.page}".`);
@@ -134,32 +124,7 @@ export function createKnowledgeServer(store, options) {
         await store.log(args.operation, args.what, args.pages ?? []);
         return "Logged.";
     }));
-    const check = tool("knowledge_check", "The knowledge base's mechanical problems in one call: broken links, orphan pages, links to retired pages, summaries whose original is gone, originals that are new, changed or missing, and the passages that cite a retired original. Fix what's mechanical; report what needs the person.", {}, async () => attempt(async () => {
-        const report = { ...(await store.check()) };
-        if (options.sourcesDir) {
-            const sources = await listSources(options.sourcesDir, options.knowledgeDir, options.projectDir ?? path.dirname(options.sourcesDir));
-            report.newOriginals = sources.filter((s) => s.status === "new").map((s) => s.path);
-            report.changedOriginals = sources.filter((s) => s.status === "changed").map((s) => ({ path: s.path, summaries: s.summaries }));
-            report.missingFromSources = sources.filter((s) => s.status === "missing").map((s) => s.path);
-            const retired = (await loadManifest(options.sourcesDir)).retired;
-            if (retired.length) {
-                const citations = [];
-                for (const info of await store.list()) {
-                    const page = await store.read(info.id);
-                    for (const original of retired) {
-                        const name = path.basename(original.path);
-                        for (const line of (page?.content ?? "").split(/\r?\n/))
-                            if (line.includes(name))
-                                citations.push({ original: original.path, page: info.id, passage: line.trim() });
-                        if (page?.fields.file?.endsWith(name) && info.status === "active")
-                            citations.push({ original: original.path, page: info.id, passage: `file: ${page.fields.file}` });
-                    }
-                }
-                report.citesRetiredOriginals = citations;
-            }
-        }
-        return JSON.stringify(report, null, 2);
-    }), { annotations: { readOnlyHint: true } });
+    const check = tool("knowledge_check", "The knowledge base's mechanical problems in one call: broken links, orphan pages and links to retired pages. Fix what's mechanical; report what needs the person. Whether its summaries are up to date with their originals is a comparison you make: list_sources' changedAt against each summary's ingested (knowledge_index shows them): both ISO 8601 in UTC, the later one sorts after as text.", {}, async () => attempt(async () => JSON.stringify(await store.check(), null, 2)), { annotations: { readOnlyHint: true } });
     return createSdkMcpServer({
         name: "knowledge",
         version: "1.0.0",

package/dist/core/tools/saveToSources.d.ts

@@ -8,10 +8,14 @@ export declare const MAX_SOURCE_BYTES: number;
 export declare function htmlToMarkdown(html: string, url: string): Promise<string | null>;
 /** Downloads `url` into `file`, refusing other schemes and anything over `maxBytes`; returns its content type. */
 export declare function downloadToFile(url: string, file: string, maxBytes: number): Promise<string>;
+/**
+ * The "Sources" section appended to the system prompt whenever there's a sources folder, with or
+ * without a knowledge base: what the originals are and how they come and go. `projectDir` and
+ * `sourcesDir` give the folder's name as the model reads it.
+ */
+export declare function sourcesPromptSection(projectDir: string, sourcesDir: string): string;
 /** Options of `createSaveToSourcesServer()`. */
 export interface SourceToolsOptions {
-    /** The knowledge folder, to tell which originals have a summary page (`list_sources`). */
-    knowledgeDir?: string;
     /** The project root: paths in the tools' answers are relative to it. Defaults to the parent of `sourcesDir`. */
     projectDir?: string;
     /** A person can be asked (not autonomous): adds `request_file` and `retire_source`, which ask first. */

package/dist/core/tools/saveToSources.js

@@ -104,6 +104,16 @@ export async function downloadToFile(url, file, maxBytes) {
     await writeFile(file, Buffer.concat(chunks));
     return response.headers.get("content-type") ?? "";
 }
+/**
+ * The "Sources" section appended to the system prompt whenever there's a sources folder, with or
+ * without a knowledge base: what the originals are and how they come and go. `projectDir` and
+ * `sourcesDir` give the folder's name as the model reads it.
+ */
+export function sourcesPromptSection(projectDir, sourcesDir) {
+    const folder = `${path.relative(projectDir, sourcesDir).split(path.sep).join("/") || "."}/`;
+    return `## Sources
+- **Originals (read-only for you)**: \`${folder}\`. Never rewrite one; build on them. \`list_sources\` lists them with when each one's content last changed (\`changedAt\`), and the missing and retired ones; add a file only with \`save_to_sources\`, \`download_to_sources\` or by asking the person (\`request_file\`), and take out a wrong or superseded one only with \`retire_source\`. \`Read\` reads PDFs and images; \`extract_text\` reads DOCX, PPTX (with speaker notes) and XLSX.`;
+}
 /**
  * The tools that keep `sourcesDir`, the originals the agent reads but never edits (Write/Edit
  * are scoped to the notes folder, see hooks/fileScopeGate.ts): `save_to_sources`,
@@ -149,9 +159,9 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
             return fail(message(error));
         }
     });
-    const listSourcesTool = tool("list_sources", "List the originals in sources/ with their status: new (no summary page points to it: ingest it), ingested, changed (it changed after its ingest: update its summary), missing (deleted by hand) or present (no knowledge base to compare with); with type, size, pages of a PDF or slides of a PPTX (read long ones in parts), provenance, the version it replaces and its summary pages. Use it instead of listing the folder.", {}, async () => {
+    const listSourcesTool = tool("list_sources", "List the originals in sources/: present, missing (deleted by hand) or retired (when, why, what replaced it); with changedAt (when its content last changed, ISO 8601 in UTC: a later date sorts after as text, to compare with when something was built from it), type, size, pages of a PDF or slides of a PPTX (read long ones in parts), provenance and the version it replaces. Use it instead of listing the folder.", {}, async () => {
         try {
-            return ok(JSON.stringify(await listSources(sourcesDir, options.knowledgeDir, projectDir), null, 2));
+            return ok(JSON.stringify(await listSources(sourcesDir), null, 2));
         }
         catch (error) {
             return fail(message(error));
@@ -215,7 +225,7 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
         }
     });
     const requestFile = tool("request_file", "Ask the person for a file you need (a syllabus, a document they have) and copy it into sources/ with its provenance. They give a path or say they don't have it; never overwrites, and doesn't copy a file identical to one already there.", {
-        description: z.string().describe("What file you need and why, in one or two sentences, in the person's language"),
+        description: z.string().describe("What file you need and why, in one or two sentences, in the language you reply in"),
         destination: z.string().optional().describe("Path to save it under, relative to sources/; the file's own name if omitted"),
         replaces,
     }, async (args) => {
@@ -235,23 +245,18 @@ export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFA
             return fail(message(error));
         }
     });
-    const retire = tool("retire_source", 'Retire an original that was wrong ("wrong") or replaced by a better one ("replaced"), after the person approves it: it\'s moved to sources/.agent-kit/retired/ (never deleted), and its summary page is marked retired (wrong) or superseded, pointing to the replacement\'s summary (replaced). Afterwards, update the index and correct or re-ground the pages that cited it.', {
+    const retire = tool("retire_source", 'Retire an original that was wrong ("wrong") or replaced by a better one ("replaced"). It asks the person itself, with a panel: don\'t ask them first. Approved, it\'s moved to sources/.agent-kit/retired/ (never deleted), and list_sources shows it as retired. What you built from it is yours to review afterwards.', {
         source: z.string().describe("The original, relative to sources/"),
         why: z.enum(["wrong", "replaced"]),
-        reason: z.string().describe("Why, in one sentence, in the person's language"),
+        reason: z.string().describe("Why, in one sentence, in the language you reply in"),
         replacedBy: z.string().optional().describe('For "replaced": the original that replaces it, relative to sources/'),
     }, async (args) => {
         const answer = await askForDecision(runDir, { title: t().retireTitle, lines: t().retireLines(inFolder(args.source), args.why, args.reason, args.replacedBy && inFolder(args.replacedBy), folder) });
         if (answer !== "" && answer !== "y" && answer !== "yes")
             return ok(answer === "q" ? "The person stopped: don't retire it, and stop what you were doing." : "The person said no: the original stays.");
         try {
-            const result = await retireSource(sourcesDir, options.knowledgeDir, projectDir, inFolder(args.source), args.why, args.reason, args.replacedBy && inFolder(args.replacedBy));
-            const pages = result.summaries.map((s) => `${s.page} marked ${s.marked}${s.supersededBy ? ` (see ${s.supersededBy})` : ""}`);
-            return ok([
-                `Retired: moved to sources/${result.movedTo}.`,
-                ...(pages.length ? pages : ["It had no summary page."]),
-                "Now update index.md, and correct or re-ground the pages that cite it (search the knowledge base for its file name).",
-            ].join("\n"));
+            const result = await retireSource(sourcesDir, inFolder(args.source), args.why, args.reason, args.replacedBy && inFolder(args.replacedBy));
+            return ok(`Retired: moved to sources/${result.movedTo}. If anything was built from it (a summary, notes that cite it), review it now: ${args.why === "wrong" ? "what it taught was wrong" : `it was replaced${args.replacedBy ? ` by sources/${inFolder(args.replacedBy)}` : ""}`}.`);
         }
         catch (error) {
             return fail(message(error));

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { setInteractionPort, getInteractionPort, type InteractionPort, type Appr
 export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";
 export { createHumanApprovalServer, DEFAULT_HUMAN_APPROVAL_TEXTS, type HumanApprovalTexts } from "./core/tools/humanApproval.js";
 export { createManualLoginServer, type ManualInterventionTexts } from "./core/tools/manualLogin.js";
-export { createSaveToSourcesServer, type SourceToolsOptions } from "./core/tools/saveToSources.js";
+export { createSaveToSourcesServer, sourcesPromptSection, type SourceToolsOptions } from "./core/tools/saveToSources.js";
 export { runChatTui, type ChatTuiOptions } from "./tui/chatTui.js";
 export type { SessionOpener } from "./tui/runs.js";
 export { createConsoleRenderer, type ConsoleRenderer, type ConsoleRendererOptions } from "./tui/consoleRenderer.js";

package/dist/index.js

@@ -36,7 +36,7 @@ export { terminalInteractionPort, setSharedReadline, getSharedReadline } from ".
 setInteractionPort(terminalInteractionPort);
 export { createHumanApprovalServer, DEFAULT_HUMAN_APPROVAL_TEXTS } from "./core/tools/humanApproval.js";
 export { createManualLoginServer } from "./core/tools/manualLogin.js";
-export { createSaveToSourcesServer } from "./core/tools/saveToSources.js";
+export { createSaveToSourcesServer, sourcesPromptSection } from "./core/tools/saveToSources.js";
 export { runChatTui } from "./tui/chatTui.js";
 export { createConsoleRenderer } from "./tui/consoleRenderer.js";
 export { runChatInk } from "./tui/ink/runChatInk.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",

package/assets/knowledge-plugin-files/.claude-plugin/plugin.json

@@ -1,4 +0,0 @@
-{
-  "name": "knowledge",
-  "description": "Built-in knowledge base workflows (an LLM wiki): page templates, ingesting sources, querying the knowledge base and health-checking it."
-}

package/assets/knowledge-plugin-files/commands/ingest.md

@@ -1,7 +0,0 @@
----
-description: Ingest material into the knowledge base right now - the files or topic given, or everything in sources/ not ingested yet
----
-
-Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
-
-If nothing is given above, ingest every original `list_sources` reports as new, and update the summaries of the ones it reports as changed. When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin-files/commands/lint.md

@@ -1,5 +0,0 @@
----
-description: Health-check the knowledge base right now - broken links, orphans, duplicates, contradictions, gaps
----
-
-Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (links, index, missing back-links) and report the rest: what needs the human's decision, and the gaps worth filling next.

package/assets/knowledge-plugin-files/commands/query.md

@@ -1,5 +0,0 @@
----
-description: Answer a question from the knowledge base, and file the answer back if it is worth keeping
----
-
-Apply the `knowledge-query` skill right now to answer: $ARGUMENTS

package/assets/knowledge-plugin-files/skills/knowledge-ingest/SKILL.md

@@ -1,46 +0,0 @@
----
-name: knowledge-ingest
-description: Ingest one source into the knowledge base - a file in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, linking everything both ways, and updating index.md and log.md.
----
-
-# Ingesting a source into the knowledge base
-
-A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Ingesting is not summarizing a file in isolation - its value is in how it connects to what the knowledge base already knows. Load the `knowledge-pages` skill first for the page templates.
-
-## 1. Check it isn't already ingested
-
-`list_sources` gives each original's status and summary pages: *new* needs ingesting; *ingested* has a page; *changed* changed after its ingest. For a document from elsewhere, look for it in `index.md` (Summaries) or `Grep` its URL inside the knowledge base. If it already has a page:
-- unchanged source: nothing to do;
-- the source changed or the page is thin: update that page instead of creating another.
-
-## 2. Read it for real
-
-Read the whole source, not its first page (a long PDF in parts: `list_sources` gives its pages). If it exists only outside the sources folder, keep the original first: `download_to_sources` for a URL (a web page is kept as markdown too: read that one), `save_to_sources` for a file in the run's folder, `request_file` to ask the person for one. `Read` reads PDFs and images; read DOCX, PPTX (with its speaker notes) and XLSX with `extract_text`.
-
-## 3. Write the summary page
-
-Create `summaries/<slug>.md` with the template: summary, key points (literal wording where exactness matters), frontmatter `file`/`url` pointing to the original.
-
-## 4. Update concepts and entities
-
-For every concept or entity the source explains or relies on:
-- no page yet: create it;
-- page exists: add what is new (a better definition, an example, a nuance, a fact) with `Edit`, and link the summary under "Sources".
-
-Check first whether it exists under another name (`Grep` the knowledge base for the term and look at `aliases`): a duplicate page is worse than none.
-
-## 5. Link both ways and look for conflicts
-
-Every link you added from page A to page B needs its counterpart in B. If the source contradicts an existing page, record both versions with attribution in both pages - don't overwrite.
-
-## 6. Close
-
-- `index.md`: new pages, and one-line descriptions that changed.
-- `log.md`: `## [date] ingest | <source title>` with the pages created and updated.
-- `overview.md`: only if the source changes the big picture.
-
-When ingesting several sources in a row, do steps 1-5 for each and close once at the end.
-
-## An original that was wrong or replaced
-
-`retire_source` (the person approves it) moves it aside and marks its summary retired (wrong) or superseded (replaced by a better one). Then update `index.md`, and fix the pages that cite it (`Grep` its file name): after a wrong one, correct or remove what it taught; after a replaced one, ingest the new original and re-ground those passages on it.