@falkenslab/agent-kit 0.21.0 → 0.22.0

package/dist/core/messages/en.d.ts

@@ -44,6 +44,42 @@ export interface Messages {
     extensionNotInstalled(name: string): string;
     extensionsUsage: string;
     extensionsCantReopen: string;
+    /** An installed extension's options in the chat (#55). */
+    extensionOptions(name: string): string;
+    extensionNoOptions(name: string): string;
+    optionNotSet: string;
+    optionSecretSet: string;
+    optionDefault: string;
+    optionRequired: string;
+    optionSensitiveInChat(key: string, name: string): string;
+    extensionOptionsSaved(name: string): string;
+    extensionRestarted(name: string): string;
+    extensionReconfiguredReopen(name: string): string;
+    /** The catalog in the chat (#56). */
+    extensionsNoMatch: string;
+    extensionIsInstalled: string;
+    extensionUpdateAvailable(installed: string): string;
+    extensionInstalled(name: string): string;
+    extensionUpdated(name: string, from: string, to: string): string;
+    extensionsUpToDate: string;
+    extensionRemoved(name: string, withData: boolean): string;
+    extensionConfirm(spec: string, marketplace: string): string;
+    extensionsBusy: string;
+    extensionsReloaded: string;
+    /** MCP elicitation (#58): a server asking the person for something. */
+    elicitTitle(server: string): string;
+    elicitQuestion: string;
+    elicitAgain: string;
+    elicitNotANumber(text: string): string;
+    elicitOutOfRange(minimum?: number, maximum?: number): string;
+    elicitUrlTitle(server: string): string;
+    elicitUrlQuestion: string;
+    /** A workspace's extensions to trust (#57). */
+    trustTitle: string;
+    trustBody: string;
+    trustQuestion: string;
+    trustDeclined: string;
+    trustGiven(names: string): string;
     currentRun: string;
     resumed(date: string): string;
     suggestionKey: string;

package/dist/core/messages/en.js

@@ -31,8 +31,40 @@ export const en = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}, in this same session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}: the session reopens, with the same conversation)`,
     extensionNotInstalled: (name) => `(${name} isn't installed: /extensions lists them)`,
-    extensionsUsage: "(usage: /extensions, /extensions enable <name>, /extensions disable <name>)",
+    extensionsUsage: "(usage: /extensions, enable|disable <name>, config <name> [key=value…], search [words], install <name>, update [name], remove <name> [--delete-data], reload, trust)",
     extensionsCantReopen: "(this chat can't reopen its session: enable or disable it from the terminal, and start again)",
+    extensionOptions: (name) => `${name}'s options:`,
+    extensionNoOptions: (name) => `(${name} has no options)`,
+    optionNotSet: "(not set)",
+    optionSecretSet: "(set, hidden)",
+    optionDefault: "(default)",
+    optionRequired: "required",
+    optionSensitiveInChat: (key, name) => `(${key} is a secret: what's typed in the chat is kept in its history, so set it from the terminal: extension config ${name} ${key})`,
+    extensionOptionsSaved: (name) => `(${name}'s options saved: they apply when its server starts again)`,
+    extensionRestarted: (name) => `(${name}'s options saved, and its server restarted with them, in this same session)`,
+    extensionReconfiguredReopen: (name) => `(${name}'s options saved: the session reopens, with the same conversation)`,
+    extensionsNoMatch: "(no extension matches: /extensions search with other words, or none to list them all)",
+    extensionIsInstalled: "(installed)",
+    extensionUpdateAvailable: (installed) => `(installed: ${installed}, update available)`,
+    extensionInstalled: (name) => `(${name} installed: it's there in a new conversation, or now with /extensions reload, keeping this one)`,
+    extensionUpdated: (name, from, to) => `(${name} updated, ${from} → ${to}: it's there in a new conversation, or now with /extensions reload)`,
+    extensionsUpToDate: "(every extension from a marketplace is up to date)",
+    extensionRemoved: (name, withData) => `(${name} removed${withData ? ", with its data" : "; its data is kept for a reinstall"})`,
+    extensionConfirm: (spec, marketplace) => `(${spec} comes from ${marketplace}, not this agent's own marketplace: it would run on this computer with your permissions. /extensions install ${spec} --yes installs it)`,
+    extensionsBusy: "(after this turn: the agent is working)",
+    extensionsReloaded: "(the session reopens with the extensions installed now, keeping the conversation)",
+    elicitTitle: (server) => `${server} asks you`,
+    elicitQuestion: "Answer it? (Enter/y: answer, n: decline, q: cancel) ",
+    elicitAgain: "That isn't a valid value: try again, or leave it empty.",
+    elicitNotANumber: (text) => `"${text}" isn't a number`,
+    elicitOutOfRange: (minimum, maximum) => `between ${minimum ?? "…"} and ${maximum ?? "…"}`,
+    elicitUrlTitle: (server) => `${server} asks you to open a page`,
+    elicitUrlQuestion: "Open it yourself, then Enter when you're done (n: decline) ",
+    trustTitle: "This workspace brings extensions",
+    trustBody: "They run code on this computer with your permissions. Trust them only if you trust where this workspace came from:",
+    trustQuestion: "Trust them and run them? (y/N) ",
+    trustDeclined: "(they stay off: /extensions trust trusts them later)",
+    trustGiven: (names) => `(${names}: trusted in this workspace, as they are now; another version asks again)`,
     currentRun: "(this one)",
     resumed: (date) => `(resumed the conversation of ${date})`,
     suggestionKey: "tab",

package/dist/core/messages/es.js

@@ -32,8 +32,40 @@ export const es = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}, en esta misma sesión)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}: la sesión se reabre, con la misma conversación)`,
     extensionNotInstalled: (name) => `(${name} no está instalada: /extensions las lista)`,
-    extensionsUsage: "(uso: /extensions, /extensions enable <nombre>, /extensions disable <nombre>)",
+    extensionsUsage: "(uso: /extensions, enable|disable <nombre>, config <nombre> [clave=valor…], search [palabras], install <nombre>, update [nombre], remove <nombre> [--delete-data], reload, trust)",
     extensionsCantReopen: "(este chat no puede reabrir su sesión: actívala o desactívala desde la terminal y vuelve a empezar)",
+    extensionOptions: (name) => `Opciones de ${name}:`,
+    extensionNoOptions: (name) => `(${name} no tiene opciones)`,
+    optionNotSet: "(sin valor)",
+    optionSecretSet: "(con valor, oculto)",
+    optionDefault: "(por defecto)",
+    optionRequired: "obligatoria",
+    optionSensitiveInChat: (key, name) => `(${key} es un secreto: lo que se escribe en el chat queda en su historial, así que ponlo desde la terminal: extension config ${name} ${key})`,
+    extensionOptionsSaved: (name) => `(opciones de ${name} guardadas: se aplican cuando su servidor vuelva a arrancar)`,
+    extensionRestarted: (name) => `(opciones de ${name} guardadas, y su servidor reiniciado con ellas, en esta misma sesión)`,
+    extensionReconfiguredReopen: (name) => `(opciones de ${name} guardadas: la sesión se reabre, con la misma conversación)`,
+    extensionsNoMatch: "(ninguna extensión coincide: /extensions search con otras palabras, o sin ninguna para verlas todas)",
+    extensionIsInstalled: "(instalada)",
+    extensionUpdateAvailable: (installed) => `(instalada: ${installed}, hay actualización)`,
+    extensionInstalled: (name) => `(${name} instalada: está en una conversación nueva, o ya con /extensions reload, sin perder esta)`,
+    extensionUpdated: (name, from, to) => `(${name} actualizada, ${from} → ${to}: está en una conversación nueva, o ya con /extensions reload)`,
+    extensionsUpToDate: "(todas las extensiones de un marketplace están al día)",
+    extensionRemoved: (name, withData) => `(${name} desinstalada${withData ? ", con sus datos" : "; sus datos se guardan por si vuelve"})`,
+    extensionConfirm: (spec, marketplace) => `(${spec} viene de ${marketplace}, que no es el marketplace de este agente: se ejecutaría en este equipo con tus permisos. /extensions install ${spec} --yes la instala)`,
+    extensionsBusy: "(después de este turno: el agente está trabajando)",
+    extensionsReloaded: "(la sesión se reabre con las extensiones instaladas ahora, con la misma conversación)",
+    elicitTitle: (server) => `${server} te pregunta`,
+    elicitQuestion: "¿Responder? (Enter/y: responder, n: rechazar, q: cancelar) ",
+    elicitAgain: "Ese valor no vale: prueba otra vez, o déjalo vacío.",
+    elicitNotANumber: (text) => `"${text}" no es un número`,
+    elicitOutOfRange: (minimum, maximum) => `entre ${minimum ?? "…"} y ${maximum ?? "…"}`,
+    elicitUrlTitle: (server) => `${server} te pide abrir una página`,
+    elicitUrlQuestion: "Ábrela tú, y Enter cuando termines (n: rechazar) ",
+    trustTitle: "Este workspace trae extensiones",
+    trustBody: "Ejecutan código en este equipo con tus permisos. Confía en ellas solo si te fías de dónde viene este workspace:",
+    trustQuestion: "¿Confiar en ellas y ejecutarlas? (y/N) ",
+    trustDeclined: "(siguen apagadas: /extensions trust confía en ellas más tarde)",
+    trustGiven: (names) => `(${names}: de confianza en este workspace, tal como están; otra versión vuelve a preguntar)`,
     currentRun: "(esta)",
     resumed: (date) => `(retomada la conversación del ${date})`,
     suggestionKey: "tab",

package/dist/core/messages/fr.js

@@ -32,8 +32,40 @@ export const fr = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"}, dans cette même session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"} : la session se rouvre, avec la même conversation)`,
     extensionNotInstalled: (name) => `(${name} n'est pas installée : /extensions les liste)`,
