@falkenslab/agent-kit 0.21.0 → 0.23.0

package/dist/core/externalExtensions.js

@@ -5,10 +5,15 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { capabilitiesProblem, parseCapabilities, providedBy } from "./extensions.js";
 import { getLanguage } from "./messages/index.js";
 import { truncate } from "./toolLabels.js";
 import { agentKitVersion } from "./version.js";
 import { outsideArchive } from "./packaged.js";
+import { extensionSecretsPath, missingOptions, optionsNamed, parseOptionValue, parseUserConfig, readOptionValues, removeSecrets, storeOptionValues } from "./extensionOptions.js";
+import { isTrusted } from "./workspaceTrust.js";
+import { checkRequirements, describeMissing, findOnPath, parseRequirements, requirementsProblem } from "./extensionRequirements.js";
+import { cachedPackageDir, cachedPackageProblem, cachePackage, npxServer, packageCacheDir, packageSpec } from "./npxPackages.js";
 export const LOCK_FILE = "extensions.lock.json";
 /**
  * An installed extension's data folder: `${CLAUDE_PLUGIN_DATA}` in its servers' arguments and
@@ -19,6 +24,39 @@ export const LOCK_FILE = "extensions.lock.json";
 export function extensionDataDir(scopeDir, name) {
     return path.join(scopeDir, ".data", name);
 }
+/**
+ * Where a scope keeps what's the person's, not the workspace's: its extensions' data and secrets
+ * (#57). The agent's scope, its own folder; a project's, a folder of its own in the agent's
+ * (`<agent scope>/.projects/<project>-<hash>/`), so nothing private travels with a project. An
+ * agent without a scope of its own keeps it in the project's.
+ */
+export function scopePrivateDir(dirs, scope) {
+    const scopeDir = dirs[scope];
+    if (!scopeDir)
+        return undefined;
+    if (scope === "agent" || !dirs.agent)
+        return scopeDir;
+    const resolved = path.resolve(scopeDir);
+    const key = createHash("sha256").update(resolved.toLowerCase()).digest("hex").slice(0, 12);
+    return path.join(dirs.agent, ".projects", `${path.basename(path.dirname(resolved)) || "project"}-${key}`);
+}
+/** The agent's store of extensions' code, by content (#57): where a project's scope keeps its extensions' code. */
+export function codeStoreDir(dirs) {
+    return dirs.agent ? path.join(dirs.agent, ".store") : undefined;
+}
+/** Where a stored extension's code is: by its name and its files' hash. */
+export function storedCodeDir(store, name, sha256) {
+    return path.join(store, name, sha256.slice(0, 16));
+}
+/**
+ * How an install into `scope` is done: its npx packages into the agent's cache, and a project's
+ * code into the agent's store when the agent has a scope of its own.
+ */
+export function installTarget(dirs, scope) {
+    const packages = packageCacheDir(dirs);
+    const store = scope === "project" ? codeStoreDir(dirs) : undefined;
+    return { ...(packages ? { packages } : {}), ...(store ? { store } : {}) };
+}
 /** A scope's lock: its extensions by name. */
 export async function readLock(scopeDir) {
     try {
@@ -48,11 +86,14 @@ export async function readExternalManifest(dir) {
     const name = raw.name;
     if (typeof name !== "string" || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name))
         throw new Error(`${file}: "name" must be kebab-case.`);
-    const kit = (raw["agent-kit"] ?? {});
+    // The kit's data, where Claude Code keeps a plugin's own (`metadata`, which it doesn't read): a
+    // top-level key would fail `claude plugin validate --strict` (#55).
+    const kit = (raw.metadata?.["agent-kit"] ?? {});
     const text = (key) => (typeof raw[key] === "string" ? { [key]: raw[key] } : {});
     const author = raw.author;
     // `repository` may be a URL or `{ url }`, as in package.json.
     const repository = typeof raw.repository === "string" ? raw.repository : raw.repository?.url;
+    const capabilities = parseCapabilities(kit.capabilities);
     return {
         name,
         description: typeof raw.description === "string" ? raw.description : "",
@@ -64,16 +105,27 @@ export async function readExternalManifest(dir) {
         ...(typeof repository === "string" ? { repository } : {}),
         ...text("license"),
         ...(Array.isArray(raw.keywords) ? { keywords: raw.keywords.filter((keyword) => typeof keyword === "string") } : {}),
-        provides: kit.provides ?? [],
+        provides: providedBy(kit.provides, capabilities),
         requires: kit.requires ?? [],
+        capabilities,
         ...(kit.kit ? { kit: kit.kit } : {}),
-        needs: Array.isArray(kit.needs) ? kit.needs.filter((program) => typeof program === "string") : [],
+        requirements: parseRequirements(kit.requirements),
         servers: await pluginServers(dir, raw),
-        readOnlyTools: kit.readOnlyTools ?? [],
+        ...(Array.isArray(kit.readOnlyTools) ? { readOnlyTools: kit.readOnlyTools.filter((tool) => typeof tool === "string") } : {}),
         labels: kit.labels ?? {},
         ...(kit.help ? { help: kit.help } : {}),
+        userConfig: parseUserConfig(raw.userConfig),
+        ...catalogLook(kit.catalog),
     };
 }
+/** A manifest's `catalog` (#59): only its `logo` and `banner`, when they're paths. */
+function catalogLook(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const { logo, banner } = raw;
+    const look = { ...(typeof logo === "string" ? { logo } : {}), ...(typeof banner === "string" ? { banner } : {}) };
+    return Object.keys(look).length ? { catalog: look } : {};
+}
 /**
  * A plugin's MCP servers, where Claude Code looks for them: `mcpServers` in `plugin.json` (inline,
  * or a path to a JSON file), else `.mcp.json` at its root, with or without the `mcpServers` key.
@@ -113,26 +165,50 @@ function expand(value, folders) {
     return value.replace(/\$\{(\w+)\}/g, (_, name) => name === "CLAUDE_PLUGIN_ROOT" ? folders.root : name === "CLAUDE_PLUGIN_DATA" ? folders.data : (process.env[name] ?? ""));
 }
 /**
- * Why one of an extension's servers can't run through the launcher (only Node, its script
- * first, inside the extension), or how the kit starts it.
+ * Why one of an extension's servers can't run through the launcher (Node, its script first,
+ * inside the extension; or npx with a package at an exact version, from the cache), or how the
+ * kit starts it.
  */
-function serverLaunch(name, server, folders) {
+function serverLaunch(name, server, folders, packages = {}) {
     const { root } = folders;
+    // Its folders as variables too, as Claude Code gives them to a plugin's servers.
+    const declared = Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), folders)]));
+    const env = { CLAUDE_PLUGIN_ROOT: root, CLAUDE_PLUGIN_DATA: folders.data, ...declared };
+    const npx = npxServer(server);
+    if (typeof npx === "string")
+        return `${npx} (its server "${name}")`;
+    if (npx) {
+        const locked = packages.locked?.[packageSpec(npx)];
+        if (!packages.cache || !locked)
+            return `runs ${packageSpec(npx)}, which wasn't fetched when it was installed: install it again`;
+        const entry = path.join(cachedPackageDir(packages.cache, npx.name, npx.version), locked.bin);
+        return { entry, args: npx.args.map((arg) => expand(arg, folders)), env };
+    }
     if (!/^node(\.exe)?$/i.test(path.basename(server.command)))
