@falkenslab/agent-kit 0.17.0 → 0.19.0

package/dist/core/toolLabels.js

@@ -3,11 +3,11 @@ import { t } from "./messages/index.js";
  * Turns a raw tool name + input into a short, readable console description, instead of
  * the tool's technical name (e.g. "mcp__playwright__browser_click"). Covers the tools
  * this kit itself provides (Read/Write/Edit/Glob/Grep/Bash/Agent/WebFetch/WebSearch/Skill,
- * plus its own human-approval/manual-intervention/save-to-sources MCP tools)
- * generically; a
- * concrete agent supplies a `describe` callback for its own domain-specific tools (e.g.
- * Playwright's browser_* cases) via `createFriendlyToolLabel()`. The kit's own labels are in
- * the current language (see messages/).
+ * plus its own human-approval/manual-intervention/clock MCP tools) generically; an extension
+ * brings its tools' labels with its contribution (`ToolLabels`, ADR-025), and a concrete agent
+ * supplies a `describe` callback for its own domain-specific tools (e.g. Playwright's
+ * browser_* cases) via `createFriendlyToolLabel()`. The kit's own labels are in the current
+ * language (see messages/).
  */
 /** Cuts `text` to `max` characters, with "…" at the end. */
 export function truncate(text, max = 60) {
@@ -37,38 +37,6 @@ function describeCore(shortName, input) {
             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":
             return labels.reading(truncatePath(text(input.file_path, labels.aFile), 80));
         case "Write":
@@ -103,15 +71,32 @@ function describeCore(shortName, input) {
             return undefined;
     }
 }
+/**
+ * A `formatAction` that shows the tools in `labels()` with their label, and any other with
+ * `formatAction` (the kit's by default). `labels` is read on every call, so it can follow the
+ * session in use (`/resume` opens another).
+ */
+export function withToolLabels(labels, formatAction = createFriendlyToolLabel()) {
+    return (toolName, toolInput) => {
+        const own = labels()?.[toolName];
+        if (!own)
+            return formatAction(toolName, toolInput);
+        return own.label(toolInput && typeof toolInput === "object" ? toolInput : {});
+    };
+}
+/** A `toolPhrase` that counts the tools in `labels()` with their phrase, and any other with `toolPhrase`. */
+export function withToolPhrases(labels, toolPhrase) {
+    return (toolName) => labels()?.[toolName]?.phrase ?? toolPhrase?.(toolName);
+}
 /**
  * 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"/"time") whose tools should be unwrapped
+ * kit's own "approvals"/"manualLogin"/"time") whose tools should be unwrapped
  * without a "[server] " prefix, e.g. "playwright".
  */
 export function createFriendlyToolLabel(options = {}) {
-    const localServers = new Set(["approvals", "manualLogin", "sourceFiles", "time", "knowledge", ...(options.extraLocalServers ?? [])]);
+    const localServers = new Set(["approvals", "manualLogin", "time", ...(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.js

@@ -34,8 +34,8 @@ export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL
         };
     });
     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)"),
+        question: z.string().describe("The question, in one sentence, in the language you reply in"),
+        options: z.array(z.string()).min(2).max(8).describe("The options, short, in the language you reply in (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);
@@ -46,7 +46,7 @@ export function createHumanApprovalServer(runDir, texts = DEFAULT_HUMAN_APPROVAL
         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) => {
+    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 language you reply in: 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];

package/dist/extensions/awareness/index.d.ts

@@ -0,0 +1,13 @@
+import type { AgentIdentity } from "../../core/agentSpec.js";
+import type { Extension } from "../../core/extensions.js";
+/** Absolute path of the awareness extension's plugin, next to `dist/` (or `src/` under tsx). */
+export declare function awarenessPluginRoot(): string;
+/** The "Who you are" section of the system prompt: name, version, what it is, the kit's version, and where to look. */
+export declare function identityPromptSection(identity: AgentIdentity): string;
+/**
+ * The awareness (#43): the agent knows who it is and what it is at each moment of a session,
+ * and the person can ask it. A "Who you are" section, `about_me` (the session's facts, read
+ * anew on every call through `ExtensionContext.session()`, and the agent's `helpGuide`), and
+ * the `help` skill, how the kit's chat is used, which doesn't change.
+ */
+export declare const awarenessExtension: Extension;

package/dist/extensions/awareness/index.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentKitVersion } from "../../core/version.js";
+import { awarenessToolLabels } from "./labels.js";
+import { createAwarenessServer } from "./tools.js";
+/** Absolute path of the awareness extension's plugin, next to `dist/` (or `src/` under tsx). */
+export function awarenessPluginRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "extensions", "awareness");
+}
+/** The "Who you are" section of the system prompt: name, version, what it is, the kit's version, and where to look. */
+export function identityPromptSection(identity) {
+    const who = `${identity.name}${identity.version ? ` ${identity.version}` : ""}${identity.description ? `: ${identity.description}` : ""}`;
+    return `## Who you are
+You are ${who}. You are built on agent-kit ${agentKitVersion()}, which provides your chat (its modes, keys and slash commands) and your built-in tools.
+- When the person asks about you as you are now (your mode, what you can do, your extensions and their tools, what's off and why, your subagents, commands, how full your context is), call \`about_me\` and answer from it: it changes during the session, so never from memory or from an earlier answer.
+- Your mode is the kit's (guided, interactive, autonomous or plan), not a permission mode you may see elsewhere: you don't know which one is on until \`about_me\` says.
+- When they ask about your domain (your own commands, configuration, folders), \`about_me\` with \`part: "guide"\`.
+- When they ask how to use you (the chat's modes, keys and commands, approvals, resuming, the command line), load the \`help\` skill.
+- Don't invent what none of them says.`;
+}
+/**
+ * The awareness (#43): the agent knows who it is and what it is at each moment of a session,
+ * and the person can ask it. A "Who you are" section, `about_me` (the session's facts, read
+ * anew on every call through `ExtensionContext.session()`, and the agent's `helpGuide`), and
+ * the `help` skill, how the kit's chat is used, which doesn't change.
+ */
+export const awarenessExtension = {
+    name: "awareness",
+    plugin: awarenessPluginRoot(),
+    missing: ({ spec }) => (spec.identity ? undefined : "needs `identity` in the spec"),
+    async contribute({ spec, session }) {
+        return {
+            mcpServers: { awareness: createAwarenessServer(session, spec.helpGuide) },
+            promptSection: identityPromptSection(spec.identity),
+            readOnlyTools: ["mcp__awareness__about_me"],
+            toolLabels: awarenessToolLabels(),
+        };
+    },
+};