-    extensionsUsage: "(usage : /extensions, /extensions enable <nom>, /extensions disable <nom>)",
+    extensionsUsage: "(usage : /extensions, enable|disable <nom>, config <nom> [clé=valeur…], search [mots], install <nom>, update [nom], remove <nom> [--delete-data], reload, trust)",
     extensionsCantReopen: "(ce chat ne peut pas rouvrir sa session : activez-la ou désactivez-la depuis le terminal, puis recommencez)",
+    extensionOptions: (name) => `Options de ${name} :`,
+    extensionNoOptions: (name) => `(${name} n'a pas d'options)`,
+    optionNotSet: "(sans valeur)",
+    optionSecretSet: "(définie, cachée)",
+    optionDefault: "(par défaut)",
+    optionRequired: "obligatoire",
+    optionSensitiveInChat: (key, name) => `(${key} est un secret : ce qu'on écrit dans le chat reste dans son historique, définissez-la donc depuis le terminal : extension config ${name} ${key})`,
+    extensionOptionsSaved: (name) => `(options de ${name} enregistrées : elles s'appliquent quand son serveur redémarre)`,
+    extensionRestarted: (name) => `(options de ${name} enregistrées, et son serveur redémarré avec elles, dans cette même session)`,
+    extensionReconfiguredReopen: (name) => `(options de ${name} enregistrées : la session se rouvre, avec la même conversation)`,
+    extensionsNoMatch: "(aucune extension ne correspond : /extensions search avec d'autres mots, ou sans pour toutes les voir)",
+    extensionIsInstalled: "(installée)",
+    extensionUpdateAvailable: (installed) => `(installée : ${installed}, mise à jour disponible)`,
+    extensionInstalled: (name) => `(${name} installée : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload, en gardant celle-ci)`,
+    extensionUpdated: (name, from, to) => `(${name} mise à jour, ${from} → ${to} : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload)`,
+    extensionsUpToDate: "(toutes les extensions d'un marketplace sont à jour)",
+    extensionRemoved: (name, withData) => `(${name} désinstallée${withData ? ", avec ses données" : " ; ses données sont gardées pour une réinstallation"})`,
+    extensionConfirm: (spec, marketplace) => `(${spec} vient de ${marketplace}, qui n'est pas le marketplace de cet agent : elle tournerait sur cet ordinateur avec vos droits. /extensions install ${spec} --yes l'installe)`,
+    extensionsBusy: "(après ce tour : l'agent travaille)",
+    extensionsReloaded: "(la session se rouvre avec les extensions installées maintenant, en gardant la conversation)",
+    elicitTitle: (server) => `${server} vous demande`,
+    elicitQuestion: "Répondre ? (Entrée/y : répondre, n : refuser, q : annuler) ",
+    elicitAgain: "Cette valeur n'est pas valide : réessayez, ou laissez vide.",
+    elicitNotANumber: (text) => `« ${text} » n'est pas un nombre`,
+    elicitOutOfRange: (minimum, maximum) => `entre ${minimum ?? "…"} et ${maximum ?? "…"}`,
+    elicitUrlTitle: (server) => `${server} vous demande d'ouvrir une page`,
+    elicitUrlQuestion: "Ouvrez-la vous-même, puis Entrée quand c'est fait (n : refuser) ",
+    trustTitle: "Cet espace de travail apporte des extensions",
+    trustBody: "Elles exécutent du code sur cet ordinateur avec vos droits. Faites-leur confiance seulement si vous avez confiance en la provenance de cet espace de travail :",
+    trustQuestion: "Leur faire confiance et les lancer ? (y/N) ",
+    trustDeclined: "(elles restent éteintes : /extensions trust leur fait confiance plus tard)",
+    trustGiven: (names) => `(${names} : de confiance dans cet espace de travail, telles qu'elles sont ; une autre version redemande)`,
     currentRun: "(celle-ci)",
     resumed: (date) => `(conversation du ${date} reprise)`,
     suggestionKey: "tab",

