@falkenslab/agent-kit 0.19.0 → 0.20.0

package/dist/extensions/knowledge/prompt.d.ts

@@ -1,11 +1,11 @@
 import type { PageType } from "./knowledgeStore.js";
 /**
- * The built-in knowledge base (an "LLM wiki"): `sourcesDir` holds the originals, `knowledgeDir`
- * is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
+ * The built-in knowledge base (an "LLM wiki"): the sources folder holds the originals, its own
+ * folder is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
  * plus the plugin's skills (knowledge-ingest, knowledge-query, knowledge-lint) and commands
  * (/knowledge:ingest, /knowledge:query, /knowledge:lint) are the schema that tells it how.
- * Domain-agnostic on purpose: an agent adds its own page types (`AgentSpec.knowledgePageTypes`),
- * or leaves it out of `AgentSpec.extensions` and writes its own rules for `knowledgeDir`.
+ * Domain-agnostic on purpose: an agent adds its own page types (`knowledge({ pageTypes })`), or
+ * leaves it out of `AgentSpec.extensions` and keeps notes of its own in `extraWritableDirs`.
  */
 /** Absolute path of the knowledge base's plugin shipped with the kit, next to `dist/` (or `src/` under tsx). */
 export declare function knowledgePluginRoot(): string;

package/dist/extensions/knowledge/prompt.js

@@ -1,12 +1,12 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 /**
- * The built-in knowledge base (an "LLM wiki"): `sourcesDir` holds the originals, `knowledgeDir`
- * is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
+ * The built-in knowledge base (an "LLM wiki"): the sources folder holds the originals, its own
+ * folder is the wiki the agent maintains through the `knowledge_*` tools (ADR-024), and the rules below
  * plus the plugin's skills (knowledge-ingest, knowledge-query, knowledge-lint) and commands
  * (/knowledge:ingest, /knowledge:query, /knowledge:lint) are the schema that tells it how.
- * Domain-agnostic on purpose: an agent adds its own page types (`AgentSpec.knowledgePageTypes`),
- * or leaves it out of `AgentSpec.extensions` and writes its own rules for `knowledgeDir`.
+ * Domain-agnostic on purpose: an agent adds its own page types (`knowledge({ pageTypes })`), or
+ * leaves it out of `AgentSpec.extensions` and keeps notes of its own in `extraWritableDirs`.
  */
 /** Absolute path of the knowledge base's plugin shipped with the kit, next to `dist/` (or `src/` under tsx). */
 export function knowledgePluginRoot() {

package/dist/extensions/memory/index.d.ts

@@ -1,12 +1,21 @@
-import type { Extension } from "../../core/extensions.js";
+import type { BaseSessionConfig } from "../../core/agentSpec.js";
+import { type Extension, type FolderOption } from "../../core/extensions.js";
 /** Absolute path of the memory extension's plugin, next to `dist/` (or `src/` under tsx). */
 export declare function memoryPluginRoot(): string;
 /** The memory's section of the system prompt: what it is, what it holds now, and its rules. */
 export declare function memoryPromptSection(index: string): string;
+/** The memory's options. */
+export interface MemoryOptions<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    /**
+     * Its folder, the agent's own outside any project (e.g. `~/.miyagi/memory`), kept across all
+     * the person's projects and never shared with another agent. Without a folder the extension is off.
+     */
+    dir: FolderOption<TConfig>;
+}
 /**
- * The memory of the person (`config.memoryDir`, #34): what the agent learns about the person it
- * works for, kept across all their projects in a folder of its own, reached only through its
- * tools (`recall`, `remember`, `forget`). What it remembers must quote the person's own messages, which it hears through
- * a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
+ * The memory of the person (#34): what the agent learns about the person it works for, kept
+ * across all their projects in a folder of its own, reached only through its tools (`recall`,
+ * `remember`, `forget`). What it remembers must quote the person's own messages, which it hears
+ * through a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
  */
-export declare const memoryExtension: Extension;
+export declare function memory<TConfig extends BaseSessionConfig = BaseSessionConfig>(options: MemoryOptions<TConfig>): Extension;

package/dist/extensions/memory/index.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { folderOf } from "../../core/extensions.js";
 import { readConversation } from "../../core/runs.js";
 import { memoryToolLabels } from "./labels.js";
 import { createMemoryStore } from "./memoryStore.js";
