@falkenslab/agent-kit 0.15.0 → 0.16.1

package/dist/core/sources.js

@@ -0,0 +1,312 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { copyFile, mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * The sources folder's bookkeeping: originals stay files (ADR-024), and the kit keeps a
+ * manifest next to them (`.agent-kit/sources.json`, inside `sourcesDir`, where the agent's
+ * file tools can't write) with each original's hash, size and provenance, the version it
+ * replaces, and the hash it had when a summary page first pointed to it. From that it tells
+ * new, ingested, changed and missing originals apart, refuses duplicates, and retires an
+ * original into `.agent-kit/retired/` instead of deleting it.
+ */
+export const KIT_DIR = ".agent-kit";
+const MANIFEST = "sources.json";
+const RETIRED_DIR = "retired";
+const posix = (p) => p.split(path.sep).join("/");
+// The model can call several tools at once: everything that reads and writes a folder's
+// manifest runs one at a time per folder, or a parallel call would lose another's entry.
+const locks = new Map();
+function serialized(sourcesDir, work) {
+    const key = path.resolve(sourcesDir);
+    const result = (locks.get(key) ?? Promise.resolve()).then(work, work);
+    locks.set(key, result.catch(() => undefined));
+    return result;
+}
+const now = () => new Date().toISOString();
+export async function hashFile(file) {
+    return createHash("sha256").update(await readFile(file)).digest("hex");
+}
+/** Resolves `candidate` against `base`; the absolute path only if it stays inside it. */
+export 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;
+}
+export async function loadManifest(sourcesDir) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(sourcesDir, KIT_DIR, MANIFEST), "utf8"));
+        return { version: 1, files: parsed.files ?? {}, retired: parsed.retired ?? [] };
+    }
+    catch {
+        return { version: 1, files: {}, retired: [] };
+    }
+}
+export async function saveManifest(sourcesDir, manifest) {
+    await mkdir(path.join(sourcesDir, KIT_DIR), { recursive: true });
+    await writeFile(path.join(sourcesDir, KIT_DIR, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+/** Every original under `sourcesDir` (paths relative to it), leaving out hidden files and folders (the kit's own among them). */
+export async function scanSources(sourcesDir) {
+    const found = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.isFile())
+                found.push(posix(path.relative(sourcesDir, full)));
+        }
+    }
+    await walk(sourcesDir);
+    return found.sort();
+}
+/** An entry for `file`, reusing the recorded hash when its size and modification time haven't changed. */
+async function freshEntry(file, known, origin) {
+    const info = await stat(file);
+    if (known && known.size === info.size && known.mtimeMs === info.mtimeMs)
+        return known;
+    return { ...(known ?? { addedAt: now(), origin }), hash: await hashFile(file), size: info.size, mtimeMs: info.mtimeMs };
+}
+/** The original a frontmatter `file:` value points to (a relative path or a markdown link), resolved from the page's folder. */
+function linkedFile(value, pageDir) {
+    const link = /\]\(([^)]+)\)/.exec(value)?.[1] ?? value.trim().replace(/^["']|["']$/g, "");
+    if (!link || /^[a-z]+:\/\//i.test(link))
+        return undefined;
+    return path.resolve(pageDir, decodeURI(link));
+}
+/** The summary pages (knowledge base layout: `summaries/*.md`) by the absolute path of the original their frontmatter `file:` points to. */
+export async function summariesByOriginal(knowledgeDir) {
+    const byOriginal = new Map();
+    const dir = path.join(knowledgeDir, "summaries");
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return byOriginal;
+    }
+    for (const name of names.filter((n) => n.endsWith(".md"))) {
+        const page = path.join(dir, name);
+        const text = await readFile(page, "utf8");
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
+        const value = /^file:\s*(.+)$/m.exec(frontmatter)?.[1];
+        const original = value ? linkedFile(value, dir) : undefined;
+        if (original)
+            byOriginal.set(path.normalize(original), [...(byOriginal.get(path.normalize(original)) ?? []), page]);
+    }
+    return byOriginal;
+}
+/** Pages of a PDF, read from its page tree without a parser; undefined when it can't tell (e.g. compressed object streams). */
+export function pdfPageCount(bytes) {
+    const text = bytes.toString("latin1");
+    const counts = [...text.matchAll(/\/Type\s*\/Pages\b[^>]*?\/Count\s+(\d+)/g)].map((m) => Number(m[1]));
+    const reversed = [...text.matchAll(/\/Count\s+(\d+)[^>]*?\/Type\s*\/Pages\b/g)].map((m) => Number(m[1]));
+    const fromTree = Math.max(0, ...counts, ...reversed);
+    if (fromTree > 0)
+        return fromTree;
+    const pages = text.match(/\/Type\s*\/Page(?![s\w])/g)?.length ?? 0;
+    return pages > 0 ? pages : undefined;
+}
+/** Slides of a PPTX, from the file names in the zip (stored uncompressed). */
+export function pptxSlideCount(bytes) {
+    const names = new Set(bytes.toString("latin1").match(/ppt\/slides\/slide\d+\.xml/g) ?? []);
+    return names.size > 0 ? names.size : undefined;
+}
+const typeOf = (file) => path.extname(file).slice(1).toLowerCase() || "file";
+/**
+ * Every original with its status, recording in the manifest the ones copied in by hand and,
+ * the first time a summary page points to one, its hash at ingest. Without a knowledge
+ * folder there's no ingest to compare with: originals are "present".
+ */
+export function listSources(sourcesDir, knowledgeDir, projectDir) {
+    return serialized(sourcesDir, () => listSourcesNow(sourcesDir, knowledgeDir, projectDir));
+}
+async function listSourcesNow(sourcesDir, knowledgeDir, projectDir) {
+    const manifest = await loadManifest(sourcesDir);
+    const summaries = knowledgeDir ? await summariesByOriginal(knowledgeDir) : new Map();
+    const files = await scanSources(sourcesDir);
+    const listing = [];
+    for (const rel of files) {
+        const full = path.join(sourcesDir, rel);
+        const entry = await freshEntry(full, manifest.files[rel], { kind: "manual" });
+        const pagesOf = summaries.get(path.normalize(full)) ?? [];
+        let status = "present";
+        if (knowledgeDir) {
+            if (pagesOf.length === 0)
+                status = "new";
+            else {
+                entry.ingestedHash ??= entry.hash;
+                status = entry.ingestedHash === entry.hash ? "ingested" : "changed";
+            }
+        }
+        manifest.files[rel] = entry;
+        const type = typeOf(rel);
+        const counts = type === "pdf" || type === "pptx"
+            ? await readFile(full).then((bytes) => (type === "pdf" ? { pages: pdfPageCount(bytes) } : { slides: pptxSlideCount(bytes) }))
+            : {};
+        listing.push({
+            path: rel,
+            status,
+            type,
+            size: entry.size,
+            ...counts,
+            origin: entry.origin,
+            ...(entry.replaces ? { replaces: entry.replaces } : {}),
+            summaries: pagesOf.map((page) => posix(path.relative(projectDir, page))),
+        });
+    }
+    for (const [rel, entry] of Object.entries(manifest.files)) {
+        if (!files.includes(rel))
+            listing.push({ path: rel, status: "missing", type: typeOf(rel), origin: entry.origin, summaries: [] });
+    }
+    await saveManifest(sourcesDir, manifest);
+    return listing;
+}
+/**
+ * Adds `file` (an absolute path) to `sourcesDir` at `destination` (a folder: under `extra.name`,
+ * or the file's own name): never overwriting, and
+ * not at all if an identical file is already there (its path is returned). `replaces`
+ * records it as a new version of an original already in the folder.
+ */
+export function addSource(sourcesDir, file, destination, origin, extra = {}) {
+    return serialized(sourcesDir, () => addSourceNow(sourcesDir, file, destination, origin, extra));
+}
+async function addSourceNow(sourcesDir, file, destination, origin, extra) {
+    // A folder ("books/", or one that exists) means: inside it, under the file's own name.
+    const isFolder = /[/\\]$/.test(destination) || (await stat(path.join(sourcesDir, destination)).catch(() => null))?.isDirectory();
+    if (isFolder)
+        destination = path.join(destination, extra.name ?? path.basename(file));
+    const target = resolveWithin(sourcesDir, destination);
+    if (!target || posix(path.relative(sourcesDir, target)).split("/").some((part) => part.startsWith("."))) {
+        throw new Error(`"${destination}" isn't a path inside sources/ (hidden folders are the kit's).`);
+    }
+    const manifest = await loadManifest(sourcesDir);
+    if (extra.replaces) {
+        const old = resolveWithin(sourcesDir, extra.replaces);
+        if (!old || !(await stat(old).catch(() => null)))
+            throw new Error(`"${extra.replaces}" isn't an original in sources/, so it can't be replaced.`);
+    }
+    const hash = await hashFile(file);
+    for (const rel of await scanSources(sourcesDir)) {
+        const entry = await freshEntry(path.join(sourcesDir, rel), manifest.files[rel], { kind: "manual" });
+        manifest.files[rel] = entry;
+        if (entry.hash === hash) {
+            await saveManifest(sourcesDir, manifest);
+            return { path: rel, duplicateOf: rel };
+        }
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    try {
+        await copyFile(file, target, constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new Error(`"${destination}" already exists in sources/: originals are never overwritten. Pick another name${extra.replaces ? "" : ", or pass `replaces` for a new version"}.`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    const rel = posix(path.relative(sourcesDir, target));
+    const info = await stat(target);
+    manifest.files[rel] = {
+        hash,
+        size: info.size,
+        mtimeMs: info.mtimeMs,
+        addedAt: now(),
+        origin,
+        ...(extra.replaces ? { replaces: posix(path.relative(sourcesDir, resolveWithin(sourcesDir, extra.replaces))) } : {}),
+        ...(extra.derivedFrom ? { derivedFrom: extra.derivedFrom } : {}),
+    };
+    await saveManifest(sourcesDir, manifest);
+    return { path: rel };
+}
+/** Adds frontmatter fields and a notice under the frontmatter of a markdown page. */
+async function markPage(page, fields, notice) {
+    const text = await readFile(page, "utf8");
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    const lines = Object.entries(fields).map(([key, value]) => `${key}: ${value}`);
+    const updated = match
+        ? `---\n${match[1].split(/\r?\n/).filter((line) => !Object.keys(fields).some((key) => line.startsWith(`${key}:`))).concat(lines).join("\n")}\n---\n\n> ${notice}\n\n${text.slice(match[0].length).replace(/^\s+/, "")}`
+        : `---\n${lines.join("\n")}\n---\n\n> ${notice}\n\n${text}`;
+    await writeFile(page, updated);
+}
+/**
+ * Moves an original to `.agent-kit/retired/` (never deleted: the person empties that folder)
+ * and records why. Its summary pages are marked: retired if the original was wrong (what it
+ * taught was wrong), superseded if it was replaced, pointing to the replacement's summary
+ * when there is one.
+ */
+export function retireSource(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
+    return serialized(sourcesDir, () => retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy));
+}
+async function retireSourceNow(sourcesDir, knowledgeDir, projectDir, source, why, reason, replacedBy) {
+    const full = resolveWithin(sourcesDir, source);
+    if (!full || !(await stat(full).catch(() => null))?.isFile())
+        throw new Error(`"${source}" isn't an original in sources/.`);
+    const rel = posix(path.relative(sourcesDir, full));
+    if (rel.split("/").some((part) => part.startsWith(".")))
+        throw new Error(`"${source}" is one of the kit's own files.`);
+    const replacement = replacedBy ? resolveWithin(sourcesDir, replacedBy) : undefined;
+    if (replacedBy && (!replacement || !(await stat(replacement).catch(() => null))))
+        throw new Error(`"${replacedBy}" isn't an original in sources/.`);
+    const summaries = knowledgeDir ? await summariesByOriginal(knowledgeDir) : new Map();
+    const manifest = await loadManifest(sourcesDir);
+    const stamp = now();
+    const movedTo = posix(path.join(KIT_DIR, RETIRED_DIR, `${stamp.replace(/[:.]/g, "-")}-${path.basename(rel)}`));
+    await mkdir(path.join(sourcesDir, KIT_DIR, RETIRED_DIR), { recursive: true });
+    await rename(full, path.join(sourcesDir, movedTo));
+    manifest.retired.push({
+        path: rel,
+        movedTo,
+        retiredAt: stamp,
+        why,
+        reason,
+        ...(replacement ? { replacedBy: posix(path.relative(sourcesDir, replacement)) } : {}),
+        ...(manifest.files[rel] ? { entry: manifest.files[rel] } : {}),
+    });
+    delete manifest.files[rel];
+    await saveManifest(sourcesDir, manifest);
+    const date = stamp.slice(0, 10);
+    const replacementSummary = replacement ? summaries.get(path.normalize(replacement))?.[0] : undefined;
+    const result = { movedTo, summaries: [] };
+    for (const page of summaries.get(path.normalize(full)) ?? []) {
+        if (why === "wrong") {
+            await markPage(page, { status: "retired", retired: date }, `Retired on ${date}: its original was wrong (${reason}). Don't rely on what it says.`);
+            result.summaries.push({ page: posix(path.relative(projectDir, page)), marked: "retired" });
+        }
+        else {
+            const link = replacementSummary ? posix(path.relative(path.dirname(page), replacementSummary)) : undefined;
+            await markPage(page, { status: "superseded", superseded: date, ...(link ? { superseded_by: link } : {}) }, `Superseded on ${date}: its original was replaced (${reason})${link ? `; see [the new summary](${link})` : ""}.`);
+            result.summaries.push({ page: posix(path.relative(projectDir, page)), marked: "superseded", ...(replacementSummary ? { supersededBy: posix(path.relative(projectDir, replacementSummary)) } : {}) });
+        }
+    }
+    return result;
+}
+/**
+ * Records `source` (relative to `sourcesDir`) as ingested now, with its current hash: a
+ * summary page was just written from it, so "changed" means changed after this.
+ */
+export function recordIngest(sourcesDir, source) {
+    return serialized(sourcesDir, async () => {
+        const full = resolveWithin(sourcesDir, source);
+        if (!full || !(await stat(full).catch(() => null))?.isFile())
+            return;
+        const rel = posix(path.relative(sourcesDir, full));
+        const manifest = await loadManifest(sourcesDir);
+        const entry = await freshEntry(full, manifest.files[rel], { kind: "manual" });
+        entry.ingestedHash = entry.hash;
+        manifest.files[rel] = entry;
+        await saveManifest(sourcesDir, manifest);
+    });
+}

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;