package/dist/core/npxPackages.d.ts

@@ -0,0 +1,48 @@
+import type { ExtensionDirs, PluginServer } from "./externalExtensions.js";
+/**
+ * Installed extensions' servers run with `npx` (#54): a `.mcp.json` that says
+ * `npx -y <package>@<x.y.z>` runs as it is in Claude Code, and in the kit too, which doesn't run
+ * npx (it needs npm, a `node` on the `PATH` for its shims, and the network while the server
+ * connects). The kit fetches the package when the extension is installed, its `sha512` integrity
+ * checked against the registry, into a cache by version shared by the agent's scopes; a session
+ * runs its `bin` with the kit's own Node (Electron's in the desktop app) through the launcher,
+ * as any installed server. Only an exact version: a published one never changes, so it's as
+ * fixed as the lock's hash. The kit installs no dependencies and runs no script: the package
+ * must bring what it needs (bundled, or `bundleDependencies`).
+ */
+/** A server run with npx: its package, the exact version, and the arguments after it (its own). */
+export interface NpxServer {
+    name: string;
+    version: string;
+    args: string[];
+}
+/** A cached package, as an extension's lock records it. */
+export interface CachedPackage {
+    /** The registry's `sha512-…`, checked when it was fetched. */
+    integrity: string;
+    /** SHA-256 over its files in the cache, checked when a session loads it. */
+    sha256: string;
+    /** Its server's script, relative to the package (its `package.json`'s `bin`). */
+    bin: string;
+}
+/** `<package>@<version>`, as a lock names a package. */
+export declare const packageSpec: (server: NpxServer) => string;
+/**
+ * Whether a server runs with npx: `undefined` when it doesn't, why the kit can't run it when it
+ * does but not as the kit can, or its package. Its command is `npx` (`npx.cmd`), its options
+ * only `-y`/`--yes`, then `<package>@<x.y.z>` and the server's own arguments.
+ */
+export declare function npxServer(server: PluginServer): NpxServer | string | undefined;
+/** Where an agent keeps the packages its extensions' npx servers run: in its scope (the project's when it has none), shared by both. */
+export declare function packageCacheDir(dirs: ExtensionDirs): string | undefined;
+/** A package's folder in the cache. */
+export declare function cachedPackageDir(cache: string, name: string, version: string): string;
+/**
+ * A package in the cache, fetched when it isn't there (or its files changed since): its
+ * integrity checked, refused when it can't run as the kit installs it. Never runs anything.
+ */
+export declare function cachePackage(cache: string, name: string, version: string): Promise<CachedPackage>;
+/** Why a package an extension's lock names can't run from the cache now (missing, or changed), or nothing. */
+export declare function cachedPackageProblem(cache: string | undefined, server: NpxServer, locked: CachedPackage | undefined): Promise<string | undefined>;
+/** Whether every package a lock names is in the cache as it was fetched (`<package>@<version>` keys). */
+export declare function cachedPackagesIntact(cache: string | undefined, locked: Record<string, CachedPackage> | undefined): Promise<boolean>;

