@falkenslab/agent-kit 0.19.0 → 0.20.0

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

@@ -4,7 +4,9 @@ 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);
+    // 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,7 @@ 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. */
+    /** 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 +98,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 +112,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

@@ -55,6 +55,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. */
@@ -70,6 +72,8 @@ export interface LockEntry {
     source: string;
     /** 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. */
     sha256: string;
     enabled: boolean;
@@ -111,15 +115,23 @@ 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.
  */
 export declare function addExtension(source: string, scopeDir: string, options?: {
     subdir?: string;
+    sha?: string;
+    marketplace?: string;
+    origin?: string;
 }): Promise<{
     name: string;
     replaced: boolean;

package/dist/core/externalExtensions.js

@@ -58,6 +58,7 @@ export async function readExternalManifest(dir) {
         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 ?? {},
@@ -254,6 +255,19 @@ export async function loadExternalExtensions(dirs) {
     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 {
@@ -268,6 +282,12 @@ async function problem(installed) {
         return `is installed as "${installed.name}" but its manifest says "${manifest.name}"`;
     if (manifest.kit && !inKitRange(agentKitVersion(), manifest.kit))
         return `works with agent-kit ${manifest.kit}, and this agent runs ${agentKitVersion()}`;
+    const missing = [];
+    for (const program of manifest.needs)
+        if (!(await onPath(program)))
+            missing.push(program);
+    if (missing.length)
+        return `needs ${missing.join(", ")}, which ${missing.length === 1 ? "isn't" : "aren't"} on this computer (on the PATH)`;
     return (await serversProblem(manifest, installed.dir)) ?? manifest;
 }
 const exec = promisify(execFile);
@@ -276,9 +296,11 @@ 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`, 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.
  */
 export async function addExtension(source, scopeDir, options = {}) {
     let from = path.resolve(source);
@@ -287,8 +309,13 @@ export async function addExtension(source, scopeDir, options = {}) {
     if (isGitSource(source)) {
         const [url, ref] = source.replace(/^github:/, "https://github.com/").split("#");
         clone = await mkdtemp(path.join(os.tmpdir(), "agent-kit-extension-"));
-        await exec("git", ["clone", "--depth", "1", ...(ref ? ["--branch", ref] : []), url, clone]);
+        // 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 {
@@ -305,8 +332,9 @@ export async function addExtension(source, scopeDir, options = {}) {
         await mkdir(scopeDir, { recursive: true });
         await cp(from, target, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
         lock[manifest.name] = {
-            source: isGitSource(source) ? `${source}${options.subdir ? ` (${options.subdir})` : ""}` : from,
+            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(),