@falkenslab/agent-kit 0.19.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/chatController.d.ts

@@ -238,7 +238,10 @@ export declare function createChatController(options: Options | SessionOpener, s
      * graphical view offers instead of quitting and starting again.
      */
     newConversation(): Promise<void>;
-    /** Enables or disables an installed extension, and opens the session again with the same conversation. */
+    /**
+     * Enables or disables an installed extension: in the running session when it was running when
+     * the session opened (#49), by opening the session again with the same conversation otherwise.
+     */
     setExtension(name: string, enabled: boolean): Promise<void>;
     /**
      * Switches the kit's language (`switchLanguage()`) and opens the session again in it, keeping

package/dist/chat/chatController.js

@@ -160,18 +160,10 @@ export async function createChatController(options, settings = {}) {
         turnDone = null;
         done?.();
     }
-    function connect() {
-        const own = ++generation;
-        queue = createInputQueue({ modeControl: modeControl() });
-        run = (settings.runQuery ?? runQuery)(queue.iterable, { ...current.options, promptSuggestions: settings.promptSuggestions ?? true });
-        const events = run.events[Symbol.asyncIterator]();
+    /** The commands the session has, and the chat's own, into the state: when it opens, and when an extension is switched in it. */
+    function loadCommands() {
+        const own = generation;
         const control = modeControl();
-        update({ mode: control?.mode ?? null, switchableModes: control?.switchable ?? [], run: current.run, extensions: current.extensions ?? null });
-        unsubscribeMode?.();
-        unsubscribeMode = control?.subscribe?.((mode) => {
-            update({ mode });
-            emit({ type: "mode", mode });
-        });
         const supported = run.supportedCommands().catch(() => null);
         knownCommands = supported.then((commands) => (commands ? new Set(commands.flatMap((command) => [command.name, ...(command.aliases ?? [])])) : null));
         void supported.then((commands) => {
@@ -194,6 +186,20 @@ export async function createChatController(options, settings = {}) {
             const sorted = [...details.values()].sort((a, b) => a.name.localeCompare(b.name));
             update({ commands: sorted.map((command) => command.name), commandDetails: sorted });
         });
+    }
+    function connect() {
+        const own = ++generation;
+        queue = createInputQueue({ modeControl: modeControl() });
+        run = (settings.runQuery ?? runQuery)(queue.iterable, { ...current.options, promptSuggestions: settings.promptSuggestions ?? true });
+        const events = run.events[Symbol.asyncIterator]();
+        const control = modeControl();
+        update({ mode: control?.mode ?? null, switchableModes: control?.switchable ?? [], run: current.run, extensions: current.extensions ?? null });
+        unsubscribeMode?.();
+        unsubscribeMode = control?.subscribe?.((mode) => {
+            update({ mode });
+            emit({ type: "mode", mode });
+        });
+        loadCommands();
         void (async () => {
             try {
                 while (true) {
@@ -221,6 +227,9 @@ export async function createChatController(options, settings = {}) {
     // A language switched to, told to the model with the next message (as a mode change is): the
     // session's prompt says it already, but a conversation in another language pulls the replies.
     let languageNotice = null;
+    // Extensions turned off or on in the running session, told to the model with the next message
+    // too: the prompt's Extensions section still says what the session opened with.
+    const extensionNotices = [];
     async function runTurn(line) {
         interrupted = false;
         const from = state.transcript.length;
@@ -229,7 +238,8 @@ export async function createChatController(options, settings = {}) {
         update({ busy: true, turnStartedAt: startedAt, activity: null, subagentActivity: null, suggestion: null });
         emit({ type: "turn-start" });
         const finished = new Promise((resolve) => (turnDone = resolve));
-        queue.push(languageNotice ? `${languageNotice}\n\n${line}` : line);
+        const notices = [languageNotice, ...extensionNotices.splice(0)].filter(Boolean);
+        queue.push(notices.length ? `${notices.join("\n")}\n\n${line}` : line);
         languageNotice = null;
         await finished;
         logRenderer.endLine();
@@ -254,6 +264,20 @@ export async function createChatController(options, settings = {}) {
         emit({ type: "conversation", messages, updatedAt, fromResume });
     }
     /** Switches to another session: a run resumed, or the same one opened again. */
+    /** An extension whose lock just changed: switched in the running session if it can be, the session opened again if not. */
+    async function applyExtension(name, enabled) {
+        if (await current.switchExtension?.(name, enabled).catch(() => false)) {
+            notice(t().extensionSwitched(name, enabled));
+            extensionNotices.push(enabled
+                ? `<system-reminder>The user turned the ${name} extension back on: its tools, skills and commands are available again.</system-reminder>`
+                : `<system-reminder>The user turned the ${name} extension off: its tools, skills, commands and subagents are gone until it's turned on again, whatever your instructions or earlier messages say.</system-reminder>`);
+            update({ extensions: current.extensions ? { ...current.extensions } : null });
+            loadCommands();
+            return;
+        }
+        notice(t().extensionToggled(name, enabled));
+        await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+    }
     async function switchTo(folder, fromResume) {
         queue.end();
         run.close();
@@ -364,8 +388,8 @@ export async function createChatController(options, settings = {}) {
             if (extensions) {
                 for (const text of extensions.lines)
                     notice(text);
-                if (extensions.reopen)
-                    await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+                if (extensions.toggled)
+                    await applyExtension(extensions.toggled.name, extensions.toggled.enabled);
                 return;
             }
             const token = slashCommandToken(line);
@@ -447,7 +471,10 @@ export async function createChatController(options, settings = {}) {
             connect();
             emit({ type: "session" });
         },
-        /** Enables or disables an installed extension, and opens the session again with the same conversation. */
+        /**
+         * Enables or disables an installed extension: in the running session when it was running when
+         * the session opened (#49), by opening the session again with the same conversation otherwise.
+         */
         async setExtension(name, enabled) {
             // An action of its own, not a line the person typed: a graphical view's toggle.
             if (!opener || !current.run)
@@ -457,8 +484,7 @@ export async function createChatController(options, settings = {}) {
             if (!installed || !dir)
                 return notice(t().extensionNotInstalled(name));
             await setExtensionEnabled(dir, name, enabled);
-            notice(t().extensionToggled(name, enabled));
-            await switchTo({ dir: current.run.dir, sessionId: await readRunSession(current.run.dir) }, false);
+            await applyExtension(name, enabled);
         },
         /**
          * Switches the kit's language (`switchLanguage()`) and opens the session again in it, keeping

package/dist/chat/extensions.d.ts

@@ -5,10 +5,14 @@ export declare function describe(extension: InstalledExtension): string;
 /**
  * `/extensions` in a chat (#37): with nothing after it, what the session runs with, what's off
  * and why, and what's installed; with `enable <name>` or `disable <name>`, changes its lock and
- * asks the chat to reopen the session (`reopen`), which keeps the conversation. `null` when
- * `line` isn't this command.
+ * says which (`toggled`): the chat turns it on or off in the running session when it can (#49),
+ * and opens the session again otherwise, keeping the conversation. `null` when `line` isn't this
+ * command.
  */
 export declare function chatExtensionsCommand(line: string, status: ExtensionsStatus | undefined, canReopen: boolean): Promise<{
     lines: string[];
-    reopen: boolean;
+    toggled?: {
+        name: string;
+        enabled: boolean;
+    };
 } | null>;

package/dist/chat/extensions.js

@@ -3,8 +3,10 @@ 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 source = extension.lock.commit ? `${extension.lock.source} @ ${extension.lock.commit.slice(0, 12)}` : path.normalize(extension.lock.source);
+    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;
     const version = extension.manifest?.version ? ` ${extension.manifest.version}` : "";
     const author = extension.manifest?.author ? `  by ${extension.manifest.author.name}` : "";
     return `${extension.name}${version}  [${extension.scope}]  ${state}${author}  from ${source}`;
@@ -12,8 +14,9 @@ export function describe(extension) {
 /**
  * `/extensions` in a chat (#37): with nothing after it, what the session runs with, what's off
  * and why, and what's installed; with `enable <name>` or `disable <name>`, changes its lock and
- * asks the chat to reopen the session (`reopen`), which keeps the conversation. `null` when
- * `line` isn't this command.
+ * says which (`toggled`): the chat turns it on or off in the running session when it can (#49),
+ * and opens the session again otherwise, keeping the conversation. `null` when `line` isn't this
+ * command.
  */
 export async function chatExtensionsCommand(line, status, canReopen) {
     const [command, action, name, ...extra] = line.trim().split(/\s+/);
@@ -25,17 +28,17 @@ export async function chatExtensionsCommand(line, status, canReopen) {
             lines.push(t().extensionOff(off, reason));
         if (status?.installed.length)
             lines.push(t().extensionsInstalled, ...status.installed.map((extension) => `  ${describe(extension)}`));
-        return { lines, reopen: false };
+        return { lines };
     }
     const enable = action.toLowerCase() === "enable";
     if ((!enable && action.toLowerCase() !== "disable") || !name || extra.length)
-        return { lines: [t().extensionsUsage], reopen: false };
+        return { lines: [t().extensionsUsage] };
     if (!canReopen)
-        return { lines: [t().extensionsCantReopen], reopen: false };
+        return { lines: [t().extensionsCantReopen] };
     const installed = (status?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
     const dir = installed ? status?.dirs[installed.scope] : undefined;
     if (!installed || !dir)
-        return { lines: [t().extensionNotInstalled(name)], reopen: false };
+        return { lines: [t().extensionNotInstalled(name)] };
     await setExtensionEnabled(dir, name, enable);
-    return { lines: [t().extensionToggled(name, enable)], reopen: true };
+    return { lines: [], toggled: { name, enabled: enable } };
 }

package/dist/chat/runs.d.ts

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

package/dist/chat/runs.js

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

package/dist/core/agentSpec.d.ts

@@ -1,6 +1,5 @@
 import type { ExtensionDirs } from "./externalExtensions.js";
 import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig, SettingSource } from "@anthropic-ai/claude-agent-sdk";
-import type { KnowledgeStore, PageType } from "../extensions/knowledge/knowledgeStore.js";
 import type { Extension } from "./extensions.js";
 /**
  * The human-supervision spectrum every agent built on this kit shares, independent of
@@ -25,27 +24,8 @@ export type Mode = "interactive" | "guided" | "autonomous" | "plan";
  */
 export interface BaseSessionConfig {
     mode: Mode;
-    /** Project root (the session's cwd): the folder under which the agent's notes, sources and runs live. */
+    /** Project root (the session's cwd): the folder under which the agent's folders and runs live. */
     projectDir: string;
-    /**
-     * Where the agent writes its own notes (the "wiki"). Setting this or `sourcesDir` is what
-     * gives the session the file tools (Read/Write/Edit/Glob/Grep, scoped — see
-     * hooks/fileScopeGate.ts); without either, the agent has no file access at all.
-     */
-    knowledgeDir?: string;
-    /**
-     * Original files, kept as obtained and apart from the notes in `knowledgeDir`: material
-     * the user drops in, plus whatever the agent saves with `save_to_sources` (downloaded
-     * documents, transcripts...). The agent can read and search it but never edit it — Write/
-     * Edit are scoped to `knowledgeDir` — and `save_to_sources` never overwrites.
-     */
-    sourcesDir?: string;
-    /**
-     * The memory of the person (the `memory` extension, #34): a folder of the agent's own outside
-     * any project, e.g. `~/.miyagi/memory`, kept across all the person's projects. Never share it
-     * with another agent. The extension needs it; only its tools (`recall`, `remember`, `forget`) reach it.
-     */
-    memoryDir?: string;
     /**
      * Where extensions are installed for this agent (#37): `agent` for all its projects (e.g.
      * `~/.miyagi/extensions`), `project` for this one (e.g. `<projectDir>/extensions`), which wins.
@@ -53,10 +33,15 @@ export interface BaseSessionConfig {
      * installs them.
      */
     extensionDirs?: ExtensionDirs;
-    /** Directories besides `knowledgeDir`/`sourcesDir` where Write/Edit are allowed (see hooks/fileScopeGate.ts). */
+    /**
+     * Directories where the agent reads, searches and writes with the file tools (Write/Edit,
+     * scoped — see hooks/fileScopeGate.ts), e.g. a folder of its own notes. Setting one gives the
+     * session all five file tools; an extension's folders (the sources, the knowledge base) come
+     * with the extension.
+     */
     extraWritableDirs?: string[];
     /**
-     * Directories besides `sourcesDir`/`extraWritableDirs` the agent may read and search (Read,
+     * Directories besides `extraWritableDirs` and the extensions' folders the agent may read and search (Read,
      * Glob, Grep), never write. Read and Glob reach nothing else on the disk but what the kit
      * knows the agent needs (see hooks/fileScopeGate.ts).
      */
@@ -96,23 +81,17 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      * model (with agent-kit's version), and needs it; the session's facts carry it too.
      */
     identity?: AgentIdentity;
-    /**
-     * Absolute path of a markdown guide to the agent's own domain (its commands, configuration,
-     * folders), which the `awareness` extension's `about_me` gives the agent when the person asks.
-     */
-    helpGuide?: string;
     /**
      * MCP servers this agent always registers (e.g. Playwright for a browser-driving
      * agent), on top of the generic ones `buildSessionOptions()` wires up itself when
-     * applicable (human approval, manual intervention, save-to-knowledge) — those aren't
-     * part of the spec because they're driven by `mode` plus this spec's own
-     * `manualInterventionTexts`/`knowledgeDir`/`sourcesDir`, not by anything else
-     * domain-specific.
+     * applicable (human approval, manual intervention) and the extensions' — those aren't
+     * part of this method because they're driven by `mode`, this spec's own
+     * `manualInterventionTexts` and its `extensions`.
      */
     buildMcpServers(config: TConfig, runDir: string): Record<string, McpServerConfig>;
     /**
      * Local plugin roots (skills/commands, SDK "local" plugin type) to load, in the order
-     * given, when the session has file tools (`config.knowledgeDir`/`config.sourcesDir`). Absolute paths; `buildSessionOptions()`
+     * given. Absolute paths; `buildSessionOptions()`
      * doesn't know or care where they live on disk.
      */
     pluginRoots(config: TConfig): string[];
@@ -136,29 +115,14 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      * over a permissive `canUseTool` — a disallowed tool never even reaches that callback.
      */
     disallowedTools?: string[];
-    /** Overrides this kit's generic `save_to_sources` tool description (registered whenever `config.sourcesDir` is set) with domain-specific wording. */
-    saveToSourcesDescription?: string;
-    /**
-     * The extensions the agent runs with (ADR-025), in order: the kit's by name (`"knowledge"`, the
-     * built-in knowledge base in `config.knowledgeDir`; `"sources"`, the originals in
-     * `config.sourcesDir`), and the agent's own as objects (an `Extension`: its plugin and what it
-     * brings). An extension the session lacks something for (its folder), or whose required
-     * capabilities nothing enabled provides, is left out, and the prompt says why. None by default.
-     * Without `"knowledge"`, `knowledgeDir` is a folder of the agent's own notes, kept with the file
-     * tools under rules it writes itself.
-     */
-    extensions?: (string | Extension)[];
-    /**
-     * The agent's own page types for the built-in knowledge base, besides the kit's
-     * (summary, concept, entity, synthesis, preference): each with its folder (`""` for the root),
-     * index section, description (told to the model) and template.
-     */
-    knowledgePageTypes?: PageType[];
     /**
-     * The knowledge base's store, instead of the kit's over markdown files in `knowledgeDir`
-     * (e.g. a database or a vector store implementing `KnowledgeStore`).
+     * The extensions the agent runs with (ADR-025), in order, each made with its own options: the
+     * kit's through their factories (`awareness()`, `sources({ dir })`, `knowledge({ dir })`,
+     * `memory({ dir })`), the agent's own as `Extension` objects (its plugin and what it brings).
+     * An extension the session lacks something for (its folder), or whose required capabilities
+     * nothing enabled provides, is left out, and the prompt says why. None by default.
      */
-    knowledgeStore?(config: TConfig): KnowledgeStore;
+    extensions?: Extension[];
     /**
      * Whether the kit tells the agent (and each subagent) to reply in the resolved language
      * (`config.language`, `--language`, the system's), following the human if they write in
@@ -231,8 +195,8 @@ export interface AgentIdentity {
 export interface PlanModeSpec<TConfig extends BaseSessionConfig = BaseSessionConfig> {
     /**
      * Whether `filePath` (absolute) is a plan file Write/Edit may touch in plan mode, e.g.
-     * `drafts/<slug>/plan.md`. It must also be writable under the file scope (`knowledgeDir`
-     * or `extraWritableDirs`), which still applies.
+     * `drafts/<slug>/plan.md`. It must also be writable under the file scope (`extraWritableDirs`),
+     * which still applies.
      */
     isPlanFile?(filePath: string, config: TConfig): boolean;
     /**

package/dist/core/extensions.d.ts

@@ -7,12 +7,17 @@ import type { SessionFacts } from "./sessionFacts.js";
  * plugin with the kit's data in its manifest (`.claude-plugin/plugin.json`, key `"agent-kit"`:
  * the capabilities it `provides` and `requires`), plus, for an internal one, the code that
  * says what it brings to a session. An agent enables the ones it wants (`AgentSpec.extensions`),
- * the kit's by name, its own as objects; `buildSessionOptions()` puts the contributions of the
- * active ones together, so the core names none of them. The kit's own (awareness, knowledge, sources, memory) live
- * in `src/extensions/<name>/`, their plugin in `extensions/<name>/`; this file is the only place
- * in the core that imports them (an ESLint rule keeps it so), and no extension imports another:
- * each owns its data, and the model connects them through their tools (#30).
+ * each made with its own options (the kit's through their factories, `knowledge({ dir })`…);
+ * `buildSessionOptions()` puts the contributions of the active ones together, so the core names
+ * none of them. The kit's own (awareness, knowledge, sources, memory) live in
+ * `src/extensions/<name>/`, their plugin in `extensions/<name>/`; the core never imports them
+ * (an ESLint rule keeps it so), and no extension imports another: each owns its data, and the
+ * model connects them through their tools (#30).
  */
+/** A folder an extension's options name: a path, or one worked out from the session's config (its project). */
+export type FolderOption<TConfig extends BaseSessionConfig = BaseSessionConfig> = string | ((config: TConfig) => string | undefined);
+/** The folder `option` names for this session's `config`, if any. */
+export declare function folderOf<TConfig extends BaseSessionConfig>(option: FolderOption<TConfig> | undefined, config: BaseSessionConfig): string | undefined;
 /** What an extension sees of the session it's contributing to. */
 export interface ExtensionContext<TConfig extends BaseSessionConfig = BaseSessionConfig> {
     config: TConfig;
@@ -22,6 +27,12 @@ export interface ExtensionContext<TConfig extends BaseSessionConfig = BaseSessio
     mode: Mode;
     /** A person can be asked (not autonomous): tools that ask them may exist. */
     interactive: boolean;
+    /**
+     * What the session's active extensions provide (their manifests' `provides`), for one that
+     * works differently beside another (the knowledge base beside the sources). Known once the
+     * extensions are resolved: empty in `missing()`.
+     */
+    capabilities: ReadonlySet<string>;
     /**
      * What the session is at the moment of the call (#43): its mode now, the extensions running
      * and off, their tools, the subagents, skills, commands and context. The core's facts, read
@@ -71,7 +82,9 @@ 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;
-    /** Why it can't run in this session (e.g. "needs `knowledgeDir` in the config"), or `undefined` when it can. */
+    /** 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. */
     contribute(context: ExtensionContext): Promise<ExtensionContribution>;
@@ -87,8 +100,6 @@ export interface ExtensionManifest {
 }
 /** Reads an extension's manifest from its plugin. */
 export declare function readExtensionManifest(pluginRoot: string): ExtensionManifest;
-/** The kit's internal extensions, by name. */
-export declare const BUILT_IN_EXTENSIONS: readonly Extension[];
 /** The extensions a session runs with, and the ones it can't, with why. */
 export interface ResolvedExtensions {
     active: {
@@ -103,11 +114,11 @@ export interface ResolvedExtensions {
     capabilities: Set<string>;
 }
 /**
- * Which of the `enabled` extensions (the kit's by name, an agent's own as objects) run in this
- * session, in the order given: those the session lacks something for are left out, and so are
- * those requiring a capability no active one provides, until nothing more drops out.
+ * Which of the `extensions` run in this session, in the order given: those the session lacks
+ * something for are left out, and so are those requiring a capability no active one provides,
+ * until nothing more drops out.
  */
-export declare function resolveExtensions(enabled: readonly (string | Extension)[], context: ExtensionContext): ResolvedExtensions;
+export declare function resolveExtensions(extensions: readonly Extension[], context: ExtensionContext): ResolvedExtensions;
 /** The prompt's "Extensions" section: what's on, and what isn't and why (ADR-025). */
 export declare function extensionsPromptSection(resolved: ResolvedExtensions): string;
 /**

package/dist/core/extensions.js

@@ -2,10 +2,10 @@ import { readFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { frontmatter } from "./pluginAgents.js";
-import { awarenessExtension } from "../extensions/awareness/index.js";
-import { sourcesExtension } from "../extensions/sources/index.js";
-import { knowledgeExtension } from "../extensions/knowledge/index.js";
-import { memoryExtension } from "../extensions/memory/index.js";
+/** The folder `option` names for this session's `config`, if any. */
+export function folderOf(option, config) {
+    return typeof option === "function" ? option(config) : option;
+}
 /** Reads an extension's manifest from its plugin. */
 export function readExtensionManifest(pluginRoot) {
     const file = path.join(pluginRoot, ".claude-plugin", "plugin.json");
@@ -14,22 +14,12 @@ export function readExtensionManifest(pluginRoot) {
         throw new Error(`${file} has no "name".`);
     return { name: raw.name, description: raw.description ?? "", provides: raw["agent-kit"]?.provides ?? [], requires: raw["agent-kit"]?.requires ?? [] };
 }
-/** The kit's internal extensions, by name. */
-export const BUILT_IN_EXTENSIONS = [awarenessExtension, sourcesExtension, knowledgeExtension, memoryExtension];
 /**
- * Which of the `enabled` extensions (the kit's by name, an agent's own as objects) run in this
- * session, in the order given: those the session lacks something for are left out, and so are
- * those requiring a capability no active one provides, until nothing more drops out.
+ * Which of the `extensions` run in this session, in the order given: those the session lacks
+ * something for are left out, and so are those requiring a capability no active one provides,
+ * until nothing more drops out.
  */
-export function resolveExtensions(enabled, context) {
-    const extensions = enabled.map((entry) => {
-        if (typeof entry !== "string")
-            return entry;
-        const found = BUILT_IN_EXTENSIONS.find((extension) => extension.name === entry);
-        if (!found)
-            throw new Error(`Unknown extension "${entry}": the kit's are ${BUILT_IN_EXTENSIONS.map((extension) => extension.name).join(", ")}; an agent's own is passed as an object.`);
-        return found;
-    });
+export function resolveExtensions(extensions, context) {
     const inactive = [];
     let active = [];
     for (const extension of extensions) {

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. */
@@ -55,6 +57,8 @@ export interface ExternalManifest {
     requires: string[];
     /** The agent-kit versions it works with, e.g. `">=0.19.0 <0.21.0"`. */
     kit?: string;
+    /** Programs it needs on this computer, found on the `PATH` (`"docker"`, `"python3"`): without one it's off, saying which. */
+    needs: string[];
     /** Its MCP servers, by name (`mcp__<name>__<tool>`), from the plugin's `.mcp.json` or `plugin.json`. */
     servers: Record<string, PluginServer>;
     /** Its tools that only read (short names, of any of its servers): plan mode lets them through. */
@@ -66,17 +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;
-    /** SHA-256 over its files, checked when it loads. */
+    /** The marketplace it was installed from (`<name>@<marketplace>`), if any. */
+    marketplace?: string;
+    /** 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. */
@@ -92,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;
@@ -111,21 +134,38 @@ export declare function loadExternalExtensions(dirs: ExtensionDirs): Promise<{
         reason: string;
     }[];
 }>;
+/** 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 declare function onPath(program: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
 /** Whether `source` names a git repository rather than a folder. */
 export declare function isGitSource(source: string): boolean;
 /**
- * Installs an extension into a scope from a folder or a git repository (`url#ref`, and `subdir`
- * for one inside it): copies its files (never runs a script), checks its manifest, and locks it,
- * enabled. An extension with the same name in that scope is replaced.
+ * 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; 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>;