@falkenslab/agent-kit 0.21.0 → 0.23.0

package/README.md

@@ -1,8 +1,5 @@
 <h1>
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-readme-dark.svg">
-    <img src="docs/assets/logo-readme.svg" alt="agent-kit" height="64">
-  </picture>
+  <img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/logo-readme-any.svg" alt="agent-kit" height="64">
 </h1>
 
 [![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)

package/assets/extension-launcher.mjs

@@ -1,16 +1,21 @@
 // Starts an external extension's MCP server (ADR-025, #37) with a clean environment: the SDK
 // merges a server's `env` with the agent's own (confirmed empirically), so the kit starts this
 // launcher instead, which keeps only the variables the system needs and those the extension
-// declares, then loads the server in this same process.
+// declares, then loads the server in this same process. Its options' values (#55) are read here,
+// when the server starts, so one changed while a session runs reaches the server started again.
 //
-// Usage: node extension-launcher.mjs <server script> <JSON array of variable names it may see> [its arguments…]
+// Usage: node extension-launcher.mjs <server script> <spec> [its arguments…]
+// where <spec> is JSON: { "keep": [variables it may see], "options"?: { "lock", "secrets", "name", "defaults" } }.
+import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 
-const [entry, declared = "[]", ...args] = process.argv.slice(2);
+const [entry, specText = "{}", ...args] = process.argv.slice(2);
 if (!entry) {
   console.error("extension-launcher: no server entry given");
   process.exit(1);
 }
+const spec = JSON.parse(specText);
+const declared = spec.keep ?? [];
 
 // What any process may need to run, on Windows and elsewhere; never a credential. Where programs
 // are installed and the desktop session too: a browser is found through PROGRAMFILES on Windows
@@ -21,11 +26,29 @@ const SYSTEM = [
   "HOMEDRIVE", "HOMEPATH", "USERNAME", "USER", "LOGNAME", "OS", "PROCESSOR_ARCHITECTURE", "NUMBER_OF_PROCESSORS",
   "DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR", "XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_DATA_HOME", "DBUS_SESSION_BUS_ADDRESS",
 ];
-const allowed = new Set([...SYSTEM, ...JSON.parse(declared)].map((name) => name.toUpperCase()));
+const allowed = new Set([...SYSTEM, ...declared].map((name) => name.toUpperCase()));
 for (const name of Object.keys(process.env)) {
   if (!allowed.has(name.toUpperCase())) delete process.env[name];
 }
 
+// Its options' values now: the lock's, the secrets', else the defaults; `${user_config.KEY}` in
+// its arguments and declared variables takes them (a list comma-separated, none as empty).
+const readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+};
+const options = spec.options;
+const values = options ? { ...options.defaults, ...readJson(options.lock)[options.name]?.options, ...readJson(options.secrets) } : {};
+const fill = (text) =>
+  text.replace(/\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => {
+    const value = values[key];
+    return value === undefined ? "" : Array.isArray(value) ? value.join(",") : String(value);
+  });
+for (const name of declared) if (process.env[name] !== undefined) process.env[name] = fill(process.env[name]);
+
 // The server reads its own arguments from argv: its own, none of the launcher's.
-process.argv = [process.argv[0], entry, ...args];
+process.argv = [process.argv[0], entry, ...args.map(fill)];
 await import(pathToFileURL(entry).href);

package/dist/chat/chatController.d.ts

