@falkenslab/agent-kit 0.15.0 → 0.16.1

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/core/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The version of agent-kit in use, read from its own `package.json` (next to `dist/`, or
+ * `src/` under tsx), e.g. to show it in an agent's header or log.
+ */
+export declare function agentKitVersion(): string;

package/dist/core/version.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+let cached;
+/**
+ * The version of agent-kit in use, read from its own `package.json` (next to `dist/`, or
+ * `src/` under tsx), e.g. to show it in an agent's header or log.
+ */
+export function agentKitVersion() {
+    cached ??= JSON.parse(readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8")).version;
+    return cached;
+}

package/dist/index.d.ts

@@ -10,6 +10,10 @@ 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 { agentKitVersion } from "./core/version.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,12 +26,12 @@ 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";

package/dist/index.js

@@ -11,6 +11,10 @@ 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 { agentKitVersion } from "./core/version.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 +28,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":

package/dist/tui/ink/SessionView.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import wrapAnsi from "wrap-ansi";
 import { useEffect, useReducer, useRef, useState, useSyncExternalStore } from "react";
 import { Box, measureElement, Static, Text, useInput, useStdout } from "ink";
-import { Select } from "@inkjs/ui";
+import { MultiSelect, Select, TextInput } from "@inkjs/ui";
 import { liveWidth } from "./sessionModel.js";
 import { createRowCache, highlightRow, isMouseReport, mouseEvents, rowsBelow, scrollBy, selectedText, visibleRows, userBarRows, } from "./fullscreen.js";
 import { framePosition } from "./terminalCursor.js";
@@ -11,6 +11,7 @@ import { fitWidth, stripAnsi } from "./lineBuffer.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
 import { inkColor } from "../theme.js";
+import { renderMarkdown } from "./markdown.js";
 // Numbered as in the Claude Code CLI's permission prompt; the digits and y/n/q answer too.
 const decisionOptions = () => [
     { label: `1. ${t().yes}`, value: "y" },
@@ -44,16 +45,42 @@ export function previewLines(lines, terminalRows, reservedRows = PANEL_RESERVED_
 }
 function CheckpointPanel({ checkpoint, renderApproval, reservedRows, width, }) {
     const decision = checkpoint.kind === "decision";
-    useInput((input) => {
-        const key = input.toLowerCase();
-        if (decision && DECISION_KEYS[key])
-            checkpoint.answer(DECISION_KEYS[key]);
-        else if (!decision && key === "1")
+    const text = checkpoint.kind === "text";
+    const choice = checkpoint.kind === "choice";
+    useInput((input, key) => {
+        if (text || choice) {
+            if (key.escape)
+                checkpoint.answer("");
+            return;
+        }
+        const lower = input.toLowerCase();
+        if (decision && DECISION_KEYS[lower])
+            checkpoint.answer(DECISION_KEYS[lower]);
+        else if (!decision && lower === "1")
             checkpoint.answer("");
     });
     const { prompt } = checkpoint;
     const { stdout } = useStdout();
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: inkColor("accent"), paddingX: 1, children: [renderApproval ? (renderApproval(prompt)) : (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: prompt.title }), previewLines(prompt.lines, stdout.rows, reservedRows, width - PANEL_FRAME_COLUMNS).map((line, index) => (_jsx(Text, { children: line }, index))), !decision && prompt.question ? _jsx(Text, { dimColor: true, children: prompt.question }) : null] })), decision ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: t().proceed }) })) : null, _jsx(Box, { marginTop: decision ? 0 : 1, children: _jsx(Select, { options: decision ? decisionOptions() : manualOptions(), onChange: (value) => checkpoint.answer(decision ? value : "") }, checkpoint.id) })] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: inkColor("accent"), paddingX: 1, children: [renderApproval ? (renderApproval(prompt)) : (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: prompt.title }), previewLines(prompt.markdown ? renderMarkdown(prompt.lines.join("\n"), width - PANEL_FRAME_COLUMNS) : prompt.lines, stdout.rows, reservedRows, width - PANEL_FRAME_COLUMNS).map((line, index) => (_jsx(Text, { children: line }, index))), !decision && prompt.question ? _jsx(Text, { dimColor: true, children: prompt.question }) : null] })), decision ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: t().proceed }) })) : null, choice && checkpoint.choice ? (_jsx(ChoiceInput, { choice: checkpoint.choice, onAnswer: (value) => checkpoint.answer(value) }, checkpoint.id)) : text ? (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { children: "> " }), _jsx(TextInput, { placeholder: t().textAnswerHint, onSubmit: (value) => checkpoint.answer(value.trim()) }, checkpoint.id)] }), _jsx(Text, { dimColor: true, children: t().textAnswerKeys })] })) : (_jsx(Box, { marginTop: decision ? 0 : 1, children: _jsx(Select, { options: decision ? decisionOptions() : manualOptions(), onChange: (value) => checkpoint.answer(decision ? value : "") }, checkpoint.id) }))] }));
+}
+/**
+ * A choice's options (one with Select, several with MultiSelect), plus "Other" to type an
+ * answer of one's own; answers as `InteractionPort.askChoice()` says: the numbers, then the
+ * typed answer on the next line.
+ */
+function ChoiceInput({ choice, onAnswer }) {
+    const [typing, setTyping] = useState(null);
+    const options = [...choice.options.map((label, i) => ({ label: `${i + 1}. ${label}`, value: String(i + 1) })), { label: t().otherOption, value: "other" }];
+    if (typing !== null) {
+        return (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { children: "> " }), _jsx(TextInput, { placeholder: t().textAnswerHint, onSubmit: (value) => onAnswer([typing, value.trim()].filter(Boolean).join("\n")) })] }), _jsx(Text, { dimColor: true, children: t().textAnswerKeys })] }));
+    }
+    return (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [choice.multiple ? (_jsx(MultiSelect, { options: options, onSubmit: (values) => {
+                    const picked = values.filter((value) => value !== "other").join(",");
+                    if (values.includes("other"))
+                        setTyping(picked);
+                    else
+                        onAnswer(picked);
+                } })) : (_jsx(Select, { options: options, onChange: (value) => (value === "other" ? setTyping("") : onAnswer(value)) })), _jsx(Text, { dimColor: true, children: t().choiceKeys(choice.multiple) })] }));
 }
 function formatTokens(count) {
     return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : String(count);
@@ -89,7 +116,21 @@ function LiveArea({ session, checkpoint, renderApproval, mode, width, statusExtr
     return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, width: width, marginTop: session.liveGap ? 1 : 0, children: [stripAnsi(session.live) ? _jsx(Text, { children: session.live }) : null, checkpoint ? (_jsx(CheckpointPanel, { checkpoint: checkpoint, renderApproval: renderApproval, reservedRows: reservedRows, width: width })) : session.busy ? (
             // Always one blank line above the spinner: from this margin, or from the live area's
             // own when a separator is pending and nothing is written above the spinner yet.
-            _jsxs(Box, { flexDirection: "column", marginTop: stripAnsi(session.live) || !session.liveGap ? 1 : 0, children: [_jsx(Working, { label: session.activity ?? t().thinking, startedAt: session.turnStartedAt, width: width }), session.subagentActivity ? _jsx(Text, { dimColor: true, children: fitWidth(`  ↳ ${session.subagentActivity}`, width) }) : null] })) : null, checkpoint ? null : children, _jsx(Text, { children: fitWidth(status, width) })] }));
+            _jsxs(Box, { flexDirection: "column", marginTop: stripAnsi(session.live) || !session.liveGap ? 1 : 0, children: [_jsx(Working, { label: session.activity ?? t().thinking, startedAt: session.turnStartedAt, width: width }), session.subagentActivity ? _jsx(Text, { dimColor: true, children: fitWidth(`  ↳ ${session.subagentActivity}`, width) }) : null] })) : null, checkpoint || !session.todos ? null : _jsx(TodoList, { todos: session.todos, width: width }), checkpoint ? null : children, _jsx(Text, { children: fitWidth(status, width) })] }));
+}
+// At most this many tasks show; the rest are counted (the one in progress always shows).
+const MAX_TODOS = 8;
+/** The agent's task list (TodoWrite), as in the Claude Code CLI: `☐` pending, `◼` in progress, `☑` done. */
+function TodoList({ todos, width }) {
+    const current = todos.findIndex((todo) => todo.status === "in_progress");
+    const first = Math.max(0, Math.min(current - 2, todos.length - MAX_TODOS));
+    const shown = todos.slice(first, first + MAX_TODOS);
+    const hidden = todos.length - shown.length;
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [shown.map((todo, i) => {
+                const line = `  ${i === 0 ? "⎿ " : "  "}${todo.status === "completed" ? "☑" : todo.status === "in_progress" ? "◼" : "☐"} ${todo.content}`;
+                const fitted = fitWidth(line, width);
+                return (_jsx(Text, { children: todo.status === "completed" ? ui.dim(ui.strike(fitted)) : todo.status === "in_progress" ? ui.bold(fitted) : fitted }, first + i));
+            }), hidden > 0 ? _jsx(Text, { children: ui.dim(fitWidth(`     ${t().moreTodos(hidden)}`, width)) }) : null] }));
 }
 /** A history line for the inline view: the human's line as a bar, a tool group unfolded with Ctrl+O. */
 function inlineItem(item, expanded, width) {
@@ -133,6 +174,16 @@ function FullscreenSession({ session, checkpoint, renderApproval, mode, header,
         if (height !== historyHeight)
             setHistoryHeight(height);
     });
+    // The history's height now: `historyHeight` is set by the effect above after the layout,
+    // so a key or a click on the first frames would still find the terminal's height.
+    function heightNow() {
+        if (!historyRef.current)
+            return historyHeight;
+        const { height } = measureElement(historyRef.current);
+        if (height !== historyHeight)
+            setHistoryHeight(height);
+        return height;
+    }
     const [anchor, setAnchor] = useState(null);
     // Mirrored in a ref: mouse reports can arrive faster than React re-renders.
     const [selection, setSelectionState] = useState(null);
@@ -161,9 +212,7 @@ function FullscreenSession({ session, checkpoint, renderApproval, mode, header,
         if (!historyRef.current || end === start)
             return null;
         const box = framePosition(historyRef.current);
-        // Measured now, not `historyHeight`: that state is set by an effect after the layout, so
-        // a click on the first frames would find the rows where they were before it.
-        const height = measureElement(historyRef.current).height;
+        const height = heightNow();
         const firstY = box.y + height - (end - start); // the rows are bottom-aligned
         let offset = y - firstY;
         // Rows that don't fit are clipped above the box, not clickable.
@@ -179,7 +228,8 @@ function FullscreenSession({ session, checkpoint, renderApproval, mode, header,
         for (const event of mouseEvents(text)) {
             if (event.kind === "wheel-up" || event.kind === "wheel-down") {
                 const steps = event.kind === "wheel-up" ? -WHEEL_ROWS : WHEEL_ROWS;
-                setAnchor((a) => scrollBy(a, steps, total, historyHeight));
+                const height = heightNow();
+                setAnchor((a) => scrollBy(a, steps, total, height));
             }
             else if (event.kind === "press") {
                 const cell = cellAt(event.x, event.y, false);
@@ -210,15 +260,15 @@ function FullscreenSession({ session, checkpoint, renderApproval, mode, header,
         }
     }
     useInput((text, key) => {
-        const page = Math.max(1, historyHeight - 1);
         if (isMouseReport(text))
             handleMouse(text);
         else if (isFocusReport(text))
             return;
-        else if (key.pageUp)
-            setAnchor((a) => scrollBy(a, -page, total, historyHeight));
-        else if (key.pageDown)
-            setAnchor((a) => scrollBy(a, page, total, historyHeight));
+        else if (key.pageUp || key.pageDown) {
+            const height = heightNow();
+            const page = Math.max(1, height - 1);
+            setAnchor((a) => scrollBy(a, key.pageUp ? -page : page, total, height));
+        }
         else if (key.ctrl && key.end)
             setAnchor(null);
         else if (text && !key.ctrl && !key.meta && !key.escape)

package/dist/tui/ink/inkInteraction.d.ts

@@ -1,9 +1,11 @@
-import type { ApprovalPrompt, InteractionPort } from "../../core/interaction.js";
-export type CheckpointKind = "decision" | "manual-intervention";
+import type { ApprovalPrompt, ChoiceSettings, InteractionPort } from "../../core/interaction.js";
+export type CheckpointKind = "decision" | "manual-intervention" | "text" | "choice";
 export interface Checkpoint {
     id: number;
     kind: CheckpointKind;
     prompt: ApprovalPrompt;
+    /** For a choice: the options and whether several can be picked. */
+    choice?: ChoiceSettings;
     /** Settles the checkpoint with the raw answer ("y", "n", "q" for a decision). */
     answer(value: string): void;
 }

package/dist/tui/ink/inkInteraction.js

@@ -1,4 +1,6 @@
+import { parseChoice } from "../../core/hooks/humanInput.js";
 import * as ui from "../ui.js";
+import { renderMarkdown } from "./markdown.js";
 import { t } from "../../core/messages/index.js";
 const outcome = (answer) => ({ y: ui.success(t().approved), n: ui.warn(t().rejected), q: ui.error(t().stopped) })[answer];
 /**
@@ -25,16 +27,30 @@ export function createInkInteraction(note) {
     function record(prompt, outcome) {
         note([ui.heading(`=== ${prompt.title} ===`), ...prompt.lines, outcome].join("\n"));
     }
-    function ask(kind, prompt, signal) {
+    /** How a settled checkpoint is written to the history. */
+    function settledAs(kind, value, choice) {
+        if (kind === "decision")
+            return outcome(value) ?? value;
+        if (kind === "text")
+            return value ? ui.success(`✔ ${value}`) : ui.dim(t().noAnswer);
+        if (kind === "choice" && choice) {
+            const answer = parseChoice(value, choice.options, choice.multiple);
+            const words = [...answer.chosen, ...(answer.other ? [answer.other] : [])];
+            return words.length ? ui.success(`✔ ${words.join("; ")}`) : ui.dim(t().noAnswer);
+        }
+        return ui.success(t().done);
+    }
+    function ask(kind, prompt, signal, choice) {
         return new Promise((resolve) => {
             const checkpoint = {
                 id: nextId++,
                 kind,
                 prompt,
+                ...(choice ? { choice } : {}),
                 answer(value) {
                     if (!remove(checkpoint))
                         return;
-                    record(prompt, kind === "decision" ? (outcome(value) ?? value) : ui.success(t().done));
+                    record(prompt.markdown ? { ...prompt, lines: renderMarkdown(prompt.lines.join("\n"), 80) } : prompt, settledAs(kind, value, choice));
                     resolve(value);
                 },
             };
@@ -50,6 +66,8 @@ export function createInkInteraction(note) {
         port: {
             askDecision: (prompt, signal) => ask("decision", prompt, signal),
             askManualIntervention: (prompt, signal) => ask("manual-intervention", prompt, signal),
+            askText: (prompt, signal) => ask("text", prompt, signal),
+            askChoice: (prompt, choice, signal) => ask("choice", prompt, signal, choice),
             notify: (message) => note(message),
         },
         subscribe(listener) {

package/dist/tui/ink/runChatInk.js

@@ -244,12 +244,17 @@ export async function runChatInk(options, tuiOptions = {}) {
     let run;
     let knownCommands;
     let generation = 0;
+    let unsubscribeMode;
     function connect() {
         const own = ++generation;
         queue = createInputQueue({ modeControl: modeControl() });
         run = runQuery(queue.iterable, { ...current.options, promptSuggestions: tuiOptions.promptSuggestions ?? true });
         const events = run.events[Symbol.asyncIterator]();
         input.setMode(modeControl()?.mode ?? null);
+        // The mode can also change from inside the session (the agent leaving plan mode with
+        // present_plan): the status bar follows it.
+        unsubscribeMode?.();
+        unsubscribeMode = modeControl()?.subscribe?.((mode) => input.setMode(mode));
         // Every registered command name and alias, built-ins included, for completion and for
         // catching an unknown "/command" before it reaches the model as plain text (see chatTui.ts).
         knownCommands = run.supportedCommands().then((commands) => new Set(commands.flatMap((c) => [c.name, ...(c.aliases ?? [])])), () => null);

package/dist/tui/ink/sessionModel.d.ts

@@ -1,6 +1,7 @@
 import type { AgentEvent, SessionUsage } from "../../core/runner.js";
 import { type ConsoleRenderer } from "../consoleRenderer.js";
 import { type ResultFormatter, type ToolDetail, type ToolPhrase } from "./toolGroup.js";
+import { type Todo } from "../../core/todos.js";
 export interface HistoryItem {
     id: number;
     text: string;
@@ -36,6 +37,8 @@ export interface SessionSnapshot {
     usage: SessionUsage | null;
     /** How full the context window is (0-100), after the latest turn; null until known. */
     contextPercent: number | null;
+    /** The main agent's task list (TodoWrite), while any task is still to do; null otherwise. */
+    todos: Todo[] | null;
 }
 export interface SessionModelOptions {
     formatAction?: (toolName: string, toolInput: unknown) => string;

package/dist/tui/ink/sessionModel.js

@@ -5,6 +5,7 @@ import { finishedLength, hasTable, renderMarkdown } from "./markdown.js";
 import { toolGroupExpanded, toolGroupSummary } from "./toolGroup.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
+import { hasOpenTodos, parseTodos, TODO_TOOL } from "../../core/todos.js";
 /**
  * Columns the live area may use: short of the edge, where the Windows console wraps early
  * (see lineBuffer.ts). Read on every use, so a resized terminal is picked up.
@@ -45,6 +46,7 @@ export function createSessionModel(options = {}) {
         turns: 0,
         usage: null,
         contextPercent: null,
+        todos: null,
     };
     function update(changes) {
         snapshot = { ...snapshot, ...changes };
@@ -190,6 +192,15 @@ export function createSessionModel(options = {}) {
                     return;
                 }
                 case "action": {
+                    // The task list isn't a tool call to show: it's drawn above the prompt, and the task
+                    // in progress becomes the spinner's label.
+                    const todos = event.toolName === TODO_TOOL ? parseTodos(event.input) : null;
+                    if (todos) {
+                        const current = todos.find((todo) => todo.status === "in_progress");
+                        snapshot = { ...snapshot, todos: hasOpenTodos(todos) ? todos : null, activity: current?.activeForm ?? snapshot.activity };
+                        refreshLive();
+                        return;
+                    }
                     flushSegment(true);
                     group ??= [];
                     group.push({ id: event.toolUseId, label: formatAction(event.toolName, event.input), toolName: event.toolName, result: null });
@@ -198,6 +209,8 @@ export function createSessionModel(options = {}) {
                     return;
                 }
                 case "tool-result": {
+                    if (event.toolName === TODO_TOOL)
+                        return;
                     const call = group?.find((c) => c.id === event.toolUseId);
                     if (call)
                         call.result = { isError: event.isError, text: event.text };
@@ -282,7 +295,7 @@ export function createSessionModel(options = {}) {
             lastKind = null;
             gapPending = false;
             reply = "";
-            snapshot = { ...snapshot, items: [], live: "", liveGap: false, turns: 0, usage: null, contextPercent: null };
+            snapshot = { ...snapshot, items: [], live: "", liveGap: false, turns: 0, usage: null, contextPercent: null, todos: null };
             refreshLive();
         },
         replay(messages, userLine) {

package/dist/tui/terminalInteraction.js

@@ -80,6 +80,8 @@ async function askOnTerminal(prompt, signal) {
 export const terminalInteractionPort = {
     askDecision: askOnTerminal,
     askManualIntervention: askOnTerminal,
+    askText: askOnTerminal,
+    askChoice: (prompt, choice, signal) => askOnTerminal({ ...prompt, lines: [...prompt.lines, ...choice.options.map((option, i) => `${i + 1}. ${option}`)], question: t().choiceQuestion(choice.multiple) }, signal),
     notify(message) {
         if (stdin.isTTY)
             console.log(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",
@@ -62,11 +62,17 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@mozilla/readability": "^0.6.0",
     "@types/node": "^24.0.0",
+    "@types/turndown": "^5.0.6",
     "eslint": "^10.9.1",
+    "fflate": "^0.8.3",
     "globals": "^17.11.0",
     "ink-testing-library": "^4.0.0",
+    "linkedom": "^0.18.13",
+    "mammoth": "^1.13.0",
     "tsx": "^4.19.0",
+    "turndown": "^7.2.4",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.68.0"
   },
@@ -75,5 +81,29 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "@mozilla/readability": ">=0.5.0",
+    "linkedom": ">=0.16.0",
+    "turndown": ">=7.0.0",
+    "mammoth": ">=1.6.0",
+    "fflate": ">=0.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@mozilla/readability": {
+      "optional": true
+    },
+    "linkedom": {
+      "optional": true
+    },
+    "turndown": {
+      "optional": true
+    },
+    "mammoth": {
+      "optional": true
+    },
+    "fflate": {
+      "optional": true
+    }
   }
 }