package/dist/core/npxPackages.js

@@ -0,0 +1,121 @@
+import { cp, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { hashExtension } from "./externalExtensions.js";
+import { fetchNpmPlugin } from "./pluginDownloads.js";
+/** `<package>@<version>`, as a lock names a package. */
+export const packageSpec = (server) => `${server.name}@${server.version}`;
+/**
+ * Whether a server runs with npx: `undefined` when it doesn't, why the kit can't run it when it
+ * does but not as the kit can, or its package. Its command is `npx` (`npx.cmd`), its options
+ * only `-y`/`--yes`, then `<package>@<x.y.z>` and the server's own arguments.
+ */
+export function npxServer(server) {
+    if (!/^npx(\.cmd|\.exe)?$/i.test(path.basename(server.command)))
+        return undefined;
+    const args = server.args ?? [];
+    let index = 0;
+    for (; index < args.length && args[index].startsWith("-"); index++) {
+        if (args[index] !== "-y" && args[index] !== "--yes")
+            return `uses the npx option "${args[index]}", and the kit runs only "npx -y <package>@<version>"`;
+    }
+    const spec = args[index];
+    if (!spec)
+        return "names no package for npx";
+    const match = /^((?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*)@(\d+\.\d+\.\d+(?:-[\w.]+)?)$/i.exec(spec);
+    if (!match)
+        return `runs "${spec}" with npx without an exact version (<package>@x.y.z), which the kit needs to run the same code every time`;
+    return { name: match[1], version: match[2], args: args.slice(index + 1) };
+}
+/** Where an agent keeps the packages its extensions' npx servers run: in its scope (the project's when it has none), shared by both. */
+export function packageCacheDir(dirs) {
+    const scope = dirs.agent ?? dirs.project;
+    return scope ? path.join(scope, ".npm") : undefined;
+}
+/** A package's folder in the cache. */
+export function cachedPackageDir(cache, name, version) {
+    return path.join(cache, ...name.split("/"), version);
+}
+/** Why a package can't run as the kit installs it (its dependencies, its scripts, its bin), or its server's script. */
+async function packageBin(dir, name) {
+    let json;
+    try {
+        json = JSON.parse(await readFile(path.join(dir, "package.json"), "utf8"));
+    }
+    catch {
+        return { problem: "has no readable package.json" };
+    }
+    const bundled = json.bundleDependencies ?? json.bundledDependencies;
+    const declared = Object.keys({ ...json.dependencies, ...json.optionalDependencies });
+    const missing = bundled === true ? [] : declared.filter((dependency) => !(Array.isArray(bundled) && bundled.includes(dependency)));
+    if (missing.length)
+        return { problem: `has dependencies it doesn't bring (${missing.join(", ")}): the kit installs none, so a package must bundle them, or list them in bundleDependencies` };
+    const scripts = ["preinstall", "install", "postinstall"].filter((script) => json.scripts?.[script]);
+    if (scripts.length)
+        return { problem: `has install scripts (${scripts.join(", ")}), which the kit never runs` };
+    if ((await stat(path.join(dir, "binding.gyp")).catch(() => null))?.isFile())
+        return { problem: "builds native code when installed (binding.gyp), which the kit never does" };
+    const bins = typeof json.bin === "string" ? { [name.split("/").pop()]: json.bin } : (json.bin ?? {});
+    const entries = Object.values(bins);
+    const bin = entries.length === 1 ? entries[0] : bins[name.split("/").pop()];
+    if (!bin)
+        return { problem: entries.length ? `has several programs (bin), none named ${name.split("/").pop()}` : "has no program to run (bin in its package.json)" };
+    const script = path.resolve(dir, bin);
+    if (path.relative(dir, script).startsWith(".."))
+        return { problem: `runs a program outside itself (${bin})` };
+    if (!(await stat(script).catch(() => null))?.isFile())
+        return { problem: `has no file at ${bin}, its program` };
+    return { bin: path.relative(dir, script).split(path.sep).join("/") };
+}
+/** What the cache keeps beside each package: what was checked when it was fetched. */
+const recordOf = (dir) => `${dir}.json`;
+/**
+ * A package in the cache, fetched when it isn't there (or its files changed since): its
+ * integrity checked, refused when it can't run as the kit installs it. Never runs anything.
+ */
+export async function cachePackage(cache, name, version) {
+    const dir = cachedPackageDir(cache, name, version);
+    const record = await readFile(recordOf(dir), "utf8").then((text) => JSON.parse(text), () => undefined);
+    if (record && (await stat(dir).catch(() => null))?.isDirectory() && (await hashExtension(dir)) === record.sha256)
+        return record;
+    const fetched = await fetchNpmPlugin(name, version);
+    try {
+        const bin = await packageBin(fetched.dir, name);
+        if ("problem" in bin)
+            throw new Error(`${name}@${version} can't run in the kit: it ${bin.problem}.`);
+        // Into its place whole: a session never sees half a package.
+        await rm(dir, { recursive: true, force: true });
+        await mkdir(path.dirname(dir), { recursive: true });
+        // Another disk than the temporary folder's: copied instead.
+        await rename(fetched.dir, dir).catch(() => cp(fetched.dir, dir, { recursive: true }));
+        const cached = { integrity: fetched.integrity, sha256: await hashExtension(dir), bin: bin.bin };
+        await writeFile(recordOf(dir), `${JSON.stringify(cached, null, 2)}\n`, "utf8");
+        return cached;
+    }
+    finally {
+        await rm(fetched.dir, { recursive: true, force: true });
+    }
+}
+/** Why a package an extension's lock names can't run from the cache now (missing, or changed), or nothing. */
+export async function cachedPackageProblem(cache, server, locked) {
+    const spec = packageSpec(server);
+    if (!cache || !locked)
+        return `runs ${spec}, which wasn't fetched when it was installed: install it again`;
+    const dir = cachedPackageDir(cache, server.name, server.version);
+    if (!(await stat(dir).catch(() => null))?.isDirectory())
+        return `runs ${spec}, which isn't in the agent's package cache any more: install it again`;
+    if ((await hashExtension(dir)) !== locked.sha256)
+        return `runs ${spec}, whose files in the cache changed since it was installed: install it again to trust them`;
+    return undefined;
+}
+/** Whether every package a lock names is in the cache as it was fetched (`<package>@<version>` keys). */
+export async function cachedPackagesIntact(cache, locked) {
+    for (const [spec, cached] of Object.entries(locked ?? {})) {
+        const at = spec.lastIndexOf("@");
+        if (!cache || at <= 0)
+            return false;
+        const dir = cachedPackageDir(cache, spec.slice(0, at), spec.slice(at + 1));
+        if (!(await stat(dir).catch(() => null))?.isDirectory() || (await hashExtension(dir)) !== cached.sha256)
+            return false;
+    }
+    return true;
+}

package/dist/core/pluginDownloads.d.ts

@@ -2,10 +2,11 @@
 export declare function untar(tar: Uint8Array): Map<string, Uint8Array>;
 /** The highest of `versions` that `wanted` asks for: an exact version, or a range (`^`, `~`, comparators, `*`). */
 export declare function pickVersion(versions: readonly string[], wanted: string): string | undefined;
-/** An npm package into a new temporary folder: `{ dir, version }`. */
+/** An npm package into a new temporary folder: `{ dir, version, integrity }` (the registry's `sha512-…`, checked). */
 export declare function fetchNpmPlugin(name: string, wanted?: string, registry?: string): Promise<{
     dir: string;
     version: string;
+    integrity: string;
 }>;
 /** A zip archive into a new temporary folder; the plugin is its root, or its only folder. */
 export declare function fetchArchivePlugin(url: string, sha256?: string): Promise<{

package/dist/core/pluginDownloads.js

@@ -89,7 +89,7 @@ export function pickVersion(versions, wanted) {
         return 0;
     }).at(-1);
 }
-/** An npm package into a new temporary folder: `{ dir, version }`. */
+/** An npm package into a new temporary folder: `{ dir, version, integrity }` (the registry's `sha512-…`, checked). */
 export async function fetchNpmPlugin(name, wanted = "latest", registry = "https://registry.npmjs.org") {
     if (!/^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(name))
         throw new Error(`"${name}" isn't an npm package name.`);
@@ -113,7 +113,7 @@ export async function fetchNpmPlugin(name, wanted = "latest", registry = "https:
         // npm puts a package's files under package/.
         const files = [...untar(gunzipSync(tarball))].flatMap(([file, data]) => (file.startsWith("package/") ? [[file.slice("package/".length), data]] : []));
         await writeFiles(dir, files);
-        return { dir, version };
+        return { dir, version, integrity: dist.integrity };
     }
     catch (error) {
         await rm(dir, { recursive: true, force: true });

package/dist/core/readOnlyHints.d.ts

@@ -0,0 +1,13 @@
+import type { McpServerStatus } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * Plan mode's read-only tools from the MCP servers themselves (#53): for an installed extension
+ * whose manifest lists no `readOnlyTools`, a tool its server marks `readOnlyHint` only reads.
+ *
+ * Asked when plan mode meets the call, not once at start: a server is `pending` for seconds after
+ * the session starts, and one turned off and on again (liveExtensions.ts) may come back with
+ * other tools. The SDK's `mcpServerStatus()` gives each connected server's tools with
+ * `annotations.readOnly`, set exactly when the server says `readOnlyHint: true` (confirmed
+ * empirically: `readOnlyHint: false` and no hint both leave it out; the names are the short ones).
+ * Anything else — not connected, not asked in time, no hint — is no: plan mode denies.
+ */
+export declare function createReadOnlyHints(servers: readonly string[], status: () => (() => Promise<McpServerStatus[]>) | undefined): (toolName: string) => Promise<boolean>;

package/dist/core/readOnlyHints.js

@@ -0,0 +1,26 @@
+/**
+ * Plan mode's read-only tools from the MCP servers themselves (#53): for an installed extension
+ * whose manifest lists no `readOnlyTools`, a tool its server marks `readOnlyHint` only reads.
+ *
+ * Asked when plan mode meets the call, not once at start: a server is `pending` for seconds after
+ * the session starts, and one turned off and on again (liveExtensions.ts) may come back with
+ * other tools. The SDK's `mcpServerStatus()` gives each connected server's tools with
+ * `annotations.readOnly`, set exactly when the server says `readOnlyHint: true` (confirmed
+ * empirically: `readOnlyHint: false` and no hint both leave it out; the names are the short ones).
+ * Anything else — not connected, not asked in time, no hint — is no: plan mode denies.
+ */
+export function createReadOnlyHints(servers, status) {
+    return async (toolName) => {
+        const server = servers.find((name) => toolName.startsWith(`mcp__${name}__`));
+        const read = status();
+        if (!server || !read)
+            return false;
+        const tool = toolName.slice(`mcp__${server}__`.length);
+        const statuses = await within(read(), []);
+        const found = statuses.find((entry) => entry.name === server && entry.status === "connected");
+        return found?.tools?.some((entry) => entry.name === tool && entry.annotations?.readOnly === true) ?? false;
+    };
+}
+// A call to the session made from a hook, before a tool runs: never let it hold the tool up.
+const TIMEOUT_MS = 3000;
+const within = (promise, fallback) => Promise.race([promise.catch(() => fallback), new Promise((resolve) => setTimeout(() => resolve(fallback), TIMEOUT_MS).unref())]);

package/dist/core/runner.js

@@ -36,6 +36,8 @@ export function runQuery(prompt, options) {
         contextUsage: () => contextUsage(),
         toggleMcpServer: (server, enabled) => result.toggleMcpServer(server, enabled),
         reloadPlugins: () => result.reloadPlugins(),
+        reconnectMcpServer: (server) => result.reconnectMcpServer(server),
+        mcpServerStatus: () => result.mcpServerStatus(),
     });
     // The main agent's tool calls by id, to name the results that come back for them.
     const toolNames = new Map();

package/dist/core/session.d.ts

@@ -6,7 +6,7 @@ import type { ToolLabels } from "./toolLabels.js";
 import type { AgentSpec, BaseSessionConfig } from "./agentSpec.js";
 import { type Language } from "./language.js";
 import { type RunFolder } from "./runs.js";
-import { type ExtensionSwitch } from "./liveExtensions.js";
+import { type ExtensionRestart, type ExtensionSwitch } from "./liveExtensions.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
  * *how* the agent runs a session (system prompt, tools, MCP servers, hooks), independent
@@ -44,11 +44,23 @@ export declare function buildSessionOptions<TConfig extends BaseSessionConfig>(c
     apis: Record<string, Record<string, unknown>>;
     /** Turns an installed extension off or on in the running session; false when that takes opening it again (#49). */
     switchExtension: ExtensionSwitch;
+    /** Restarts an installed extension's servers in the running session, with its options as they are now (#55). */
+    restartExtension: ExtensionRestart;
 }>;
 export { createModeControl, togglePlanMode, type ModeControl } from "./modeControl.js";
 /** The extensions of a session: where they're installed, what's installed, what runs and what can't (with why). */
 export interface ExtensionsStatus {
     dirs: ExtensionDirs;
+    /** The agent's own marketplace (`officialMarketplace`), for the chats' catalog. */
+    official?: string;
+    /** The topics the chats' catalog shows (`catalogTopics`); none, every extension. */
+    catalogTopics?: string[];
+    /** The workspace's extensions that don't run until the person trusts them there (#57): the chats ask. */
+    untrusted: {
+        name: string;
+        version?: string;
+        source: string;
+    }[];
     installed: InstalledExtension[];
     /** The names of the extensions this session runs with, the kit's and the agent's too. */
     active: string[];

package/dist/core/session.js

@@ -17,12 +17,15 @@ import { extensionsPromptSection, resolveExtensions, skillsMissingCapabilities }
 import { allowAnyMcpTool } from "./mcpPermissions.js";
 import { pluginAgents } from "./pluginAgents.js";
 import { outsideArchive, unpackedClaudeExecutable } from "./packaged.js";
-import { listInstalled, loadExternalExtensions } from "./externalExtensions.js";
+import { listInstalled, loadExternalExtensions, scopePrivateDir } from "./externalExtensions.js";
 import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
 import { createSessionView, registerSessionView } from "./sessionFacts.js";
-import { createExtensionSwitch, mountPlugin } from "./liveExtensions.js";
+import { createExtensionRestart, createExtensionSwitch, mountPlugin } from "./liveExtensions.js";
+import { secretsDir } from "./extensionOptions.js";
+import { createElicitationHandler } from "./elicitation.js";
+import { createReadOnlyHints } from "./readOnlyHints.js";
 import { agentKitVersion } from "./version.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
@@ -170,8 +173,18 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const allowedSubagentTypes = [...new Set([...(subagents?.allowedSubagentTypes ?? []), ...Object.keys(fromPlugins)])];
     // The extensions' read-only tools, for the plan gate: a list the live switch changes (liveExtensions.ts).
     const readOnlyTools = fromExtensions((contribution) => contribution.readOnlyTools);
+    // Those whose manifest lists none: their servers say, asked while the session runs (#53).
+    const readOnlyHintServers = fromExtensions((contribution) => contribution.readOnlyHintServers);
     // What no file tool may touch: the agent's denied paths and the SDK's own credentials.
-    const deniedPaths = [...(config.deniedPaths ?? []), path.join(claudeConfigDir(), ".credentials.json")];
+    // And the installed extensions' sensitive option values (#55), in each scope's .secrets/.
+    const deniedPaths = [
+        ...(config.deniedPaths ?? []),
+        path.join(claudeConfigDir(), ".credentials.json"),
+        ...["agent", "project"].flatMap((scope) => {
+            const privateDir = config.extensionDirs ? scopePrivateDir(config.extensionDirs, scope) : undefined;
+            return privateDir ? [secretsDir(privateDir)] : [];
+        }),
+    ];
     const transcriptPath = path.join(runDir, "transcript.jsonl");
     const transcriptLogger = createTranscriptLogger(transcriptPath, config.secrets ?? []);
     const promptSections = [
@@ -269,6 +282,9 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
             // The date and date arithmetic, in every session and mode: only reads (tools/time.ts).
             time: createTimeServer(config.timeZone),
         },
+        // A server asking the person for something mid-tool (MCP elicitation, #58): through the
+        // interaction port, never the model; declined when no one can be asked (autonomous).
+        onElicitation: createElicitationHandler(runDir, () => modeControl.mode !== "autonomous"),
         hooks: {
             PreToolUse: [
                 { hooks: [transcriptLogger.preToolUse] },
@@ -303,6 +319,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                                 createPlanGate({
                                     projectDir: config.projectDir,
                                     readOnlyTools,
+                                    ...(readOnlyHintServers.length ? { isReadOnlyHinted: createReadOnlyHints(readOnlyHintServers, () => late.view?.controls().mcpServerStatus) } : {}),
                                     ...(spec.planMode?.isPlanFile ? { isPlanFile: (filePath) => spec.planMode.isPlanFile(filePath, config) } : {}),
                                     ...(spec.planMode?.isReadOnlyTool ? { isReadOnlyTool: spec.planMode.isReadOnlyTool } : {}),
                                 }, () => modeControl.mode === "plan"),
@@ -330,6 +347,9 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const toolLabels = Object.assign({}, ...added.map((contribution) => contribution.toolLabels ?? {}));
     const extensions = {
         dirs: extensionDirs,
+        ...(config.officialMarketplace ? { official: config.officialMarketplace } : {}),
+        ...(config.catalogTopics?.length ? { catalogTopics: config.catalogTopics } : {}),
+        untrusted: external.untrusted.map((installed) => ({ name: installed.name, ...(installed.manifest?.version ? { version: installed.manifest.version } : {}), source: installed.lock.marketplace ?? installed.lock.source })),
         installed: await listInstalled(extensionDirs),
         active: resolved.active.map(({ extension }) => extension.name),
         about: Object.fromEntries(resolved.active.map(({ extension, manifest }) => [extension.name, { description: manifest.description, provides: manifest.provides }])),
@@ -357,8 +377,9 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     };
     late.view = createSessionView(viewBase, modeControl);
     registerSessionView(sdkOptions, late.view);
-    // Turning an installed extension off and on while the session runs (#49).
-    const switchExtension = createExtensionSwitch(resolved.active.flatMap(({ extension, manifest }, index) => {
+    // Turning an installed extension off and on while the session runs (#49), and restarting its
+    // servers when its options change (#55).
+    const liveExtensions = resolved.active.flatMap(({ extension, manifest }, index) => {
         const installed = installedDirs.get(extension.name);
         if (!installed)
             return [];
@@ -378,9 +399,12 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 help: contribution?.helpLines ?? [],
             },
         ];
-    }), { readOnlyTools, allowedSubagentTypes, toolLabels, status: extensions, facts: viewBase, controls: () => late.view?.controls() ?? {} });
+    });
+    const liveTargets = { readOnlyTools, allowedSubagentTypes, toolLabels, status: extensions, facts: viewBase, controls: () => late.view?.controls() ?? {} };
+    const switchExtension = createExtensionSwitch(liveExtensions, liveTargets);
+    const restartExtension = createExtensionRestart(liveExtensions, liveTargets);
     const apis = Object.fromEntries(resolved.active.flatMap(({ extension }, index) => (added[index]?.api ? [[extension.name, added[index].api]] : [])));
-    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, switchExtension };
+    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, switchExtension, restartExtension };
 }
 export { createModeControl, togglePlanMode } from "./modeControl.js";
 /** The Claude Code configuration folder the SDK's CLI uses: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */

