@falkenslab/agent-kit 0.14.0 → 0.16.0

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;

package/dist/core/tools/time.js

@@ -0,0 +1,129 @@
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+/**
+ * The date and time, and date arithmetic, for every agent: the kit puts no date in the
+ * prompt and only subagents have Bash, so without these an agent can't know what day it
+ * is, and models get "days until" and "three weeks from" wrong often enough to matter
+ * (deadlines, a course's calendar). Only reads: the plan gate lets the server through.
+ */
+const DAY_MS = 86_400_000;
+const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** "now" in `timeZone`, as calendar parts. */
+export function nowIn(timeZone, now = new Date()) {
+    const parts = Object.fromEntries(new Intl.DateTimeFormat("en-CA", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+        timeZoneName: "longOffset",
+    })
+        .formatToParts(now)
+        .map((part) => [part.type, part.value]));
+    const date = `${parts.year}-${parts.month}-${parts.day}`;
+    return {
+        date,
+        time: `${parts.hour}:${parts.minute}:${parts.second}`,
+        weekday: WEEKDAYS[toDay(date).getUTCDay()],
+        timeZone,
+        utcOffset: parts.timeZoneName.replace("GMT", "") || "+00:00",
+        utc: now.toISOString(),
+    };
+}
+/** A YYYY-MM-DD calendar date as midnight UTC, so arithmetic never meets daylight saving. */
+function toDay(date) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    if (!match)
+        throw new Error(`"${date}" isn't a date in YYYY-MM-DD form.`);
+    const day = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+    if (day.toISOString().slice(0, 10) !== date)
+        throw new Error(`"${date}" isn't a real date.`);
+    return day;
+}
+const fromDay = (day) => day.toISOString().slice(0, 10);
+const isWorkingDay = (day) => day.getUTCDay() !== 0 && day.getUTCDay() !== 6;
+/** Days, weeks and working days (Monday to Friday) from `from` to `to`; negative when `to` is earlier. */
+export function dateDifference(from, to) {
+    const start = toDay(from);
+    const end = toDay(to);
+    const days = Math.round((end.getTime() - start.getTime()) / DAY_MS);
+    // Working days counted from the day after the earlier date up to the later one included, as
+    // "in N working days"; the same count, negative, when `to` is earlier.
+    const [first, last] = days < 0 ? [end, start] : [start, end];
+    let workingDays = 0;
+    for (let day = first.getTime() + DAY_MS; day <= last.getTime(); day += DAY_MS)
+        if (isWorkingDay(new Date(day)))
+            workingDays++;
+    return { from, to, days, weeks: Math.trunc(days / 7), remainderDays: days % 7, workingDays: days < 0 ? -workingDays : workingDays, toWeekday: WEEKDAYS[end.getUTCDay()] };
+}
+/** `date` plus `amount` (negative to go back) `unit`s; months keep the day, or the month's last one. */
+export function dateAdd(date, amount, unit) {
+    if (!Number.isInteger(amount))
+        throw new Error("The amount must be a whole number.");
+    const start = toDay(date);
+    let result;
+    if (unit === "days" || unit === "weeks") {
+        result = new Date(start.getTime() + amount * (unit === "weeks" ? 7 : 1) * DAY_MS);
+    }
+    else if (unit === "months") {
+        const target = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + amount, 1));
+        const lastDay = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+        result = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth(), Math.min(start.getUTCDate(), lastDay)));
+    }
+    else {
+        result = start;
+        const step = Math.sign(amount);
+        for (let left = Math.abs(amount); left > 0;) {
+            result = new Date(result.getTime() + step * DAY_MS);
+            if (isWorkingDay(result))
+                left--;
+        }
+    }
+    return { date: fromDay(result), weekday: WEEKDAYS[result.getUTCDay()] };
+}
+const text = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] });
+const failure = (error) => ({ content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true });
+/** The time zone the tools answer in: `timeZone` if valid, otherwise the system's. */
+export function resolveTimeZone(timeZone) {
+    const system = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (!timeZone)
+        return system;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone });
+        return timeZone;
+    }
+    catch {
+        throw new Error(`Unknown time zone "${timeZone}" (an IANA name, e.g. "Europe/Madrid").`);
+    }
+}
+/** `current_time` and `date_math`, in `timeZone` (an IANA name; the system's if not given). */
+export function createTimeServer(timeZone) {
+    const zone = resolveTimeZone(timeZone);
+    const currentTime = tool("current_time", "The current date and time: the local date (YYYY-MM-DD), time, weekday, time zone and UTC offset, and the instant in UTC. Use it whenever you need today's date or the time; don't guess them.", {}, async () => text(nowIn(zone)), { annotations: { readOnlyHint: true } });
+    const dateMath = tool("date_math", 'Exact date arithmetic on calendar dates (YYYY-MM-DD, local). "difference": days, weeks and working days (Monday to Friday) from `from` to `to`. "add": `from` plus `amount` (negative to go back) days, weeks, months or working days. `from` defaults to today. Use it instead of counting dates yourself.', {
+        operation: z.enum(["difference", "add"]),
+        from: z.string().optional().describe("Start date, YYYY-MM-DD; today if omitted"),
+        to: z.string().optional().describe('End date, YYYY-MM-DD (for "difference")'),
+        amount: z.number().int().optional().describe('How many units to add, negative to subtract (for "add")'),
+        unit: z.enum(["days", "weeks", "months", "working_days"]).optional().describe('The unit of `amount` (for "add"); days if omitted'),
+    }, async (args) => {
+        try {
+            const from = args.from ?? nowIn(zone).date;
+            if (args.operation === "difference") {
+                if (!args.to)
+                    throw new Error('"difference" needs `to`.');
+                return text(dateDifference(from, args.to));
+            }
+            if (args.amount === undefined)
+                throw new Error('"add" needs `amount`.');
+            return text({ from, ...dateAdd(from, args.amount, args.unit ?? "days") });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    }, { annotations: { readOnlyHint: true } });
+    return createSdkMcpServer({ name: "time", version: "1.0.0", tools: [currentTime, dateMath] });
+}

package/dist/index.d.ts

@@ -10,6 +10,9 @@ export type { Mode, BaseSessionConfig, AgentSpec, PlanModeSpec } from "./core/ag
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode, type ModeControl } from "./core/session.js";
 export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
