@falkenslab/agent-kit 0.20.0 → 0.21.0

package/assets/extension-launcher.mjs

@@ -12,8 +12,15 @@ if (!entry) {
   process.exit(1);
 }
 
-// What any process may need to run, on Windows and elsewhere; never a credential.
-const SYSTEM = ["PATH", "PATHEXT", "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "TEMP", "TMP", "TMPDIR", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "LANG", "LC_ALL", "TZ"];
+// What any process may need to run, on Windows and elsewhere; never a credential. Where programs
+// are installed and the desktop session too: a browser is found through PROGRAMFILES on Windows
+// (Playwright found no Edge without them, #52) and opens a window through DISPLAY on Linux.
+const SYSTEM = [
+  "PATH", "PATHEXT", "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "TEMP", "TMP", "TMPDIR", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "LANG", "LC_ALL", "TZ",
+  "PROGRAMFILES", "PROGRAMFILES(X86)", "PROGRAMW6432", "COMMONPROGRAMFILES", "COMMONPROGRAMFILES(X86)", "COMMONPROGRAMW6432", "PROGRAMDATA", "ALLUSERSPROFILE",
+  "HOMEDRIVE", "HOMEPATH", "USERNAME", "USER", "LOGNAME", "OS", "PROCESSOR_ARCHITECTURE", "NUMBER_OF_PROCESSORS",
+  "DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR", "XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_DATA_HOME", "DBUS_SESSION_BUS_ADDRESS",
+];
 const allowed = new Set([...SYSTEM, ...JSON.parse(declared)].map((name) => name.toUpperCase()));
 for (const name of Object.keys(process.env)) {
   if (!allowed.has(name.toUpperCase())) delete process.env[name];

package/dist/chat/extensions.js

@@ -3,7 +3,7 @@ import { setExtensionEnabled } from "../core/externalExtensions.js";
 import { t } from "../core/messages/index.js";
 /** One line for an installed extension: name and version, scope, on or off, its author, where it came from. */
 export function describe(extension) {
-    const state = extension.shadowed ? "not used (the project's wins)" : extension.lock.enabled ? "enabled" : "disabled";
+    const state = `${extension.shadowed ? "not used (the project's wins)" : extension.lock.enabled ? "enabled" : "disabled"}${extension.lock.linked ? ", linked" : ""}`;
     // From a marketplace, its name there (`jokebook@shipyard`): the copy it came from is the kit's business.
     const where = extension.lock.commit ? `${extension.lock.source} @ ${extension.lock.commit.slice(0, 12)}` : path.normalize(extension.lock.source);
     const source = extension.lock.marketplace ? `${extension.lock.marketplace}${extension.lock.commit ? ` @ ${extension.lock.commit.slice(0, 12)}` : ""}` : where;

package/dist/core/extensions.d.ts

@@ -82,6 +82,8 @@ export interface Extension {
     plugin: string;
     /** Installed rather than shipped in a package (#37): its subagents get no `Bash`, and no plugin hook runs. */
     external?: boolean;
+    /** An installed one's scope folder, where its lock is (its plugin is elsewhere when it's linked). */
+    installedIn?: string;
     /** Why it can't run in this session (e.g. "needs a folder (`dir`)"), or `undefined` when it can. */
     missing?(context: ExtensionContext): string | undefined;
     /** What it brings to the session, once it's active. */

package/dist/core/externalExtensions.d.ts

@@ -9,7 +9,9 @@ import { type ToolPhrase } from "./messages/index.js";
  * extension is a Claude Code plugin as it is (#38): its MCP servers come from its `.mcp.json`,
  * and the kit starts each with Node through a launcher that leaves it only the system's
  * variables and its own `env`. The `"agent-kit"` key of its `plugin.json` is optional: it adds
- * what the kit's gates and chat can use (capabilities, read-only tools, labels, help).
+ * what the kit's gates and chat can use (capabilities, read-only tools, labels, help). Each has a
+ * data folder of its own (`${CLAUDE_PLUGIN_DATA}`, as Claude Code gives a plugin), kept across
+ * sessions and updates; one being developed is linked rather than copied (#52).
  */
 /** The two folders an agent installs extensions into; either may be left out. */
 export interface ExtensionDirs {
@@ -24,7 +26,7 @@ export type ExtensionScope = keyof ExtensionDirs;
 export interface PluginServer {
     command: string;
     args?: string[];
-    /** Its variables: a value may take the agent's with `${VAR}`. */
+    /** Its variables: a value may take the agent's with `${VAR}`, and its folders with `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}`. */
     env?: Record<string, string>;
 }
 /** How the chat shows one of its tools in one language: `{field}` takes the call's input. */
@@ -68,19 +70,31 @@ export interface ExternalManifest {
 }
 /** One extension in a scope's lock. */
 export interface LockEntry {
-    /** Where it came from: a folder, or a git URL (with `#ref` when given). */
+    /** Where it came from: a folder, or a git URL (with `#ref` when given). A linked one runs from there. */
     source: string;
+    /**
+     * Linked rather than copied (`extension add --link`), to develop it: it runs from its folder,
+     * whose files aren't checked, so a rebuild takes effect when its server starts again.
+     */
+    linked?: boolean;
     /** The commit it was cloned at, for a git source. */
     commit?: string;
     /** The marketplace it was installed from (`<name>@<marketplace>`), if any. */
     marketplace?: string;
-    /** SHA-256 over its files, checked when it loads. */
+    /** SHA-256 over its files, checked when it loads; empty for a linked one. */
     sha256: string;
     enabled: boolean;
     /** When it was installed, ISO 8601 in UTC. */
     installed: string;
 }
 export declare const LOCK_FILE = "extensions.lock.json";
+/**
+ * An installed extension's data folder: `${CLAUDE_PLUGIN_DATA}` in its servers' arguments and
+ * variables (a browser profile, a cache), in its scope, outside its plugin and its hash, so it's
+ * kept across sessions and updates. Created when a session starts it; removing the extension
+ * asks before deleting it.
+ */
+export declare function extensionDataDir(scopeDir: string, name: string): string;
 /** A scope's lock: its extensions by name. */
 export declare function readLock(scopeDir: string): Promise<Record<string, LockEntry>>;
 /** Reads an extension's manifest, checking what the kit needs from it. */
@@ -96,7 +110,12 @@ export declare function inKitRange(version: string, range: string): boolean;
 export interface InstalledExtension {
     name: string;
     scope: ExtensionScope;
+    /** Its scope's folder, where its lock is. */
+    scopeDir: string;
+    /** Its plugin: in its scope's folder, or where it is when it's linked. */
     dir: string;
+    /** Its data folder (`${CLAUDE_PLUGIN_DATA}`), which may not exist yet. */
+    dataDir: string;
     lock: LockEntry;
     /** Also installed in the project's scope, which wins: this one isn't used. */
     shadowed: boolean;
@@ -125,19 +144,28 @@ export declare function isGitSource(source: string): boolean;
  * 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.
+ * 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.
  */
 export declare function addExtension(source: string, scopeDir: string, options?: {
     subdir?: string;
     sha?: string;
     marketplace?: string;
     origin?: string;
+    link?: boolean;
 }): Promise<{
     name: string;
     replaced: boolean;
     commit?: string;
 }>;
-/** Removes an extension from a scope (its files and its lock entry); false when it wasn't there. */
-export declare function removeExtension(scopeDir: string, name: string): Promise<boolean>;
+/**
+ * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left
+ * where it is), and its data folder with `deleteData`; false when it wasn't there.
+ */
+export declare function removeExtension(scopeDir: string, name: string, options?: {
+    deleteData?: boolean;
+}): Promise<boolean>;
+/** The size in bytes of the files under `dir` (0 when it doesn't exist). */
+export declare function folderSize(dir: string): Promise<number>;
 /** Enables or disables an installed extension in a scope; false when it isn't there. */
 export declare function setExtensionEnabled(scopeDir: string, name: string, enabled: boolean): Promise<boolean>;

package/dist/core/externalExtensions.js

@@ -10,6 +10,15 @@ import { truncate } from "./toolLabels.js";
 import { agentKitVersion } from "./version.js";
 import { outsideArchive } from "./packaged.js";
 export const LOCK_FILE = "extensions.lock.json";
+/**
+ * An installed extension's data folder: `${CLAUDE_PLUGIN_DATA}` in its servers' arguments and
+ * variables (a browser profile, a cache), in its scope, outside its plugin and its hash, so it's
+ * kept across sessions and updates. Created when a session starts it; removing the extension
+ * asks before deleting it.
+ */
+export function extensionDataDir(scopeDir, name) {
+    return path.join(scopeDir, ".data", name);
+}
 /** A scope's lock: its extensions by name. */
 export async function readLock(scopeDir) {
     try {
@@ -99,29 +108,32 @@ async function pluginServers(dir, raw) {
     }
     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] ?? "")));
+/** `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` and `${VAR}` (the agent's variable) in a server's values. */
+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.
  */
-function serverLaunch(name, server, root) {
+function serverLaunch(name, server, folders) {
+    const { root } = folders;
     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));
+    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})`;
-    return { entry, args, env: Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), root)])) };
+    // 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 } };
 }
 /** 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);
+        const launch = serverLaunch(name, server, { root, data: "" });
         if (typeof launch === "string")
             return launch;
         if (!(await stat(launch.entry).catch(() => null))?.isFile())
@@ -188,9 +200,9 @@ export async function listInstalled(dirs) {
         if (!scopeDir)
             continue;
         for (const [name, lock] of Object.entries(await readLock(scopeDir))) {
-            const dir = path.join(scopeDir, name);
+            const dir = lock.linked ? lock.source : 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 } : {}) });
+            installed.push({ name, scope, scopeDir, dir, dataDir: extensionDataDir(scopeDir, name), lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
         }
     }
     return installed;
@@ -218,10 +230,13 @@ function externalExtension(installed, manifest) {
         name: manifest.name,
         plugin: installed.dir,
         external: true,
+        installedIn: installed.scopeDir,
         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, installed.dir);
+                const launch = serverLaunch(name, server, { root: installed.dir, data: installed.dataDir });
                 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.
@@ -271,7 +286,7 @@ export async function onPath(program, env = process.env) {
 async function problem(installed) {
     let manifest;
     try {
-        if ((await hashExtension(installed.dir)) !== installed.lock.sha256)
+        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);
     }
@@ -300,9 +315,12 @@ export function isGitSource(source) {
  * 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.
+ * 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.
  */
 export async function addExtension(source, scopeDir, options = {}) {
+    if (options.link && isGitSource(source))
+        throw new Error("Only a folder can be linked: a git repository is installed as a copy.");
     let from = path.resolve(source);
     let commit;
     let clone;
@@ -326,10 +344,18 @@ export async function addExtension(source, scopeDir, options = {}) {
         if (servers)
             throw new Error(`${manifest.name} can't be installed: it ${servers}.`);
         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 lock = await readLock(scopeDir);
         const replaced = Boolean(lock[manifest.name]);
         await rm(target, { recursive: true, force: true });
         await mkdir(scopeDir, { recursive: true });
+        if (options.link) {
+            lock[manifest.name] = { source: from, linked: true, sha256: "", enabled: true, installed: new Date().toISOString() };
+            await writeLock(scopeDir, lock);
+            return { name: manifest.name, replaced };
+        }
         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),
@@ -347,16 +373,33 @@ export async function addExtension(source, scopeDir, options = {}) {
             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) {
+/**
+ * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left
+ * where it is), and its data folder with `deleteData`; false when it wasn't there.
+ */
+export async function removeExtension(scopeDir, name, options = {}) {
     const lock = await readLock(scopeDir);
     if (!lock[name])
         return false;
     delete lock[name];
     await rm(path.join(scopeDir, name), { recursive: true, force: true });
+    if (options.deleteData)
+        await rm(extensionDataDir(scopeDir, name), { recursive: true, force: true });
     await writeLock(scopeDir, lock);
     return true;
 }
+/** The size in bytes of the files under `dir` (0 when it doesn't exist). */
+export async function folderSize(dir) {
+    let size = 0;
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            size += await folderSize(full);
+        else if (entry.isFile())
+            size += (await stat(full)).size;
+    }
+    return size;
+}
 /** 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);

package/dist/core/liveExtensions.d.ts

@@ -5,23 +5,37 @@ 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
+ * confirmed empirically) and its plugin, mounted in the run's folder, is unmounted or mounted 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'
+ * empirically, through a link too). 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).
  */
+/**
+ * Mounts an installed extension's plugin at `at`, in a run's folder, for the session to load from
+ * there: a link to it (a junction on Windows, which needs no privilege), so nothing is copied and
+ * its `node_modules` costs nothing; a copy where a link can't be made. The CLI loads a plugin
+ * through a link, and `reloadPlugins()` unloads it when the link goes and loads it when it's back
+ * (confirmed empirically).
+ */
+export declare function mountPlugin(from: string, at: string): Promise<"link" | "copy">;
+/**
+ * Takes a mounted plugin away: a link is removed, never what it points at (its contents are the
+ * installed extension); a copy is emptied, so the path stays for mounting it again.
+ */
+export declare function unmountPlugin(at: string): Promise<void>;
 /** 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. */
+    /** Its plugin as installed (in its scope's folder, or where it's linked): what's mounted in the run's folder. */
     installedDir: string;
+    /** Its scope's folder, where its lock is. */
     scopeDir: string;
-    /** Its plugin, copied into the run's folder for this session. */
-    pluginCopy: string;
+    /** Where its plugin is mounted in the run's folder for this session (`mountPlugin()`). */
+    pluginMount: string;
     servers: string[];
     readOnlyTools: string[];
     toolLabels: ToolLabels;

package/dist/core/liveExtensions.js

@@ -1,6 +1,57 @@
-import { cp, readdir, rm } from "node:fs/promises";
+import { cp, lstat, mkdir, readdir, rm, symlink, unlink } from "node:fs/promises";
 import path from "node:path";
 import { hashExtension, listInstalled, readLock } from "./externalExtensions.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, mounted in the run's folder, is unmounted or mounted again
+ * before `reloadPlugins()` (its skills, commands and subagents go and come back, confirmed
+ * empirically, through a link too). 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).
+ */
+/**
+ * Mounts an installed extension's plugin at `at`, in a run's folder, for the session to load from
+ * there: a link to it (a junction on Windows, which needs no privilege), so nothing is copied and
+ * its `node_modules` costs nothing; a copy where a link can't be made. The CLI loads a plugin
+ * through a link, and `reloadPlugins()` unloads it when the link goes and loads it when it's back
+ * (confirmed empirically).
+ */
+export async function mountPlugin(from, at) {
+    // Whatever was there goes: a link (never what it points at), or a copy, whole.
+    const found = await lstat(at).catch(() => undefined);
+    if (found?.isSymbolicLink())
+        await unlink(at);
+    else if (found)
+        await rm(at, { recursive: true, force: true });
+    await mkdir(path.dirname(at), { recursive: true });
+    try {
+        await symlink(from, at, process.platform === "win32" ? "junction" : "dir");
+        return "link";
+    }
+    catch {
+        await cp(from, at, { recursive: true });
+        return "copy";
+    }
+}
+/**
+ * Takes a mounted plugin away: a link is removed, never what it points at (its contents are the
+ * installed extension); a copy is emptied, so the path stays for mounting it again.
+ */
+export async function unmountPlugin(at) {
+    const found = await lstat(at).catch(() => undefined);
+    if (!found)
+        return;
+    if (found.isSymbolicLink())
+        await unlink(at);
+    else
+        for (const entry of await readdir(at))
+            await rm(path.join(at, entry), { recursive: true, force: true });
+}
 /** The switch for a session's installed extensions. */
 export function createExtensionSwitch(extensions, targets) {
     const off = new Set();
@@ -13,14 +64,14 @@ export function createExtensionSwitch(extensions, targets) {
             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.
+            // A linked one's aren't checked: it's being developed, and a rebuild is why it's turned on again.
             const lock = (await readLock(extension.scopeDir))[name];
-            if (!lock || lock.sha256 !== (await hashExtension(extension.installedDir)))
+            if (!lock || (!lock.linked && lock.sha256 !== (await hashExtension(extension.installedDir))))
                 return false;
-            await cp(extension.installedDir, extension.pluginCopy, { recursive: true });
+            await mountPlugin(extension.installedDir, extension.pluginMount);
         }
         else {
-            for (const entry of await readdir(extension.pluginCopy))
-                await rm(path.join(extension.pluginCopy, entry), { recursive: true, force: true });
+            await unmountPlugin(extension.pluginMount);
         }
         await controls.reloadPlugins();
         for (const server of extension.servers)

package/dist/core/session.js

@@ -1,4 +1,4 @@
-import { cp, readdir, readFile, rm } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { createTranscriptLogger } from "./hooks/transcriptLogger.js";
@@ -22,7 +22,7 @@ import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
 import { createSessionView, registerSessionView } from "./sessionFacts.js";
-import { createExtensionSwitch } from "./liveExtensions.js";
+import { createExtensionSwitch, mountPlugin } from "./liveExtensions.js";
 import { agentKitVersion } from "./version.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
@@ -81,15 +81,15 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const enabledNames = new Set((spec.extensions ?? []).map((extension) => extension.name));
     const resolved = resolveExtensions([...(spec.extensions ?? []), ...external.extensions.filter((extension) => !enabledNames.has(extension.name))], extensionContext);
     resolved.inactive.push(...external.off, ...external.extensions.filter((extension) => enabledNames.has(extension.name)).map((extension) => ({ name: extension.name, reason: "has the name of one this agent already has" })));
-    // Each installed one's plugin, copied into the run's folder: the running session empties and
-    // fills the copy to turn the extension off and on (liveExtensions.ts), never what's installed.
+    // Each installed one's plugin, mounted in the run's folder (a link, nothing copied): the running
+    // session unmounts and mounts it to turn the extension off and on (liveExtensions.ts), never
+    // touching what's installed.
     const installedDirs = new Map();
     for (const { extension } of resolved.active.filter(({ extension }) => extension.external)) {
-        const copy = path.join(runDir, "extensions", extension.name);
-        await rm(copy, { recursive: true, force: true });
-        await cp(extension.plugin, copy, { recursive: true });
-        installedDirs.set(extension.name, extension.plugin);
-        extension.plugin = copy;
+        const mount = path.join(runDir, "extensions", extension.name);
+        await mountPlugin(extension.plugin, mount);
+        installedDirs.set(extension.name, { dir: extension.plugin, scopeDir: extension.installedIn ?? path.dirname(extension.plugin) });
+        extension.plugin = mount;
     }
     const externalPlugins = new Set(resolved.active.filter(({ extension }) => extension.external).map(({ extension }) => path.resolve(extension.plugin)));
     extensionContext.capabilities = resolved.capabilities;
@@ -359,16 +359,16 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     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) => {
-        const installedDir = installedDirs.get(extension.name);
-        if (!installedDir)
+        const installed = installedDirs.get(extension.name);
+        if (!installed)
             return [];
         const contribution = added[index];
         return [
             {
                 name: extension.name,
-                installedDir,
-                scopeDir: path.dirname(installedDir),
-                pluginCopy: extension.plugin,
+                installedDir: installed.dir,
+                scopeDir: installed.scopeDir,
+                pluginMount: extension.plugin,
                 servers: Object.keys(contribution?.mcpServers ?? {}),
                 readOnlyTools: contribution?.readOnlyTools ?? [],
                 toolLabels: contribution?.toolLabels ?? {},

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { sources, type SourcesOptions } from "./extensions/sources/index.js";
 export { knowledge, type KnowledgeOptions } from "./extensions/knowledge/index.js";
 export { memory, type MemoryOptions } from "./extensions/memory/index.js";
 export { readExtensionManifest, type Extension, type ExtensionContext, type ExtensionContribution, type ExtensionManifest, type FolderOption, } from "./core/extensions.js";
-export { addExtension, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type InstalledExtension, type LockEntry, } from "./core/externalExtensions.js";
+export { addExtension, extensionDataDir, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type InstalledExtension, type LockEntry, } from "./core/externalExtensions.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, type KnownMarketplace, type MarketplaceManifest, type MarketplacePlugin, type PluginSource, } from "./core/marketplaces.js";
 export { runExtensionCommand } from "./tui/extensionCommand.js";
 export { agentKitVersion } from "./core/version.js";

package/dist/index.js

@@ -16,7 +16,7 @@ export { sources } from "./extensions/sources/index.js";
 export { knowledge } from "./extensions/knowledge/index.js";
 export { memory } from "./extensions/memory/index.js";
 export { readExtensionManifest, } from "./core/extensions.js";
-export { addExtension, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, } from "./core/externalExtensions.js";
+export { addExtension, extensionDataDir, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, } from "./core/externalExtensions.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, } from "./core/marketplaces.js";
 export { runExtensionCommand } from "./tui/extensionCommand.js";
 export { agentKitVersion } from "./core/version.js";

package/dist/tui/extensionCommand.d.ts

@@ -9,7 +9,9 @@ export { chatExtensionsCommand, describe } from "../chat/extensions.js";
  * - `extension list`
  * - `extension info <name>`: its metadata, what it offers and where its README is
  * - `extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]`
- * - `extension remove|enable|disable <name> [--project | --agent]`
+ * - `extension add <folder> --link [--project]`: registered where it is, to develop it (not copied, its files not checked)
+ * - `extension remove <name> [--project | --agent] [--yes | --keep-data]`: asks before deleting its data folder
+ * - `extension enable|disable <name> [--project | --agent]`
  * - `extension search [words]`: what the known marketplaces offer
  * - `extension marketplace add <folder | git URL[#ref] | owner/repo> [--yes]`, `list`, `update [name]`, `remove <name>`
  *

package/dist/tui/extensionCommand.js

@@ -2,7 +2,7 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, removeMarketplace, updateMarketplace, } from "../core/marketplaces.js";
-import { addExtension, isGitSource, listInstalled, removeExtension, setExtensionEnabled, } from "../core/externalExtensions.js";
+import { addExtension, folderSize, isGitSource, listInstalled, removeExtension, setExtensionEnabled, } from "../core/externalExtensions.js";
 import { describe } from "../chat/extensions.js";
 export { chatExtensionsCommand, describe } from "../chat/extensions.js";
 /**
@@ -14,7 +14,9 @@ export { chatExtensionsCommand, describe } from "../chat/extensions.js";
  * - `extension list`
  * - `extension info <name>`: its metadata, what it offers and where its README is
  * - `extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]`
- * - `extension remove|enable|disable <name> [--project | --agent]`
+ * - `extension add <folder> --link [--project]`: registered where it is, to develop it (not copied, its files not checked)
+ * - `extension remove <name> [--project | --agent] [--yes | --keep-data]`: asks before deleting its data folder
+ * - `extension enable|disable <name> [--project | --agent]`
  * - `extension search [words]`: what the known marketplaces offer
  * - `extension marketplace add <folder | git URL[#ref] | owner/repo> [--yes]`, `list`, `update [name]`, `remove <name>`
  *
@@ -92,6 +94,13 @@ export async function runExtensionCommand(argv, options) {
                     return fail(`This agent has no ${scope} scope for extensions.`);
                 // A plugin of a marketplace, unless it's a folder here or a git URL.
                 const isFolder = await stat(path.resolve(source)).then((found) => found.isDirectory(), () => false);
+                if (flag("link")) {
+                    if (!isFolder)
+                        return fail(`Only a folder can be linked: ${source} isn't one here.`);
+                    const result = await addExtension(source, dir, { link: true });
+                    write(`Linked ${result.name} in the ${scope} scope: it runs from ${path.resolve(source)}, whose files aren't checked. A rebuild takes effect when its server starts again (a new session, or \`/extensions disable\` and \`enable\` in the chat).`);
+                    return true;
+                }
                 if (!isFolder && !isGitSource(source) && /^[A-Za-z0-9][\w.-]*(@[A-Za-z0-9][\w.-]*)?$/.test(source)) {
                     await knownMarketplaces();
                     const { marketplace, plugin } = await findPlugin(marketsDir, source);
@@ -121,13 +130,18 @@ export async function runExtensionCommand(argv, options) {
                     return fail(`${name} isn't installed${askedScope ? ` in the ${askedScope} scope` : ""}. \`${command} extension list\` lists them.`);
                 if (found.length > 1 && !askedScope)
                     return fail(`${name} is installed in both scopes: say which, with --project or --agent.`);
-                const { scope } = found[0];
+                const { scope, dataDir } = found[0];
                 const dir = scopeDir(scope);
-                if (action === "remove")
-                    await removeExtension(dir, name);
-                else
+                if (action !== "remove") {
                     await setExtensionEnabled(dir, name, action === "enable");
-                write(`${name} ${action === "remove" ? "removed" : `${action}d`} in the ${scope} scope. It applies from the next session (in the chat, \`/extensions\` reopens it).`);
+                    write(`${name} ${action}d in the ${scope} scope. It applies from the next session (in the chat, \`/extensions\` reopens it).`);
+                    return true;
+                }
+                // Its data (a browser profile, a signed-in session) may be worth keeping for a reinstall: asked, unless said.
+                const size = await folderSize(dataDir);
+                const deleteData = size > 0 && !flag("keep-data") && (await confirmed(`Delete its data too (${dataDir}, ${formatSize(size)})? (y/N) `, (typed) => /^(y|yes|s|si|sí)$/i.test(typed)));
+                await removeExtension(dir, name, { deleteData });
+                write(`${name} removed in the ${scope} scope${size > 0 ? (deleteData ? ", with its data" : `; its data stays in ${dataDir}`) : ""}. It applies from the next session (in the chat, \`/extensions\` reopens it).`);
                 return true;
             }
             case "search": {
@@ -155,7 +169,9 @@ export async function runExtensionCommand(argv, options) {
                     "  list                                   what's installed, in which scope, on or off",
                     "  info <name>                            its metadata, what it offers, its README",
                     "  add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]",
-                    "  remove|enable|disable <name> [--project | --agent]",
+                    "  add <folder> --link [--project]       to develop one: runs from its folder, not copied nor checked",
+                    "  remove <name> [--project | --agent] [--yes | --keep-data]",
+                    "  enable|disable <name> [--project | --agent]",
                     "  search [words]                         what the known marketplaces offer",
                     "  marketplace add <folder | git URL[#ref] | owner/repo> [--yes]",
                     "  marketplace list | update [name] | remove <name>",
@@ -252,6 +268,18 @@ async function info(extension) {
         ...field("Only read", manifest.readOnlyTools.join(", ") || undefined),
         ...field("Variables", Object.values(manifest.servers).flatMap((server) => Object.keys(server.env ?? {})).join(", ") || undefined),
         ...field("Installed", `${extension.scope} scope, ${extension.lock.enabled ? "enabled" : "disabled"}, on ${extension.lock.installed}, from ${describe(extension).split("  from ")[1]}`),
+        ...field("Data", (await stat(extension.dataDir).catch(() => null))?.isDirectory() ? `${extension.dataDir} (${formatSize(await folderSize(extension.dataDir))})` : undefined),
         ...field("README", (await stat(readme).catch(() => null))?.isFile() ? readme : undefined),
     ];
 }
+/** A size in bytes, as a person reads it: `512 B`, `3.4 KB`, `120 MB`. */
+function formatSize(bytes) {
+    const units = ["B", "KB", "MB", "GB"];
+    let size = bytes;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit++;
+    }
+    return `${unit === 0 ? size : size.toFixed(size < 10 ? 1 : 0)} ${units[unit]}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",