@falkenslab/agent-kit 0.14.0 → 0.16.0

package/dist/core/todos.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The SDK's `TodoWrite` tool: the model keeps a task list on long jobs, sending the whole
+ * list with every call (confirmed empirically: an `action` event whose input is
+ * `{ todos: [{ content, status, activeForm }] }`, and a result that only says it was saved).
+ * The chats show the list instead of the calls.
+ */
+export type TodoStatus = "pending" | "in_progress" | "completed";
+/** One task: what to do, in the imperative ("Prepare the slides"), and while it's done ("Preparing the slides"). */
+export interface Todo {
+    content: string;
+    status: TodoStatus;
+    activeForm: string;
+}
+export declare const TODO_TOOL = "TodoWrite";
+/** The list in a `TodoWrite` call's input, or `null` if it isn't one. */
+export declare function parseTodos(input: unknown): Todo[] | null;
+/** Whether any task is still to do. */
+export declare function hasOpenTodos(todos: readonly Todo[] | null): boolean;
+/** The tasks that started and the ones finished from `before` to `after`, matched by their text. */
+export declare function todoChanges(before: readonly Todo[], after: readonly Todo[]): {
+    started: Todo[];
+    completed: Todo[];
+};

package/dist/core/todos.js

@@ -0,0 +1,33 @@
+/**
+ * The SDK's `TodoWrite` tool: the model keeps a task list on long jobs, sending the whole
+ * list with every call (confirmed empirically: an `action` event whose input is
+ * `{ todos: [{ content, status, activeForm }] }`, and a result that only says it was saved).
+ * The chats show the list instead of the calls.
+ */
+export const TODO_TOOL = "TodoWrite";
+const STATUSES = new Set(["pending", "in_progress", "completed"]);
+/** The list in a `TodoWrite` call's input, or `null` if it isn't one. */
+export function parseTodos(input) {
+    const todos = input?.todos;
+    if (!Array.isArray(todos))
+        return null;
+    return todos
+        .filter((todo) => Boolean(todo) && typeof todo === "object")
+        .map((todo) => ({
+        content: String(todo.content ?? ""),
+        status: (STATUSES.has(String(todo.status)) ? todo.status : "pending"),
+        activeForm: String(todo.activeForm ?? todo.content ?? ""),
+    }));
+}
+/** Whether any task is still to do. */
+export function hasOpenTodos(todos) {
+    return Boolean(todos?.some((todo) => todo.status !== "completed"));
+}
+/** The tasks that started and the ones finished from `before` to `after`, matched by their text. */
+export function todoChanges(before, after) {
+    const previous = new Map(before.map((todo) => [todo.content, todo.status]));
+    return {
+        started: after.filter((todo) => todo.status === "in_progress" && previous.get(todo.content) !== "in_progress"),
+        completed: after.filter((todo) => todo.status === "completed" && previous.get(todo.content) !== "completed"),
+    };
+}

package/dist/core/toolLabels.d.ts

