@falkenslab/agent-kit 0.17.0 → 0.19.0

package/dist/tui/ink/runChatInk.js

@@ -1,35 +1,31 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createWriteStream } from "node:fs";
-import path from "node:path";
 import { stdin, stdout } from "node:process";
 import { useSyncExternalStore } from "react";
 import { Box, render, Text, useInput } from "ink";
 import { Select } from "@inkjs/ui";
 import { getInteractionPort, setInteractionPort } from "../../core/interaction.js";
-import { createInputQueue, togglePlanMode } from "../../core/session.js";
-import { runQuery } from "../../core/runner.js";
-import { listRuns, readConversation } from "../../core/runs.js";
-import { capHistory, loadHistory, runChatTui, saveHistory, slashCommandToken } from "../chatTui.js";
+import { runChatTui } from "../chatTui.js";
+import { createChatController } from "../../chat/chatController.js";
 import * as ui from "../ui.js";
 import { t } from "../../core/messages/index.js";
 import { applyLanguage } from "../language.js";
 import { applyTheme, inkColor } from "../theme.js";
 import { KitTheme } from "./inkTheme.js";
-import { firstRun, openSession, runDate, runFolderOf, runLabel } from "../runs.js";
+import { runDate } from "../../chat/runs.js";
 import { createInkInteraction } from "./inkInteraction.js";
 import { PromptInput } from "./PromptInput.js";
 import { createSessionModel, liveWidth } from "./sessionModel.js";
 import { SessionView } from "./SessionView.js";
-import { fitWidth, stripAnsi } from "./lineBuffer.js";
+import { fitWidth } from "./lineBuffer.js";
 import { clipboardSequence, enterFullscreen } from "./fullscreen.js";
 import { createCursorController, CursorContext } from "./terminalCursor.js";
 import { createTerminalStatus, focusFromReport } from "./terminalStatus.js";
 import { listProjectFiles } from "./fileMentions.js";
 import { headerLines } from "./header.js";
 const DEFAULT_PROMPT_LABEL = "\n> ";
-/** The chat's own commands, never sent to the model (the agent-help skill lists them; a test keeps both in step). */
+/** The chat's own commands, never sent to the model (the awareness extension's help skill lists them; a test keeps both in step). */
 export const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
-export const LOCAL_COMMANDS = { copy: "/copy", resume: "/resume", plan: "/plan" };
+export const LOCAL_COMMANDS = { copy: "/copy", resume: "/resume", plan: "/plan", extensions: "/extensions" };
 const DEFAULT_HISTORY_LIMIT = 100;
 // The prompt's frame: a border and one column of padding on each side.
 const PROMPT_FRAME_COLUMNS = 4;
@@ -120,11 +116,12 @@ function PickerPanel({ picker }) {
     const width = liveWidth(columns) - PROMPT_FRAME_COLUMNS;
     return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: inkColor("border"), paddingX: 1, children: [_jsx(Text, { bold: true, children: picker.title }), _jsx(Select, { options: picker.options.map((option) => ({ ...option, label: fitWidth(option.label, Math.max(10, width - 2)) })), visibleOptionCount: Math.min(8, picker.options.length), onChange: (value) => picker.resolve(value) }), _jsx(Text, { dimColor: true, children: t().resumeHint })] }));
 }