@@ -1,6 +1,7 @@
 import type { Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { Mode } from "../core/agentSpec.js";
 import { type ApprovalPrompt, type ChoiceSettings } from "../core/interaction.js";
+import type { FormRequest } from "../core/elicitation.js";
 import { type Language } from "../core/language.js";
 import { type AgentEvent, type AgentRun, type SessionUsage } from "../core/runner.js";
 import { type RunFolder } from "../core/runs.js";
@@ -8,6 +9,8 @@ import { type ExtensionsStatus, type ModeControl } from "../core/session.js";
 import { type Todo } from "../core/todos.js";
 import { type ToolLabels } from "../core/toolLabels.js";
 import type { ToolPhrase } from "../core/messages/index.js";
+import { type ExtensionOptionState, type ExtensionScope } from "../core/externalExtensions.js";
+import { type CatalogEntry } from "../core/extensionCatalog.js";
 import { type SessionOpener } from "./runs.js";
 /**
  * The chat's logic without an interface (ADR-026, #39): opening, reopening and resuming the
@@ -104,6 +107,12 @@ export type ChatQuestion = {
     kind: "choice";
     prompt: ApprovalPrompt;
     choice: ChoiceSettings;
+}
+/** A form an MCP server asks for (#58): answered with `answer(id, JSON.stringify({ action, content }))`. */
+ | {
+    kind: "form";
+    prompt: ApprovalPrompt;
+    form: FormRequest;
 };
 /** A checkpoint waiting for the person's answer, with `panels: "state"`. */
 export type ChatPanel = ChatQuestion & {
@@ -243,6 +252,57 @@ export declare function createChatController(options: Options | SessionOpener, s
      * the session opened (#49), by opening the session again with the same conversation otherwise.
      */
     setExtension(name: string, enabled: boolean): Promise<void>;
+    /**
+     * The catalog (#56): what the agent's marketplaces offer (its `officialMarketplace` among
+     * them), matching `words` when given, with what's installed and what has an update.
+     */
+    extensionCatalog(words?: readonly string[]): Promise<CatalogEntry[]>;
+    /**
+     * A catalog entry's logo or banner (#59), as a file for a view to serve; `undefined` when it
+     * has none, or isn't offered. From the catalog the view last listed, when it has.
+     */
+    extensionImage(spec: string, kind: "logo" | "banner"): Promise<string | undefined>;
+    /**
+     * Installs an extension from the catalog (`<name>@<marketplace>`, or a name only one offers)
+     * into the agent's scope, or `scope`. One from a marketplace that isn't the agent's own isn't
+     * installed until `confirmed`: the result says which (`confirm`), for the view to ask the
+     * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
+     */
+    installExtension(spec: string, options?: {
+        scope?: ExtensionScope;
+        confirmed?: boolean;
+    }): Promise<{
+        name?: string;
+        missing?: string[];
+        confirm?: {
+            marketplace: string;
+            description?: string;
+        };
+    }>;
+    /** Updates one installed extension from its marketplace, or every one with a newer version there; the names updated. */
+    updateExtension(name?: string): Promise<string[]>;
+    /**
+     * Uninstalls an extension, and its data with `deleteData`: turned off in the running session
+     * first when it's running (#49), the session opened again when that can't be done.
+     */
+    removeExtension(name: string, options?: {
+        deleteData?: boolean;
+    }): Promise<void>;
+    /** An installed extension's options as they are now (a secret's value is never given). */
+    extensionOptions(name: string): Promise<ExtensionOptionState[]>;
+    /**
+     * Sets an installed extension's options from a view's form (`undefined` clears one), secrets
+     * too: a form isn't kept in the chat's history, as a typed line is. Its servers restart with
+     * them in the running session (#55), or the session opens again.
+     */
+    setExtensionOptions(name: string, values: Record<string, string | undefined>): Promise<void>;
+    /**
+     * Trusts the workspace's extensions as they are now (#57) and opens the session again with
+     * them, keeping the conversation: what the person answers when the chat asks, or later.
+     */
+    trustWorkspace(): Promise<void>;
+    /** Opens the session again with what's installed now, keeping the conversation: an extension just installed or updated, now. */
+    reopen(): Promise<void>;
     /**
      * 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.

package/dist/chat/chatController.js

@@ -10,7 +10,10 @@ 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 { trustWorkspace } from "../core/workspaceTrust.js";
+import { askForDecision } from "../core/hooks/humanInput.js";
+import { extensionOptionStates, listInstalled, removeExtension as removeInstalled, setExtensionEnabled, setExtensionOptions as storeExtensionOptions } from "../core/externalExtensions.js";
+import { extensionCatalog as readCatalog, installExtension as installFromCatalog, needsConfirmation, updateExtension as updateFromCatalog } from "../core/extensionCatalog.js";
 import { capHistory, loadHistory, saveHistory, slashCommandToken } from "./history.js";
 import { firstRun, openSession, runFolderOf, runLabel } from "./runs.js";
 const DEFAULT_EXIT_COMMANDS = ["/exit", "/quit"];
@@ -175,7 +178,7 @@ export async function createChatController(options, settings = {}) {
                 ...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>]" },
+                { name: "extensions", description: t().commandExtensions, argumentHint: "[enable|disable|config|search|install|update|remove|reload]" },
             ];
             const details = new Map();
             for (const command of [...(commands ?? []).map(({ name, description, argumentHint }) => ({ name, description: description ?? "", argumentHint: argumentHint ?? "" })), ...local])
@@ -278,6 +281,47 @@ export async function createChatController(options, settings = {}) {
         notice(t().extensionToggled(name, enabled));
         await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
     }
+    /** An extension whose options just changed: its servers restarted in the running session if they can be, the session opened again if not (#55). */
+    async function applyOptions(name) {
+        if (await current.restartExtension?.(name).catch(() => false)) {
+            notice(t().extensionRestarted(name));
+            extensionNotices.push(`<system-reminder>The user changed the ${name} extension's settings: its server restarted with them. A call that failed just now may work again.</system-reminder>`);
+            return;
+        }
+        notice(t().extensionReconfiguredReopen(name));
+        await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+    }
+    /** The catalog as the view last listed it (#59): what its images are served from. */
+    let lastCatalog;
+    /** The installed extensions as they are now on disk, into the state (after installing, updating or removing one). */
+    async function refreshInstalled() {
+        if (!current.extensions)
+            return;
+        // In place: the session's live switch keeps a hold of the same status (liveExtensions.ts).
+        current.extensions.installed = await listInstalled(current.extensions.dirs);
+        update({ extensions: { ...current.extensions } });
+    }
+    /** What `/extensions install|update|remove|reload` asks for, through the controller's own actions. */
+    async function runExtensionAction(action) {
+        try {
+            if (action.type === "install") {
+                const result = await controller.installExtension(action.spec, { confirmed: action.confirmed });
+                if (result.confirm)
+                    notice(t().extensionConfirm(action.spec, result.confirm.marketplace));
+            }
+            else if (action.type === "update")
+                await controller.updateExtension(action.name);
+            else if (action.type === "remove")
+                await controller.removeExtension(action.name, { deleteData: action.deleteData });
+            else if (action.type === "trust")
+                await controller.trustWorkspace();
+            else
+                await controller.reopen();
+        }
+        catch (error) {
+            notice(`(${error instanceof Error ? error.message : String(error)})`, "warn");
+        }
+    }
     async function switchTo(folder, fromResume) {
         queue.end();
         run.close();
@@ -288,6 +332,28 @@ export async function createChatController(options, settings = {}) {
         emit({ type: "session" });
         if (fromResume)
             await showConversation(current.run, true);
+        void askTrust();
+    }
+    /**
+     * A session opened with extensions the workspace brings that the person hasn't trusted here
+     * (#57): asked once (no by default); trusted, the session opens again with them. Declined, not
+     * asked again in this chat: `/extensions trust` trusts them later.
+     */
+    let trustDeclined = false;
+    async function askTrust() {
+        const untrusted = current.extensions?.untrusted ?? [];
+        if (!untrusted.length || trustDeclined || !opener || !current.run)
+            return;
+        const answer = await askForDecision(current.run.dir, {
+            title: t().trustTitle,
+            lines: [t().trustBody, "", ...untrusted.map((extension) => `- ${extension.name}${extension.version ? ` ${extension.version}` : ""}  (${extension.source})`)],
+            question: t().trustQuestion,
+        });
+        if (answer !== "y") {
+            trustDeclined = true;
+            return notice(t().trustDeclined);
+        }
+        await controller.trustWorkspace();
     }
     // A choice in place of the prompt, when the view doesn't ask it itself.
     let choiceResolve = null;
@@ -324,6 +390,17 @@ export async function createChatController(options, settings = {}) {
         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),
+        // The answer is the form's, JSON; anything else (the panel dropped) is a cancel.
+        askForm: async (form, signal) => {
+            const raw = await ask({ kind: "form", prompt: { title: form.server, lines: [form.message] }, form }, signal);
+            try {
+                const answer = JSON.parse(raw);
+                return answer.action === "accept" ? { action: "accept", content: answer.content ?? {} } : { action: answer.action === "decline" ? "decline" : "cancel" };
+            }
+            catch {
+                return { action: "cancel" };
+            }
+        },
         notify: (message) => notice(message),
     };
     const previousPort = settings.panels === "state" ? getInteractionPort() : null;
@@ -352,6 +429,8 @@ export async function createChatController(options, settings = {}) {
         async start() {
             if (current.run)
                 await showConversation(current.run, false);
+            // Asked alongside, not before: a view draws its panels once the chat has started.
+            void askTrust();
             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`);
@@ -390,6 +469,10 @@ export async function createChatController(options, settings = {}) {
                     notice(text);
                 if (extensions.toggled)
                     await applyExtension(extensions.toggled.name, extensions.toggled.enabled);
+                if (extensions.reconfigured)
+                    await applyOptions(extensions.reconfigured);
+                if (extensions.action)
+                    await runExtensionAction(extensions.action);
                 return;
             }
             const token = slashCommandToken(line);
@@ -486,6 +569,133 @@ export async function createChatController(options, settings = {}) {
             await setExtensionEnabled(dir, name, enabled);
             await applyExtension(name, enabled);
         },
+        /**
+         * The catalog (#56): what the agent's marketplaces offer (its `officialMarketplace` among
+         * them), matching `words` when given, with what's installed and what has an update.
+         */
+        async extensionCatalog(words = []) {
+            if (!current.extensions)
+                return [];
+            const entries = await readCatalog(current.extensions.dirs, { ...(current.extensions.official ? { official: current.extensions.official } : {}), ...(current.extensions.catalogTopics ? { topics: current.extensions.catalogTopics } : {}), words });
+            if (!words.length)
+                lastCatalog = entries;
+            return entries;
+        },
+        /**
+         * A catalog entry's logo or banner (#59), as a file for a view to serve; `undefined` when it
+         * has none, or isn't offered. From the catalog the view last listed, when it has.
+         */
+        async extensionImage(spec, kind) {
+            const entries = lastCatalog ?? (await controller.extensionCatalog());
+            return entries.find((entry) => entry.spec === spec)?.[kind];
+        },
+        /**
+         * Installs an extension from the catalog (`<name>@<marketplace>`, or a name only one offers)
+         * into the agent's scope, or `scope`. One from a marketplace that isn't the agent's own isn't
+         * installed until `confirmed`: the result says which (`confirm`), for the view to ask the
+         * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
+         */
+        async installExtension(spec, options = {}) {
+            if (!current.extensions)
+                throw new Error("This chat's session has no extensions folder.");
+            const official = current.extensions.official ? { official: current.extensions.official } : {};
+            const foreign = await needsConfirmation(current.extensions.dirs, spec, current.extensions.official);
+            if (foreign && !options.confirmed)
+                return { confirm: { marketplace: foreign.marketplace.name, ...(foreign.plugin.description ? { description: foreign.plugin.description } : {}) } };
+            const result = await installFromCatalog(current.extensions.dirs, spec, { ...official, ...(options.scope ? { scope: options.scope } : {}) });
+            await refreshInstalled();
+            notice(t().extensionInstalled(result.name));
+            // What it needs and this computer lacks (#63): the person installs it, the kit never does.
+            for (const line of result.missing)
+                notice(t().extensionLacks(result.name, line));
+            return { name: result.name, missing: result.missing };
+        },
+        /** Updates one installed extension from its marketplace, or every one with a newer version there; the names updated. */
+        async updateExtension(name) {
+            if (!current.extensions)
+                return [];
+            const official = current.extensions.official ? { official: current.extensions.official } : {};
+            const names = name ? [name] : (await readCatalog(current.extensions.dirs, official)).filter((entry) => entry.update).map((entry) => entry.plugin.name);
+            // Updating what's installed isn't offering: every installed one, whatever its topics.
+            if (!names.length)
+                notice(t().extensionsUpToDate);
+            for (const each of names) {
+                const result = await updateFromCatalog(current.extensions.dirs, each, official);
+                notice(t().extensionUpdated(each, result.from ?? "?", result.to ?? "?"));
+            }
+            await refreshInstalled();
+            return names;
+        },
+        /**
+         * Uninstalls an extension, and its data with `deleteData`: turned off in the running session
+         * first when it's running (#49), the session opened again when that can't be done.
+         */
+        async removeExtension(name, options = {}) {
+            const installed = (current.extensions?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
+            if (!installed)
+                return notice(t().extensionNotInstalled(name));
+            const running = current.extensions?.active.includes(name) ?? false;
+            const switched = running ? await current.switchExtension?.(name, false).catch(() => false) : true;
+            await removeInstalled(installed.scopeDir, name, { deleteData: Boolean(options.deleteData), privateDir: installed.privateDir });
+            // Gone, not off: out of what's listed as off in this session too.
+            if (current.extensions)
+                current.extensions.inactive = current.extensions.inactive.filter((off) => off.name !== name);
+            await refreshInstalled();
+            notice(t().extensionRemoved(name, Boolean(options.deleteData)));
+            if (running && switched) {
+                extensionNotices.push(`<system-reminder>The user uninstalled the ${name} extension: its tools, skills, commands and subagents are gone, whatever your instructions or earlier messages say.</system-reminder>`);
+                loadCommands();
+            }
+            else if (running && opener && current.run)
+                await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+        },
+        /** An installed extension's options as they are now (a secret's value is never given). */
+        async extensionOptions(name) {
+            const installed = (current.extensions?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
+            return installed ? extensionOptionStates(installed) : [];
+        },
+        /**
+         * Sets an installed extension's options from a view's form (`undefined` clears one), secrets
+         * too: a form isn't kept in the chat's history, as a typed line is. Its servers restart with
+         * them in the running session (#55), or the session opens again.
+         */
+        async setExtensionOptions(name, values) {
+            const installed = (current.extensions?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
+            if (!installed)
+                return notice(t().extensionNotInstalled(name));
+            await storeExtensionOptions(installed, name, values);
+            await refreshInstalled();
+            if (current.extensions?.active.includes(name))
+                await applyOptions(name);
+            else if (opener && current.run) {
+                // Off for want of a value, maybe: a new session may run it now.
+                notice(t().extensionReconfiguredReopen(name));
+                await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+            }
+        },
+        /**
+         * Trusts the workspace's extensions as they are now (#57) and opens the session again with
+         * them, keeping the conversation: what the person answers when the chat asks, or later.
+         */
+        async trustWorkspace() {
+            if (!current.extensions)
+                return;
+            const names = await trustWorkspace(current.extensions.dirs);
+            if (!names.length)
+                return;
+            notice(t().trustGiven(names.join(", ")));
+            if (opener && current.run && !state.busy)
+                await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+        },
+        /** Opens the session again with what's installed now, keeping the conversation: an extension just installed or updated, now. */
+        async reopen() {
+            if (!opener || !current.run)
+                return notice(t().extensionsCantReopen);
+            if (state.busy)
+                return notice(t().extensionsBusy);
+            notice(t().extensionsReloaded);
+            await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+        },
         /**
          * 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.

package/dist/chat/extensions.d.ts

@@ -1,13 +1,45 @@
 import { type InstalledExtension } from "../core/externalExtensions.js";
 import type { ExtensionsStatus } from "../core/session.js";
+import { type CatalogEntry } from "../core/extensionCatalog.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;
+/**
+ * What the active extensions let the agent do (#62), in the session's language: a heading per
+ * extension with capabilities, a line per capability, and the tools a capability names that its
+ * server doesn't offer, once the session has started and knows them.
+ */
+export declare function describeCapabilities(status: ExtensionsStatus): string[];
+/** What the chat does for `/extensions install|update|remove|reload` (#56). */
+export type ExtensionAction = {
+    type: "install";
+    spec: string;
+    confirmed: boolean;
+} | {
+    type: "update";
+    name?: string;
+} | {
+    type: "remove";
+    name: string;
+    deleteData: boolean;
+} | {
+    type: "reload";
+} | {
+    type: "trust";
+};
+/** One line for a catalog entry: what installs it, its version, whether it's installed or has an update, what it is. */
+export declare function describeEntry(entry: CatalogEntry): string;
+/** An installed extension's options, one line each: its value, its default, or whether a sensitive one is set (never its value). */
+export declare function describeOptions(extension: InstalledExtension): Promise<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.
+ * and opens the session again otherwise, keeping the conversation. With `config <name>`, its
+ * options; with `key=value` after it, sets them (`reconfigured`: the chat restarts its servers,
+ * #55). A sensitive one isn't set here: what's typed in a chat is kept in its history. The
+ * catalog (#56): `search [words]` lists what the agent's marketplaces offer; `install <name>`,
+ * `update [name]`, `remove <name> [--delete-data]` and `reload` are the chat's to do (`action`),
+ * since they change what the session has. `null` when `line` isn't this command.
  */
 export declare function chatExtensionsCommand(line: string, status: ExtensionsStatus | undefined, canReopen: boolean): Promise<{
     lines: string[];
@@ -15,4 +47,6 @@ export declare function chatExtensionsCommand(line: string, status: ExtensionsSt
         name: string;
         enabled: boolean;
     };
+    reconfigured?: string;
+    action?: ExtensionAction;
 } | null>;

package/dist/chat/extensions.js

@@ -1,6 +1,7 @@
 import path from "node:path";
-import { setExtensionEnabled } from "../core/externalExtensions.js";
+import { extensionOptionStates, setExtensionEnabled, setExtensionOptions } from "../core/externalExtensions.js";
 import { t } from "../core/messages/index.js";
+import { extensionCatalog } from "../core/extensionCatalog.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"}${extension.lock.linked ? ", linked" : ""}`;
@@ -11,19 +12,102 @@ export function describe(extension) {
     const author = extension.manifest?.author ? `  by ${extension.manifest.author.name}` : "";
     return `${extension.name}${version}  [${extension.scope}]  ${state}${author}  from ${source}`;
 }
+/**
+ * What the active extensions let the agent do (#62), in the session's language: a heading per
+ * extension with capabilities, a line per capability, and the tools a capability names that its
+ * server doesn't offer, once the session has started and knows them.
+ */
+export function describeCapabilities(status) {
+    const offered = new Set(status.sessionTools?.() ?? []);
+    return status.active.flatMap((name) => {
+        const capabilities = status.about[name]?.capabilities ?? [];
+        const unavailable = status.about[name]?.unavailable ?? [];
+        if (!capabilities.length && !unavailable.length)
+            return [];
+        return [
+            t().extensionCan(name),
+            ...capabilities.map(({ label, description, tools }) => {
+                const missing = offered.size ? [...new Set(tools.filter((tool) => !offered.has(tool)).map((tool) => tool.replace(/^mcp__.+?__/, "")))] : [];
+                return `  - ${label}${description ? `: ${description}` : ""}${missing.length ? ` ${t().capabilityToolsMissing(missing.join(", "))}` : ""}`;
+            }),
+            // What it can't do on this computer, with what to install (#63).
+            ...unavailable.map(({ label, reason }) => `  - ${t().capabilityUnavailable(label, reason)}`),
+        ];
+    });
+}
+/** One line for a catalog entry: what installs it, its version, whether it's installed or has an update, what it is. */
+export function describeEntry(entry) {
+    const state = entry.installed ? (entry.update ? ` ${t().extensionUpdateAvailable(entry.installed.manifest?.version ?? "?")}` : ` ${t().extensionIsInstalled}`) : "";
+    return `${entry.spec}${entry.version ? ` ${entry.version}` : ""}${state}${entry.plugin.description ? `  ${entry.plugin.description}` : ""}`;
+}
+/** An installed extension's options, one line each: its value, its default, or whether a sensitive one is set (never its value). */
+export async function describeOptions(extension) {
+    return (await extensionOptionStates(extension)).map(({ key, option, value, set, isDefault }) => {
+        const shown = option.sensitive ? (set ? t().optionSecretSet : t().optionNotSet) : set ? `${Array.isArray(value) ? value.join(",") : String(value)}${isDefault ? ` ${t().optionDefault}` : ""}` : t().optionNotSet;
+        return `  ${key} = ${shown}  (${option.title}${option.required ? `, ${t().optionRequired}` : ""})`;
+    });
+}
 /**
  * `/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.
+ * and opens the session again otherwise, keeping the conversation. With `config <name>`, its
+ * options; with `key=value` after it, sets them (`reconfigured`: the chat restarts its servers,
+ * #55). A sensitive one isn't set here: what's typed in a chat is kept in its history. The
+ * catalog (#56): `search [words]` lists what the agent's marketplaces offer; `install <name>`,
+ * `update [name]`, `remove <name> [--delete-data]` and `reload` are the chat's to do (`action`),
+ * since they change what the session has. `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;
+    const verb = action?.toLowerCase();
+    if (verb === "search") {
+        const words = [name, ...extra].filter((word) => Boolean(word));
+        const entries = status ? await extensionCatalog(status.dirs, { ...(status.official ? { official: status.official } : {}), ...(status.catalogTopics ? { topics: status.catalogTopics } : {}), words }).catch(() => []) : [];
+        return { lines: entries.length ? entries.map((entry) => `  ${describeEntry(entry)}`) : [t().extensionsNoMatch] };
+    }
+    if (verb === "install" && name)
+        return canReopen ? { lines: [], action: { type: "install", spec: name, confirmed: extra.includes("--yes") } } : { lines: [t().extensionsCantReopen] };
+    if (verb === "update")
+        return canReopen ? { lines: [], action: { type: "update", ...(name ? { name } : {}) } } : { lines: [t().extensionsCantReopen] };
+    if (verb === "remove" && name)
+        return canReopen ? { lines: [], action: { type: "remove", name, deleteData: extra.includes("--delete-data") } } : { lines: [t().extensionsCantReopen] };
+    if (verb === "reload" && !name)
+        return canReopen ? { lines: [], action: { type: "reload" } } : { lines: [t().extensionsCantReopen] };
+    if (verb === "trust" && !name)
+        return canReopen ? { lines: [], action: { type: "trust" } } : { lines: [t().extensionsCantReopen] };
+    if (action?.toLowerCase() === "config" && name) {
+        const installed = (status?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
+        if (!installed)
+            return { lines: [t().extensionNotInstalled(name)] };
+        if (!extra.length) {
+            const options = await describeOptions(installed);
+            return { lines: options.length ? [t().extensionOptions(name), ...options] : [t().extensionNoOptions(name)] };
+        }
+        const typed = {};
+        for (const pair of extra) {
+            const at = pair.indexOf("=");
+            const key = at > 0 ? pair.slice(0, at) : pair;
+            if (installed.manifest?.userConfig[key]?.sensitive)
+                return { lines: [t().optionSensitiveInChat(key, name)] };
+            typed[key] = at > 0 ? pair.slice(at + 1) || undefined : undefined;
+        }
+        try {
+            await setExtensionOptions(installed, name, typed);
+        }
+        catch (error) {
+            return { lines: [`(${error instanceof Error ? error.message : String(error)})`] };
+        }
+        if (!canReopen)
+            return { lines: [t().extensionOptionsSaved(name)] };
+        return { lines: [], reconfigured: name };
+    }
     if (!action) {
         const lines = [status?.active.length ? t().extensionsRunning(status.active.join(", ")) : t().extensionsNone];
+        if (status)
+            lines.push(...describeCapabilities(status));
         for (const { name: off, reason } of status?.inactive ?? [])
             lines.push(t().extensionOff(off, reason));
         if (status?.installed.length)

package/dist/chat/runs.d.ts

@@ -1,7 +1,7 @@
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
 import type { ExtensionsStatus, ModeControl } from "../core/session.js";
 import type { ToolLabels } from "../core/toolLabels.js";
-import type { ExtensionSwitch } from "../core/liveExtensions.js";
+import type { ExtensionRestart, ExtensionSwitch } from "../core/liveExtensions.js";
 import { type RunFolder, type RunSummary } from "../core/runs.js";
 /**
  * Builds the session's options for a run folder, e.g.
@@ -16,6 +16,7 @@ export type SessionOpener = (run: RunFolder) => Promise<Options | {
     extensions?: ExtensionsStatus;
     apis?: Record<string, Record<string, unknown>>;
     switchExtension?: ExtensionSwitch;
+    restartExtension?: ExtensionRestart;
 }>;
 export interface OpenedSession {
     run: RunFolder;
@@ -25,6 +26,7 @@ export interface OpenedSession {
     extensions?: ExtensionsStatus;
     apis?: Record<string, Record<string, unknown>>;
     switchExtension?: ExtensionSwitch;
+    restartExtension?: ExtensionRestart;
 }
 /** The run a chat starts with: the latest one with `--continue` (if any), a new one otherwise. */
 export declare function firstRun(runsDir: string, argv?: readonly string[]): Promise<RunFolder>;

package/dist/chat/runs.js

@@ -13,7 +13,7 @@ export async function firstRun(runsDir, argv = process.argv.slice(2)) {
 export async function openSession(opener, run) {
     const opened = await opener(run);
     // The SDK's Options has no "options" field: this is buildSessionOptions()'s result.
-    return "options" in opened ? { run, options: opened.options, modeControl: opened.modeControl, toolLabels: opened.toolLabels, extensions: opened.extensions, apis: opened.apis, switchExtension: opened.switchExtension } : { run, options: opened };
+    return "options" in opened ? { run, options: opened.options, modeControl: opened.modeControl, toolLabels: opened.toolLabels, extensions: opened.extensions, apis: opened.apis, switchExtension: opened.switchExtension, restartExtension: opened.restartExtension } : { run, options: opened };
 }
 /** A run's date for a person, in the kit's language. */
 export function runDate(date) {

package/dist/core/agentSpec.d.ts

@@ -33,6 +33,17 @@ export interface BaseSessionConfig {
      * installs them.
      */
     extensionDirs?: ExtensionDirs;
+    /**
+     * The agent's own marketplace of extensions (a folder or a git URL, `#ref`): the chats' catalog
+     * (`/extensions`, #56) offers what it has, installed without a confirmation, as
+     * `runExtensionCommand()`'s `official` does.
+     */
+    officialMarketplace?: string;
+    /**
+     * The topics of the extensions this agent offers its users (#59), e.g. `["miyagi"]`: the chats'
+     * catalog and `extension search` show only those with one of them. Without it, every one.
+     */
+    catalogTopics?: string[];
     /**
      * Directories where the agent reads, searches and writes with the file tools (Write/Edit,
      * scoped — see hooks/fileScopeGate.ts), e.g. a folder of its own notes. Setting one gives the