-        return `runs its server "${name}" with "${server.command}": only Node servers can be installed`;
+        return `runs its server "${name}" with "${server.command}": only Node servers, or npx with a package's exact version, can be installed`;
     const [script, ...args] = (server.args ?? []).map((arg) => expand(arg, folders));
     if (!script)
         return `gives its server "${name}" no script to run`;
     const entry = path.resolve(root, script);
     if (path.relative(root, entry).startsWith(".."))
         return `runs its server "${name}" from outside its folder (${script})`;
-    // Its folders as variables too, as Claude Code gives them to a plugin's servers.
-    const declared = Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), folders)]));
-    return { entry, args, env: { CLAUDE_PLUGIN_ROOT: root, CLAUDE_PLUGIN_DATA: folders.data, ...declared } };
+    return { entry, args, env };
 }
-/** Why an extension's servers can't run, or nothing: each must be Node, with its script there. */
-async function serversProblem(manifest, root) {
+/**
+ * Why an extension's servers can't run, or nothing: each Node with its script there, or npx with
+ * a package at an exact version (in the cache, once `packages` is given: when it loads).
+ */
+async function serversProblem(manifest, root, packages) {
     for (const [name, server] of Object.entries(manifest.servers)) {
+        const npx = npxServer(server);
+        if (typeof npx === "string")
+            return `${npx} (its server "${name}")`;
+        if (npx) {
+            const problem = packages && (await cachedPackageProblem(packages.cache, npx, packages.locked?.[packageSpec(npx)]));
+            if (problem)
+                return problem;
+            continue;
+        }
         const launch = serverLaunch(name, server, { root, data: "" });
         if (typeof launch === "string")
             return launch;
@@ -141,7 +217,28 @@ async function serversProblem(manifest, root) {
     }
     return undefined;
 }
-/** SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. */
+/** Fetches the packages an extension's npx servers run into the cache (#54), as its lock records them. */
+async function fetchServerPackages(manifest, cache) {
+    const packages = {};
+    for (const server of Object.values(manifest.servers)) {
+        const npx = npxServer(server);
+        if (!npx || typeof npx === "string")
+            continue;
+        packages[packageSpec(npx)] = await cachePackage(cache, npx.name, npx.version);
+    }
+    return packages;
+}
+/** A text file's bytes with CRLF as LF (latin1 maps each byte to itself); a binary one's (a NUL byte in it) as they are. */
+function withoutCarriageReturns(bytes) {
+    if (bytes.includes(0) || !bytes.includes(13))
+        return bytes;
+    return Buffer.from(bytes.toString("latin1").replace(/\r\n/g, "\n"), "latin1");
+}
+/**
+ * SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. A text
+ * file's line endings don't count (CRLF is taken as LF): git checks the same commit out with CRLF
+ * on one computer and LF on another, and a workspace's lock must match on both (#57).
+ */
 export async function hashExtension(dir) {
     const hash = createHash("sha256");
     async function walk(relative) {
@@ -151,7 +248,7 @@ export async function hashExtension(dir) {
             if (entry.isDirectory())
                 await walk(child);
             else if (entry.isFile())
-                hash.update(`${child}\0`).update(await readFile(path.join(dir, child))).update("\0");
+                hash.update(`${child}\0`).update(withoutCarriageReturns(await readFile(path.join(dir, child)))).update("\0");
         }
     }
     await walk("");
@@ -199,10 +296,12 @@ export async function listInstalled(dirs) {
         const scopeDir = dirs[scope];
         if (!scopeDir)
             continue;
+        const privateDir = scopePrivateDir(dirs, scope);
+        const store = codeStoreDir(dirs);
         for (const [name, lock] of Object.entries(await readLock(scopeDir))) {
-            const dir = lock.linked ? lock.source : path.join(scopeDir, name);
+            const dir = lock.linked ? lock.source : lock.stored && store ? storedCodeDir(store, name, lock.sha256) : path.join(scopeDir, name);
             const manifest = await readExternalManifest(dir).catch(() => undefined);
-            installed.push({ name, scope, scopeDir, dir, dataDir: extensionDataDir(scopeDir, name), lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
+            installed.push({ name, scope, scopeDir, dir, dataDir: extensionDataDir(privateDir, name), privateDir, lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
         }
     }
     return installed;
@@ -225,67 +324,101 @@ function manifestToolLabels(manifest) {
     }));
 }
 /** The extension an installed one makes: its servers started through the launcher, its rules from its manifest. */
-function externalExtension(installed, manifest) {
+function externalExtension(installed, manifest, cache, unavailable = []) {
     return {
         name: manifest.name,
         plugin: installed.dir,
         external: true,
         installedIn: installed.scopeDir,
+        ...(unavailable.length ? { unavailable } : {}),
         async contribute() {
             const servers = {};
             if (Object.keys(manifest.servers).length)
                 await mkdir(installed.dataDir, { recursive: true });
             for (const [name, server] of Object.entries(manifest.servers)) {
-                const launch = serverLaunch(name, server, { root: installed.dir, data: installed.dataDir });
+                const launch = serverLaunch(name, server, { root: installed.dir, data: installed.dataDir }, { cache, locked: installed.lock.packages });
                 if (typeof launch === "string")
                     continue; // checked when it loaded
                 // Its `env` reaches it (the SDK merges it with the agent's); the launcher removes the rest.
                 // Inside Electron, process.execPath is the app itself: ELECTRON_RUN_AS_NODE makes it run
                 // the launcher as Node (the launcher removes it, with the rest, once it runs).
                 const env = process.versions.electron ? { ...launch.env, ELECTRON_RUN_AS_NODE: "1" } : launch.env;
-                servers[name] = { type: "stdio", command: process.execPath, args: [extensionLauncherPath(), launch.entry, JSON.stringify(Object.keys(launch.env)), ...launch.args], env };
+                // The launcher's own spec: the variables it keeps, and where its options' values are, read
+                // when it starts the server, so a changed value reaches a server started again (#55).
+                const spec = {
+                    keep: Object.keys(launch.env),
+                    ...(Object.keys(manifest.userConfig).length
+                        ? { options: { lock: path.join(installed.scopeDir, LOCK_FILE), secrets: extensionSecretsPath(installed.privateDir, installed.name), name: installed.name, defaults: optionDefaults(manifest.userConfig) } }
+                        : {}),
+                };
+                servers[name] = { type: "stdio", command: process.execPath, args: [extensionLauncherPath(), launch.entry, JSON.stringify(spec), ...launch.args], env };
             }
             return {
                 mcpServers: servers,
-                readOnlyTools: Object.keys(manifest.servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)),
+                // Its manifest's list, or its servers' own word: the server is the code the kit trusts
+                // least, so its hints only fill the list's absence (ADR-025).
+                ...(manifest.readOnlyTools
+                    ? { readOnlyTools: Object.keys(manifest.servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)) }
+                    : { readOnlyTools: [], readOnlyHintServers: Object.keys(servers) }),
                 toolLabels: manifestToolLabels(manifest),
                 ...(manifest.help ? { helpLines: [manifest.help] } : {}),
             };
         },
     };
 }
+/** Its options' defaults, for the launcher. */
+function optionDefaults(declared) {
+    return Object.fromEntries(Object.entries(declared).flatMap(([key, option]) => (option.default === undefined ? [] : [[key, option.default]])));
+}
+/** Why its options keep it from running (a server naming one it doesn't declare, a required one without a value), or nothing. */
+function optionsProblem(manifest, values) {
+    const named = optionsNamed(Object.values(manifest.servers).flatMap((server) => [server.command, ...(server.args ?? []), ...Object.values(server.env ?? {}).map(String)]));
+    const undeclared = named.filter((key) => !manifest.userConfig[key]);
+    if (undeclared.length)
+        return `names ${undeclared.map((key) => "${user_config." + key + "}").join(", ")}, which its userConfig doesn't declare`;
+    const missing = missingOptions(manifest.userConfig, values);
+    if (missing.length)
+        return `needs ${missing.map((key) => `${key} (${manifest.userConfig[key].title})`).join(", ")} set: \`extension config ${manifest.name} ${missing[0]}=<value>\``;
+    return undefined;
+}
 /** The installed extensions a session runs with, and those it can't (with why). Disabled ones are neither. */
 export async function loadExternalExtensions(dirs) {
     const extensions = [];
     const off = [];
+    const untrusted = [];
+    const cache = packageCacheDir(dirs);
     for (const installed of await listInstalled(dirs)) {
         if (installed.shadowed || !installed.lock.enabled)
             continue;
-        const reason = await problem(installed);
+        // A workspace's own: only once the person trusts it there (#57); the agent's never asks.
+        if (installed.scope === "project" && dirs.agent && !(await isTrusted(dirs.agent, installed.scopeDir, installed.name, installed.lock))) {
+            untrusted.push(installed);
+            off.push({ name: installed.name, reason: "comes with this workspace and isn't trusted here yet: `extension trust`, or the chat asks" });
+            continue;
+        }
+        const reason = await problem(installed, cache);
         if (typeof reason === "string")
             off.push({ name: installed.name, reason });
         else
-            extensions.push(externalExtension(installed, reason));
+            extensions.push(externalExtension(installed, reason.manifest, cache, reason.unavailable));
     }
-    return { extensions, off };
+    return { extensions, off, untrusted };
 }
 /** Why an installed extension can't load, or its manifest when it can. */
 /** Whether a program is on the `PATH`, as a shell would find it (with `PATHEXT`'s extensions on Windows). */
 export async function onPath(program, env = process.env) {
-    const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
-    const extensions = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").map((extension) => extension.toLowerCase())] : [""];
-    for (const dir of dirs) {
-        for (const extension of extensions) {
-            const found = await stat(path.join(dir, `${program}${extension}`)).then((entry) => entry.isFile(), () => false);
-            if (found)
-                return true;
-        }
-    }
-    return false;
+    return (await findOnPath(program, env)) !== undefined;
+}
+/** A requirement this computer lacks, as the person reads it: what it is, what for, and how to install it. */
+export function missingRequirement(check) {
+    const needed = check.requirement.for.length ? ` for ${check.requirement.for.join(", ")}` : "";
+    return `needs ${describeMissing(check)}${needed}`;
 }
-async function problem(installed) {
+async function problem(installed, cache) {
     let manifest;
     try {
+        if (installed.lock.stored && !(await stat(installed.dir).catch(() => null))?.isDirectory())
+            return "isn't on this computer yet (its workspace says which version it uses): `extension restore` gets it";
         if (!installed.lock.linked && (await hashExtension(installed.dir)) !== installed.lock.sha256)
             return "has files that changed since it was installed: install it again to trust them";
         manifest = await readExternalManifest(installed.dir);
@@ -297,13 +430,22 @@ async function problem(installed) {
         return `is installed as "${installed.name}" but its manifest says "${manifest.name}"`;
     if (manifest.kit && !inKitRange(agentKitVersion(), manifest.kit))
         return `works with agent-kit ${manifest.kit}, and this agent runs ${agentKitVersion()}`;
-    const missing = [];
-    for (const program of manifest.needs)
-        if (!(await onPath(program)))
-            missing.push(program);
-    if (missing.length)
-        return `needs ${missing.join(", ")}, which ${missing.length === 1 ? "isn't" : "aren't"} on this computer (on the PATH)`;
-    return (await serversProblem(manifest, installed.dir)) ?? manifest;
+    const requirements = requirementsProblem(manifest.requirements, manifest.provides);
+    if (requirements)
+        return requirements;
+    // A program the whole extension needs keeps it off; one only some capabilities need, those (#63).
+    const checks = (await checkRequirements(manifest.requirements)).filter((check) => !check.ok);
+    const whole = checks.filter((check) => !check.requirement.for.length);
+    if (whole.length)
+        return whole.map((check) => missingRequirement(check)).join("; ");
+    const unavailable = checks.map((check) => ({ capabilities: check.requirement.for, reason: `needs ${describeMissing(check)}` }));
+    const capabilities = await capabilitiesProblem(installed.dir, manifest.capabilities);
+    if (capabilities)
+        return capabilities;
+    const options = optionsProblem(manifest, await readOptionValues(installed.privateDir, installed.name, manifest.userConfig, installed.lock.options));
+    if (options)
+        return options;
+    return (await serversProblem(manifest, installed.dir, { cache, locked: installed.lock.packages })) ?? { manifest, unavailable };
 }
 const exec = promisify(execFile);
 /** Whether `source` names a git repository rather than a folder. */
@@ -316,7 +458,9 @@ export function isGitSource(source) {
  * manifest, and locks it, enabled, with the marketplace it came from when it did (`origin`, for a
  * temporary folder, is what the lock says it came from). An extension with the same name in that
  * scope is replaced; its data folder stays. With `link`, a folder is registered where it is
- * instead, to develop it: not copied, and its files not checked.
+ * instead, to develop it: not copied, and its files not checked. The packages its npx servers
+ * run are fetched into `packages` (#54), the agent's package cache (`packageCacheDir()`; by
+ * default the scope's).
  */
 export async function addExtension(source, scopeDir, options = {}) {
     if (options.link && isGitSource(source))
@@ -340,33 +484,55 @@ export async function addExtension(source, scopeDir, options = {}) {
         if (options.subdir)
             from = path.join(from, options.subdir);
         const manifest = await readExternalManifest(from);
-        const servers = await serversProblem(manifest, from);
+        const servers = (await serversProblem(manifest, from)) ?? (await capabilitiesProblem(from, manifest.capabilities)) ?? requirementsProblem(manifest.requirements, manifest.provides);
         if (servers)
             throw new Error(`${manifest.name} can't be installed: it ${servers}.`);
+        // What it needs and this computer lacks: said, never installed, and it installs anyway (#63).
+        const missing = (await checkRequirements(manifest.requirements)).filter((check) => !check.ok).map((check) => missingRequirement(check));
         const target = path.join(scopeDir, manifest.name);
         // Replacing what's installed there would delete the source itself.
         if (path.resolve(from) === path.resolve(target))
             throw new Error(`${from} is where ${manifest.name} is installed: install it from another folder.`);
+        const packages = await fetchServerPackages(manifest, options.packages ?? path.join(scopeDir, ".npm"));
+        const locked = Object.keys(packages).length ? { packages } : {};
         const lock = await readLock(scopeDir);
         const replaced = Boolean(lock[manifest.name]);
+        // Reinstalled, it keeps the values it had for the options it still declares, as it keeps its data.
+        const kept = Object.fromEntries(Object.entries(lock[manifest.name]?.options ?? {}).filter(([key]) => manifest.userConfig[key] && !manifest.userConfig[key].sensitive));
+        if (Object.keys(kept).length)
+            locked.options = kept;
         await rm(target, { recursive: true, force: true });
         await mkdir(scopeDir, { recursive: true });
+        const origin = options.origin ?? (isGitSource(source) ? source : from);
+        const provenance = { ...(commit ? { commit } : {}), ...(options.subdir ? { subdir: options.subdir } : {}), ...(options.marketplace ? { marketplace: options.marketplace } : {}) };
+        if (options.store && !options.link) {
+            // By content, in the agent's store: two workspaces with the same version share one copy.
+            const sha256 = await hashExtension(from);
+            const stored = storedCodeDir(options.store, manifest.name, sha256);
+            if (!(await stat(stored).catch(() => null))?.isDirectory() || (await hashExtension(stored)) !== sha256) {
+                await rm(stored, { recursive: true, force: true });
+                await cp(from, stored, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
+            }
+            lock[manifest.name] = { source: origin, ...provenance, sha256, stored: true, ...locked, enabled: true, installed: new Date().toISOString() };
+            await writeLock(scopeDir, lock);
+            return { name: manifest.name, replaced, missing, ...(commit ? { commit } : {}) };
+        }
         if (options.link) {
-            lock[manifest.name] = { source: from, linked: true, sha256: "", enabled: true, installed: new Date().toISOString() };
+            lock[manifest.name] = { source: from, linked: true, sha256: "", ...locked, enabled: true, installed: new Date().toISOString() };
             await writeLock(scopeDir, lock);
-            return { name: manifest.name, replaced };
+            return { name: manifest.name, replaced, missing };
         }
         await cp(from, target, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
         lock[manifest.name] = {
-            source: options.origin ?? (isGitSource(source) ? `${source}${options.subdir ? ` (${options.subdir})` : ""}` : from),
-            ...(commit ? { commit } : {}),
-            ...(options.marketplace ? { marketplace: options.marketplace } : {}),
+            source: origin,
+            ...provenance,
             sha256: await hashExtension(target),
+            ...locked,
             enabled: true,
             installed: new Date().toISOString(),
         };
         await writeLock(scopeDir, lock);
-        return { name: manifest.name, replaced, ...(commit ? { commit } : {}) };
+        return { name: manifest.name, replaced, missing, ...(commit ? { commit } : {}) };
     }
     finally {
         if (clone)
@@ -378,13 +544,16 @@ export async function addExtension(source, scopeDir, options = {}) {
  * where it is), and its data folder with `deleteData`; false when it wasn't there.
  */
 export async function removeExtension(scopeDir, name, options = {}) {
+    const privateDir = options.privateDir ?? scopeDir;
     const lock = await readLock(scopeDir);
     if (!lock[name])
         return false;
     delete lock[name];
     await rm(path.join(scopeDir, name), { recursive: true, force: true });
+    // A stored one's code stays in the store: another workspace may use the same version.
     if (options.deleteData)
-        await rm(extensionDataDir(scopeDir, name), { recursive: true, force: true });
+        await rm(extensionDataDir(privateDir, name), { recursive: true, force: true });
+    await removeSecrets(privateDir, name);
     await writeLock(scopeDir, lock);
     return true;
 }
@@ -409,3 +578,46 @@ export async function setExtensionEnabled(scopeDir, name, enabled) {
     await writeLock(scopeDir, lock);
     return true;
 }
+/**
+ * Sets an installed extension's options (#55), each from what the person typed (`undefined`
+ * clears it), checked against its `userConfig`: sensitive ones into the scope's secrets, the rest
+ * into its lock. A running session's servers take them when they start again.
+ */
+export async function setExtensionOptions(where, name, typed) {
+    // A scope's folder (the agent's, whose code and secrets are in it), or an installed one, which knows where they are.
+    const scopeDir = typeof where === "string" ? where : where.scopeDir;
+    const privateDir = typeof where === "string" ? where : where.privateDir;
+    const lock = await readLock(scopeDir);
+    const entry = lock[name];
+    if (!entry)
+        throw new Error(`${name} isn't installed in ${scopeDir}.`);
+    const manifest = (typeof where === "string" ? undefined : where.manifest) ?? (await readExternalManifest(entry.linked ? entry.source : path.join(scopeDir, name)));
+    const changes = {};
+    for (const [key, text] of Object.entries(typed)) {
+        const option = manifest.userConfig[key];
+        if (!option)
+            throw new Error(`${name} has no option "${key}"${Object.keys(manifest.userConfig).length ? `: it has ${Object.keys(manifest.userConfig).join(", ")}` : ""}.`);
+        try {
+            changes[key] = text === undefined ? undefined : parseOptionValue(option, text);
+        }
+        catch (error) {
+            throw new Error(`${key}: ${error instanceof Error ? error.message : String(error)}.`, { cause: error });
+        }
+    }
+    const options = await storeOptionValues(privateDir, name, manifest.userConfig, entry.options ?? {}, changes);
+    lock[name] = { ...entry, options };
+    if (!Object.keys(options).length)
+        delete lock[name].options;
+    await writeLock(scopeDir, lock);
+}
+/** An installed extension's options, as they are now. */
+export async function extensionOptionStates(installed) {
+    const declared = installed.manifest?.userConfig ?? {};
+    const values = await readOptionValues(installed.privateDir, installed.name, declared, installed.lock.options);
+    const secrets = await readOptionValues(installed.privateDir, installed.name, Object.fromEntries(Object.entries(declared).map(([key, option]) => [key, { ...option, default: undefined }])), installed.lock.options);
+    return Object.entries(declared).map(([key, option]) => {
+        const value = values[key];
+        const own = secrets[key];
+        return { key, option, ...(value !== undefined && !option.sensitive ? { value } : {}), set: value !== undefined && value !== "", isDefault: value !== undefined && own === undefined };
+    });
+}

package/dist/core/hooks/planGate.d.ts

@@ -9,6 +9,8 @@ export interface PlanScope {
     isReadOnlyTool?(toolName: string, input: Record<string, unknown>): boolean;
     /** The enabled extensions' MCP tools that only read (`mcp__<server>__<tool>`). */
     readOnlyTools?: readonly string[];
+    /** Whether an MCP tool's own server marks it `readOnlyHint`, for the extensions whose manifest lists none (readOnlyHints.ts). */
+    isReadOnlyHinted?(toolName: string): Promise<boolean>;
 }
 /**
  * The reason to deny `toolName` with `input` in plan mode, or `undefined` to let it through.

package/dist/core/hooks/planGate.js

@@ -41,6 +41,9 @@ export function createPlanGate(scope, isActive) {
         const reason = checkPlanScope(scope, pre.tool_name, (pre.tool_input ?? {}));
         if (!reason)
             return {};
+        // Asked last, and only for an MCP tool nothing else let through: it's a call to the session.
+        if (pre.tool_name.startsWith("mcp__") && (await scope.isReadOnlyHinted?.(pre.tool_name)))
+            return {};
         return {
             hookSpecificOutput: {
                 hookEventName: pre.hook_event_name,

package/dist/core/interaction.d.ts

@@ -1,3 +1,4 @@
+import type { FormAnswer, FormRequest } from "./elicitation.js";
 /** What a checkpoint shows the person: a title, detail lines and, in a plain terminal, the question. */
 export interface ApprovalPrompt {
     title: string;
@@ -43,6 +44,12 @@ export interface InteractionPort {
      * `askDecision()`, with the options numbered in the prompt.
      */
     askChoice?(prompt: ApprovalPrompt, choice: ChoiceSettings, signal: AbortSignal): Promise<string>;
+    /**
+     * A form an MCP server asks for (elicitation, #58), whole: its fields, and the person's
+     * values, or that they declined or cancelled. Optional: without it the kit asks field by
+     * field through the other methods. Never written to a log: the answer is the server's.
+     */
+    askForm?(form: FormRequest, signal: AbortSignal): Promise<FormAnswer>;
     /** A one-way message for the person. */
     notify(message: string): void;
 }

package/dist/core/liveExtensions.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionsStatus } from "./session.js";
+import { type ExtensionCapability, type UnavailableCapability } from "./extensions.js";
 import type { SessionLive, StaticSessionFacts } from "./sessionFacts.js";
 import type { ToolLabels } from "./toolLabels.js";
 /**
@@ -43,6 +44,9 @@ export interface LiveExtension {
     agents: string[];
     description: string;
     provides: string[];
+    capabilities: ExtensionCapability[];
+    /** What it can't do on this computer (#63). */
+    unavailable: UnavailableCapability[];
     help: string[];
 }
 /** The session's own lists the switch keeps in step: the same objects the gates, the chat and the view read. */
@@ -63,3 +67,14 @@ export interface LiveTargets {
 export type ExtensionSwitch = (name: string, enabled: boolean) => Promise<boolean>;
 /** The switch for a session's installed extensions. */
 export declare function createExtensionSwitch(extensions: readonly LiveExtension[], targets: LiveTargets): ExtensionSwitch;
+/**
+ * Restarts `name`'s MCP servers in the running session, so they take its options as they are now
+ * (#55): the launcher reads them when it starts a server. `reconnectMcpServer()` ends a server's
+ * process and starts a new one with the session's config (confirmed empirically; `setMcpServers()`
+ * replaced every server of the session and left the old process running). False when it can't
+ * be done here (not running in this session, or the session hasn't started): the next session
+ * takes them.
+ */
+export type ExtensionRestart = (name: string) => Promise<boolean>;
+/** The restart for a session's installed extensions. */
+export declare function createExtensionRestart(extensions: readonly LiveExtension[], targets: LiveTargets): ExtensionRestart;

package/dist/core/liveExtensions.js

@@ -1,6 +1,8 @@
 import { cp, lstat, mkdir, readdir, rm, symlink, unlink } from "node:fs/promises";
 import path from "node:path";
+import { aboutExtension, describeCapability } from "./extensions.js";
 import { hashExtension, listInstalled, readLock } from "./externalExtensions.js";
+import { cachedPackagesIntact, packageCacheDir } from "./npxPackages.js";
 /**
  * Turning an installed extension off and on in a running session (#49), without reopening it.
  * Only one that was running when the session opened: its MCP servers are toggled
@@ -68,6 +70,9 @@ export function createExtensionSwitch(extensions, targets) {
             const lock = (await readLock(extension.scopeDir))[name];
             if (!lock || (!lock.linked && lock.sha256 !== (await hashExtension(extension.installedDir))))
                 return false;
+            // The packages its npx servers run (#54), checked whether it's linked or not.
+            if (!(await cachedPackagesIntact(packageCacheDir(targets.status.dirs), lock.packages)))
+                return false;
             await mountPlugin(extension.installedDir, extension.pluginMount);
         }
         else {
@@ -85,6 +90,24 @@ export function createExtensionSwitch(extensions, targets) {
         return true;
     };
 }
+/** The restart for a session's installed extensions. */
+export function createExtensionRestart(extensions, targets) {
+    return async (name) => {
+        const extension = extensions.find((candidate) => candidate.name === name);
+        const reconnect = targets.controls().reconnectMcpServer;
+        if (!extension || !reconnect || !extension.servers.length)
+            return false;
+        try {
+            for (const server of extension.servers)
+                await reconnect(server);
+            return true;
+        }
+        catch {
+            // Turned off in the session: it starts with them when it's turned on again.
+            return false;
+        }
+    };
+}
 /** The kit's lists, as the extension is now. */
 function follow(extension, enabled, targets) {
     const without = (list, items) => {
@@ -100,9 +123,17 @@ function follow(extension, enabled, targets) {
         targets.allowedSubagentTypes.push(...extension.agents);
         Object.assign(targets.toolLabels, extension.toolLabels);
         status.active.push(extension.name);
-        status.about[extension.name] = { description: extension.description, provides: extension.provides };
+        status.about[extension.name] = aboutExtension({ name: extension.name, description: extension.description, provides: extension.provides, requires: [], capabilities: extension.capabilities }, extension.servers, facts.language, extension.unavailable);
         status.inactive = status.inactive.filter((entry) => entry.name !== extension.name);
-        facts.extensions.active.push({ name: extension.name, description: extension.description, provides: extension.provides, servers: extension.servers, help: extension.help });
+        facts.extensions.active.push({
+            name: extension.name,
+            description: extension.description,
+            provides: extension.provides,
+            capabilities: extension.capabilities.map((capability) => describeCapability(capability, "en")),
+            unavailable: extension.unavailable.map(({ capability, reason }) => ({ ...describeCapability(capability, "en"), reason })),
+            servers: extension.servers,
+            help: extension.help,
+        });
         facts.extensions.inactive = facts.extensions.inactive.filter((entry) => entry.name !== extension.name);
     }
     else {