-function ChatApp({ model, interaction, input, promptLabel, renderApproval, mode, fullscreen, header, onFocusChange, modeControl: currentModeControl, onInterrupt }) {
+function ChatApp({ model, interaction, input, promptLabel, renderApproval, mode, fullscreen, header, onFocusChange, controller }) {
     const chat = useSyncExternalStore(input.subscribe, input.getSnapshot);
     const session = useSyncExternalStore(model.subscribe, model.getSnapshot);
     const checkpoint = useSyncExternalStore(interaction.subscribe, interaction.getSnapshot);
-    const modeControl = currentModeControl();
+    const control = useSyncExternalStore(controller.subscribe, controller.getState);
+    const onInterrupt = () => controller.interrupt();
     // Ctrl+C stops what is running (a checkpoint, then the turn) and leaves only when idle;
     // Esc interrupts the turn but never answers a checkpoint or leaves.
     useInput((text, key) => {
@@ -139,13 +136,7 @@ function ChatApp({ model, interaction, input, promptLabel, renderApproval, mode,
         }
         if (key.shift && key.tab) {
             // Shift+Tab: the next mode this session allows.
-            if (!modeControl || modeControl.switchable.length < 2) {
-                model.note(ui.dim(t().modeLocked(modeControl?.mode ?? mode)), "notice");
-                return;
-            }
-            const next = modeControl.switchable[(modeControl.switchable.indexOf(modeControl.mode) + 1) % modeControl.switchable.length];
-            modeControl.set(next);
-            input.setMode(next);
+            controller.cycleMode();
             return;
         }
         if (key.ctrl && text === "c" && chat.picker) {
@@ -164,7 +155,7 @@ function ChatApp({ model, interaction, input, promptLabel, renderApproval, mode,
             onInterrupt();
         }
     });
-    return (_jsx(SessionView, { model: model, interaction: interaction, renderApproval: renderApproval, mode: chat.mode ?? mode, modeSwitchable: (modeControl?.switchable.length ?? 0) > 1, closed: chat.closed, fullscreen: fullscreen, header: header, onCopy: fullscreen ? (text) => void stdout.write(clipboardSequence(text)) : undefined, children: _jsxs(Box, { flexDirection: "column", children: [chat.queued.map((line, index) => (_jsx(Text, { wrap: "truncate-end", children: ui.dim(`  ${t().queued(line)}`) }, index))), chat.picker ? (_jsx(PickerPanel, { picker: chat.picker })) : (_jsx(Box, { borderStyle: "round", borderColor: inkColor("border"), paddingX: 1, children: _jsx(PromptInput, { label: promptLabel.replace(/^\n+/, ""), history: chat.history, commands: chat.commands, inset: PROMPT_FRAME_COLUMNS, suggestion: chat.suggestion, onSubmit: (line) => input.submit(line), onRecallQueued: () => input.unqueueLast(), files: chat.files, onExit: () => input.submit(null) }) }))] }) }));
+    return (_jsx(SessionView, { model: model, interaction: interaction, renderApproval: renderApproval, mode: control.mode ?? mode, modeSwitchable: control.switchableModes.length > 1, closed: chat.closed, fullscreen: fullscreen, header: header, onCopy: fullscreen ? (text) => void stdout.write(clipboardSequence(text)) : undefined, children: _jsxs(Box, { flexDirection: "column", children: [chat.queued.map((line, index) => (_jsx(Text, { wrap: "truncate-end", children: ui.dim(`  ${t().queued(line)}`) }, index))), chat.picker ? (_jsx(PickerPanel, { picker: chat.picker })) : (_jsx(Box, { borderStyle: "round", borderColor: inkColor("border"), paddingX: 1, children: _jsx(PromptInput, { label: promptLabel.replace(/^\n+/, ""), history: chat.history, commands: chat.commands, inset: PROMPT_FRAME_COLUMNS, suggestion: chat.suggestion, onSubmit: (line) => input.submit(line), onRecallQueued: () => input.unqueueLast(), files: chat.files, onExit: () => input.submit(null) }) }))] }) }));
 }
 /**
  * The Ink counterpart of `runChatTui()`, with the same options, session log and history
@@ -188,166 +179,107 @@ export async function runChatInk(options, tuiOptions = {}) {
     const languageWarnings = [];
     applyLanguage(tuiOptions.language, (line) => languageWarnings.push(line));
     applyTheme(tuiOptions.theme);
-    const opener = typeof options === "function" ? options : null;
-    const runsDir = opener ? tuiOptions.runsDir : undefined;
-    if (opener && !runsDir)
-        throw new Error("runChatInk(): a session opener needs `runsDir`.");
-    const exitCommands = new Set((tuiOptions.exitCommands ?? DEFAULT_EXIT_COMMANDS).map((c) => c.toLowerCase()));
     const promptLabel = tuiOptions.promptLabel ?? DEFAULT_PROMPT_LABEL;
     const userLine = (text) => `${promptLabel.replace(/^\n+/, "")}${text}`;
-    const historyLimit = tuiOptions.historyLimit ?? DEFAULT_HISTORY_LIMIT;
-    let historyEntries = tuiOptions.historyPath ? capHistory(await loadHistory(tuiOptions.historyPath), historyLimit) : [];
-    // The session in use: with runs, the run's folder, rebuilt on /resume.
-    let current = opener && runsDir ? await openSession(opener, await firstRun(runsDir)) : { options: options, run: null };
-    const modeControl = () => current.modeControl ?? tuiOptions.modeControl;
-    // With runs, the session log is the run's own; it moves with /resume.
-    let sessionLog = null;
-    function openLog() {
-        sessionLog?.end();
-        const file = current.run ? path.join(current.run.dir, "session.log") : tuiOptions.sessionLogPath;
-        sessionLog = file ? createWriteStream(file, { flags: "a" }) : null;
-    }
-    openLog();
-    const mirror = (text) => void sessionLog?.write(stripAnsi(text));
-    const model = createSessionModel({
+    const input = createChatInput();
+    // Set once the terminal integration is up: /copy needs it.
+    let status = null;
+    const controller = await createChatController(options, {
+        exitCommands: tuiOptions.exitCommands ?? DEFAULT_EXIT_COMMANDS,
+        initialPrompt: tuiOptions.initialPrompt,
+        sessionLogPath: tuiOptions.sessionLogPath,
+        promptLabel,
+        agentLabel: tuiOptions.agentLabel,
+        historyPath: tuiOptions.historyPath,
+        historyLimit: tuiOptions.historyLimit ?? DEFAULT_HISTORY_LIMIT,
+        runsDir: tuiOptions.runsDir,
+        modeControl: tuiOptions.modeControl,
+        toolLabels: tuiOptions.toolLabels,
         formatAction: tuiOptions.formatAction,
         toolPhrase: tuiOptions.toolPhrase,
+        promptSuggestions: tuiOptions.promptSuggestions ?? true,
+        // The /resume list in place of the prompt.
+        pick: (title, choices) => input.pick(title, choices),
+        // A local command, never sent to the model: the last reply to the clipboard (OSC 52).
+        ...(tuiOptions.terminalIntegration === false
+            ? {}
+            : {
+                commands: {
+                    copy: () => {
+                        const reply = controller.lastReply();
+                        if (reply)
+                            stdout.write(clipboardSequence(reply));
+                        model.writeLine(ui.dim(reply ? t().copiedReply(reply.length) : t().nothingToCopy));
+                    },
+                },
+            }),
+    });
+    // The screen, drawn from the controller's events; the session log is the controller's.
+    const model = createSessionModel({
+        formatAction: controller.formatAction,
+        toolPhrase: controller.toolPhrase,
         toolDetail: tuiOptions.toolDetail,
         formatResult: tuiOptions.formatResult,
         agentLabel: tuiOptions.agentLabel,
-        onWrite: mirror,
         width: () => liveWidth(stdout.columns),
     });
     const interaction = createInkInteraction((text) => model.note(text));
-    const input = createChatInput();
     if (tuiOptions.firstPromptSuggestion)
         input.setSuggestion(tuiOptions.firstPromptSuggestion);
-    void listProjectFiles(current.options.cwd ?? process.cwd()).then((files) => input.setFiles(files));
-    let turnInterrupted = false;
-    function interruptTurn() {
-        if (turnInterrupted)
-            return;
-        turnInterrupted = true;
-        void run.interrupt();
-        model.writeLine(ui.warn(t().interrupted));
-    }
-    // One reader per session instead of drainTurn()'s one per turn: the prompt suggestion
-    // arrives after its turn's turn-end, while the human is already at the prompt, and MCP
-    // errors arrive before the first turn. Still manual .next() calls, never a for-await that
-    // could be broken out of (ADR-010). A reader left behind by /resume stops reporting.
-    let turnDone = null;
-    let readError = null;
-    function finishTurn() {
-        const done = turnDone;
-        turnDone = null;
-        done?.();
-    }
-    let queue = createInputQueue();
-    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);
-        void knownCommands.then((names) => {
-            const exits = [...exitCommands].filter((c) => c.startsWith("/")).map((c) => c.slice(1));
-            const local = [
-                ...(tuiOptions.terminalIntegration === false ? [] : ["copy"]),
-                ...(runsDir ? ["resume"] : []),
-                ...(modeControl()?.switchable.includes("plan") ? ["plan"] : []),
-            ];
-            input.setCommands([...new Set([...(names ?? []), ...exits, ...local])].sort());
-        });
-        void (async () => {
-            try {
-                while (true) {
-                    const { value, done } = await events.next();
-                    if (own !== generation || done)
-                        break;
-                    if (value.type === "prompt-suggestion") {
-                        input.setSuggestion(value.suggestion);
-                        continue;
-                    }
-                    model.render(value);
-                    if (value.type === "turn-end")
-                        finishTurn();
-                }
-            }
-            catch (error) {
-                if (own === generation)
-                    readError = error;
-            }
-            if (own === generation)
-                finishTurn();
-        })();
-    }
-    connect();
-    async function runTurn(line) {
-        input.setSuggestion(null);
-        status?.turnStarted();
-        turnInterrupted = false;
-        model.separate();
-        model.startTurn();
-        const finished = new Promise((resolve) => (turnDone = resolve));
-        queue.push(line);
-        await finished;
-        model.endTurn();
-        status?.turnEnded();
-        void run.contextUsage().then((usage) => usage && model.setContextPercent(usage.percentage));
-        if (readError)
-            throw readError;
-    }
-    /** Draws the run's earlier conversation (when it has one) and says it was resumed. */
-    async function showConversation(folder, fromResume) {
-        if (!folder.sessionId)
-            return;
-        const messages = await readConversation(folder.dir);
-        const [summary] = (await listRuns(path.dirname(folder.dir))).filter((r) => path.resolve(r.dir) === path.resolve(folder.dir));
-        // In full screen the history is redrawn from the start; inline, the terminal's
-        // scrollback can't be taken back, so the conversation follows what's already there.
-        if (fromResume && tuiOptions.fullscreen)
-            model.reset();
-        model.replay(messages, userLine);
-        model.writeLine(ui.dim(t().resumed(runDate(summary?.updatedAt ?? new Date()))));
-    }
-    /** /resume: picks one of the runs and switches the session to it. */
-    async function resume() {
-        if (!opener || !runsDir)
-            return;
-        const runs = await listRuns(runsDir);
-        if (runs.length === 0) {
-            model.writeLine(ui.dim(t().noEarlierRuns));
-            return;
+    const refreshFiles = () => void listProjectFiles(controller.cwd()).then((files) => input.setFiles(files));
+    refreshFiles();
+    const toned = (text, tone) => (tone === "plain" ? text : tone === "dim" ? ui.dim(text) : tone === "warn" ? ui.warn(text) : ui.error(text));
+    controller.onEvent((event) => {
+        switch (event.type) {
+            case "agent":
+                if (event.event.type === "prompt-suggestion")
+                    input.setSuggestion(event.event.suggestion);
+                else
+                    model.render(event.event);
+                return;
+            case "user":
+                model.note(userLine(event.text), "user");
+                return;
+            case "notice":
+                model.writeLine(toned(event.text, event.tone));
+                return;
+            case "turn-start":
+                input.setSuggestion(null);
+                status?.turnStarted();
+                model.separate();
+                model.startTurn();
+                return;
+            case "turn-end":
+                model.endTurn();
+                status?.turnEnded();
+                return;
+            case "conversation":
+                // In full screen the history is redrawn from the start; inline, the terminal's
+                // scrollback can't be taken back, so the conversation follows what's already there.
+                if (event.fromResume && tuiOptions.fullscreen)
+                    model.reset();
+                model.replay(event.messages, userLine);
+                model.writeLine(ui.dim(t().resumed(runDate(event.updatedAt))));
+                return;
+            case "session":
+                refreshFiles();
+                return;
+            case "mode":
+                return; // the status bar follows the state
         }
-        const chosen = await input.pick(t().resumeTitle, runs.map((summary, i) => ({ label: `${i + 1}. ${runLabel(summary, current.run ?? undefined)}`, value: summary.dir })));
-        const summary = runs.find((r) => r.dir === chosen);
-        if (!summary || (current.run && path.resolve(summary.dir) === path.resolve(current.run.dir)))
-            return;
-        queue.end();
-        run.close();
-        current = await openSession(opener, await runFolderOf(summary));
-        openLog();
-        connect();
-        await showConversation(current.run, true);
-    }
+    });
+    controller.subscribe((state) => {
+        input.setCommands(state.commands);
+        if (state.contextPercent !== model.getSnapshot().contextPercent)
+            model.setContextPercent(state.contextPercent);
+    });
     const previousPort = getInteractionPort();
     setInteractionPort(interaction.port);
     const restoreTerminal = tuiOptions.fullscreen ? enterFullscreen(stdout) : null;
     const cursor = tuiOptions.fullscreen ? createCursorController(stdout) : null;
-    const status = tuiOptions.terminalIntegration === false ? null : createTerminalStatus((text) => void stdout.write(text), tuiOptions.header?.title ?? "agent");
+    status = tuiOptions.terminalIntegration === false ? null : createTerminalStatus((text) => void stdout.write(text), tuiOptions.header?.title ?? "agent");
     status?.start();
-    const app = render(_jsx(CursorContext.Provider, { value: cursor, children: _jsx(KitTheme, { children: _jsx(ChatApp, { model: model, interaction: interaction, input: input, promptLabel: promptLabel, renderApproval: tuiOptions.renderApproval, mode: tuiOptions.mode, fullscreen: tuiOptions.fullscreen, header: tuiOptions.header && tuiOptions.fullscreen ? headerLines(tuiOptions.header) : undefined, onFocusChange: status ? (focused) => status.setFocused(focused) : undefined, modeControl: modeControl, onInterrupt: interruptTurn }) }) }), 
+    const app = render(_jsx(CursorContext.Provider, { value: cursor, children: _jsx(KitTheme, { children: _jsx(ChatApp, { model: model, interaction: interaction, input: input, promptLabel: promptLabel, renderApproval: tuiOptions.renderApproval, mode: tuiOptions.mode, fullscreen: tuiOptions.fullscreen, header: tuiOptions.header && tuiOptions.fullscreen ? headerLines(tuiOptions.header) : undefined, onFocusChange: status ? (focused) => status?.setFocused(focused) : undefined, controller: controller }) }) }), 
     // In full screen Ink writes through the cursor controller, which places the terminal's cursor.
     { exitOnCtrlC: false, ...(cursor ? { stdout: cursor.stream } : {}) });
     try {
@@ -355,71 +287,24 @@ export async function runChatInk(options, tuiOptions = {}) {
         if (tuiOptions.header && !tuiOptions.fullscreen)
             model.note(headerLines(tuiOptions.header).join("\n"));
         for (const warning of languageWarnings)
-            model.writeLine(ui.warn(warning));
+            controller.notice(warning, "warn");
         if (tuiOptions.welcomeMessage)
-            model.writeLine(tuiOptions.welcomeMessage);
-        if (current.run)
-            await showConversation(current.run, false);
-        if (tuiOptions.initialPrompt && !current.run?.sessionId) {
-            // Logged but not shown, like runChatTui(): it is the agent's cue, not something typed.
-            mirror(`${promptLabel}${tuiOptions.initialPrompt}\n`);
-            await runTurn(tuiOptions.initialPrompt);
-        }
+            controller.notice(tuiOptions.welcomeMessage, "plain");
+        await controller.start();
         while (true) {
             // The blank line before the prompt is in place while typing, so Enter doesn't push
             // everything down a line: promptLabel's own leading newlines only reach the log.
             model.separate();
-            const raw = await input.next(historyEntries.map((entry) => entry.text));
-            if (raw === null)
+            const line = await input.next(controller.getState().history);
+            if (line === null)
                 break;
-            const line = raw.trim();
-            if (!line)
-                continue;
-            mirror(`${promptLabel}${line}\n`);
-            model.note(userLine(line), "user");
-            if (tuiOptions.historyPath) {
-                historyEntries = capHistory([...historyEntries, { text: line, timestamp: new Date().toISOString() }], historyLimit);
-                await saveHistory(tuiOptions.historyPath, historyEntries);
-            }
-            if (exitCommands.has(line.toLowerCase()))
+            if ((await controller.send(line)) === "exit")
                 break;
-            // A local command, never sent to the model: the last reply to the clipboard (OSC 52).
-            if (status && line.toLowerCase() === LOCAL_COMMANDS.copy) {
-                const reply = model.lastReply();
-                if (reply)
-                    stdout.write(clipboardSequence(reply));
-                model.writeLine(ui.dim(reply ? t().copiedReply(reply.length) : t().nothingToCopy));
-                continue;
-            }
-            if (runsDir && line.toLowerCase() === LOCAL_COMMANDS.resume) {
-                await resume();
-                continue;
-            }
-            // A local command too: into plan mode, or back to the mode it was entered from.
-            if (line.toLowerCase() === LOCAL_COMMANDS.plan) {
-                const control = modeControl();
-                const next = control ? togglePlanMode(control) : null;
-                if (next)
-                    input.setMode(next);
-                else
-                    model.writeLine(ui.dim(t().modeLocked(control?.mode ?? tuiOptions.mode)));
-                continue;
-            }
-            const commandToken = slashCommandToken(line);
-            if (commandToken) {
-                const names = await knownCommands;
-                if (names && !names.has(commandToken)) {
-                    model.writeLine(ui.warn(t().unknownCommand(commandToken)));
-                    continue;
-                }
-            }
-            await runTurn(line);
         }
     }
     finally {
         setInteractionPort(previousPort);
-        queue.end();
-        run.close();
+        controller.close();
         input.close();
         // One more frame with only the history, so the prompt and status bar don't stay behind.
         await new Promise((resolve) => setTimeout(resolve, 0));
@@ -427,6 +312,5 @@ export async function runChatInk(options, tuiOptions = {}) {
         await app.waitUntilExit();
         status?.stop();
         restoreTerminal?.();
-        sessionLog?.end();
     }
 }

package/extensions/awareness/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "awareness",
+  "description": "You know who you are and what you are right now (your mode, extensions, tools, subagents, commands, context) through about_me, and how your chat is used through the help skill.",
+  "agent-kit": {
+    "provides": [
+      "self-awareness"
+    ],
+    "requires": []
+  }
+}

package/{assets/agent-help → extensions/awareness/skills/help}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: agent-help
-description: How to use this agent - its chat's modes, keys and slash commands, resuming an earlier conversation, approvals and questions, the command line, and the agent's own commands and configuration. Load it whenever the person asks how to do something with you, what a key or command does, or what you can do.
+name: help
+description: How to use this agent's chat - its modes, keys and slash commands, resuming an earlier conversation, approvals and questions, the command line. Load it whenever the person asks how to do something with you, or what a key or command does.
 ---
 
 # Helping the person use you
 
-Answer from this page only: the chat's part below is the same for every agent built on agent-kit, and the "This session" and "This agent" sections at the end are about you. If something isn't covered here, say you don't know rather than inventing a key, command or option. Answer in the person's language, briefly, with the exact key or command; keys and commands are typed as written here, whatever the language.
+This page is the chat's part, the same for every agent built on agent-kit. What you are right now (your mode, the commands this session has, your extensions) comes from `about_me`, and your own domain from `about_me` with `part: "guide"`. If something is in none of them, say you don't know rather than inventing a key, command or option. Answer in the language you reply in, briefly, with the exact key or command; keys and commands are typed as written here, whatever the language.
 
 ## Modes
 
@@ -45,6 +45,7 @@ Messages typed while the agent works are queued and sent when it finishes.
 - `/exit` or `/quit`: leave the chat (an agent can name its own exit commands instead).
 - `/copy`: copy the last reply to the clipboard.
 - `/resume`: pick an earlier conversation to go on with (`↑`/`↓`, `Enter`, `Esc` to cancel), where the agent keeps its conversations.
+- `/extensions`: what the session runs with, what's off and why, and the extensions installed; `/extensions enable <name>` or `/extensions disable <name>` turns an installed one on or off and reopens the session, keeping the conversation.
 - `/plan`: plan mode on or off (see Modes).
 
 Typing `/` and `Tab` lists every command, the agent's own included (named `/plugin:command`). An unknown `/command` isn't sent.

package/{assets/knowledge-plugin → extensions/knowledge}/.claude-plugin/plugin.json

@@ -1,4 +1,10 @@
 {
   "name": "knowledge",
-  "description": "Built-in knowledge base workflows (an LLM wiki) over the kit's knowledge_* tools: ingesting sources, querying the knowledge base and health-checking it."
+  "description": "Built-in knowledge base workflows (an LLM wiki) over the kit's knowledge_* tools: ingesting sources, querying the knowledge base and health-checking it.",
+  "agent-kit": {
+    "provides": [
+      "knowledge-base"
+    ],
+    "requires": []
+  }
 }

package/extensions/knowledge/commands/ingest.md

@@ -0,0 +1,7 @@
+---
+description: Ingest material into the knowledge base right now - the files or topic given, or everything in sources/ not ingested yet
+---
+
+Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
+
+If nothing is given above, ingest every original in `list_sources` that no summary is about, and update the summaries whose original's `changedAt` is after their `ingested` (both ISO 8601 in UTC: the later one sorts after as text). When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/{assets/knowledge-plugin → extensions/knowledge}/skills/knowledge-ingest/SKILL.md

@@ -9,7 +9,12 @@ A source is ingested once, and from then on the knowledge base holds what it tau
 
 ## 1. Check it isn't already ingested
 
-`list_sources` gives each original's status and summary pages: *new* needs ingesting; *ingested* has a page; *changed* changed after its ingest (update its summary). For a document from elsewhere, `knowledge_search` its title or URL.
+The sources and the knowledge base each keep their own data; you match them:
+
+- `list_sources` gives each original with `changedAt`, when its content last changed.
+- `knowledge_index` gives each summary with `file`, the original it's about, and `ingested`, when it was written.
+
+An original with no summary needs ingesting. One whose `changedAt` is after its summary's `ingested` changed since: update its summary (`knowledge_rewrite`, which sets `ingested` again). Both dates are ISO 8601 in UTC, so the later one sorts after as text; use `date_math` if in doubt. For a document from elsewhere, `knowledge_search` its title or URL.
 
 ## 2. Read it for real
 
@@ -17,7 +22,7 @@ Read the whole source, not its first page (a long PDF in parts: `list_sources` g
 
 ## 3. Write the summary page
 
-`knowledge_create` with type `summary` (call it once without content to get the template), and the field `file` (the original, relative to sources/) or `url`. Key points quote literally where exactness matters. Create the new concept and entity pages it feeds in the same call (`also`): they can link to each other.
+`knowledge_create` with type `summary` (call it once without content to get the template), and the field `file` (the original, exactly as `list_sources` names it) or `url`; `ingested` is set for you. Key points quote literally where exactness matters. Create the new concept and entity pages it feeds in the same call (`also`): they can link to each other.
 
 ## 4. Update concepts and entities
 
@@ -33,4 +38,4 @@ If the source contradicts a page, record both versions with attribution in both
 
 ## An original that was wrong or replaced
 
-`retire_source` (the person approves it) moves it aside and marks its summary retired (wrong) or superseded (replaced). Then `knowledge_check` lists the passages that cite it: after a wrong one, correct or remove what it taught (`knowledge_edit`, or `knowledge_retire` for a page that was only about it); after a replaced one, ingest the new original and re-ground those passages on it.
+`retire_source` (it asks the person itself) moves it aside; `list_sources` shows it as retired, with why and what replaced it. The knowledge base is then yours to update: find its summaries (`knowledge_index`, by `file`) and the passages that cite it (`knowledge_search` its file name). After a wrong one, `knowledge_retire` its summary (it asks the person itself: don't ask them first) and correct or remove what it taught (`knowledge_edit`, or `knowledge_retire` for a page that was only about it). After a replaced one, ingest the new original, `knowledge_supersede` the old summary by the new one, and re-ground those passages on it.

package/{assets/knowledge-plugin → extensions/knowledge}/skills/knowledge-lint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-lint
-description: Health-check the knowledge base - broken links, orphan pages, links to retired pages, missing or changed originals, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
+description: Health-check the knowledge base - broken links, orphan pages, links to retired pages, summaries behind their originals, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
 ---
 
 # Linting the knowledge base
@@ -9,14 +9,21 @@ A knowledge base maintained across sessions drifts. Lint it when asked and after
 
 ## 1. The mechanical checks, in one call
 
-`knowledge_check` returns broken links, orphan pages, links to retired pages, summaries whose original is gone, originals that are new, changed or missing, and the passages that cite a retired original. The index and backlinks are kept by the store: there's nothing to fix there.
+`knowledge_check` returns broken links, orphan pages and links to retired pages. The index and backlinks are kept by the store: there's nothing to fix there.
 
 - **Broken links**: fix them with `knowledge_edit` when the right target is obvious (a typo, a page under a close name: `knowledge_search`); otherwise report them.
 - **Orphans**: link them from the pages where they belong, or report why they don't belong anywhere.
-- **Links to retired pages, passages citing a retired original**: correct or re-ground them.
-- **New or changed originals**: report them as what to ingest or update next (or do it, if asked).
+- **Links to retired pages**: correct or re-ground them.
 
-## 2. The checks that need judgement
+## 2. The knowledge base against its originals
+
+When there's a sources folder, match `list_sources` with `knowledge_index`:
+
+- **Not ingested**: present originals no summary is about. Report them as what to ingest next (or do it, if asked).
+- **Behind**: summaries whose original's `changedAt` is after their `ingested`, (ISO 8601 in UTC: the later one sorts after as text). Report them as what to update.
+- **Retired or missing originals**: summaries still active whose original is retired (`knowledge_retire` them if it was wrong, which asks the person itself, or `knowledge_supersede` them if it was replaced) or missing (report them); and the passages that cite them (`knowledge_search` the file name).
+
+## 3. The checks that need judgement
 
 Use `knowledge_index` and `knowledge_search`; read only the pages a check needs.
 

package/extensions/memory/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "memory",
+  "description": "Your memory of the person you work for, across all their projects: who they are and how they want things done, kept only from what they tell you, through its tools: recall, remember and forget.",
+  "agent-kit": {
+    "provides": [
+      "person-memory"
+    ],
+    "requires": []
+  }
+}

package/extensions/memory/commands/forget.md

@@ -0,0 +1,8 @@
+---
+description: Forget an entry of what the agent remembers about you
+argument-hint: <entry>
+---
+
+The person wants you to forget this from your memory of them: $ARGUMENTS
+
+Find the entry with `recall` (by name, or the one whose description matches) and `forget` it, then say which one you forgot. If nothing is given above, or several entries match, show them and ask which. Stop applying what it said from now on.

package/extensions/memory/commands/list.md

@@ -0,0 +1,5 @@
+---
+description: Show what the agent remembers about you, across all your projects
+---
+
+Call `recall`, without a name, right now and show the person everything you remember about them, grouped by type (who they are, how they want things done), one short line per entry with its name. If it's empty, say so. End by telling them `/memory:forget <entry>` forgets an entry, or that they can just tell you what's wrong.

package/extensions/sources/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "sources",
+  "description": "The sources folder: originals kept as obtained, listed, downloaded, asked for and retired through the kit's sources tools.",
+  "agent-kit": {
+    "provides": [
+      "sources"
+    ],
+    "requires": []
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",
@@ -32,7 +32,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "assets"
+    "assets",
+    "extensions"
   ],
   "scripts": {
     "build": "tsc",

package/assets/knowledge-plugin/commands/ingest.md

@@ -1,7 +0,0 @@
----
-description: Ingest material into the knowledge base right now - the files or topic given, or everything in sources/ not ingested yet
----
-
-Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
-
-If nothing is given above, ingest every original `list_sources` reports as new, and update the summaries of the ones it reports as changed. When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin/commands/query.md

@@ -1,5 +0,0 @@
----
-description: Answer a question from the knowledge base, and file the answer back if it is worth keeping
----
-
-Apply the `knowledge-query` skill right now to answer: $ARGUMENTS

package/assets/knowledge-plugin-files/.claude-plugin/plugin.json

@@ -1,4 +0,0 @@
-{
-  "name": "knowledge",
-  "description": "Built-in knowledge base workflows (an LLM wiki): page templates, ingesting sources, querying the knowledge base and health-checking it."
-}