package/dist/core/sessionFacts.d.ts

@@ -1,4 +1,4 @@
-import type { Options, SlashCommand } from "@anthropic-ai/claude-agent-sdk";
+import type { McpServerStatus, Options, SlashCommand } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentIdentity, Mode } from "./agentSpec.js";
 import type { Language } from "./language.js";
 import type { ModeControl } from "./modeControl.js";
@@ -61,6 +61,10 @@ export interface SessionLive {
     /** The running session's controls an installed extension is turned off and on with (liveExtensions.ts). */
     toggleMcpServer?: (server: string, enabled: boolean) => Promise<void>;
     reloadPlugins?: () => Promise<unknown>;
+    /** Restarts one of its MCP servers: an installed extension's, when its options change (#55). */
+    reconnectMcpServer?: (server: string) => Promise<void>;
+    /** Its MCP servers as they are now: their tools and what each says of itself (plan mode's read-only hints). */
+    mcpServerStatus?: () => Promise<McpServerStatus[]>;
 }
 /** The facts known when the options are built: everything but the mode and what only the running session knows. */
 export type StaticSessionFacts = Omit<SessionFacts, "mode" | "switchableModes" | "tools" | "commands" | "context" | "extensions"> & {

package/dist/core/workspaceTrust.d.ts

@@ -0,0 +1,12 @@
+import { type ExtensionDirs, type LockEntry } from "./externalExtensions.js";
+/** What's trusted of an extension: its code, its files' hash and its npx packages'. */
+export declare function codeHash(lock: LockEntry): string;
+/** Whether an extension of a project's scope is trusted in that workspace, with the code its lock has now. */
+export declare function isTrusted(agentDir: string, projectScope: string, name: string, lock: LockEntry): Promise<boolean>;
+/** Trusts these extensions of a project's scope, with the code their lock has now. */
+export declare function trust(agentDir: string, projectScope: string, entries: Record<string, LockEntry>): Promise<void>;
+/**
+ * Trusts a workspace's extensions (its project scope's, all or `names`) with the code its lock
+ * has now: what the person does when the chat asks, or with `extension trust`. The names trusted.
+ */
+export declare function trustWorkspace(dirs: ExtensionDirs, names?: readonly string[]): Promise<string[]>;