@falkenslab/agent-kit 0.18.0 → 0.20.0

package/dist/core/externalExtensions.js

@@ -0,0 +1,368 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cp, mkdtemp, readdir, readFile, rm, stat, writeFile, mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { getLanguage } from "./messages/index.js";
+import { truncate } from "./toolLabels.js";
+import { agentKitVersion } from "./version.js";
+import { outsideArchive } from "./packaged.js";
+export const LOCK_FILE = "extensions.lock.json";
+/** A scope's lock: its extensions by name. */
+export async function readLock(scopeDir) {
+    try {
+        return JSON.parse(await readFile(path.join(scopeDir, LOCK_FILE), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+async function writeLock(scopeDir, lock) {
+    await mkdir(scopeDir, { recursive: true });
+    const sorted = Object.fromEntries(Object.keys(lock).sort().map((name) => [name, lock[name]]));
+    await writeFile(path.join(scopeDir, LOCK_FILE), `${JSON.stringify(sorted, null, 2)}\n`, "utf8");
+}
+/** Reads an extension's manifest, checking what the kit needs from it. */
+export async function readExternalManifest(dir) {
+    const file = path.join(dir, ".claude-plugin", "plugin.json");
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        throw new Error(`${dir} isn't an extension: it has no readable .claude-plugin/plugin.json.`);
+    }
+    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"] ?? {});
+    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;
+    return {
+        name,
+        description: typeof raw.description === "string" ? raw.description : "",
+        ...text("version"),
+        ...(author && typeof author === "object" && typeof author.name === "string"
+            ? { author: { name: author.name, ...(author.email ? { email: author.email } : {}), ...(author.url ? { url: author.url } : {}) } }
+            : {}),
+        ...text("homepage"),
+        ...(typeof repository === "string" ? { repository } : {}),
+        ...text("license"),
+        ...(Array.isArray(raw.keywords) ? { keywords: raw.keywords.filter((keyword) => typeof keyword === "string") } : {}),
+        provides: kit.provides ?? [],
+        requires: kit.requires ?? [],
+        ...(kit.kit ? { kit: kit.kit } : {}),
+        needs: Array.isArray(kit.needs) ? kit.needs.filter((program) => typeof program === "string") : [],
+        servers: await pluginServers(dir, raw),
+        readOnlyTools: kit.readOnlyTools ?? [],
+        labels: kit.labels ?? {},
+        ...(kit.help ? { help: kit.help } : {}),
+    };
+}
+/**
+ * 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.
+ */
+async function pluginServers(dir, raw) {
+    const read = async (file) => {
+        try {
+            return JSON.parse(await readFile(path.join(dir, file), "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw new Error(`${file} can't be read as JSON.`, { cause: error });
+        }
+    };
+    let declared = raw.mcpServers;
+    if (typeof declared === "string")
+        declared = await read(declared);
+    if (declared === undefined)
+        declared = await read(".mcp.json");
+    if (declared && typeof declared === "object" && "mcpServers" in declared)
+        declared = declared.mcpServers;
+    if (declared === undefined || declared === null)
+        return {};
+    if (typeof declared !== "object")
+        throw new Error("its MCP servers aren't a JSON object.");
+    const servers = {};
+    for (const [name, server] of Object.entries(declared)) {
+        if (!server || typeof server.command !== "string")
+            throw new Error(`its MCP server "${name}" has no command.`);
+        servers[name] = { command: server.command, ...(Array.isArray(server.args) ? { args: server.args.map(String) } : {}), ...(server.env ? { env: server.env } : {}) };
+    }
+    return servers;
+}
+/** `${CLAUDE_PLUGIN_ROOT}` (the extension's folder) and `${VAR}` (the agent's variable) in a server's values. */
+function expand(value, root) {
+    return value.replace(/\$\{(\w+)\}/g, (_, name) => (name === "CLAUDE_PLUGIN_ROOT" ? root : (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.
+ */
+function serverLaunch(name, server, root) {
+    if (!/^node(\.exe)?$/i.test(path.basename(server.command)))
+        return `runs its server "${name}" with "${server.command}": only Node servers can be installed`;
+    const [script, ...args] = (server.args ?? []).map((arg) => expand(arg, root));
+    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})`;
+    return { entry, args, env: Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), root)])) };
+}
+/** Why an extension's servers can't run, or nothing: each must be Node, with its script there. */
+async function serversProblem(manifest, root) {
+    for (const [name, server] of Object.entries(manifest.servers)) {
+        const launch = serverLaunch(name, server, root);
+        if (typeof launch === "string")
+            return launch;
+        if (!(await stat(launch.entry).catch(() => null))?.isFile())
+            return `has no script at ${path.relative(root, launch.entry)} for its server "${name}"`;
+    }
+    return undefined;
+}
+/** SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. */
+export async function hashExtension(dir) {
+    const hash = createHash("sha256");
+    async function walk(relative) {
+        const entries = (await readdir(path.join(dir, relative), { withFileTypes: true })).filter((entry) => entry.name !== ".git");
+        for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+            const child = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                await walk(child);
+            else if (entry.isFile())
+                hash.update(`${child}\0`).update(await readFile(path.join(dir, child))).update("\0");
+        }
+    }
+    await walk("");
+    return hash.digest("hex");
+}
+/**
+ * Whether `version` (x.y.z) is in `range`: comparators separated by spaces, all of which must
+ * hold (`>=0.19.0 <0.21.0`, `=0.19.2`, `0.19.2`).
+ */
+export function inKitRange(version, range) {
+    const parse = (text) => text.split("-")[0].split(".").map((part) => Number(part) || 0);
+    const compare = (a, b) => {
+        for (let i = 0; i < 3; i++)
+            if ((a[i] ?? 0) !== (b[i] ?? 0))
+                return (a[i] ?? 0) - (b[i] ?? 0);
+        return 0;
+    };
+    const current = parse(version);
+    return range
+        .trim()
+        .split(/\s+/)
+        .every((comparator) => {
+        const match = /^(>=|<=|>|<|=)?\s*v?(\d+(?:\.\d+){0,2})$/.exec(comparator);
+        if (!match)
+            return false;
+        const order = compare(current, parse(match[2]));
+        switch (match[1]) {
+            case ">=":
+                return order >= 0;
+            case "<=":
+                return order <= 0;
+            case ">":
+                return order > 0;
+            case "<":
+                return order < 0;
+            default:
+                return order === 0;
+        }
+    });
+}
+/** Every extension installed in the scopes, the project's first. */
+export async function listInstalled(dirs) {
+    const installed = [];
+    for (const scope of ["project", "agent"]) {
+        const scopeDir = dirs[scope];
+        if (!scopeDir)
+            continue;
+        for (const [name, lock] of Object.entries(await readLock(scopeDir))) {
+            const dir = path.join(scopeDir, name);
+            const manifest = await readExternalManifest(dir).catch(() => undefined);
+            installed.push({ name, scope, dir, lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
+        }
+    }
+    return installed;
+}
+/** The launcher that starts an external extension's server with a clean environment. */
+export function extensionLauncherPath() {
+    // Node runs it as another process: outside the archive when packaged (#42).
+    return outsideArchive(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "extension-launcher.mjs"));
+}
+/** Its tools' chat labels in the kit's language, from its manifest: `{field}` takes the input; for each of its servers. */
+function manifestToolLabels(manifest) {
+    const language = getLanguage();
+    const fill = (template, input) => template.replace(/\{(\w+)\}/g, (_, field) => (input[field] === undefined ? "" : truncate(String(input[field]), 60)));
+    return Object.fromEntries(Object.entries(manifest.labels).flatMap(([tool, byLanguage]) => {
+        const texts = byLanguage[language] ?? byLanguage.en;
+        if (!texts)
+            return [];
+        const label = { label: (input) => fill(texts.label, input), ...(texts.phrase ? { phrase: texts.phrase } : {}) };
+        return Object.keys(manifest.servers).map((server) => [`mcp__${server}__${tool}`, label]);
+    }));
+}
+/** The extension an installed one makes: its servers started through the launcher, its rules from its manifest. */
+function externalExtension(installed, manifest) {
+    return {
+        name: manifest.name,
+        plugin: installed.dir,
+        external: true,
+        async contribute() {
+            const servers = {};
+            for (const [name, server] of Object.entries(manifest.servers)) {
+                const launch = serverLaunch(name, server, installed.dir);
+                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 };
+            }
+            return {
+                mcpServers: servers,
+                readOnlyTools: Object.keys(manifest.servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)),
+                toolLabels: manifestToolLabels(manifest),
+                ...(manifest.help ? { helpLines: [manifest.help] } : {}),
+            };
+        },
+    };
+}
+/** 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 = [];
+    for (const installed of await listInstalled(dirs)) {
+        if (installed.shadowed || !installed.lock.enabled)
+            continue;
+        const reason = await problem(installed);
+        if (typeof reason === "string")
+            off.push({ name: installed.name, reason });
+        else
+            extensions.push(externalExtension(installed, reason));
+    }
+    return { extensions, off };
+}
+/** 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;
+}
+async function problem(installed) {
+    let manifest;
+    try {
+        if ((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);
+    }
+    catch (error) {
+        return `can't be read (${error instanceof Error ? error.message : String(error)})`;
+    }
+    if (manifest.name !== installed.name)
+        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 exec = promisify(execFile);
+/** Whether `source` names a git repository rather than a folder. */
+export function isGitSource(source) {
+    return /^(https?:\/\/|git@|ssh:\/\/|git:\/\/|file:\/\/|github:)/.test(source) || /\.git(#.*)?$/.test(source);
+}
+/**
+ * Installs an extension into a scope from a folder or a git repository (`url#ref`, `sha` to pin
+ * a commit, and `subdir` for one inside it): copies its files (never runs a script), checks its
+ * 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.
+ */
+export async function addExtension(source, scopeDir, options = {}) {
+    let from = path.resolve(source);
+    let commit;
+    let clone;
+    if (isGitSource(source)) {
+        const [url, ref] = source.replace(/^github:/, "https://github.com/").split("#");
+        clone = await mkdtemp(path.join(os.tmpdir(), "agent-kit-extension-"));
+        // A pinned commit needs the history to check it out; otherwise the tip is enough.
+        await exec("git", ["clone", ...(options.sha ? [] : ["--depth", "1"]), ...(ref ? ["--branch", ref] : []), url, clone]);
+        if (options.sha)
+            await exec("git", ["-C", clone, "checkout", "--quiet", options.sha]);
+        commit = (await exec("git", ["-C", clone, "rev-parse", "HEAD"])).stdout.trim();
+        if (options.sha && commit !== options.sha.toLowerCase())
+            throw new Error(`${url} has no commit ${options.sha}.`);
+        from = clone;
+    }
+    try {
+        if (options.subdir)
+            from = path.join(from, options.subdir);
+        const manifest = await readExternalManifest(from);
+        const servers = await serversProblem(manifest, from);
+        if (servers)
+            throw new Error(`${manifest.name} can't be installed: it ${servers}.`);
+        const target = path.join(scopeDir, manifest.name);
+        const lock = await readLock(scopeDir);
+        const replaced = Boolean(lock[manifest.name]);
+        await rm(target, { recursive: true, force: true });
+        await mkdir(scopeDir, { recursive: true });
+        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 } : {}),
+            sha256: await hashExtension(target),
+            enabled: true,
+            installed: new Date().toISOString(),
+        };
+        await writeLock(scopeDir, lock);
+        return { name: manifest.name, replaced, ...(commit ? { commit } : {}) };
+    }
+    finally {
+        if (clone)
+            await rm(clone, { recursive: true, force: true });
+    }
+}
+/** Removes an extension from a scope (its files and its lock entry); false when it wasn't there. */
+export async function removeExtension(scopeDir, name) {
+    const lock = await readLock(scopeDir);
+    if (!lock[name])
+        return false;
+    delete lock[name];
+    await rm(path.join(scopeDir, name), { recursive: true, force: true });
+    await writeLock(scopeDir, lock);
+    return true;
+}
+/** Enables or disables an installed extension in a scope; false when it isn't there. */
+export async function setExtensionEnabled(scopeDir, name, enabled) {
+    const lock = await readLock(scopeDir);
+    if (!lock[name])
+        return false;
+    lock[name] = { ...lock[name], enabled };
+    await writeLock(scopeDir, lock);
+    return true;
+}

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

@@ -7,6 +7,8 @@ export interface PlanScope {
     isPlanFile?(filePath: string): boolean;
     /** Whether one of the agent's own MCP tools only reads. */
     isReadOnlyTool?(toolName: string, input: Record<string, unknown>): boolean;
+    /** The enabled extensions' MCP tools that only read (`mcp__<server>__<tool>`). */
+    readOnlyTools?: readonly string[];
 }
 /**
  * The reason to deny `toolName` with `input` in plan mode, or `undefined` to let it through.

package/dist/core/hooks/planGate.js

@@ -3,15 +3,6 @@ import path from "node:path";
 const READING_TOOLS = new Set(["Read", "Glob", "Grep", "WebFetch", "WebSearch", "Skill", "Agent", "TodoWrite"]);
 /** The kit's own MCP servers whose tools only ask a human (approvals, manual intervention) or only read (the date and time). */
 const ASKING_SERVERS = ["mcp__approvals__", "mcp__manualLogin__", "mcp__time__"];
-/** The kit's own MCP tools that only read, on servers that also have tools that write. */
-const READING_KIT_TOOLS = new Set([
-    "mcp__sourceFiles__list_sources",
-    "mcp__sourceFiles__extract_text",
-    "mcp__knowledge__knowledge_index",
-    "mcp__knowledge__knowledge_search",
-    "mcp__knowledge__knowledge_read",
-    "mcp__knowledge__knowledge_check",
-]);
 /** Why a call is denied in plan mode, and what the model should do instead. */
 const denial = "Plan mode: nothing can be changed until the user leaves plan mode. Keep reading and researching, then present the plan; the user switches out of plan mode when they want it carried out.";
 /**
@@ -22,7 +13,7 @@ const denial = "Plan mode: nothing can be changed until the user leaves plan mod
 export function checkPlanScope(scope, toolName, input) {
     if (READING_TOOLS.has(toolName))
         return undefined;
-    if (ASKING_SERVERS.some((prefix) => toolName.startsWith(prefix)) || READING_KIT_TOOLS.has(toolName))
+    if (ASKING_SERVERS.some((prefix) => toolName.startsWith(prefix)) || scope.readOnlyTools?.includes(toolName))
         return undefined;
     if (toolName === "Write" || toolName === "Edit") {
         const target = typeof input.file_path === "string" && input.file_path !== "" ? path.resolve(scope.projectDir, input.file_path) : undefined;

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

@@ -8,4 +8,4 @@ import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
  * session.ts's `ModeControl`): the hook stays registered and, while inactive, gives no
  * decision at all, so the tool call goes on exactly as if the hook weren't there.
  */
-export declare function createStepGate(runDir: string, isActive?: () => boolean): HookCallback;
+export declare function createStepGate(runDir: string, isActive?: () => boolean, selfAskingTools?: readonly string[]): HookCallback;

package/dist/core/hooks/stepGate.js

@@ -1,7 +1,7 @@
 import { askForDecision } from "./humanInput.js";
 import { t } from "../messages/index.js";
 const SELF_ASKING_SERVERS = ["mcp__approvals__", "mcp__manualLogin__"];
-const SELF_ASKING_TOOLS = new Set(["mcp__sourceFiles__request_file", "mcp__sourceFiles__retire_source", "mcp__knowledge__knowledge_retire", "TodoWrite"]);
+const SELF_ASKING_TOOLS = new Set(["TodoWrite"]);
 /**
  * PreToolUse hook for "interactive" mode: pauses before every action and asks for
  * confirmation (by keyboard or by file, see humanInput.ts), like reviewing a plan step
@@ -11,14 +11,14 @@ const SELF_ASKING_TOOLS = new Set(["mcp__sourceFiles__request_file", "mcp__sourc
  * session.ts's `ModeControl`): the hook stays registered and, while inactive, gives no
  * decision at all, so the tool call goes on exactly as if the hook weren't there.
  */
-export function createStepGate(runDir, isActive = () => true) {
+export function createStepGate(runDir, isActive = () => true, selfAskingTools = []) {
     return async (input) => {
         if (!isActive())
             return {};
         const pre = input;
         // A tool that asks the person itself (an approval, a question, the plan, a file, retiring
         // a source) or only keeps the task list isn't asked about first: that would be asking to ask.
-        if (SELF_ASKING_SERVERS.some((prefix) => pre.tool_name.startsWith(prefix)) || SELF_ASKING_TOOLS.has(pre.tool_name))
+        if (SELF_ASKING_SERVERS.some((prefix) => pre.tool_name.startsWith(prefix)) || SELF_ASKING_TOOLS.has(pre.tool_name) || selfAskingTools.includes(pre.tool_name))
             return {};
         const answer = await askForDecision(runDir, {
             title: t().proposedAction,

package/dist/core/liveExtensions.d.ts

@@ -0,0 +1,51 @@
+import type { ExtensionsStatus } from "./session.js";
+import type { SessionLive, StaticSessionFacts } from "./sessionFacts.js";
+import type { ToolLabels } from "./toolLabels.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
+ * (`toggleMcpServer()`, which removes their tools from the model's context and brings them back,
+ * confirmed empirically) and its plugin, a copy in the run's folder, is emptied or filled again
+ * before `reloadPlugins()` (its skills, commands and subagents go and come back, confirmed
+ * empirically). The kit's own lists follow: the plan gate's read-only tools, the subagent gates'
+ * allowed types, the chat's labels, `/extensions` and what `about_me` says. One that wasn't
+ * running has no plugin path the session knows: it takes reopening the session.
+ *
+ * Not through `setMcpServers()`: it leaves the servers given at start alone (confirmed
+ * empirically: removing one from its set removes nothing).
+ */
+/** What an installed extension brought to this session, to take it away and bring it back. */
+export interface LiveExtension {
+    name: string;
+    /** Where it's installed (its scope's folder): the plugin copy is filled from there. */
+    installedDir: string;
+    scopeDir: string;
+    /** Its plugin, copied into the run's folder for this session. */
+    pluginCopy: string;
+    servers: string[];
+    readOnlyTools: string[];
+    toolLabels: ToolLabels;
+    /** Its subagents, as the type gate names them (`<plugin>:<name>`). */
+    agents: string[];
+    description: string;
+    provides: string[];
+    help: string[];
+}
+/** The session's own lists the switch keeps in step: the same objects the gates, the chat and the view read. */
+export interface LiveTargets {
+    readOnlyTools: string[];
+    allowedSubagentTypes: string[];
+    toolLabels: ToolLabels;
+    status: ExtensionsStatus;
+    facts: StaticSessionFacts;
+    /** The running session's controls, once it has started. */
+    controls: () => SessionLive;
+}
+/**
+ * Turns `name` on or off in the running session; false when it can't be done here (it wasn't
+ * running when the session opened, the session hasn't started, or its files changed since it
+ * was installed), and the session must be opened again.
+ */
+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;

package/dist/core/liveExtensions.js

@@ -0,0 +1,70 @@
+import { cp, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { hashExtension, listInstalled, readLock } from "./externalExtensions.js";
+/** The switch for a session's installed extensions. */
+export function createExtensionSwitch(extensions, targets) {
+    const off = new Set();
+    return async (name, enabled) => {
+        const extension = extensions.find((candidate) => candidate.name === name);
+        const controls = targets.controls();
+        if (!extension || !controls.toggleMcpServer || !controls.reloadPlugins)
+            return false;
+        if (enabled === !off.has(name))
+            return true; // already as asked
+        if (enabled) {
+            // Its files as they were installed, or nothing: a changed one is for a new session to judge.
+            const lock = (await readLock(extension.scopeDir))[name];
+            if (!lock || lock.sha256 !== (await hashExtension(extension.installedDir)))
+                return false;
+            await cp(extension.installedDir, extension.pluginCopy, { recursive: true });
+        }
+        else {
+            for (const entry of await readdir(extension.pluginCopy))
+                await rm(path.join(extension.pluginCopy, entry), { recursive: true, force: true });
+        }
+        await controls.reloadPlugins();
+        for (const server of extension.servers)
+            await controls.toggleMcpServer(server, enabled);
+        if (enabled)
+            off.delete(name);
+        else
+            off.add(name);
+        follow(extension, enabled, targets);
+        targets.status.installed = await listInstalled(targets.status.dirs);
+        return true;
+    };
+}
+/** The kit's lists, as the extension is now. */
+function follow(extension, enabled, targets) {
+    const without = (list, items) => {
+        for (const item of items) {
+            const index = list.indexOf(item);
+            if (index >= 0)
+                list.splice(index, 1);
+        }
+    };
+    const { status, facts } = targets;
+    if (enabled) {
+        targets.readOnlyTools.push(...extension.readOnlyTools);
+        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.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.inactive = facts.extensions.inactive.filter((entry) => entry.name !== extension.name);
+    }
+    else {
+        without(targets.readOnlyTools, extension.readOnlyTools);
+        without(targets.allowedSubagentTypes, extension.agents);
+        // The same object the chat reads its labels from: changed in place, readonly to everyone else.
+        for (const tool of Object.keys(extension.toolLabels))
+            delete targets.toolLabels[tool];
+        without(status.active, [extension.name]);
+        delete status.about[extension.name];
+        const reason = { name: extension.name, reason: "was turned off in this session" };
+        status.inactive.push(reason);
+        facts.extensions.active = facts.extensions.active.filter((entry) => entry.name !== extension.name);
+        facts.extensions.inactive.push(reason);
+    }
+}