package/dist/extensions/awareness/labels.d.ts

@@ -0,0 +1,3 @@
+import type { ToolLabels } from "../../core/toolLabels.js";
+/** How the chat shows the awareness's tool (server `awareness`), in the kit's language. */
+export declare function awarenessToolLabels(): ToolLabels;

package/dist/extensions/awareness/labels.js

@@ -0,0 +1,12 @@
+import { getLanguage } from "../../core/messages/index.js";
+const TEXTS = {
+    en: { now: "Looking at itself", guide: "Reading its own guide", phrase: ["looked at itself", "looked at itself {n} times"] },
+    es: { now: "Mirándose a sí mismo", guide: "Leyendo su propia guía", phrase: ["se miró a sí mismo", "se miró a sí mismo {n} veces"] },
+    fr: { now: "Se regarde lui-même", guide: "Lit son propre guide", phrase: ["s'est regardé lui-même", "s'est regardé lui-même {n} fois"] },
+    de: { now: "Betrachtet sich selbst", guide: "Liest seine eigene Anleitung", phrase: ["sich selbst betrachtet", "sich selbst {n}-mal betrachtet"] },
+};
+/** How the chat shows the awareness's tool (server `awareness`), in the kit's language. */
+export function awarenessToolLabels() {
+    const texts = TEXTS[getLanguage()];
+    return { mcp__awareness__about_me: { label: (input) => (input.part === "guide" ? texts.guide : texts.now), phrase: texts.phrase } };
+}