@@ -21,7 +21,7 @@ export type ToolDescriber = (shortName: string, input: Record<string, unknown>)
  * Builds a `friendlyToolLabel(toolName, toolInput)` — `describe` lets the host agent
  * layer its own domain-specific cases (e.g. Playwright's browser_* tools) on top of this
  * kit's generic ones; `extraLocalServers` names any *additional* MCP server (beyond this
- * kit's own "approvals"/"manualLogin"/"sourceFiles") whose tools should be unwrapped
+ * kit's own "approvals"/"manualLogin"/"sourceFiles"/"time") whose tools should be unwrapped
  * without a "[server] " prefix, e.g. "playwright".
  */
 export declare function createFriendlyToolLabel(options?: {

package/dist/core/toolLabels.js

@@ -27,8 +27,46 @@ function describeCore(shortName, input) {
     switch (shortName) {
         case "request_human_approval":
             return labels.askingApproval(truncate(text(input.summary, ""), 120));
+        case "ask_human":
+            return labels.askingHuman(truncate(text(input.question, ""), 100));
+        case "present_plan":
+            return labels.presentingPlan;
         case "request_manual_login":
             return labels.waitingManual;
+        case "current_time":
+            return labels.checkingTime;
+        case "date_math":
+            return labels.calculatingDates;
+        case "knowledge_index":
+            return labels.knowledgeIndex;
+        case "knowledge_search":
+            return labels.knowledgeSearch(truncate(text(input.query, ""), 60));
+        case "knowledge_read":
+            return labels.knowledgeRead(text(input.page, labels.aPage));
+        case "knowledge_create":
+            return labels.knowledgeCreate(`${text(input.type, "")}/${text(input.slug, "")}`);
+        case "knowledge_edit":
+            return labels.knowledgeEdit(text(input.page, labels.aPage));
+        case "knowledge_rewrite":
+            return labels.knowledgeRewrite(text(input.page, labels.aPage));
+        case "knowledge_supersede":
+            return labels.knowledgeSupersede(text(input.page, labels.aPage));
+        case "knowledge_retire":
+            return labels.knowledgeRetire(text(input.page, labels.aPage));
+        case "knowledge_log":
+            return labels.knowledgeLog;
+        case "knowledge_check":
+            return labels.knowledgeCheck;
+        case "list_sources":
+            return labels.listingSources;
+        case "extract_text":
+            return labels.extractingText(truncatePath(text(input.source, labels.aFile), 70));
+        case "download_to_sources":
+            return labels.downloading(truncate(text(input.url, labels.aPage), 80));
+        case "request_file":
+            return labels.requestingFile(truncate(text(input.description, ""), 100));
+        case "retire_source":
+            return labels.retiringSource(truncatePath(text(input.source, ""), 70));
         case "save_to_sources":
             return labels.savingToSources(truncatePath(text(input.destination, ""), 70));
         case "Read":
@@ -59,6 +97,8 @@ function describeCore(shortName, input) {
         // explicitly in `tools`). Confirmed empirically: its input is `{ skill: "name" }`.
         case "Skill":
             return labels.applyingSkill(text(input.skill, labels.aSkill));
+        case "TodoWrite":
+            return labels.updatingTasks;
         default:
             return undefined;
     }
@@ -67,11 +107,11 @@ function describeCore(shortName, input) {
  * Builds a `friendlyToolLabel(toolName, toolInput)` — `describe` lets the host agent
  * layer its own domain-specific cases (e.g. Playwright's browser_* tools) on top of this
  * kit's generic ones; `extraLocalServers` names any *additional* MCP server (beyond this
- * kit's own "approvals"/"manualLogin"/"sourceFiles") whose tools should be unwrapped
+ * kit's own "approvals"/"manualLogin"/"sourceFiles"/"time") whose tools should be unwrapped
  * without a "[server] " prefix, e.g. "playwright".
  */
 export function createFriendlyToolLabel(options = {}) {
-    const localServers = new Set(["approvals", "manualLogin", "sourceFiles", ...(options.extraLocalServers ?? [])]);
+    const localServers = new Set(["approvals", "manualLogin", "sourceFiles", "time", "knowledge", ...(options.extraLocalServers ?? [])]);
     const describe = (shortName, input) => options.describe?.(shortName, input) ?? describeCore(shortName, input) ?? shortName.replace(/_/g, " ");
     return (toolName, toolInput) => {
         const input = toolInput && typeof toolInput === "object" ? toolInput : {};

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

@@ -1,3 +1,4 @@
+import { type ModeControl } from "../modeControl.js";
 /** The approval tool's texts: its description (when the model should call it) and what it returns when approved or rejected. */
 export interface HumanApprovalTexts {
     description: string;
@@ -7,9 +8,12 @@ export interface HumanApprovalTexts {
 /** Domain-neutral defaults — a concrete agent should normally override these via `AgentSpec.humanApprovalTexts` with wording specific to what "publishing" means in its domain. */
 export declare const DEFAULT_HUMAN_APPROVAL_TEXTS: HumanApprovalTexts;
 /**
- * Checkpoint tool for "guided" mode: the agent explores freely, but
- * must call this tool and wait for human approval right before any action that publishes
- * something visible to others and that's hard to naturally undo. Everything else —
- * browsing and reading — doesn't go through this.
+ * The tools that ask the person, in every mode but autonomous: `request_human_approval`
+ * (right before an action that publishes something visible to others and that's hard to
+ * undo), `ask_human` (a choice between options, in a panel, within the turn) and, when the
+ * session can be in plan mode (`modeControl`), `present_plan`, the kit's own way out of plan
+ * mode (ADR-023): the person runs the plan, keeps planning or cancels.
  */
-export declare function createHumanApprovalServer(runDir: string, texts?: HumanApprovalTexts): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+export declare function createHumanApprovalServer(runDir: string, texts?: HumanApprovalTexts, options?: {
+    modeControl?: ModeControl;
+}): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/core/tools/humanApproval.js

@@ -1,7 +1,8 @@
 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
-import { askForDecision } from "../hooks/humanInput.js";
+import { askForChoice, askForDecision, askForText } from "../hooks/humanInput.js";
 import { t } from "../messages/index.js";
+import { togglePlanMode } from "../modeControl.js";
 const APPROVED_ANSWERS = new Set(["", "y", "yes"]);
 /** Domain-neutral defaults — a concrete agent should normally override these via `AgentSpec.humanApprovalTexts` with wording specific to what "publishing" means in its domain. */
 export const DEFAULT_HUMAN_APPROVAL_TEXTS = {
@@ -11,13 +12,15 @@ export const DEFAULT_HUMAN_APPROVAL_TEXTS = {
     approved: "Approved by the human. You may continue.",
     rejected: "Rejected by the human. Don't proceed with that; ask what to do differently.",
 };
+const ok = (text) => ({ content: [{ type: "text", text }] });
 /**
- * Checkpoint tool for "guided" mode: the agent explores freely, but
- * must call this tool and wait for human approval right before any action that publishes
- * something visible to others and that's hard to naturally undo. Everything else —
- * browsing and reading — doesn't go through this.
+ * The tools that ask the person, in every mode but autonomous: `request_human_approval`
+ * (right before an action that publishes something visible to others and that's hard to
+ * undo), `ask_human` (a choice between options, in a panel, within the turn) and, when the
+ * session can be in plan mode (`modeControl`), `present_plan`, the kit's own way out of plan
+ * mode (ADR-023): the person runs the plan, keeps planning or cancels.
  */
-export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL_TEXTS) {
+export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL_TEXTS, options = {}) {
     const requestHumanApproval = tool("request_human_approval", texts.description, {
         summary: z.string().describe("Brief summary of what you're about to submit or publish"),
     }, async (args) => {
@@ -30,9 +33,38 @@ export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL
             content: [{ type: "text", text: approved ? texts.approved : texts.rejected }],
         };
     });
+    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)"),
+        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);
+        const parts = [
+            ...(answer.chosen.length ? [`The person chose: ${answer.chosen.join("; ")}.`] : []),
+            ...(answer.other ? [`Their own answer: ${answer.other}`] : []),
+        ];
+        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) => {
+        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];
+        const answer = await askForChoice(runDir, { title: t().planTitle, lines: args.plan.split("\n"), markdown: true }, choices);
+        const picked = answer.chosen[0];
+        if (picked === t().runPlan) {
+            const mode = togglePlanMode(control) ?? control.mode;
+            control.takeNotice?.(); // told here, not again with the next message
+            return ok(`The person approved the plan. Plan mode is off (now ${mode} mode): carry the plan out now, step by step.${answer.other ? ` They added: ${answer.other}` : ""}`);
+        }
+        if (picked === t().cancelPlan)
+            return ok("The person cancelled the plan. Stop, and ask them what they want instead.");
+        const comment = answer.other ?? (await askForText(runDir, { title: t().planTitle, lines: [], question: t().planCommentQuestion }));
+        return ok(`The person wants to keep planning${comment ? `: ${comment}` : ""}. You're still in plan mode: revise the plan and present it again.`);
+    });
     return createSdkMcpServer({
         name: "approvals",
         version: "1.0.0",
-        tools: [requestHumanApproval],
+        tools: [requestHumanApproval, askHuman, ...(control?.switchable.includes("plan") ? [presentPlan] : [])],
     });
 }

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

@@ -0,0 +1,16 @@
+import type { KnowledgeStore } from "../knowledgeStore.js";
+/** 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

@@ -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;