@falkenslab/agent-kit 0.18.0 → 0.20.0

package/dist/chat/chatController.js

@@ -0,0 +1,536 @@
+import { createWriteStream } from "node:fs";
+import path from "node:path";
+import { getInteractionPort, setInteractionPort } from "../core/interaction.js";
+import { getLanguage, switchLanguage, t } from "../core/messages/index.js";
+import { LANGUAGE_NAMES } from "../core/language.js";
+import { runQuery } from "../core/runner.js";
+import { createRunFolder, listRuns, readConversation, readRunSession } from "../core/runs.js";
+import { createInputQueue, togglePlanMode } from "../core/session.js";
+import { hasOpenTodos, parseTodos, TODO_TOOL } from "../core/todos.js";
+import { withToolLabels, withToolPhrases } from "../core/toolLabels.js";
+import { createConsoleRenderer } from "../tui/consoleRenderer.js";
+import { chatExtensionsCommand } from "./extensions.js";
+import { setExtensionEnabled } from "../core/externalExtensions.js";
+import { capHistory, loadHistory, saveHistory, slashCommandToken } from "./history.js";
+import { firstRun, openSession, runFolderOf, runLabel } from "./runs.js";
+const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
+const DEFAULT_HISTORY_LIMIT = 100;
+const DEFAULT_PROMPT_LABEL = "\n> ";
+/**
+ * Opens the chat's session (the first run with a session opener, `--continue` picking the
+ * latest) and loads the history; `start()` then draws the run's conversation and sends the
+ * initial prompt, `send()` each line the person types.
+ */
+export async function createChatController(options, settings = {}) {
+    const opener = typeof options === "function" ? options : null;
+    const runsDir = opener ? settings.runsDir : undefined;
+    if (opener && !runsDir)
+        throw new Error("A chat with a session opener needs `runsDir`.");
+    const exitCommands = new Set((settings.exitCommands ?? DEFAULT_EXIT_COMMANDS).map((command) => command.toLowerCase()));
+    const promptLabel = settings.promptLabel ?? DEFAULT_PROMPT_LABEL;
+    const historyLimit = settings.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+    let historyEntries = settings.historyPath ? capHistory(await loadHistory(settings.historyPath), historyLimit) : [];
+    // The session in use: with runs, the run's folder, opened again on /resume or /extensions.
+    let current = opener && runsDir ? await openSession(opener, await firstRun(runsDir)) : { options: options, run: null };
+    const modeControl = () => current.modeControl ?? settings.modeControl;
+    const formatAction = withToolLabels(() => current.toolLabels ?? settings.toolLabels, settings.formatAction);
+    const toolPhrase = withToolPhrases(() => current.toolLabels ?? settings.toolLabels, settings.toolPhrase);
+    // State and listeners.
+    const stateListeners = new Set();
+    const eventListeners = new Set();
+    let nextId = 0;
+    let state = {
+        transcript: [],
+        busy: false,
+        turnStartedAt: null,
+        activity: null,
+        subagentActivity: null,
+        todos: null,
+        mode: null,
+        switchableModes: [],
+        turns: 0,
+        usage: null,
+        contextPercent: null,
+        suggestion: null,
+        commands: [],
+        commandDetails: [],
+        language: getLanguage(),
+        history: historyEntries.map((entry) => entry.text),
+        panel: null,
+        choice: null,
+        run: current.run,
+        extensions: current.extensions ?? null,
+        closed: false,
+    };
+    function update(changes) {
+        state = { ...state, ...changes };
+        for (const listener of stateListeners)
+            listener(state);
+    }
+    function emit(event) {
+        for (const listener of eventListeners)
+            listener(event);
+    }
+    function addEntry(entry) {
+        update({ transcript: [...state.transcript, entry] });
+    }
+    // The session log: the console's text, as the plain chat would print it.
+    let sessionLog = null;
+    function openLog() {
+        sessionLog?.end();
+        const file = current.run ? path.join(current.run.dir, "session.log") : settings.sessionLogPath;
+        sessionLog = file ? createWriteStream(file, { flags: "a" }) : null;
+    }
+    openLog();
+    // eslint-disable-next-line no-control-regex -- ESC starts the SGR sequences the renderer writes
+    const log = (text) => void sessionLog?.write(text.replace(/\x1b\[[0-9;]*m/g, ""));
+    const logRenderer = createConsoleRenderer({ formatAction, agentLabel: settings.agentLabel, output: () => { }, onWrite: log });
+    /** A notice: in the transcript, to the views, and in the session log. */
+    function notice(text, tone = "dim") {
+        logRenderer.writeLine(text);
+        addEntry({ id: nextId++, kind: "notice", tone, text });
+        emit({ type: "notice", tone, text });
+    }
+    /** What the agent does, into the transcript. */
+    function record(event) {
+        const last = state.transcript.at(-1);
+        switch (event.type) {
+            case "text":
+                if (last?.kind === "agent")
+                    update({ transcript: [...state.transcript.slice(0, -1), { ...last, text: last.text + event.text }] });
+                else
+                    addEntry({ id: nextId++, kind: "agent", text: event.text });
+                return;
+            case "action": {
+                const todos = event.toolName === TODO_TOOL ? parseTodos(event.input) : null;
+                if (todos) {
+                    const doing = todos.find((todo) => todo.status === "in_progress");
+                    update({ todos: hasOpenTodos(todos) ? todos : null, activity: doing?.activeForm ?? state.activity });
+                    return;
+                }
+                const label = formatAction(event.toolName, event.input);
+                const call = { ...(event.toolUseId ? { id: event.toolUseId } : {}), toolName: event.toolName, label, result: null, children: [] };
+                const transcript = last?.kind === "tools" ? [...state.transcript.slice(0, -1), { ...last, calls: [...last.calls, call] }] : [...state.transcript, { id: nextId++, kind: "tools", calls: [call] }];
+                update({ transcript, activity: label, subagentActivity: null });
+                return;
+            }
+            case "tool-result":
+            case "subagent-action": {
+                if (event.type === "tool-result" && event.toolName === TODO_TOOL)
+                    return;
+                const id = event.type === "tool-result" ? event.toolUseId : event.parentToolUseId;
+                const label = event.type === "subagent-action" ? formatAction(event.toolName, event.input) : null;
+                const transcript = state.transcript.map((entry) => entry.kind !== "tools" || !entry.calls.some((call) => call.id !== undefined && call.id === id)
+                    ? entry
+                    : {
+                        ...entry,
+                        calls: entry.calls.map((call) => call.id !== id ? call : event.type === "tool-result" ? { ...call, result: { isError: event.isError, text: event.text } } : { ...call, children: [...call.children, label] }),
+                    });
+                update({ transcript, ...(label ? { subagentActivity: label } : {}) });
+                return;
+            }
+            case "mcp-error":
+                addEntry({ id: nextId++, kind: "notice", tone: "warn", text: t().mcpFailed(event.failedServers.join(", ")) });
+                return;
+            case "info":
+                addEntry({ id: nextId++, kind: "notice", tone: event.level === "warning" ? "warn" : "dim", text: `(${event.text})` });
+                return;
+            case "turn-end":
+                if (event.failed && event.errorText)
+                    addEntry({ id: nextId++, kind: "notice", tone: "error", text: event.errorText });
+                update({ turns: state.turns + 1, usage: event.usage ?? state.usage });
+                return;
+            case "prompt-suggestion":
+                update({ suggestion: event.suggestion });
+                return;
+        }
+    }
+    // The agent run: one reader per session, never a for-await that could be broken out of
+    // (ADR-010); a reader left behind by a reopened session stops reporting.
+    let queue = createInputQueue();
+    let run;
+    let knownCommands;
+    let generation = 0;
+    let turnDone = null;
+    let readError = null;
+    let unsubscribeMode;
+    let interrupted = false;
+    function finishTurn() {
+        const done = turnDone;
+        turnDone = null;
+        done?.();
+    }
+    /** The commands the session has, and the chat's own, into the state: when it opens, and when an extension is switched in it. */
+    function loadCommands() {
+        const own = generation;
+        const control = modeControl();
+        const supported = run.supportedCommands().catch(() => null);
+        knownCommands = supported.then((commands) => (commands ? new Set(commands.flatMap((command) => [command.name, ...(command.aliases ?? [])])) : null));
+        void supported.then((commands) => {
+            if (own !== generation)
+                return;
+            const exits = [...exitCommands].filter((command) => command.startsWith("/")).map((command) => command.slice(1));
+            const viewCommands = Object.keys(settings.commands ?? {}).map((name) => ({ name, description: "", argumentHint: "" }));
+            const local = [
+                ...viewCommands,
+                ...(runsDir ? [{ name: "resume", description: t().commandResume, argumentHint: "" }] : []),
+                ...(control?.switchable.includes("plan") ? [{ name: "plan", description: t().commandPlan, argumentHint: "" }] : []),
+                { name: "extensions", description: t().commandExtensions, argumentHint: "[enable|disable <name>]" },
+            ];
+            const details = new Map();
+            for (const command of [...(commands ?? []).map(({ name, description, argumentHint }) => ({ name, description: description ?? "", argumentHint: argumentHint ?? "" })), ...local])
+                details.set(command.name, command);
+            for (const name of exits)
+                if (!details.has(name))
+                    details.set(name, { name, description: "", argumentHint: "" });
+            const sorted = [...details.values()].sort((a, b) => a.name.localeCompare(b.name));
+            update({ commands: sorted.map((command) => command.name), commandDetails: sorted });
+        });
+    }
+    function connect() {
+        const own = ++generation;
+        queue = createInputQueue({ modeControl: modeControl() });
+        run = (settings.runQuery ?? runQuery)(queue.iterable, { ...current.options, promptSuggestions: settings.promptSuggestions ?? true });
+        const events = run.events[Symbol.asyncIterator]();
+        const control = modeControl();
+        update({ mode: control?.mode ?? null, switchableModes: control?.switchable ?? [], run: current.run, extensions: current.extensions ?? null });
+        unsubscribeMode?.();
+        unsubscribeMode = control?.subscribe?.((mode) => {
+            update({ mode });
+            emit({ type: "mode", mode });
+        });
+        loadCommands();
+        void (async () => {
+            try {
+                while (true) {
+                    const { value, done } = await events.next();
+                    if (own !== generation || done)
+                        break;
+                    if (value.type !== "prompt-suggestion")
+                        logRenderer.render(value);
+                    record(value);
+                    emit({ type: "agent", event: value });
+                    if (value.type === "turn-end")
+                        finishTurn();
+                }
+            }
+            catch (error) {
+                if (own === generation)
+                    readError = error;
+            }
+            if (own === generation)
+                finishTurn();
+        })();
+    }
+    // The agent's text in the latest turn (for /copy), kept when it ends.
+    let latestReply = "";
+    // A language switched to, told to the model with the next message (as a mode change is): the
+    // session's prompt says it already, but a conversation in another language pulls the replies.
+    let languageNotice = null;
+    // Extensions turned off or on in the running session, told to the model with the next message
+    // too: the prompt's Extensions section still says what the session opened with.
+    const extensionNotices = [];
+    async function runTurn(line) {
+        interrupted = false;
+        const from = state.transcript.length;
+        const startedAt = Date.now();
+        logRenderer.startTurn();
+        update({ busy: true, turnStartedAt: startedAt, activity: null, subagentActivity: null, suggestion: null });
+        emit({ type: "turn-start" });
+        const finished = new Promise((resolve) => (turnDone = resolve));
+        const notices = [languageNotice, ...extensionNotices.splice(0)].filter(Boolean);
+        queue.push(notices.length ? `${notices.join("\n")}\n\n${line}` : line);
+        languageNotice = null;
+        await finished;
+        logRenderer.endLine();
+        latestReply = state.transcript.slice(from).flatMap((entry) => (entry.kind === "agent" ? [entry.text] : [])).join("").trim();
+        const seconds = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
+        addEntry({ id: nextId++, kind: "turn-summary", seconds });
+        update({ busy: false, turnStartedAt: null, activity: null, subagentActivity: null });
+        emit({ type: "turn-end", seconds });
+        void run.contextUsage().then((usage) => usage && update({ contextPercent: usage.percentage }));
+        if (readError)
+            throw readError;
+    }
+    /** Draws a run's earlier conversation, if it has one. */
+    async function showConversation(folder, fromResume) {
+        if (!folder.sessionId)
+            return;
+        const messages = await readConversation(folder.dir);
+        const [summary] = (await listRuns(path.dirname(folder.dir))).filter((other) => path.resolve(other.dir) === path.resolve(folder.dir));
+        const updatedAt = summary?.updatedAt ?? new Date();
+        const replayed = messages.map((message) => ({ id: nextId++, kind: message.role === "user" ? "user" : "agent", text: message.text }));
+        update({ transcript: fromResume ? replayed : [...state.transcript, ...replayed], turns: (fromResume ? 0 : state.turns) + messages.filter((message) => message.role === "user").length });
+        emit({ type: "conversation", messages, updatedAt, fromResume });
+    }
+    /** Switches to another session: a run resumed, or the same one opened again. */
+    /** An extension whose lock just changed: switched in the running session if it can be, the session opened again if not. */
+    async function applyExtension(name, enabled) {
+        if (await current.switchExtension?.(name, enabled).catch(() => false)) {
+            notice(t().extensionSwitched(name, enabled));
+            extensionNotices.push(enabled
+                ? `<system-reminder>The user turned the ${name} extension back on: its tools, skills and commands are available again.</system-reminder>`
+                : `<system-reminder>The user turned the ${name} extension off: its tools, skills, commands and subagents are gone until it's turned on again, whatever your instructions or earlier messages say.</system-reminder>`);
+            update({ extensions: current.extensions ? { ...current.extensions } : null });
+            loadCommands();
+            return;
+        }
+        notice(t().extensionToggled(name, enabled));
+        await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+    }
+    async function switchTo(folder, fromResume) {
+        queue.end();
+        run.close();
+        current = await openSession(opener, folder);
+        if (fromResume)
+            openLog();
+        connect();
+        emit({ type: "session" });
+        if (fromResume)
+            await showConversation(current.run, true);
+    }
+    // A choice in place of the prompt, when the view doesn't ask it itself.
+    let choiceResolve = null;
+    function pick(title, options) {
+        if (settings.pick)
+            return settings.pick(title, options);
+        return new Promise((resolve) => {
+            choiceResolve = (value) => {
+                choiceResolve = null;
+                update({ choice: null });
+                resolve(value);
+            };
+            update({ choice: { title, options } });
+        });
+    }
+    // The controller's own interaction port (`panels: "state"`): a checkpoint is the state's panel.
+    const answers = new Map();
+    function ask(question, signal) {
+        const id = nextId++;
+        return new Promise((resolve) => {
+            const settle = (answer) => {
+                answers.delete(id);
+                if (state.panel?.id === id)
+                    update({ panel: null });
+                resolve(answer);
+            };
+            answers.set(id, settle);
+            signal.addEventListener("abort", () => answers.has(id) && settle(""), { once: true });
+            update({ panel: { ...question, id } });
+        });
+    }
+    const statePort = {
+        askDecision: (prompt, signal) => ask({ kind: "decision", prompt }, signal),
+        askManualIntervention: (prompt, signal) => ask({ kind: "manual", prompt }, signal),
+        askText: (prompt, signal) => ask({ kind: "text", prompt }, signal),
+        askChoice: (prompt, choice, signal) => ask({ kind: "choice", prompt, choice }, signal),
+        notify: (message) => notice(message),
+    };
+    const previousPort = settings.panels === "state" ? getInteractionPort() : null;
+    if (settings.panels === "state")
+        setInteractionPort(statePort);
+    connect();
+    const controller = {
+        /** The state now. */
+        getState: () => state,
+        /** Calls `listener` with every new state; returns how to stop. */
+        subscribe(listener) {
+            stateListeners.add(listener);
+            return () => stateListeners.delete(listener);
+        },
+        /** Calls `listener` with every event, in order; returns how to stop. */
+        onEvent(listener) {
+            eventListeners.add(listener);
+            return () => eventListeners.delete(listener);
+        },
+        /** Tool call labels and phrases with the extensions' (for a view that renders events itself). */
+        formatAction,
+        toolPhrase,
+        /** The folder the session works in. */
+        cwd: () => current.options.cwd ?? process.cwd(),
+        /** Draws the run's earlier conversation, then sends the initial prompt (for a new run). */
+        async start() {
+            if (current.run)
+                await showConversation(current.run, false);
+            if (settings.initialPrompt && !current.run?.sessionId) {
+                // Logged but not shown: it's the agent's cue, not something the person typed.
+                log(`${promptLabel}${settings.initialPrompt}\n`);
+                await runTurn(settings.initialPrompt);
+            }
+        },
+        /**
+         * A line the person sent: an exit command ("exit"), one of the chat's commands, or a turn,
+         * resolved when it ends. An unknown slash command is caught before it reaches the model.
+         */
+        async send(raw) {
+            const line = raw.trim();
+            if (!line)
+                return;
+            log(`${promptLabel}${line}\n`);
+            addEntry({ id: nextId++, kind: "user", text: line });
+            emit({ type: "user", text: line });
+            if (settings.historyPath) {
+                historyEntries = capHistory([...historyEntries, { text: line, timestamp: new Date().toISOString() }], historyLimit);
+                update({ history: historyEntries.map((entry) => entry.text) });
+                await saveHistory(settings.historyPath, historyEntries);
+            }
+            const lower = line.toLowerCase();
+            if (exitCommands.has(lower))
+                return "exit";
+            const own = settings.commands?.[lower.slice(1)];
+            if (lower.startsWith("/") && own)
+                return void (await own());
+            if (runsDir && lower === "/resume")
+                return void (await controller.resume());
+            if (lower === "/plan")
+                return void controller.togglePlan();
+            const extensions = await chatExtensionsCommand(line, current.extensions, Boolean(opener && current.run));
+            if (extensions) {
+                for (const text of extensions.lines)
+                    notice(text);
+                if (extensions.toggled)
+                    await applyExtension(extensions.toggled.name, extensions.toggled.enabled);
+                return;
+            }
+            const token = slashCommandToken(line);
+            if (token) {
+                const names = await knownCommands;
+                if (names && !names.has(token))
+                    return notice(t().unknownCommand(token), "warn");
+            }
+            await runTurn(line);
+        },
+        /** Stops the turn running, if any. */
+        interrupt() {
+            if (!state.busy || interrupted)
+                return;
+            interrupted = true;
+            void run.interrupt();
+            notice(t().interrupted, "warn");
+        },
+        /** Switches to a mode the session allows; says so when it can't. */
+        setMode(mode) {
+            const control = modeControl();
+            if (!control || !control.switchable.includes(mode))
+                return notice(t().modeLocked(control?.mode ?? state.mode ?? undefined));
+            control.set(mode);
+            if (!control.subscribe) {
+                update({ mode });
+                emit({ type: "mode", mode });
+            }
+        },
+        /** The next mode the session allows (Shift+Tab). */
+        cycleMode() {
+            const control = modeControl();
+            if (!control || control.switchable.length < 2)
+                return notice(t().modeLocked(control?.mode ?? state.mode ?? undefined));
+            controller.setMode(control.switchable[(control.switchable.indexOf(control.mode) + 1) % control.switchable.length]);
+        },
+        /** Into plan mode, or back to the mode it was entered from (`/plan`). */
+        togglePlan() {
+            const control = modeControl();
+            const next = control ? togglePlanMode(control) : null;
+            if (!next)
+                return notice(t().modeLocked(control?.mode ?? state.mode ?? undefined));
+            if (!control?.subscribe) {
+                update({ mode: next });
+                emit({ type: "mode", mode: next });
+            }
+        },
+        /** The runs to resume, newest first, labelled for a person. */
+        async listRuns() {
+            if (!runsDir)
+                return [];
+            return (await listRuns(runsDir)).map((summary, index) => ({ label: `${index + 1}. ${runLabel(summary, current.run ?? undefined)}`, dir: summary.dir }));
+        },
+        /** `/resume`: with `dir`, switches to that run; without it, asks which. */
+        async resume(dir) {
+            if (!opener || !runsDir)
+                return;
+            const runs = await listRuns(runsDir);
+            if (runs.length === 0)
+                return notice(t().noEarlierRuns);
+            const chosen = dir ?? (await pick(t().resumeTitle, (await controller.listRuns()).map(({ label, dir: value }) => ({ label, value }))));
+            const summary = runs.find((other) => other.dir === chosen);
+            if (!summary || (current.run && path.resolve(summary.dir) === path.resolve(current.run.dir)))
+                return;
+            await switchTo(await runFolderOf(summary), true);
+        },
+        /**
+         * Starts a new conversation in a new run, leaving the current one to resume later: what a
+         * graphical view offers instead of quitting and starting again.
+         */
+        async newConversation() {
+            if (!opener || !runsDir)
+                return;
+            queue.end();
+            run.close();
+            current = await openSession(opener, await createRunFolder(runsDir));
+            openLog();
+            update({ transcript: [], turns: 0, usage: null, contextPercent: null, todos: null, suggestion: null });
+            connect();
+            emit({ type: "session" });
+        },
+        /**
+         * Enables or disables an installed extension: in the running session when it was running when
+         * the session opened (#49), by opening the session again with the same conversation otherwise.
+         */
+        async setExtension(name, enabled) {
+            // An action of its own, not a line the person typed: a graphical view's toggle.
+            if (!opener || !current.run)
+                return notice(t().extensionsCantReopen);
+            const installed = (current.extensions?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
+            const dir = installed ? current.extensions?.dirs[installed.scope] : undefined;
+            if (!installed || !dir)
+                return notice(t().extensionNotInstalled(name));
+            await setExtensionEnabled(dir, name, enabled);
+            await applyExtension(name, enabled);
+        },
+        /**
+         * Switches the kit's language (`switchLanguage()`) and opens the session again in it, keeping
+         * the conversation: the agent's next reply, the labels and the kit's notices come in it.
+         * `note` adds the host's own words to what the model is told (the agent's name in that
+         * language: the earlier conversation keeps pulling the old one).
+         */
+        async setLanguage(language, { note } = {}) {
+            switchLanguage(language);
+            update({ language });
+            const name = LANGUAGE_NAMES[language];
+            languageNotice = `<system-reminder>The user switched the chat's language to ${name}. From now on, reply in ${name}, and keep everything you write in ${name}, whatever language earlier messages are in. The names your instructions give now (your own included) are the ones to use.${note ? ` ${note}` : ""}</system-reminder>`;
+            if (opener && current.run)
+                await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+        },
+        /** What an active extension hands the host (its `api`), e.g. the sources' `addSource`; `undefined` when it isn't active. */
+        api(extension) {
+            return current.apis?.[extension];
+        },
+        /** Answers the state's panel (`panels: "state"`). */
+        answer(panelId, answer) {
+            answers.get(panelId)?.(answer);
+        },
+        /** Answers the state's choice (`null`: cancelled). */
+        choose(value) {
+            choiceResolve?.(value);
+        },
+        /** A notice from the view (a welcome): in the transcript and the session log. */
+        notice,
+        /** The agent's text in the latest turn that ended, plain (for `/copy`). */
+        lastReply: () => latestReply,
+        /** Ends the chat: the agent run, the session log, the controller's port. */
+        close() {
+            if (state.closed)
+                return;
+            queue.end();
+            run.close();
+            unsubscribeMode?.();
+            for (const settle of [...answers.values()])
+                settle("");
+            choiceResolve?.(null);
+            if (settings.panels === "state")
+                setInteractionPort(previousPort);
+            sessionLog?.end();
+            update({ closed: true, busy: false });
+        },
+    };
+    return controller;
+}

package/dist/chat/extensions.d.ts

@@ -0,0 +1,18 @@
+import { type InstalledExtension } from "../core/externalExtensions.js";
+import type { ExtensionsStatus } from "../core/session.js";
+/** One line for an installed extension: name and version, scope, on or off, its author, where it came from. */
+export declare function describe(extension: InstalledExtension): string;
+/**
+ * `/extensions` in a chat (#37): with nothing after it, what the session runs with, what's off
+ * and why, and what's installed; with `enable <name>` or `disable <name>`, changes its lock and
+ * says which (`toggled`): the chat turns it on or off in the running session when it can (#49),
+ * and opens the session again otherwise, keeping the conversation. `null` when `line` isn't this
+ * command.
+ */
+export declare function chatExtensionsCommand(line: string, status: ExtensionsStatus | undefined, canReopen: boolean): Promise<{
+    lines: string[];
+    toggled?: {
+        name: string;
+        enabled: boolean;
+    };
+} | null>;

package/dist/chat/extensions.js

@@ -0,0 +1,44 @@
+import path from "node:path";
+import { setExtensionEnabled } from "../core/externalExtensions.js";
+import { t } from "../core/messages/index.js";
+/** One line for an installed extension: name and version, scope, on or off, its author, where it came from. */
+export function describe(extension) {
+    const state = extension.shadowed ? "not used (the project's wins)" : extension.lock.enabled ? "enabled" : "disabled";
+    // From a marketplace, its name there (`jokebook@shipyard`): the copy it came from is the kit's business.
+    const where = extension.lock.commit ? `${extension.lock.source} @ ${extension.lock.commit.slice(0, 12)}` : path.normalize(extension.lock.source);
+    const source = extension.lock.marketplace ? `${extension.lock.marketplace}${extension.lock.commit ? ` @ ${extension.lock.commit.slice(0, 12)}` : ""}` : where;
+    const version = extension.manifest?.version ? ` ${extension.manifest.version}` : "";
+    const author = extension.manifest?.author ? `  by ${extension.manifest.author.name}` : "";
+    return `${extension.name}${version}  [${extension.scope}]  ${state}${author}  from ${source}`;
+}
+/**
+ * `/extensions` in a chat (#37): with nothing after it, what the session runs with, what's off
+ * and why, and what's installed; with `enable <name>` or `disable <name>`, changes its lock and
+ * says which (`toggled`): the chat turns it on or off in the running session when it can (#49),
+ * and opens the session again otherwise, keeping the conversation. `null` when `line` isn't this
+ * command.
+ */
+export async function chatExtensionsCommand(line, status, canReopen) {
+    const [command, action, name, ...extra] = line.trim().split(/\s+/);
+    if (command?.toLowerCase() !== "/extensions")
+        return null;
+    if (!action) {
+        const lines = [status?.active.length ? t().extensionsRunning(status.active.join(", ")) : t().extensionsNone];
+        for (const { name: off, reason } of status?.inactive ?? [])
+            lines.push(t().extensionOff(off, reason));
+        if (status?.installed.length)
+            lines.push(t().extensionsInstalled, ...status.installed.map((extension) => `  ${describe(extension)}`));
+        return { lines };
+    }
+    const enable = action.toLowerCase() === "enable";
+    if ((!enable && action.toLowerCase() !== "disable") || !name || extra.length)
+        return { lines: [t().extensionsUsage] };
+    if (!canReopen)
+        return { lines: [t().extensionsCantReopen] };
+    const installed = (status?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
+    const dir = installed ? status?.dirs[installed.scope] : undefined;
+    if (!installed || !dir)
+        return { lines: [t().extensionNotInstalled(name)] };
+    await setExtensionEnabled(dir, name, enable);
+    return { lines: [], toggled: { name, enabled: enable } };
+}

package/dist/chat/history.d.ts

@@ -0,0 +1,17 @@
+/** One line the person sent, as the history file keeps it. */
+export interface HistoryEntry {
+    text: string;
+    timestamp: string;
+}
+/** Keeps only the most recent `limit` entries (oldest-first order in, oldest-first out). */
+export declare function capHistory(entries: readonly HistoryEntry[], limit: number): HistoryEntry[];
+/** Oldest-first. Missing file reads as empty — nothing to load yet is the normal case. */
+export declare function loadHistory(filePath: string): Promise<HistoryEntry[]>;
+/** Overwrites the whole file (not appended) so a prior prune (oldest entries dropped) sticks. */
+export declare function saveHistory(filePath: string, entries: readonly HistoryEntry[]): Promise<void>;
+/**
+ * The command name a typed line would invoke (e.g. "chiste" for both "/chiste" and
+ * "/chiste con salsa"), or `null` for a line that isn't a slash command at all (doesn't
+ * start with "/") or is just a bare "/" with nothing after it.
+ */
+export declare function slashCommandToken(line: string): string | null;

package/dist/chat/history.js

@@ -0,0 +1,39 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+/** Keeps only the most recent `limit` entries (oldest-first order in, oldest-first out). */
+export function capHistory(entries, limit) {
+    return entries.length > limit ? entries.slice(-limit) : entries.slice();
+}
+/** Oldest-first. Missing file reads as empty — nothing to load yet is the normal case. */
+export async function loadHistory(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return raw
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => JSON.parse(line));
+}
+/** Overwrites the whole file (not appended) so a prior prune (oldest entries dropped) sticks. */
+export async function saveHistory(filePath, entries) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const body = entries.map((entry) => JSON.stringify(entry)).join("\n");
+    await writeFile(filePath, entries.length > 0 ? `${body}\n` : "", "utf8");
+}
+/**
+ * The command name a typed line would invoke (e.g. "chiste" for both "/chiste" and
+ * "/chiste con salsa"), or `null` for a line that isn't a slash command at all (doesn't
+ * start with "/") or is just a bare "/" with nothing after it.
+ */
+export function slashCommandToken(line) {
+    if (!line.startsWith("/"))
+        return null;
+    const token = line.slice(1).split(/\s/, 1)[0];
+    return token ? token : null;
+}