@@ -22,35 +23,37 @@ ${index}
 - Write entries in the language you reply in.`;
 }
 /**
- * The memory of the person (`config.memoryDir`, #34): what the agent learns about the person it
- * works for, kept across all their projects in a folder of its own, reached only through its
- * tools (`recall`, `remember`, `forget`). What it remembers must quote the person's own messages, which it hears through
- * a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
+ * The memory of the person (#34): what the agent learns about the person it works for, kept
+ * across all their projects in a folder of its own, reached only through its tools (`recall`,
+ * `remember`, `forget`). What it remembers must quote the person's own messages, which it hears
+ * through a `UserPromptSubmit` hook (and, for a resumed run, from the run's conversation).
  */
-export const memoryExtension = {
-    name: "memory",
-    plugin: memoryPluginRoot(),
-    missing: ({ config }) => (config.memoryDir ? undefined : "needs `memoryDir` in the config"),
-    async contribute({ config, runDir }) {
-        const memoryDir = config.memoryDir;
-        const store = createMemoryStore(memoryDir);
-        // What the person wrote: earlier in a resumed run, then each message as it's sent.
-        const said = (await readConversation(runDir)).filter((message) => message.role === "user").map((message) => message.text);
-        const hear = async (input) => {
-            if (input.hook_event_name === "UserPromptSubmit")
-                said.push(input.prompt);
-            return {};
-        };
-        return {
-            mcpServers: { memory: createMemoryServer(store, said) },
-            promptSection: memoryPromptSection(memoryIndex(await store.list())),
-            toolOnlyDirs: [{ dir: memoryDir, instead: "its tools: recall, remember, forget" }],
-            readOnlyTools: ["mcp__memory__recall"],
-            hooks: { UserPromptSubmit: [{ hooks: [hear] }] },
-            toolLabels: memoryToolLabels(),
-            helpLines: [
-                "You keep a memory of the person across all their projects (how they like things done, who they are): `/memory:list` shows it, `/memory:forget <entry>` forgets an entry. Only what they tell you goes in it.",
-            ],
-        };
-    },
-};
+export function memory(options) {
+    return {
+        name: "memory",
+        plugin: memoryPluginRoot(),
+        missing: ({ config }) => (folderOf(options.dir, config) ? undefined : "needs a folder (`dir`)"),
+        async contribute({ config, runDir }) {
+            const memoryDir = folderOf(options.dir, config);
+            const store = createMemoryStore(memoryDir);
+            // What the person wrote: earlier in a resumed run, then each message as it's sent.
+            const said = (await readConversation(runDir)).filter((message) => message.role === "user").map((message) => message.text);
+            const hear = async (input) => {
+                if (input.hook_event_name === "UserPromptSubmit")
+                    said.push(input.prompt);
+                return {};
+            };
+            return {
+                mcpServers: { memory: createMemoryServer(store, said) },
+                promptSection: memoryPromptSection(memoryIndex(await store.list())),
+                toolOnlyDirs: [{ dir: memoryDir, instead: "its tools: recall, remember, forget" }],
+                readOnlyTools: ["mcp__memory__recall"],
+                hooks: { UserPromptSubmit: [{ hooks: [hear] }] },
+                toolLabels: memoryToolLabels(),
+                helpLines: [
+                    "You keep a memory of the person across all their projects (how they like things done, who they are): `/memory:list` shows it, `/memory:forget <entry>` forgets an entry. Only what they tell you goes in it.",
+                ],
+            };
+        },
+    };
+}

package/dist/extensions/sources/index.d.ts

@@ -1,9 +1,21 @@
-import type { Extension } from "../../core/extensions.js";
+import type { BaseSessionConfig } from "../../core/agentSpec.js";
+import { type Extension, type FolderOption } from "../../core/extensions.js";
 /** Absolute path of the sources extension's plugin, next to `dist/` (or `src/` under tsx). */
 export declare function sourcesPluginRoot(): string;
+/** The sources extension's options. */
+export interface SourcesOptions<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    /**
+     * The sources folder: original files kept as obtained, apart from any notes. Material the
+     * person drops in, plus whatever the agent saves with `save_to_sources` (downloaded documents,
+     * transcripts…). The agent reads and searches it, never edits it, and `save_to_sources` never
+     * overwrites. Without a folder the extension is off.
+     */
+    dir: FolderOption<TConfig>;
+    /** The `save_to_sources` tool's description in the agent's own words, instead of the kit's generic one. */
+    saveDescription?: string;
+}
 /**
- * The sources folder (`config.sourcesDir`): originals kept as obtained, read with `Read` and
- * `extract_text`, added and retired only through its tools (`sourceFiles`). It knows nothing of
- * a knowledge base (#30).
+ * The sources folder: originals kept as obtained, read with `Read` and `extract_text`, added and
+ * retired only through its tools (`sourceFiles`). It knows nothing of a knowledge base (#30).
  */
-export declare const sourcesExtension: Extension;
+export declare function sources<TConfig extends BaseSessionConfig = BaseSessionConfig>(options: SourcesOptions<TConfig>): Extension;

package/dist/extensions/sources/index.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { folderOf } from "../../core/extensions.js";
 import { sourcesToolLabels } from "./labels.js";
 import { addSource } from "./sources.js";
 import { createSaveToSourcesServer, sourcesPromptSection } from "./tools.js";
@@ -8,33 +9,34 @@ export function sourcesPluginRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "extensions", "sources");
 }
 /**
- * The sources folder (`config.sourcesDir`): originals kept as obtained, read with `Read` and
- * `extract_text`, added and retired only through its tools (`sourceFiles`). It knows nothing of
- * a knowledge base (#30).
+ * The sources folder: originals kept as obtained, read with `Read` and `extract_text`, added and
+ * retired only through its tools (`sourceFiles`). It knows nothing of a knowledge base (#30).
  */
-export const sourcesExtension = {
-    name: "sources",
-    plugin: sourcesPluginRoot(),
-    missing: ({ config }) => (config.sourcesDir ? undefined : "needs `sourcesDir` in the config"),
-    async contribute({ config, spec, runDir, interactive }) {
-        const sourcesDir = config.sourcesDir;
-        const folder = `${path.relative(config.projectDir, sourcesDir).split(path.sep).join("/")}/`;
-        return {
-            // Asking a person (request_file, retire_source) only where there is one.
-            mcpServers: { sourceFiles: createSaveToSourcesServer(runDir, sourcesDir, spec.saveToSourcesDescription, { projectDir: config.projectDir, interactive }) },
-            promptSection: sourcesPromptSection(config.projectDir, sourcesDir),
-            // The originals are read and searched, never written: the only way in is its tools.
-            fileTools: ["Read", "Glob", "Grep"],
-            readOnlyDirs: [sourcesDir],
-            readOnlyTools: ["mcp__sourceFiles__list_sources", "mcp__sourceFiles__extract_text"],
-            selfAskingTools: ["mcp__sourceFiles__request_file", "mcp__sourceFiles__retire_source"],
-            toolLabels: sourcesToolLabels(),
-            // For the host (a page's "add to the chest"): a file the person gave, with the same rules
-            // as the tools (never overwriting, a duplicate recognized) and the person as its origin.
-            api: {
-                addSource: (file, name, subfolder = "") => addSource(sourcesDir, file, subfolder ? `${subfolder.replace(/[/\\]*$/, "")}/` : name, { kind: "person", from: name }, subfolder ? { name } : {}),
-            },
-            helpLines: [`Originals go in \`${folder}\`: the person drops files there (or you ask for one, or download it), and you never change them.`],
-        };
-    },
-};
+export function sources(options) {
+    return {
+        name: "sources",
+        plugin: sourcesPluginRoot(),
+        missing: ({ config }) => (folderOf(options.dir, config) ? undefined : "needs a folder (`dir`)"),
+        async contribute({ config, runDir, interactive }) {
+            const sourcesDir = folderOf(options.dir, config);
+            const folder = `${path.relative(config.projectDir, sourcesDir).split(path.sep).join("/")}/`;
+            return {
+                // Asking a person (request_file, retire_source) only where there is one.
+                mcpServers: { sourceFiles: createSaveToSourcesServer(runDir, sourcesDir, options.saveDescription, { projectDir: config.projectDir, interactive }) },
+                promptSection: sourcesPromptSection(config.projectDir, sourcesDir),
+                // The originals are read and searched, never written: the only way in is its tools.
+                fileTools: ["Read", "Glob", "Grep"],
+                readOnlyDirs: [sourcesDir],
+                readOnlyTools: ["mcp__sourceFiles__list_sources", "mcp__sourceFiles__extract_text"],
+                selfAskingTools: ["mcp__sourceFiles__request_file", "mcp__sourceFiles__retire_source"],
+                toolLabels: sourcesToolLabels(),
+                // For the host (a page's "add to the chest"): a file the person gave, with the same rules
+                // as the tools (never overwriting, a duplicate recognized) and the person as its origin.
+                api: {
+                    addSource: (file, name, subfolder = "") => addSource(sourcesDir, file, subfolder ? `${subfolder.replace(/[/\\]*$/, "")}/` : name, { kind: "person", from: name }, subfolder ? { name } : {}),
+                },
+                helpLines: [`Originals go in \`${folder}\`: the person drops files there (or you ask for one, or download it), and you never change them.`],
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -11,8 +11,13 @@ export { buildSessionOptions, createInputQueue, createDeferred, createModeContro
 export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
 export type { SessionFacts } from "./core/sessionFacts.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./extensions/knowledge/prompt.js";
-export { readExtensionManifest, type Extension, type ExtensionContext, type ExtensionContribution, type ExtensionManifest, } from "./core/extensions.js";
+export { awareness, type AwarenessOptions } from "./extensions/awareness/index.js";
+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 { 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";
 export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, type KnowledgeStore, type PageType, type KnowledgePage, type PageInfo, type SearchHit, type CheckReport, type FieldChanges, type NewPage, } from "./extensions/knowledge/knowledgeStore.js";

package/dist/index.js

@@ -11,8 +11,13 @@ export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withTo
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";
 export { runQuery } from "./core/runner.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./extensions/knowledge/prompt.js";
+export { awareness } from "./extensions/awareness/index.js";
+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 { 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";
 export { BUILT_IN_PAGE_TYPES, isSlug, parseId, linkedIds, } from "./extensions/knowledge/knowledgeStore.js";

package/dist/tui/extensionCommand.d.ts

@@ -8,14 +8,23 @@ 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]> [--project] [--path <subfolder>]`
+ * - `extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]`
  * - `extension remove|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>`
  *
  * Without a scope, `add` installs into the agent's (the project's when the agent has no scope of
- * its own); the others act where the extension is, the project's first.
+ * its own); the others act where the extension is, the project's first. The marketplaces live in
+ * the same folder. `official` is the agent's own marketplace (a folder or git URL): known without
+ * asking, and installed from without a confirmation. Any other is added after a warning and
+ * typing its name, and installing from it asks first; `--yes` answers for the person (a script).
  */
 export declare function runExtensionCommand(argv: readonly string[], options: {
     dirs: ExtensionDirs;
     command?: string;
     write?: (line: string) => void;
+    /** The agent's official marketplace: a folder or a git URL (`#ref`). */
+    official?: string;
+    /** Asks the person (a confirmation); by default on the terminal, and nothing without one. */
+    ask?: (question: string) => Promise<string>;
 }): Promise<boolean>;

package/dist/tui/extensionCommand.js

@@ -1,6 +1,8 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
-import { addExtension, listInstalled, removeExtension, setExtensionEnabled, } from "../core/externalExtensions.js";
+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 { describe } from "../chat/extensions.js";
 export { chatExtensionsCommand, describe } from "../chat/extensions.js";
 /**
@@ -11,11 +13,16 @@ 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]> [--project] [--path <subfolder>]`
+ * - `extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]`
  * - `extension remove|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>`
  *
  * Without a scope, `add` installs into the agent's (the project's when the agent has no scope of
- * its own); the others act where the extension is, the project's first.
+ * its own); the others act where the extension is, the project's first. The marketplaces live in
+ * the same folder. `official` is the agent's own marketplace (a folder or git URL): known without
+ * asking, and installed from without a confirmation. Any other is added after a warning and
+ * typing its name, and installing from it asks first; `--yes` answers for the person (a script).
  */
 export async function runExtensionCommand(argv, options) {
     if (argv[0] !== "extension")
@@ -36,6 +43,22 @@ export async function runExtensionCommand(argv, options) {
         return true;
     };
     const scopeDir = (scope) => options.dirs[scope];
+    // The marketplaces live with the agent's extensions (the project's when it has no scope of its own).
+    const marketsDir = options.dirs.agent ?? options.dirs.project;
+    const ask = options.ask ?? askOnTerminal;
+    const confirmed = async (question, accepts) => flag("yes") || accepts((await ask(question)).trim());
+    // The agent's own marketplace, known without asking; a folder is copied afresh each time (it's the agent's own code).
+    const knownMarketplaces = async () => {
+        if (!marketsDir)
+            throw new Error("This agent has no folder for extensions.");
+        const known = await listMarketplaces(marketsDir);
+        const official = options.official;
+        if (official && !(isGitSource(official) && known.some((marketplace) => marketplace.official))) {
+            await addMarketplace(official, marketsDir, { official: true });
+            return listMarketplaces(marketsDir);
+        }
+        return known;
+    };
     try {
         switch (action) {
             case "list": {
@@ -62,11 +85,26 @@ export async function runExtensionCommand(argv, options) {
             case "add": {
                 const source = positional[0];
                 if (!source)
-                    return fail(`Usage: ${command} extension add <folder | git URL[#ref]> [--project] [--path <subfolder>]`);
+                    return fail(`Usage: ${command} extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>]`);
                 const scope = askedScope ?? (options.dirs.agent ? "agent" : "project");
                 const dir = scopeDir(scope);
                 if (!dir)
                     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 (!isFolder && !isGitSource(source) && /^[A-Za-z0-9][\w.-]*(@[A-Za-z0-9][\w.-]*)?$/.test(source)) {
+                    await knownMarketplaces();
+                    const { marketplace, plugin } = await findPlugin(marketsDir, source);
+                    if (!marketplace.official) {
+                        write(`${plugin.name}${plugin.version ? ` ${plugin.version}` : ""}, from the marketplace ${marketplace.name} (${marketplace.source}): ${plugin.description ?? "no description"}`);
+                        write("It will run on this computer with your permissions.");
+                        if (!(await confirmed("Install it? (y/N) ", (typed) => /^(y|yes|s|si|sí)$/i.test(typed))))
+                            return fail("Not installed.");
+                    }
+                    const result = await installFromMarketplace(marketsDir, source, dir);
+                    write(`${result.replaced ? "Reinstalled" : "Installed"} ${result.name} from ${result.marketplace} in the ${scope} scope (${dir})${result.commit ? `, at ${result.commit.slice(0, 12)}` : ""}. It's enabled: it runs from the next session.`);
+                    return true;
+                }
                 const subdir = value("path");
                 const result = await addExtension(source, dir, subdir ? { subdir } : {});
                 write(`${result.replaced ? "Reinstalled" : "Installed"} ${result.name} in the ${scope} scope (${dir})${result.commit ? `, at ${result.commit.slice(0, 12)}` : ""}. It's enabled: it runs from the next session.`);
@@ -92,19 +130,104 @@ export async function runExtensionCommand(argv, options) {
                 write(`${name} ${action === "remove" ? "removed" : `${action}d`} in the ${scope} scope. It applies from the next session (in the chat, \`/extensions\` reopens it).`);
                 return true;
             }
+            case "search": {
+                const words = positional.map((word) => word.toLowerCase());
+                const installed = new Set((await listInstalled(options.dirs)).map((extension) => extension.name));
+                const offered = (await knownMarketplaces()).flatMap((marketplace) => (marketplace.manifest?.plugins ?? []).map((plugin) => ({ marketplace, plugin })));
+                const matching = offered.filter(({ plugin }) => {
+                    const text = [plugin.name, plugin.description, plugin.category, ...(plugin.tags ?? []), ...(plugin.keywords ?? [])].join(" ").toLowerCase();
+                    return words.every((word) => text.includes(word));
+                });
+                if (!matching.length) {
+                    write(offered.length ? "No extension matches." : `No marketplace offers extensions yet. \`${command} extension marketplace add <folder | git URL | owner/repo>\` adds one.`);
+                    return true;
+                }
+                for (const { marketplace, plugin } of matching) {
+                    write(`${plugin.name}@${marketplace.name}${plugin.version ? ` ${plugin.version}` : ""}${installed.has(plugin.name) ? " (installed)" : ""}${plugin.description ? `  ${plugin.description}` : ""}`);
+                }
+                return true;
+            }
+            case "marketplace":
+                return await marketplaceCommand();
             default:
                 return fail([
                     `Usage: ${command} extension <action>`,
                     "  list                                   what's installed, in which scope, on or off",
                     "  info <name>                            its metadata, what it offers, its README",
-                    "  add <folder | git URL[#ref]> [--project] [--path <subfolder>]",
+                    "  add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]",
                     "  remove|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>",
                 ].join("\n"));
         }
     }
     catch (error) {
         return fail(error instanceof Error ? error.message : String(error));
     }
+    /** `extension marketplace <add | list | update | remove>`. */
+    async function marketplaceCommand() {
+        const [what, name] = positional;
+        switch (what) {
+            case "add": {
+                if (!name)
+                    return fail(`Usage: ${command} extension marketplace add <folder | git URL[#ref] | owner/repo> [--yes]`);
+                await knownMarketplaces();
+                const manifest = await inspectMarketplace(name);
+                write(`The marketplace ${manifest.name}, by ${manifest.owner.name}${manifest.description ? `: ${manifest.description}` : ""} (${manifest.plugins.length} extension${manifest.plugins.length === 1 ? "" : "s"}).`);
+                write("Its extensions run on this computer with your permissions, and it isn't this agent's own: add it only if you trust who publishes it.");
+                if (!(await confirmed(`Type its name (${manifest.name}) to add it: `, (typed) => typed === manifest.name)))
+                    return fail("Not added.");
+                const result = await addMarketplace(name, marketsDir);
+                write(`${result.replaced ? "Updated" : "Added"} the marketplace ${result.name}${result.commit ? `, at ${result.commit.slice(0, 12)}` : ""}. \`${command} extension search\` lists what it offers.`);
+                return true;
+            }
+            case "list": {
+                const known = await knownMarketplaces();
+                if (!known.length) {
+                    write(`No marketplaces. \`${command} extension marketplace add <folder | git URL | owner/repo>\` adds one.`);
+                    return true;
+                }
+                for (const marketplace of known) {
+                    write(`${marketplace.name}${marketplace.official ? " (official)" : ""}  ${marketplace.manifest ? `${marketplace.manifest.plugins.length} extension${marketplace.manifest.plugins.length === 1 ? "" : "s"}` : "can't be read"}  from ${marketplace.source}${marketplace.commit ? ` at ${marketplace.commit.slice(0, 12)}` : ""}, updated ${marketplace.updated.slice(0, 10)}`);
+                }
+                return true;
+            }
+            case "update": {
+                const known = await knownMarketplaces();
+                const chosen = name ? known.filter((marketplace) => marketplace.name === name) : known;
+                if (name && !chosen.length)
+                    return fail(`No marketplace ${name}.`);
+                for (const marketplace of chosen) {
+                    const { commit } = await updateMarketplace(marketsDir, marketplace.name);
+                    write(`Updated ${marketplace.name}${commit ? `, at ${commit.slice(0, 12)}` : ""}. Its installed extensions stay as they are: \`${command} extension add <name>@${marketplace.name}\` installs one again.`);
+                }
+                return true;
+            }
+            case "remove": {
+                if (!name)
+                    return fail(`Usage: ${command} extension marketplace remove <name>`);
+                if (!marketsDir || !(await removeMarketplace(marketsDir, name)))
+                    return fail(`No marketplace ${name}.`);
+                write(`Removed the marketplace ${name}. The extensions installed from it stay.`);
+                return true;
+            }
+            default:
+                return fail(`Usage: ${command} extension marketplace <add | list | update | remove>`);
+        }
+    }
+}
+/** A question on the terminal, or no answer without one. */
+async function askOnTerminal(question) {
+    if (!process.stdin.isTTY)
+        return "";
+    const terminal = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await terminal.question(question);
+    }
+    finally {
+        terminal.close();
+    }
 }
 /** Everything an installed extension's manifest says about it, for `extension info`. */
 async function info(extension) {
@@ -124,6 +247,7 @@ async function info(extension) {
         ...field("Works with", manifest.kit && `agent-kit ${manifest.kit}`),
         ...field("Provides", manifest.provides.join(", ") || undefined),
         ...field("Requires", manifest.requires.join(", ") || undefined),
+        ...field("Needs", manifest.needs.join(", ") || undefined),
         ...field("Servers", Object.keys(manifest.servers).join(", ") || undefined),
         ...field("Only read", manifest.readOnlyTools.join(", ") || undefined),
         ...field("Variables", Object.values(manifest.servers).flatMap((server) => Object.keys(server.env ?? {})).join(", ") || undefined),

package/package.json

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