@falkenslab/agent-kit 0.18.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 language you reply in, 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/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.18.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/dist/core/agentHelp.d.ts

@@ -1,30 +0,0 @@
-import type { AgentIdentity, Mode } from "./agentSpec.js";
-/**
- * The agent's self-knowledge: who it is (a section of the system prompt) and how it is used
- * (the `agent-help` skill). The chat's part of the skill is the kit's, the same for every
- * agent and kept next to the chat's code (`assets/agent-help/SKILL.md`, checked against the
- * chat's commands and keys by a test); the agent's part is its own guide (`AgentSpec.helpGuide`).
- */
-/** The plugin the skill is loaded from, as the SDK names its skills ("agent-kit:agent-help"). */
-export declare const AGENT_HELP_SKILL = "agent-kit:agent-help";
-/** Absolute path of the kit's part of the skill, next to `dist/` (or `src/` under tsx). */
-export declare function agentHelpSkillPath(): string;
-/** The "Who you are" section appended to the system prompt: name, version, what it is, the kit's version. */
-export declare function identityPromptSection(identity: AgentIdentity): string;
-/** What the generated skill says about this session. */
-export interface AgentHelpSession {
-    mode: Mode;
-    /** The modes Shift+Tab goes through (`ModeControl.switchable`). */
-    switchable: readonly Mode[];
-    /** The built-in knowledge base is on: its slash commands exist. */
-    knowledgeBase: boolean;
-    /** The sources folder, as shown to the model (e.g. "sources/"). */
-    sourcesFolder?: string;
-}
-/**
- * Writes the `agent-help` plugin into `dir` (a folder of this run's), with the kit's part of
- * the skill, this session's facts and the agent's own guide, and returns its root. Generated
- * rather than shipped as it is: the guide goes inside the skill, so the agent needs no file
- * tools to read it, and nothing about it reaches the context until the skill is loaded.
- */
-export declare function writeAgentHelpPlugin(dir: string, session: AgentHelpSession, helpGuide?: string): Promise<string>;

package/dist/core/agentHelp.js

@@ -1,55 +0,0 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { agentKitVersion } from "./version.js";
-/**
- * The agent's self-knowledge: who it is (a section of the system prompt) and how it is used
- * (the `agent-help` skill). The chat's part of the skill is the kit's, the same for every
- * agent and kept next to the chat's code (`assets/agent-help/SKILL.md`, checked against the
- * chat's commands and keys by a test); the agent's part is its own guide (`AgentSpec.helpGuide`).
- */
-/** The plugin the skill is loaded from, as the SDK names its skills ("agent-kit:agent-help"). */
-export const AGENT_HELP_SKILL = "agent-kit:agent-help";
-/** Absolute path of the kit's part of the skill, next to `dist/` (or `src/` under tsx). */
-export function agentHelpSkillPath() {
-    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "agent-help", "SKILL.md");
-}
-/** The "Who you are" section appended to the system prompt: name, version, what it is, the kit's version. */
-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 how to use you (your modes, keys or commands, resuming an earlier conversation, your configuration, what you can do), load the \`agent-help\` skill and answer from it; don't invent options it doesn't list.`;
-}
-/** The skill's "This session" section. */
-function sessionSection(session) {
-    const lines = [
-        `- This session started in **${session.mode}** mode.`,
-        session.switchable.length > 1
-            ? `- \`Shift+Tab\` goes through: ${session.switchable.join(", ")}.`
-            : "- The mode can't be switched during this session.",
-    ];
-    if (session.knowledgeBase)
-        lines.push("- 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).");
-    if (session.sourcesFolder)
-        lines.push(`- Originals go in \`${session.sourcesFolder}\`: the person drops files there (or you ask for one, or download it), and you never change them.`);
-    return `## This session\n\n${lines.join("\n")}`;
-}
-/**
- * Writes the `agent-help` plugin into `dir` (a folder of this run's), with the kit's part of
- * the skill, this session's facts and the agent's own guide, and returns its root. Generated
- * rather than shipped as it is: the guide goes inside the skill, so the agent needs no file
- * tools to read it, and nothing about it reaches the context until the skill is loaded.
- */
-export async function writeAgentHelpPlugin(dir, session, helpGuide) {
-    const kitPart = (await readFile(agentHelpSkillPath(), "utf8")).trimEnd();
-    const guide = helpGuide ? (await readFile(helpGuide, "utf8")).trim() : "";
-    const agentPart = guide
-        ? `## This agent\n\nThe agent's own guide, for everything about its domain (its commands, configuration, folders):\n\n${guide}`
-        : "## This agent\n\nThis agent has no guide of its own: for its domain, say only what your instructions tell you, and that the rest isn't documented.";
-    await mkdir(path.join(dir, ".claude-plugin"), { recursive: true });
-    await mkdir(path.join(dir, "skills", "agent-help"), { recursive: true });
-    await writeFile(path.join(dir, ".claude-plugin", "plugin.json"), `${JSON.stringify({ name: "agent-kit", description: "How to use this agent: the kit's chat and the agent's own guide." }, null, 2)}\n`);
-    await writeFile(path.join(dir, "skills", "agent-help", "SKILL.md"), `${kitPart}\n\n${sessionSection(session)}\n\n${agentPart}\n`);
-    return dir;
-}