+export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, type KnowledgeStore, type PageType, type KnowledgePage, type PageInfo, type SearchHit, type CheckReport, type FieldChanges, type NewPage, } from "./core/knowledgeStore.js";
+export { createFileKnowledgeStore, type FileKnowledgeStoreOptions } from "./core/fileKnowledgeStore.js";
+export { createKnowledgeServer, type KnowledgeToolsOptions } from "./core/tools/knowledgeTools.js";
 export { resolveLanguage, detectLanguage, SUPPORTED_LANGUAGES, type Language, type LanguageSources, type ResolvedLanguage, } from "./core/language.js";
 export { setLanguage, getLanguage, messagesFor, type Messages } from "./core/messages/index.js";
 export { createRunStore, createRunFolder, listRuns, readConversation, type RunFolder, type RunSummary, type ConversationMessage, } from "./core/runs.js";
@@ -22,17 +25,17 @@ export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
 export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
 export { createFileScopeGate, checkFileScope, type FileScope } from "./core/hooks/fileScopeGate.js";
 export { createPlanGate, checkPlanScope, type PlanScope } from "./core/hooks/planGate.js";
-export { askForDecision, askForManualIntervention } from "./core/hooks/humanInput.js";
-export { setInteractionPort, getInteractionPort, type InteractionPort, type ApprovalPrompt } from "./core/interaction.js";
+export { askForDecision, askForManualIntervention, askForChoice, askForText, type ChoiceAnswer } from "./core/hooks/humanInput.js";
+export { setInteractionPort, getInteractionPort, type InteractionPort, type ApprovalPrompt, type ChoiceSettings } from "./core/interaction.js";
 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 } from "./core/tools/saveToSources.js";
+export { createSaveToSourcesServer, 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";
 export { runChatInk, type InkChatOptions, type HeaderInfo } from "./tui/ink/runChatInk.js";
-export type { ToolPhrase } from "./tui/ink/toolGroup.js";
+export type { ToolPhrase, ToolDetail, ResultFormatter } from "./tui/ink/toolGroup.js";
 export type { RenderApproval } from "./tui/ink/SessionView.js";
 export { createProgressView, type ProgressView, type ProgressViewOptions } from "./tui/ink/progressView.js";
 export { runWizard, type WizardStep, type SelectStep, type InputStep, type PasswordStep, type ConfirmStep, type WizardAnswers, type WizardOptions, } from "./tui/ink/wizard.js";

package/dist/index.js

@@ -11,6 +11,9 @@ export { createFriendlyToolLabel, truncate, truncatePath, } from "./core/toolLab
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";
 export { runQuery } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./core/knowledge.js";
+export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, } from "./core/knowledgeStore.js";
+export { createFileKnowledgeStore } from "./core/fileKnowledgeStore.js";
+export { createKnowledgeServer } from "./core/tools/knowledgeTools.js";
 export { resolveLanguage, detectLanguage, SUPPORTED_LANGUAGES, } from "./core/language.js";
 export { setLanguage, getLanguage, messagesFor } from "./core/messages/index.js";
 export { createRunStore, createRunFolder, listRuns, readConversation, } from "./core/runs.js";
