@falkenslab/agent-kit 0.15.0 → 0.16.0

package/dist/core/tools/knowledgeTools.js

@@ -0,0 +1,161 @@
+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";
+/**
+ * The `knowledge_*` tools: the only way the agent reaches the built-in knowledge base
+ * (ADR-024). They work on pages by id (`concept/bowline`) over a `KnowledgeStore`, never on
+ * files, so the storage can change underneath; the store keeps the index and the backlinks.
+ */
+const ok = (text) => ({ content: [{ type: "text", text }] });
+const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+const message = (error) => (error instanceof Error ? error.message : String(error));
+/** Runs a tool's work, turning a thrown error into an answer the model can act on. */
+async function attempt(work) {
+    try {
+        return ok(await work());
+    }
+    catch (error) {
+        return fail(message(error));
+    }
+}
+const OVERVIEW = "overview";
+/** The `knowledge` MCP server over `store`. */
+export function createKnowledgeServer(store, options) {
+    const typeNames = store.types().map((t) => t.type);
+    // A list of pairs, not z.record(): a record in a tool's schema makes the SDK drop every
+    // tool of the server, silently (confirmed empirically).
+    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/');
+    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);
+        return hits.length ? hits.map((hit) => `- ${hit.id} — ${hit.title}: ${hit.snippet}`).join("\n") : "No page matches.";
+    }), { annotations: { readOnlyHint: true } });
+    const read = tool("knowledge_read", 'A page by its id ("concept/bowline"), or "overview": its fields, its content (links to other pages as ids) and the pages that link to it.', { page: z.string().describe('The page id, or "overview"') }, async (args) => attempt(async () => {
+        if (args.page === OVERVIEW)
+            return (await store.overview()) || "There's no overview yet: write it with knowledge_rewrite (page \"overview\").";
+        const page = await store.read(args.page);
+        if (!page)
+            throw new Error(`There's no page "${args.page}". knowledge_search or knowledge_index finds the right one.`);
+        const fieldLines = Object.entries(page.fields).map(([key, value]) => `${key}: ${value}`);
+        return [`id: ${page.id}`, `title: ${page.title}`, ...fieldLines, `linked from: ${page.linkedFrom.join(", ") || "(nothing)"}`, "", page.content].join("\n");
+    }), { annotations: { readOnlyHint: true } });
+    const create = tool("knowledge_create", `Create a page. Types: ${store
+        .types()
+        .map((type) => `${type.type} (${type.description})`)
+        .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"),
+        content: z.string().optional().describe("The page's markdown body (under its title), following the type's template"),
+        fields,
+        also: z
+            .array(z.object({
+            type: z.enum(typeNames),
+            slug: z.string(),
+            title: z.string(),
+            content: z.string(),
+            fields,
+        }))
+            .optional()
+            .describe("More pages to create in the same call, which may link to each other and to this one (a summary and the new concepts it feeds): all are created, or none"),
+    }, 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.`;
+        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) })),
+        ]);
+        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);
+        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);
+            return "Rewrote the overview.";
+        }
+        await store.rewrite(args.page, args.content, changes(args.fields));
+        await ingested(args.page);
+        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 page = await store.read(args.page);
+        if (!page)
+            throw new Error(`There's no page "${args.page}".`);
+        const answer = await askForDecision(options.runDir, { title: t().retirePageTitle, lines: [`${page.title} (${page.id})`, args.reason] });
+        if (answer === "q")
+            return "The person stopped: don't retire it, and stop what you were doing.";
+        if (answer !== "" && answer !== "y" && answer !== "yes")
+            return "The person said no: the page stays.";
+        await store.retire(args.page, args.reason);
+        return `Retired ${args.page}. Now fix the pages that link to it (knowledge_check).`;
+    }));
+    const log = tool("knowledge_log", "Add an entry to the knowledge base's log, dated today: once an operation is done (an ingest, a query filed back, a lint, an update), what it was and the pages it touched.", {
+        operation: z.string().describe('"ingest", "query", "lint" or "update"'),
+        what: z.string().describe("What, in one line"),
+        pages: z.array(z.string()).optional().describe("The ids of the pages created or changed"),
+    }, async (args) => attempt(async () => {
+        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 } });
+    return createSdkMcpServer({
+        name: "knowledge",
+        version: "1.0.0",
+        tools: [index, search, read, create, edit, rewrite, supersede, ...(options.interactive ? [retire] : []), log, check],
+    });
+}

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