package/dist/extensions/awareness/tools.d.ts

@@ -0,0 +1,5 @@
+import type { SessionFacts } from "../../core/sessionFacts.js";
+/** The session's facts as the model reads them: markdown, in English (ADR-019). */
+export declare function describeSession(facts: SessionFacts): string;
+/** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
+export declare function createAwarenessServer(session: () => Promise<SessionFacts>, helpGuide?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/extensions/awareness/tools.js

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+/**
+ * `about_me`, the awareness's one tool (#43): what the agent is right now, read from the
+ * session on every call, so it answers with the mode after Shift+Tab, the extensions after
+ * `/extensions enable`, the context as it fills; or the agent's own guide to its domain.
+ */
+const ok = (text) => ({ content: [{ type: "text", text }] });
+/** A tool's name as the agent's extensions give it, without the `mcp__<server>__` prefix. */
+const short = (tool) => tool.replace(/^mcp__.+?__/, "");
+/** The session's facts as the model reads them: markdown, in English (ADR-019). */
+export function describeSession(facts) {
+    const who = facts.identity
+        ? `${facts.identity.name}${facts.identity.version ? ` ${facts.identity.version}` : ""}${facts.identity.description ? `: ${facts.identity.description}` : ""}`
+        : "an agent";
+    const sections = [`# You, right now\n\nYou are ${who}, on agent-kit ${facts.kitVersion}.`];
+    const others = facts.switchableModes.filter((mode) => mode !== facts.mode);
+    sections.push(`## Mode\n\nYou are in **${facts.mode}** mode now. ${facts.switchableModes.length > 1 ? `The person can switch it with Shift+Tab to ${others.join(" or ")}.` : "It can't be switched in this session."}`);
+    const active = facts.extensions.active.map(({ name, description, tools, help }) => {
+        const toolList = tools.length ? ` Tools: ${tools.map(short).join(", ")}.` : "";
+        return `- **${name}**: ${description}${toolList}${help.map((line) => `\n  ${line}`).join("")}`;
+    });
+    const inactive = facts.extensions.inactive.map(({ name, reason }) => `- **${name}** is off: it ${reason}.`);
+    sections.push(`## Extensions\n\n${[...active, ...inactive].join("\n") || "None."}`);
+    if (facts.subagents.length)
+        sections.push(`## Subagents you can delegate to\n\n${facts.subagents.map(({ name, description }) => `- **${name}**: ${description}`).join("\n")}`);
+    const own = facts.tools.filter((tool) => !tool.startsWith("mcp__"));
+    if (own.length)
+        sections.push(`## Built-in tools\n\n${own.join(", ")}.`);
+    if (facts.commands.length) {
+        sections.push(`## Commands the person can type\n\n${facts.commands.map(({ name, description, argumentHint }) => `- \`/${name}${argumentHint ? ` ${argumentHint}` : ""}\`${description ? `: ${description}` : ""}`).join("\n")}`);
+    }
+    else if (facts.skills.length) {
+        sections.push(`## Skills\n\n${facts.skills.join(", ")}.`);
+    }
+    if (facts.context) {
+        const thousands = (tokens) => `${Math.round(tokens / 1000)}k`;
+        sections.push(`## Context\n\n${Math.round(facts.context.percentage)}% of the context window used (${thousands(facts.context.totalTokens)} of ${thousands(facts.context.maxTokens)} tokens).`);
+    }
+    return sections.join("\n\n");
+}
+/** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
+export function createAwarenessServer(session, helpGuide) {
+    const aboutMe = tool("about_me", "What you are right now: your mode and the ones the person can switch to, your extensions with their tools and the ones off (with why), your subagents, the commands the person can type, how full your context is. With `part: \"guide\"`, your own guide to your domain (your commands, configuration, folders). It changes during a session: call it whenever the person asks about you, rather than answering from memory.", { part: z.enum(["now", "guide"]).optional().describe("`now` (the default): what you are right now. `guide`: your own guide to your domain.") }, async ({ part }) => {
+        if (part === "guide") {
+            if (!helpGuide)
+                return ok("You have no guide of your own: for your domain, say only what your instructions tell you, and that the rest isn't documented.");
+            return ok(await readFile(helpGuide, "utf8"));
+        }
+        return ok(describeSession(await session()));
+    }, { annotations: { readOnlyHint: true } });
+    return createSdkMcpServer({ name: "awareness", version: "1.0.0", tools: [aboutMe] });
+}

package/dist/{core → extensions/knowledge}/fileKnowledgeStore.d.ts

@@ -1,10 +1,8 @@
 import { type KnowledgeStore, type PageType } from "./knowledgeStore.js";
 /** Options of `createFileKnowledgeStore()`. */
 export interface FileKnowledgeStoreOptions {
-    /** The agent's own page types, besides the kit's four. */
+    /** The agent's own page types, besides the kit's. */
     pageTypes?: readonly PageType[];
-    /** The sources folder: a summary's `file` field is given relative to it. */
-    sourcesDir?: string;
 }
 /** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
 export declare function createFileKnowledgeStore(knowledgeDir: string, options?: FileKnowledgeStoreOptions): KnowledgeStore;

package/dist/{core → extensions/knowledge}/fileKnowledgeStore.js

@@ -27,6 +27,8 @@ function serialize(fields, body) {
     const lines = [...fields].map(([key, value]) => `${key}: ${/[:#]/.test(value) && !/^\[.*\]$/.test(value) ? JSON.stringify(value) : value}`);
     return `---\n${lines.join("\n")}\n---\n\n${body.replace(/^\s+/, "").replace(/\s*$/, "")}\n`;
 }
+/** When a summary was written from its original (ISO 8601, as `list_sources`' `changedAt`). */
+const stampNow = () => new Date().toISOString();
 /** A `KnowledgeStore` over the markdown files of `knowledgeDir`. */
 export function createFileKnowledgeStore(knowledgeDir, options = {}) {
     const declared = options.pageTypes ?? [];
@@ -134,9 +136,9 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
         for (const [i, page] of ready.entries()) {
             const fields = newPages[i].fields ?? {};
             page.body = toFile(page.body, page.file);
-            if (page.type.type === "summary" && !("ingested" in fields))
-                page.fields.set("ingested", today());
-            await applyFields(page, fields); // may refuse a summary's missing original, before anything is written
+            await applyFields(page, fields);
+            if (page.type.type === "summary")
+                page.fields.set("ingested", stampNow());
         }
         for (const page of ready) {
             await mkdir(path.dirname(page.file), { recursive: true });
@@ -159,28 +161,20 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
         if (missing.length)
             throw new Error(`These links point to pages that don't exist: ${missing.join(", ")}. Create them first, or link existing ones (knowledge_search).`);
     }
-    /** A field given by the model, made ready to store: `file` (relative to sources/) becomes a link from the page. */
-    async function storedField(key, value, file) {
-        if (key !== "file" || !options.sourcesDir || /^[a-z]+:\/\//i.test(value))
-            return value;
-        // Relative to the sources folder; a leading "sources/" or the folder's own name is dropped.
-        let relative = value.replace(/\\/g, "/").replace(/^\.\//, "");
-        for (const prefix of ["sources/", `${path.basename(options.sourcesDir)}/`])
-            if (relative.startsWith(prefix))
-                relative = relative.slice(prefix.length);
-        const original = path.resolve(options.sourcesDir, relative);
-        if (!(await stat(original).catch(() => null))?.isFile())
-            throw new Error(`"${value}" isn't an original in sources/ (list_sources lists them).`);
-        return posix(path.relative(path.dirname(file), original));
-    }
+    /**
+     * Sets or removes the fields given. `type` is the page's, and a summary's `ingested` is the
+     * store's (when it was written from its original), so neither is taken from the caller.
+     * `file` is kept as given: the original's path relative to the sources folder, which the
+     * store doesn't check (the sources are another extension's data, #30).
+     */
     async function applyFields(page, changes = {}) {
         for (const [key, value] of Object.entries(changes)) {
-            if (key === "type")
+            if (key === "type" || key === "ingested")
                 continue;
             if (value === null)
                 page.fields.delete(key);
             else
-                page.fields.set(key, await storedField(key, value, page.file));
+                page.fields.set(key, value);
         }
         page.fields.set("updated", today());
     }
@@ -191,7 +185,8 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
     }
     /** The notice under the frontmatter of a superseded or retired page. */
     const withNotice = (body, notice) => `> ${notice}\n\n${body.replace(/^> (Superseded|Retired) on [^\n]*\n\n/, "")}`;
-    async function indexText() {
+    /** The catalog: with links as ids (`summary/kitchen`) for the tools, or as files for `index.md`. */
+    async function indexText(links = "ids") {
         const pages = (await allPages()).filter((p) => statusOf(p) !== "retired");
         const lines = ["# Index", ""];
         for (const type of types) {
@@ -202,7 +197,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
             for (const page of own) {
                 const extras = (type.indexFields ?? []).filter((f) => page.fields.get(f)).map((f) => `${f}: ${page.fields.get(f)}`);
                 const status = statusOf(page) === "superseded" ? " (superseded)" : "";
-                lines.push(`- [${titleOf(page)}](${posix(path.relative(knowledgeDir, page.file))}) — ${descriptionOf(page)}${extras.length ? ` (${extras.join(", ")})` : ""}${status}`);
+                lines.push(`- [${titleOf(page)}](${links === "ids" ? page.id : posix(path.relative(knowledgeDir, page.file))}) — ${descriptionOf(page)}${extras.length ? ` (${extras.join(", ")})` : ""}${status}`);
             }
             lines.push("");
         }
@@ -210,7 +205,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
     }
     async function writeIndex() {
         await mkdir(knowledgeDir, { recursive: true });
-        await writeFile(path.join(knowledgeDir, "index.md"), await indexText());
+        await writeFile(path.join(knowledgeDir, "index.md"), await indexText("files"));
     }
     async function pagesByFile() {
         const pages = await allPages();
@@ -265,6 +260,9 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
             await linksResolve(content, id);
             page.body = toFile(/^#\s/.test(content.trimStart()) ? content : `# ${titleOf(page)}\n\n${content}`, page.file);
             await applyFields(page, fields);
+            // A summary redone whole is redone from its original: written now.
+            if (page.type.type === "summary")
+                page.fields.set("ingested", stampNow());
             await save(page);
         },
         async supersede(id, by, reason) {
@@ -325,7 +323,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
                 .slice(0, limit)
                 .map(({ id, title, snippet }) => ({ id, title, snippet }));
         },
-        index: indexText,
+        index: () => indexText("ids"),
         async recentLog(limit = 10) {
             const text = await readFile(path.join(knowledgeDir, "log.md"), "utf8").catch(() => "");
             // Entries start with "## [date] operation | what"; the newest are at the bottom.
@@ -345,7 +343,7 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
             const reservedFiles = new Set([...RESERVED].map((name) => path.normalize(path.join(knowledgeDir, `${name}.md`))));
             const known = new Map(pages.map((p) => [p.id, p]));
             const inbound = new Map();
-            const report = { brokenLinks: [], orphans: [], linksToRetired: [], missingOriginals: [] };
+            const report = { brokenLinks: [], orphans: [], linksToRetired: [] };
             for (const page of pages) {
                 if (statusOf(page) === "retired")
                     continue;
@@ -370,13 +368,9 @@ export function createFileKnowledgeStore(knowledgeDir, options = {}) {
                     if (id !== page.id)
                         inbound.set(id, (inbound.get(id) ?? 0) + 1);
                 }
-                const file = page.fields.get("file");
-                if (file && !/^[a-z]+:\/\//i.test(file) && !(await stat(path.resolve(path.dirname(page.file), file)).catch(() => null))) {
-                    report.missingOriginals.push({ page: page.id, file });
-                }
             }
             report.orphans = pages
-                .filter((p) => statusOf(p) !== "retired" && p.type.type !== "summary" && p.type.type !== "synthesis" && !inbound.get(p.id))
+                .filter((p) => statusOf(p) !== "retired" && !["summary", "synthesis", "preference"].includes(p.type.type) && !inbound.get(p.id))
                 .map((p) => p.id);
             return report;
         },

package/dist/extensions/knowledge/index.d.ts

@@ -0,0 +1,8 @@
+import type { Extension } from "../../core/extensions.js";
+/**
+ * The built-in knowledge base (`config.knowledgeDir`, ADR-008, ADR-024): an interlinked wiki the
+ * agent keeps only through its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over
+ * markdown files, or the agent's own). Not enabled, `knowledgeDir` is left to the core as a
+ * folder of the agent's own notes.
+ */
+export declare const knowledgeExtension: Extension;

package/dist/extensions/knowledge/index.js

@@ -0,0 +1,35 @@
+import { createFileKnowledgeStore } from "./fileKnowledgeStore.js";
+import { knowledgeToolLabels } from "./labels.js";
+import { knowledgePluginRoot, knowledgePromptSection } from "./prompt.js";
+import { createKnowledgeServer } from "./tools.js";
+/**
+ * The built-in knowledge base (`config.knowledgeDir`, ADR-008, ADR-024): an interlinked wiki the
+ * agent keeps only through its `knowledge_*` tools, over a `KnowledgeStore` (the kit's over
+ * markdown files, or the agent's own). Not enabled, `knowledgeDir` is left to the core as a
+ * folder of the agent's own notes.
+ */
+export const knowledgeExtension = {
+    name: "knowledge",
+    plugin: knowledgePluginRoot(),
+    missing: ({ config }) => (config.knowledgeDir ? undefined : "needs `knowledgeDir` in the config"),
+    async contribute({ config, spec, runDir, interactive }) {
+        const knowledgeDir = config.knowledgeDir;
+        const store = spec.knowledgeStore?.(config) ?? createFileKnowledgeStore(knowledgeDir, { pageTypes: spec.knowledgePageTypes });
+        // The person's preferences, by title, for its prompt section (#33).
+        const preferences = (await store.list()).filter((page) => page.type === "preference" && page.status === "active").map(({ id, title }) => ({ id, title }));
+        return {
+            // knowledge_retire asks a person, so it exists only where there is one.
+            mcpServers: { knowledge: createKnowledgeServer(store, { runDir, interactive }) },
+            promptSection: knowledgePromptSection({ withSources: Boolean(config.sourcesDir), pageTypes: store.types(), preferences }),
+            // Never the file tools on the knowledge folder (ADR-024): the denial points to the tools.
+            toolOnlyDirs: [{ dir: knowledgeDir, instead: "the knowledge_* tools" }],
+            readOnlyTools: ["mcp__knowledge__knowledge_index", "mcp__knowledge__knowledge_search", "mcp__knowledge__knowledge_read", "mcp__knowledge__knowledge_check"],
+            selfAskingTools: ["mcp__knowledge__knowledge_retire"],
+            toolLabels: knowledgeToolLabels(),
+            helpLines: [
+                "You keep a knowledge base (your memory across sessions). Its commands: `/knowledge:ingest` (learn the new or changed files of the sources folder), `/knowledge:query <question>` (answer from it), `/knowledge:lint` (check it and fix what's mechanical).",
+            ],
+            api: { knowledgeStore: store },
+        };
+    },
+};

package/dist/{core → extensions/knowledge}/knowledgeStore.d.ts

@@ -5,7 +5,7 @@
  * skills. A page is identified by its type and slug, `concept/bowline`, and links between
  * pages use that id too: `[Bowline](concept/bowline)`.
  */
-/** A kind of page: the kit's four, or one an agent declares (`AgentSpec.knowledgePageTypes`). */
+/** A kind of page: one of the kit's, or one an agent declares (`AgentSpec.knowledgePageTypes`). */
 export interface PageType {
     /** Its name, lowercase: `concept`, `topic`. Page ids start with it. */
     type: string;
@@ -44,6 +44,7 @@ export interface PageInfo {
     status: string;
     fields: Record<string, string>;
 }
+/** A page that `search()` found, with where it matched. */
 export interface SearchHit {
     id: string;
     title: string;
@@ -57,18 +58,13 @@ export interface CheckReport {
         page: string;
         target: string;
     }[];
-    /** Pages nothing links to (summaries and syntheses aside, which the index reaches). */
+    /** Pages nothing links to (summaries, syntheses and preferences aside, which the index reaches). */
     orphans: string[];
     /** Links to retired pages. */
     linksToRetired: {
         page: string;
         target: string;
     }[];
-    /** Summary pages whose original is gone from the sources folder. */
-    missingOriginals: {
-        page: string;
-        file: string;
-    }[];
 }
 /** A page to create. */
 export interface NewPage {
@@ -110,7 +106,7 @@ export interface KnowledgeStore {
     retire(id: string, reason: string): Promise<void>;
     /** Pages matching words of `query` in their title, aliases or body, best first. */
     search(query: string, limit?: number): Promise<SearchHit[]>;
-    /** The catalog: every active or superseded page, one line each, by section. */
+    /** The catalog: every active or superseded page, one line each, by section, linked by id (`concept/bowline`), as everything the model reads. */
     index(): Promise<string>;
     /** Adds an entry to the operation log, dated today. */
     log(operation: string, what: string, pages?: readonly string[]): Promise<void>;
@@ -126,7 +122,7 @@ export interface KnowledgeStore {
     /** Replaces the overview. */
     writeOverview(content: string): Promise<void>;
 }
-/** The kit's page types (ADR-008). */
+/** The kit's page types (ADR-008), and the person's preferences (#33). */
 export declare const BUILT_IN_PAGE_TYPES: readonly PageType[];
 /** Whether `slug` is lowercase ASCII words joined by hyphens. */
 export declare function isSlug(slug: string): boolean;

package/dist/{core → extensions/knowledge}/knowledgeStore.js

@@ -5,13 +5,14 @@
  * skills. A page is identified by its type and slug, `concept/bowline`, and links between
  * pages use that id too: `[Bowline](concept/bowline)`.
  */
-/** The kit's page types (ADR-008). */
+/** The kit's page types (ADR-008), and the person's preferences (#33). */
 export const BUILT_IN_PAGE_TYPES = [
     {
         type: "summary",
         dir: "summaries",
         indexSection: "Summaries",
-        description: "One per ingested source: what it says, its key points and the pages it feeds. Fields: file (the original, relative to sources/) or url; ingested.",
+        description: "One per ingested source: what it says, its key points and the pages it feeds. Fields: file (the original, relative to the sources folder, as list_sources names it) or url; ingested (when it was written from its original, set by the knowledge base itself).",
+        indexFields: ["file", "url", "ingested"],
         template: `## Summary
 <Two to four paragraphs: what it actually says.>
 
@@ -67,6 +68,19 @@ export const BUILT_IN_PAGE_TYPES = [
         description: "An answer worth keeping: a comparison, an analysis, a report. Fields: question.",
         template: `<The answer, with links to every page it draws on.>`,
     },
+    {
+        type: "preference",
+        dir: "preferences",
+        indexSection: "Preferences",
+        description: "How the person wants things done in this project, one per page: created only from what the person said in the chat, never from a document, a web page or a tool result, and written in the language of the chat. Fields: since (the date they said it).",
+        template: `<The preference in one sentence, as the person would put it.>
+
+## Why
+- <The reason they gave, if any.>
+
+## Example
+- <What following it looks like.>`,
+    },
 ];
 const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 /** Whether `slug` is lowercase ASCII words joined by hyphens. */

package/dist/extensions/knowledge/labels.d.ts

@@ -0,0 +1,3 @@
+import { type ToolLabels } from "../../core/toolLabels.js";
+/** How the chat shows the knowledge_* tools (server `knowledge`), in the kit's language. */
+export declare function knowledgeToolLabels(): ToolLabels;