@@ -24,7 +27,7 @@ export { createSubagentTypeGate } from "./core/hooks/subagentTypeGate.js";
 export { createSubagentForegroundGate } from "./core/hooks/subagentForegroundGate.js";
 export { createFileScopeGate, checkFileScope } from "./core/hooks/fileScopeGate.js";
 export { createPlanGate, checkPlanScope } from "./core/hooks/planGate.js";
-export { askForDecision, askForManualIntervention } from "./core/hooks/humanInput.js";
+export { askForDecision, askForManualIntervention, askForChoice, askForText } from "./core/hooks/humanInput.js";
 export { setInteractionPort, getInteractionPort } from "./core/interaction.js";
 export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";
 // The checkpoints answer on the terminal by default, as they always have; a non-terminal

package/dist/tui/chatTui.js

@@ -188,6 +188,14 @@ export async function runChatTui(options, tuiOptions = {}) {
         },
     });
     const { writeLine } = renderer;
+    // The mode can change from inside the session (the agent leaving plan mode with
+    // present_plan): say so, as /plan does.
+    let unsubscribeMode;
+    const watchMode = () => {
+        unsubscribeMode?.();
+        unsubscribeMode = modeControl()?.subscribe?.((mode) => writeLine(ui.dim(`⏵⏵ ${t().mode(mode)}`)));
+    };
+    watchMode();
     // Cached lazily (not fetched until the first "/..." line, and only once — the SDK docs
     // don't promise this list changes mid-session, and re-fetching per line would add a
     // round-trip to the CLI subprocess for every turn): every registered command name/alias,
@@ -261,6 +269,7 @@ export async function runChatTui(options, tuiOptions = {}) {
         queue = createInputQueue({ modeControl: modeControl() });
         run = runQuery(queue.iterable, current.options);
         events = run.events[Symbol.asyncIterator]();
+        watchMode();
         knownCommandTokens = null;
         await showConversation(current.run);
     }
@@ -304,7 +313,11 @@ export async function runChatTui(options, tuiOptions = {}) {
             if (line.toLowerCase() === "/plan") {
                 const control = modeControl();
                 const next = control ? togglePlanMode(control) : null;
-                writeLine(ui.dim(next ? `⏵⏵ ${t().mode(next)}` : t().modeLocked(control?.mode)));
+                // The new mode's line comes from watchMode(); a control without subscribe() says it here.
+                if (!next)
+                    writeLine(ui.dim(t().modeLocked(control?.mode)));
+                else if (!control?.subscribe)
+                    writeLine(ui.dim(`⏵⏵ ${t().mode(next)}`));
                 continue;
             }
             // A line that *looks* like a slash command but matches nothing registered (a typo,

package/dist/tui/consoleRenderer.js

@@ -1,5 +1,6 @@
 import { stdout } from "node:process";
 import { createFriendlyToolLabel } from "../core/toolLabels.js";
+import { parseTodos, todoChanges, TODO_TOOL } from "../core/todos.js";
 import * as ui from "./ui.js";
 import { t } from "../core/messages/index.js";
 /**
@@ -14,6 +15,8 @@ export function createConsoleRenderer(options = {}) {
     const output = options.output ?? ((text) => void stdout.write(text));
     let atLineStart = true;
     let labelPrinted = false;
+    // The main agent's task list, to print only what changed in each TodoWrite call.
+    let todos = [];
     function write(text) {
         if (text.length === 0)
             return;
@@ -39,9 +42,20 @@ export function createConsoleRenderer(options = {}) {
                 }
                 write(ui.agent(event.text));
                 return;
-            case "action":
-                writeLine(ui.action(`[action] ${formatAction(event.toolName, event.input)}`));
+            case "action": {
+                const next = event.toolName === TODO_TOOL ? parseTodos(event.input) : null;
+                if (!next) {
+                    writeLine(ui.action(`[action] ${formatAction(event.toolName, event.input)}`));
+                    return;
+                }
+                const { started, completed } = todoChanges(todos, next);
+                todos = next;
+                for (const todo of completed)
+                    writeLine(ui.action(`[task] ☑ ${todo.content}`));
+                for (const todo of started)
+                    writeLine(ui.action(`[task] ◼ ${todo.activeForm}`));
                 return;
+            }
             case "subagent-action":
             case "tool-result":
             case "prompt-suggestion":