@@ -1,10 +1,29 @@
+/** The most `download_to_sources` and `request_file` copy in. */
+export declare const MAX_SOURCE_BYTES: number;
 /**
- * `save_to_sources`: the only way the agent adds to `sourcesDir` (Write/Edit are scoped
- * to the notes folder, see hooks/fileScopeGate.ts), so the originals stay as obtained.
- * Deliberately just an fs.copyFile with COPYFILE_EXCL — no parsing, no format conversion,
- * no overwriting. A document downloaded via a browser-automation tool typically lands in
- * this run's own folder, which the file tools can't reach; this tool's only job is getting
- * it into `sourcesDir`, where the SDK's own Read tool already knows how to interpret it
- * (PDF/DOCX text extraction, multimodal images).
+ * The main content of a web page as markdown, with the optional libraries
+ * (`@mozilla/readability`, `linkedom`, `turndown`); null when they aren't installed or the
+ * page has no readable content.
  */
-export declare function createSaveToSourcesServer(runDir: string, sourcesDir: string, description?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+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>;
+/** 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. */
+    interactive?: boolean;
+    /** The most `download_to_sources` and `request_file` copy in; 50 MB by default. */
+    maxBytes?: number;
+}
+/**
+ * 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`,
+ * `list_sources` and `download_to_sources`, plus `request_file` and `retire_source` when a
+ * person can be asked. Nothing is ever overwritten or deleted; the bookkeeping is in
+ * sources.ts.
+ */
+export declare function createSaveToSourcesServer(runDir: string, sourcesDir: string, description?: string, options?: SourceToolsOptions): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/core/tools/saveToSources.js

@@ -1,13 +1,11 @@
 import path from "node:path";
-import { constants, copyFile, mkdir, readdir, stat } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
-/** Resolves `candidate` against `base`; returns the absolute path only if it stays inside it. */
-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;
-}
+import { addSource, listSources, resolveWithin, retireSource } from "../sources.js";
+import { askForDecision, askForText } from "../hooks/humanInput.js";
+import { t } from "../messages/index.js";
+import { EXTRACTABLE, extractText } from "../extractText.js";
 /**
  * `resolvedPath` as given if it exists; otherwise, a same-directory sibling whose
  * filename is Unicode-equal under NFC normalization. Needed because a file downloaded via
@@ -37,69 +35,219 @@ async function resolveExistingFileToleratingNormalization(resolvedPath) {
     const match = entries.find((name) => name.normalize("NFC") === wantName);
     return match ? path.join(dir, match) : undefined;
 }
+// Confirmed empirically: the SDK's Read tool reads PDFs and images, but refuses DOCX and
+// PPTX ("This tool cannot read binary files").
 const DEFAULT_DESCRIPTION = "Copy a file from this run's own folder (e.g. something just downloaded) into a folder " +
     "under sources/, where original files are kept as they were obtained, apart from your " +
-    "own notes. It becomes readable there with the SDK's own Read tool, which already " +
-    "extracts text from PDF/DOCX and interprets images directly. This tool does no parsing " +
-    "or conversion itself, it only relocates the file, and it never overwrites a file " +
-    "that's already in sources/. Use it right after downloading a document you're about to " +
-    "study in depth, so it's still there for later sessions instead of only existing for " +
-    "this run.";
+    "own notes. Read reads PDFs and images there; DOCX, PPTX and XLSX are read with extract_text. This tool does " +
+    "no conversion, never overwrites a file already in sources/, and doesn't copy a file " +
+    "identical to one already there (it returns that one's path). For a new version of an " +
+    "original, save it under a new name with `replaces` set to the old one. Use it right after " +
+    "downloading a document you're about to study in depth, so later sessions have it too.";
+/** The most `download_to_sources` and `request_file` copy in. */
+export const MAX_SOURCE_BYTES = 50 * 1024 * 1024;
+const ok = (text) => ({ content: [{ type: "text", text }] });
+const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+const message = (error) => (error instanceof Error ? error.message : String(error));
+function added(result, extra = "") {
+    return result.duplicateOf
+        ? `An identical file is already in sources/${result.duplicateOf}: nothing was copied. Use that one.`
+        : `Saved to sources/${result.path}.${extra}`;
+}
+/**
+ * The main content of a web page as markdown, with the optional libraries
+ * (`@mozilla/readability`, `linkedom`, `turndown`); null when they aren't installed or the
+ * page has no readable content.
+ */
+export async function htmlToMarkdown(html, url) {
+    try {
+        const [{ Readability }, { parseHTML }, { default: TurndownService }] = await Promise.all([
+            import("@mozilla/readability"),
+            import("linkedom"),
+            import("turndown"),
+        ]);
+        const { document } = parseHTML(html);
+        const article = new Readability(document).parse();
+        if (!article?.content)
+            return null;
+        const markdown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" }).turndown(article.content);
+        return `# ${article.title ?? url}\n\nSource: ${url}\n\n${markdown}\n`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Downloads `url` into `file`, refusing other schemes and anything over `maxBytes`; returns its content type. */
+export async function downloadToFile(url, file, maxBytes) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`"${url}" isn't a URL.`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        throw new Error(`Only http and https URLs can be downloaded, not "${parsed.protocol}".`);
+    const response = await fetch(parsed, { redirect: "follow" });
+    if (!response.ok || !response.body)
+        throw new Error(`The download failed: HTTP ${response.status}.`);
+    const declared = Number(response.headers.get("content-length") ?? 0);
+    if (declared > maxBytes)
+        throw new Error(`The file is ${declared} bytes, over the ${maxBytes}-byte limit.`);
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+        size += chunk.byteLength;
+        if (size > maxBytes)
+            throw new Error(`The file is over the ${maxBytes}-byte limit.`);
+        chunks.push(chunk);
+    }
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, Buffer.concat(chunks));
+    return response.headers.get("content-type") ?? "";
+}
 /**
- * `save_to_sources`: the only way the agent adds to `sourcesDir` (Write/Edit are scoped
- * to the notes folder, see hooks/fileScopeGate.ts), so the originals stay as obtained.
- * Deliberately just an fs.copyFile with COPYFILE_EXCL — no parsing, no format conversion,
- * no overwriting. A document downloaded via a browser-automation tool typically lands in
- * this run's own folder, which the file tools can't reach; this tool's only job is getting
- * it into `sourcesDir`, where the SDK's own Read tool already knows how to interpret it
- * (PDF/DOCX text extraction, multimodal images).
+ * 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`,
+ * `list_sources` and `download_to_sources`, plus `request_file` and `retire_source` when a
+ * person can be asked. Nothing is ever overwritten or deleted; the bookkeeping is in
+ * sources.ts.
  */
-export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFAULT_DESCRIPTION) {
+export function createSaveToSourcesServer(runDir, sourcesDir, description = DEFAULT_DESCRIPTION, options = {}) {
+    const projectDir = options.projectDir ?? path.dirname(sourcesDir);
+    const maxBytes = options.maxBytes ?? MAX_SOURCE_BYTES;
+    const replaces = z.string().optional().describe("For a new version: the original it replaces, relative to sources/ (kept, never overwritten)");
     const saveToSources = tool("save_to_sources", description, {
         source: z.string().describe("Path to the file, relative to this run's own folder - not a URL"),
-        destination: z.string().describe('Path to save it under, relative to sources/, e.g. "topic-3/slides.pdf"'),
+        destination: z.string().describe('Path to save it under, relative to sources/, e.g. "topic-3/slides.pdf" (a folder, "topic-3/", keeps its own name)'),
+        replaces,
     }, async (args) => {
         const candidate = resolveWithin(runDir, args.source);
-        if (!candidate) {
-            return {
-                content: [{ type: "text", text: `"${args.source}" isn't inside this run's folder - refusing to read it.` }],
-                isError: true,
-            };
-        }
+        if (!candidate)
+            return fail(`"${args.source}" isn't inside this run's folder - refusing to read it.`);
         const resolvedSource = await resolveExistingFileToleratingNormalization(candidate);
         if (!resolvedSource) {
-            return {
-                content: [{ type: "text", text: `Couldn't find "${args.source}" in this run's folder (checked byte-for-byte and Unicode-normalized names) - double check the exact path, e.g. with Glob.` }],
-                isError: true,
-            };
+            return fail(`Couldn't find "${args.source}" in this run's folder (checked byte-for-byte and Unicode-normalized names) - double check the exact path, e.g. with Glob.`);
+        }
+        try {
+            const relative = path.relative(runDir, resolvedSource).split(path.sep).join("/");
+            return ok(added(await addSource(sourcesDir, resolvedSource, args.destination, { kind: "run", from: relative }, { replaces: args.replaces })));
+        }
+        catch (error) {
+            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 () => {
+        try {
+            return ok(JSON.stringify(await listSources(sourcesDir, options.knowledgeDir, projectDir), null, 2));
+        }
+        catch (error) {
+            return fail(message(error));
+        }
+    }, { annotations: { readOnlyHint: true } });
+    const extractTextTool = tool("extract_text", "Read a Word (DOCX), PowerPoint (PPTX) or Excel (XLSX) original in sources/ as markdown, which Read can't: a document's headings, paragraphs, lists and tables; a deck's slides with their speaker notes (`from`/`to` pick slides of a long one; list_sources gives the count); a workbook's sheets as tables. Images are left out.", {
+        source: z.string().describe("The original, relative to sources/"),
+        from: z.number().int().positive().optional().describe("First slide (PPTX)"),
+        to: z.number().int().positive().optional().describe("Last slide (PPTX)"),
+    }, async (args) => {
+        const file = resolveWithin(sourcesDir, args.source);
+        if (!file || !(await stat(file).catch(() => null))?.isFile())
+            return fail(`"${args.source}" isn't an original in sources/ (list_sources lists them).`);
+        if (!EXTRACTABLE.has(path.extname(file).slice(1).toLowerCase()))
+            return fail(`extract_text reads DOCX, PPTX and XLSX; read "${args.source}" with Read.`);
+        try {
+            return ok(await extractText(file, args.from, args.to));
+        }
+        catch (error) {
+            return fail(message(error));
+        }
+    }, { annotations: { readOnlyHint: true } });
+    const downloadToSources = tool("download_to_sources", `Download an original (a PDF, an image, a web page...) from an http(s) URL straight into sources/, without its content going through your context; up to ${Math.round(maxBytes / 1024 / 1024)} MB, never overwriting, and not at all if an identical file is already there. A web page is also kept as its main content in markdown next to it (when the kit's optional libraries are installed), to quote literally and read again: WebFetch only gives a summary.`, {
+        url: z.string().describe("The http or https URL"),
+        destination: z.string().describe('Path to save it under, relative to sources/, e.g. "topic-3/syllabus.pdf" or "web/rules.html"'),
+        replaces,
+    }, async (args) => {
+        const temp = path.join(runDir, "downloads", `${Date.now()}-${path.basename(args.destination)}`);
+        try {
+            const type = await downloadToFile(args.url, temp, maxBytes);
+            const name = decodeURIComponent(new URL(args.url).pathname.split("/").filter(Boolean).pop() ?? "download");
+            const result = await addSource(sourcesDir, temp, args.destination, { kind: "url", from: args.url }, { replaces: args.replaces, name });
+            let extra = "";
+            if (!result.duplicateOf && /html/i.test(type)) {
+                const html = await readFile(temp, "utf8");
+                const markdown = await htmlToMarkdown(html, args.url);
+                if (markdown) {
+                    const mdTemp = `${temp}.md`;
+                    await writeFile(mdTemp, markdown);
+                    const mdDestination = result.path.replace(/\.[^./]+$/, "") + ".md";
+                    try {
+                        const md = await addSource(sourcesDir, mdTemp, mdDestination, { kind: "url", from: args.url }, { derivedFrom: result.path });
+                        extra = md.duplicateOf ? "" : ` Its main content is in sources/${md.path}: read that one.`;
+                    }
+                    catch (error) {
+                        extra = ` (Its markdown wasn't kept: ${message(error)})`;
+                    }
+                }
+                else {
+                    extra = " (No markdown copy: the page had no readable content, or the kit's optional libraries for it aren't installed.)";
+                }
+            }
+            return ok(added(result, extra));
         }
-        const resolvedDestination = resolveWithin(sourcesDir, args.destination);
-        if (!resolvedDestination) {
-            return {
-                content: [{ type: "text", text: `"${args.destination}" isn't inside sources/ - refusing to write there.` }],
-                isError: true,
-            };
+        catch (error) {
+            return fail(message(error));
+        }
+        finally {
+            await rm(temp, { force: true });
+            await rm(`${temp}.md`, { force: true });
         }
+    });
+    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"),
+        destination: z.string().optional().describe("Path to save it under, relative to sources/; the file's own name if omitted"),
+        replaces,
+    }, async (args) => {
+        const answer = (await askForText(runDir, { title: t().fileRequestTitle, lines: [args.description], question: t().fileRequestQuestion })).replace(/^["']|["']$/g, "").trim();
+        if (!answer)
+            return ok("The person doesn't have that file (or didn't give one). Go on without it, or ask for something else.");
+        const file = path.resolve(answer);
+        const info = await stat(file).catch(() => null);
+        if (!info?.isFile())
+            return fail(`"${answer}" isn't a file the person has here. Ask again if needed.`);
+        if (info.size > maxBytes)
+            return fail(`"${answer}" is ${info.size} bytes, over the ${maxBytes}-byte limit.`);
         try {
-            await mkdir(path.dirname(resolvedDestination), { recursive: true });
-            await copyFile(resolvedSource, resolvedDestination, constants.COPYFILE_EXCL);
+            return ok(added(await addSource(sourcesDir, file, args.destination ?? path.basename(file), { kind: "person", from: path.basename(file) }, { replaces: args.replaces })));
         }
         catch (error) {
-            const exists = error.code === "EEXIST";
-            return {
-                content: [{
-                        type: "text",
-                        text: exists
-                            ? `"${args.destination}" already exists in sources/ - originals are never overwritten; pick another destination name.`
-                            : `Couldn't copy "${args.source}" to sources/: ${error instanceof Error ? error.message : String(error)}`,
-                    }],
-                isError: true,
-            };
+            return fail(message(error));
         }
-        const savedAs = path.relative(sourcesDir, resolvedDestination).split(path.sep).join("/");
-        return {
-            content: [{ type: "text", text: `Saved to sources/${savedAs} - read it from there with Read.` }],
-        };
     });
-    return createSdkMcpServer({ name: "sourceFiles", version: "1.0.0", tools: [saveToSources] });
+    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.', {
+        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"),
+        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(args.source, args.why, args.reason, args.replacedBy) });
+        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, args.source, args.why, args.reason, 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"));
+        }
+        catch (error) {
+            return fail(message(error));
+        }
+    });
+    return createSdkMcpServer({
+        name: "sourceFiles",
+        version: "1.0.0",
+        tools: [saveToSources, listSourcesTool, extractTextTool, downloadToSources, ...(options.interactive ? [requestFile, retire] : [])],
+    });
 }

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

@@ -0,0 +1,29 @@
+/** "now" in `timeZone`, as calendar parts. */
+export declare function nowIn(timeZone: string, now?: Date): {
+    date: string;
+    time: string;
+    weekday: string;
+    timeZone: string;
+    utcOffset: string;
+    utc: string;
+};
+/** Days, weeks and working days (Monday to Friday) from `from` to `to`; negative when `to` is earlier. */
+export declare function dateDifference(from: string, to: string): {
+    from: string;
+    to: string;
+    days: number;
+    weeks: number;
+    remainderDays: number;
+    workingDays: number;
+    toWeekday: string;
+};
+export type DateUnit = "days" | "weeks" | "months" | "working_days";
+/** `date` plus `amount` (negative to go back) `unit`s; months keep the day, or the month's last one. */
+export declare function dateAdd(date: string, amount: number, unit: DateUnit): {
+    date: string;
+    weekday: string;
+};
+/** The time zone the tools answer in: `timeZone` if valid, otherwise the system's. */
+export declare function resolveTimeZone(timeZone?: string): string;
+/** `current_time` and `date_math`, in `timeZone` (an IANA name; the system's if not given). */
+export declare function createTimeServer(timeZone?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;