@falkenslab/agent-kit 0.21.0 → 0.23.0

package/dist/tui/extensionCommand.js

@@ -1,9 +1,13 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
-import { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, removeMarketplace, updateMarketplace, } from "../core/marketplaces.js";
-import { addExtension, folderSize, isGitSource, listInstalled, removeExtension, setExtensionEnabled, } from "../core/externalExtensions.js";
-import { describe } from "../chat/extensions.js";
+import { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, removeMarketplace, updateMarketplace, } from "../core/marketplaces.js";
+import { addExtension, extensionOptionStates, installTarget, folderSize, isGitSource, listInstalled, removeExtension, setExtensionEnabled, setExtensionOptions, } from "../core/externalExtensions.js";
+import { describe, describeOptions } from "../chat/extensions.js";
+import { extensionCatalog, knownMarketplaces as catalogMarketplaces, restoreExtensions, updateExtension } from "../core/extensionCatalog.js";
+import { trustWorkspace } from "../core/workspaceTrust.js";
+import { describeCapability } from "../core/extensions.js";
+import { getLanguage } from "../core/messages/index.js";
 export { chatExtensionsCommand, describe } from "../chat/extensions.js";
 /**
  * The `extension` command an agent exposes in its own binary (#37), e.g. `captain extension add
@@ -13,10 +17,14 @@ export { chatExtensionsCommand, describe } from "../chat/extensions.js";
  *
  * - `extension list`
  * - `extension info <name>`: its metadata, what it offers and where its README is
- * - `extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]`
+ * - `extension add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--set key=value…] [--yes]`: asks for its options (#55) unless `--set` gives them
  * - `extension add <folder> --link [--project]`: registered where it is, to develop it (not copied, its files not checked)
  * - `extension remove <name> [--project | --agent] [--yes | --keep-data]`: asks before deleting its data folder
  * - `extension enable|disable <name> [--project | --agent]`
+ * - `extension config <name> [key=value… | key… | --unset key…] [--project | --agent]`: its options; `key` alone asks for it (without echo when it's a secret)
+ * - `extension update [name] [--yes]`: one installed from a marketplace (or all that have a newer version there) to the version it offers now, its data and options kept
+ * - `extension restore [--trust]`: gets the code a workspace's lock lists and this computer lacks (#57); `--trust` trusts it too
+ * - `extension trust [name…]`: lets a workspace's extensions run, as their code is now
  * - `extension search [words]`: what the known marketplaces offer
  * - `extension marketplace add <folder | git URL[#ref] | owner/repo> [--yes]`, `list`, `update [name]`, `remove <name>`
  *
@@ -37,7 +45,8 @@ export async function runExtensionCommand(argv, options) {
         const index = rest.indexOf(`--${name}`);
         return index >= 0 ? rest[index + 1] : undefined;
     };
-    const positional = rest.filter((arg, index) => !arg.startsWith("--") && rest[index - 1] !== "--path");
+    const values = (name) => rest.flatMap((arg, index) => (rest[index - 1] === `--${name}` ? [arg] : []));
+    const positional = rest.filter((arg, index) => !arg.startsWith("--") && !["--path", "--set", "--unset"].includes(rest[index - 1]));
     const askedScope = flag("project") ? "project" : flag("agent") ? "agent" : undefined;
     const fail = (message) => {
         write(message);
@@ -48,19 +57,41 @@ export async function runExtensionCommand(argv, options) {
     // 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);
+    const askSecret = options.askSecret ?? (options.ask ? options.ask : askSecretOnTerminal);
+    /**
+     * After installing `name` into `dir`: its options from `--set`, then asked for each still
+     * without a value (on a terminal; none without one), saying which required ones are left.
+     */
+    const configure = async (name, dir) => {
+        const installed = (await listInstalled(options.dirs)).find((extension) => extension.name === name && extension.scopeDir === dir);
+        const declared = installed?.manifest?.userConfig ?? {};
+        if (!installed || !Object.keys(declared).length)
+            return;
+        const typed = {};
+        for (const pair of values("set")) {
+            const at = pair.indexOf("=");
+            if (at <= 0)
+                throw new Error(`--set takes key=value: "${pair}"`);
+            typed[pair.slice(0, at)] = pair.slice(at + 1);
+        }
+        const states = await describeOptionStates(installed);
+        for (const [key, option] of Object.entries(declared)) {
+            if (key in typed || states.get(key))
+                continue;
+            const question = `${option.title}${option.required ? "" : " (optional)"}${option.default !== undefined ? ` [${String(option.default)}]` : ""}: ${option.description}\n  ${key} = `;
+            const answer = (await (option.sensitive ? askSecret : ask)(question)).trim();
+            if (answer)
+                typed[key] = answer;
         }
-        return known;
+        if (Object.keys(typed).length)
+            await setExtensionOptions(installed, name, typed);
+        const missing = Object.entries(declared).filter(([key, option]) => option.required && !(key in typed) && !states.get(key) && option.default === undefined).map(([key]) => key);
+        if (missing.length)
+            write(`It stays off until ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} set: \`${command} extension config ${name} ${missing[0]}\`.`);
     };
+    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 = () => catalogMarketplaces(options.dirs, options.official);
     try {
         switch (action) {
             case "list": {
@@ -92,13 +123,26 @@ export async function runExtensionCommand(argv, options) {
                 const dir = scopeDir(scope);
                 if (!dir)
                     return fail(`This agent has no ${scope} scope for extensions.`);
+                // The packages its npx servers run, in the agent's cache, shared by both scopes (#54); a
+                // project's code in the agent's store, its lock all the workspace keeps (#57).
+                const packages = installTarget(options.dirs, scope);
+                // Installed into the workspace by the person: trusted there as it is.
+                const trusted = async (name) => void (scope === "project" && (await trustWorkspace(options.dirs, [name])));
+                // What it needs and this computer lacks (#63): said, never installed.
+                const lacking = (missing) => {
+                    for (const line of missing)
+                        write(`It ${line}.`);
+                };
                 // A plugin of a marketplace, unless it's a folder here or a git URL.
                 const isFolder = await stat(path.resolve(source)).then((found) => found.isDirectory(), () => false);
                 if (flag("link")) {
                     if (!isFolder)
                         return fail(`Only a folder can be linked: ${source} isn't one here.`);
-                    const result = await addExtension(source, dir, { link: true });
+                    const result = await addExtension(source, dir, { link: true, ...(packages.packages ? { packages: packages.packages } : {}) });
+                    await trusted(result.name);
+                    await configure(result.name, dir);
                     write(`Linked ${result.name} in the ${scope} scope: it runs from ${path.resolve(source)}, whose files aren't checked. A rebuild takes effect when its server starts again (a new session, or \`/extensions disable\` and \`enable\` in the chat).`);
+                    lacking(result.missing);
                     return true;
                 }
                 if (!isFolder && !isGitSource(source) && /^[A-Za-z0-9][\w.-]*(@[A-Za-z0-9][\w.-]*)?$/.test(source)) {
@@ -110,13 +154,19 @@ export async function runExtensionCommand(argv, options) {
                         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);
+                    const result = await installFromMarketplace(marketsDir, source, dir, packages);
+                    await trusted(result.name);
+                    await configure(result.name, 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.`);
+                    lacking(result.missing);
                     return true;
                 }
                 const subdir = value("path");
-                const result = await addExtension(source, dir, subdir ? { subdir } : {});
+                const result = await addExtension(source, dir, { ...(subdir ? { subdir } : {}), ...packages });
+                await trusted(result.name);
+                await configure(result.name, dir);
                 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.`);
+                lacking(result.missing);
                 return true;
             }
             case "remove":
@@ -130,7 +180,7 @@ export async function runExtensionCommand(argv, options) {
                     return fail(`${name} isn't installed${askedScope ? ` in the ${askedScope} scope` : ""}. \`${command} extension list\` lists them.`);
                 if (found.length > 1 && !askedScope)
                     return fail(`${name} is installed in both scopes: say which, with --project or --agent.`);
-                const { scope, dataDir } = found[0];
+                const { scope, dataDir, privateDir } = found[0];
                 const dir = scopeDir(scope);
                 if (action !== "remove") {
                     await setExtensionEnabled(dir, name, action === "enable");
@@ -140,24 +190,95 @@ export async function runExtensionCommand(argv, options) {
                 // Its data (a browser profile, a signed-in session) may be worth keeping for a reinstall: asked, unless said.
                 const size = await folderSize(dataDir);
                 const deleteData = size > 0 && !flag("keep-data") && (await confirmed(`Delete its data too (${dataDir}, ${formatSize(size)})? (y/N) `, (typed) => /^(y|yes|s|si|sí)$/i.test(typed)));
-                await removeExtension(dir, name, { deleteData });
+                await removeExtension(dir, name, { deleteData, privateDir });
                 write(`${name} removed in the ${scope} scope${size > 0 ? (deleteData ? ", with its data" : `; its data stays in ${dataDir}`) : ""}. It applies from the next session (in the chat, \`/extensions\` reopens it).`);
                 return true;
             }
+            case "config": {
+                const name = positional[0];
+                if (!name)
+                    return fail(`Usage: ${command} extension config <name> [key=value… | key… | --unset key…] [--project | --agent]`);
+                const found = (await listInstalled(options.dirs)).filter((extension) => extension.name === name && !extension.shadowed && (!askedScope || extension.scope === askedScope));
+                if (!found.length)
+                    return fail(`${name} isn't installed${askedScope ? ` in the ${askedScope} scope` : ""}. \`${command} extension list\` lists them.`);
+                const installed = found[0];
+                const declared = installed.manifest?.userConfig ?? {};
+                const typed = {};
+                for (const key of values("unset"))
+                    typed[key] = undefined;
+                for (const pair of positional.slice(1)) {
+                    const at = pair.indexOf("=");
+                    if (at > 0)
+                        typed[pair.slice(0, at)] = pair.slice(at + 1);
+                    else {
+                        const option = declared[pair];
+                        if (!option)
+                            return fail(`${name} has no option "${pair}"${Object.keys(declared).length ? `: it has ${Object.keys(declared).join(", ")}` : ""}.`);
+                        typed[pair] = (await (option.sensitive ? askSecret : ask)(`${option.title}: ${option.description}\n  ${pair} = `)).trim() || undefined;
+                    }
+                }
+                if (Object.keys(typed).length) {
+                    await setExtensionOptions(installed, name, typed);
+                    write(`${name}'s options saved in the ${installed.scope} scope. They apply when its server starts again: the next session, or in a chat \`/extensions disable ${name}\` and \`enable\`.`);
+                }
+                const lines = await describeOptions((await listInstalled(options.dirs)).find((extension) => extension.name === name && extension.scopeDir === installed.scopeDir));
+                if (!lines.length)
+                    write(`${name} has no options.`);
+                for (const line of lines)
+                    write(line);
+                return true;
+            }
+            case "restore": {
+                const result = await restoreExtensions(options.dirs, options.official ? { official: options.official } : {});
+                for (const name of result.restored)
+                    write(`Restored ${name}.`);
+                for (const { name, reason } of result.failed)
+                    write(`${name} can't be restored: ${reason}.`);
+                if (!result.restored.length && !result.failed.length)
+                    write("This workspace's extensions are all on this computer.");
+                if (result.failed.length)
+                    process.exitCode = 1;
+                if (flag("trust"))
+                    for (const name of await trustWorkspace(options.dirs))
+                        write(`Trusted ${name} in this workspace.`);
+                else if (options.dirs.project && options.dirs.agent)
+                    write(`They run once you trust them: \`${command} extension trust\`, or the chat asks.`);
+                return true;
+            }
+            case "trust": {
+                if (!options.dirs.project || !options.dirs.agent)
+                    return fail("This agent has no workspace scope to trust: only its own, which never asks.");
+                const names = await trustWorkspace(options.dirs, positional.length ? positional : undefined);
+                if (!names.length)
+                    write("This workspace has no extensions.");
+                for (const name of names)
+                    write(`Trusted ${name} in this workspace, as it is now: another version asks again.`);
+                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));
-                });
+                const matching = await extensionCatalog(options.dirs, { ...(options.official ? { official: options.official } : {}), ...(options.catalogTopics?.length ? { topics: options.catalogTopics } : {}), words: positional });
                 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.`);
+                    const offered = (await knownMarketplaces()).some((marketplace) => marketplace.manifest?.plugins.length);
+                    write(offered ? "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}` : ""}`);
+                for (const entry of matching) {
+                    const state = entry.installed ? (entry.update ? ` (installed: ${entry.installed.manifest?.version ?? "?"}, update available)` : " (installed)") : "";
+                    write(`${entry.spec}${entry.version ? ` ${entry.version}` : ""}${state}${entry.plugin.description ? `  ${entry.plugin.description}` : ""}`);
+                }
+                return true;
+            }
+            case "update": {
+                const name = positional[0];
+                const official = options.official ? { official: options.official } : {};
+                const names = name ? [name] : (await extensionCatalog(options.dirs, official)).filter((entry) => entry.update).map((entry) => entry.plugin.name);
+                if (!names.length) {
+                    write("Every extension from a marketplace is up to date.");
+                    return true;
+                }
+                for (const each of names) {
+                    const result = await updateExtension(options.dirs, each, official);
+                    write(`Updated ${each}${result.from || result.to ? ` (${result.from ?? "?"} → ${result.to ?? "?"})` : ""} in the ${result.scope} scope: its data and options kept. It runs from the next session.`);
                 }
                 return true;
             }
@@ -168,10 +289,14 @@ export async function runExtensionCommand(argv, options) {
                     `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] | plugin[@marketplace]> [--project] [--path <subfolder>] [--yes]",
+                    "  add <folder | git URL[#ref] | plugin[@marketplace]> [--project] [--path <subfolder>] [--set key=value…] [--yes]",
                     "  add <folder> --link [--project]       to develop one: runs from its folder, not copied nor checked",
                     "  remove <name> [--project | --agent] [--yes | --keep-data]",
                     "  enable|disable <name> [--project | --agent]",
+                    "  config <name> [key=value… | key… | --unset key…]   its options (key alone asks for it)",
+                    "  update [name]                          to the version its marketplace offers now (all that have one, without a name)",
+                    "  restore [--trust]                      gets what this workspace's lock lists and this computer lacks",
+                    "  trust [name…]                          lets this workspace's extensions run, as they are now",
                     "  search [words]                         what the known marketplaces offer",
                     "  marketplace add <folder | git URL[#ref] | owner/repo> [--yes]",
                     "  marketplace list | update [name] | remove <name>",
@@ -234,6 +359,32 @@ export async function runExtensionCommand(argv, options) {
     }
 }
 /** A question on the terminal, or no answer without one. */
+/** Which of an installed extension's options have a value of their own (not a default). */
+async function describeOptionStates(installed) {
+    return new Map((await extensionOptionStates(installed)).map((state) => [state.key, state.set && !state.isDefault]));
+}
+/** A secret from the terminal, not echoed; "" without one. */
+async function askSecretOnTerminal(question) {
+    if (!process.stdin.isTTY)
+        return "";
+    const terminal = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    // What's typed isn't written back: only the question, readline's first write.
+    const output = terminal;
+    let prompted = false;
+    output._writeToOutput = (text) => {
+        if (prompted)
+            return;
+        prompted = true;
+        output.output.write(text);
+    };
+    try {
+        return await terminal.question(question);
+    }
+    finally {
+        terminal.close();
+        process.stdout.write("\n");
+    }
+}
 async function askOnTerminal(question) {
     if (!process.stdin.isTTY)
         return "";
@@ -261,11 +412,25 @@ async function info(extension) {
         ...field("Repository", manifest.repository),
         ...field("Keywords", manifest.keywords?.join(", ")),
         ...field("Works with", manifest.kit && `agent-kit ${manifest.kit}`),
+        // What it lets the agent do (#62), in the kit's language: one per line.
+        ...manifest.capabilities.flatMap((capability, index) => {
+            const { id, label, description } = describeCapability(capability, getLanguage());
+            return field(index ? "" : "Can do", `${label} (${id})${description ? `: ${description}` : ""}`);
+        }),
         ...field("Provides", manifest.provides.join(", ") || undefined),
         ...field("Requires", manifest.requires.join(", ") || undefined),
-        ...field("Needs", manifest.needs.join(", ") || undefined),
+        // The programs it needs on this computer (#63), one per line, with what for.
+        ...manifest.requirements.flatMap((requirement, index) => field(index ? "" : "Needs", `${requirement.name} (${requirement.program}${requirement.version ? ` ${requirement.version.min} or later` : ""})${requirement.for.length ? ` for ${requirement.for.join(", ")}` : ""}`)),
         ...field("Servers", Object.keys(manifest.servers).join(", ") || undefined),
-        ...field("Only read", manifest.readOnlyTools.join(", ") || undefined),
+        ...field("Only read", manifest.readOnlyTools
+            ? `${manifest.readOnlyTools.join(", ") || "none"} (its manifest)`
+            : Object.keys(manifest.servers).length
+                ? "what its servers mark readOnlyHint"
+                : undefined),
+        ...field("Packages", Object.keys(extension.lock.packages ?? {}).join(", ") || undefined),
+        ...field("Options", Object.entries(manifest.userConfig)
+            .map(([key, option]) => `${key} (${[option.title, option.required && "required", option.sensitive && "secret"].filter(Boolean).join(", ")})`)
+            .join(", ") || undefined),
         ...field("Variables", Object.values(manifest.servers).flatMap((server) => Object.keys(server.env ?? {})).join(", ") || undefined),
         ...field("Installed", `${extension.scope} scope, ${extension.lock.enabled ? "enabled" : "disabled"}, on ${extension.lock.installed}, from ${describe(extension).split("  from ")[1]}`),
         ...field("Data", (await stat(extension.dataDir).catch(() => null))?.isDirectory() ? `${extension.dataDir} (${formatSize(await folderSize(extension.dataDir))})` : undefined),

package/extensions/awareness/.claude-plugin/plugin.json

@@ -1,10 +1,18 @@
 {
   "name": "awareness",
+  "version": "1.0.0",
   "description": "You know who you are and what you are right now (your mode, extensions, tools, subagents, commands, context) through about_me, and how your chat is used through the help skill.",
-  "agent-kit": {
-    "provides": [
-      "self-awareness"
-    ],
-    "requires": []
+  "author": {
+    "name": "Falkenslab",
+    "url": "https://github.com/falkenslab"
+  },
+  "license": "MIT",
+  "metadata": {
+    "agent-kit": {
+      "provides": [
+        "self-awareness"
+      ],
+      "requires": []
+    }
   }
 }

package/extensions/knowledge/.claude-plugin/plugin.json

@@ -1,10 +1,18 @@
 {
   "name": "knowledge",
+  "version": "1.0.0",
   "description": "Built-in knowledge base workflows (an LLM wiki) over the kit's knowledge_* tools: ingesting sources, querying the knowledge base and health-checking it.",
-  "agent-kit": {
-    "provides": [
-      "knowledge-base"
-    ],
-    "requires": []
+  "author": {
+    "name": "Falkenslab",
+    "url": "https://github.com/falkenslab"
+  },
+  "license": "MIT",
+  "metadata": {
+    "agent-kit": {
+      "provides": [
+        "knowledge-base"
+      ],
+      "requires": []
+    }
   }
 }

package/extensions/memory/.claude-plugin/plugin.json

@@ -1,10 +1,18 @@
 {
   "name": "memory",
+  "version": "1.0.0",
   "description": "Your memory of the person you work for, across all their projects: who they are and how they want things done, kept only from what they tell you, through its tools: recall, remember and forget.",
-  "agent-kit": {
-    "provides": [
-      "person-memory"
-    ],
-    "requires": []
+  "author": {
+    "name": "Falkenslab",
+    "url": "https://github.com/falkenslab"
+  },
+  "license": "MIT",
+  "metadata": {
+    "agent-kit": {
+      "provides": [
+        "person-memory"
+      ],
+      "requires": []
+    }
   }
 }

package/extensions/sources/.claude-plugin/plugin.json

@@ -1,10 +1,18 @@
 {
   "name": "sources",
+  "version": "1.0.0",
   "description": "The sources folder: originals kept as obtained, listed, downloaded, asked for and retired through the kit's sources tools.",
-  "agent-kit": {
-    "provides": [
-      "sources"
-    ],
-    "requires": []
+  "author": {
+    "name": "Falkenslab",
+    "url": "https://github.com/falkenslab"
+  },
+  "license": "MIT",
+  "metadata": {
+    "agent-kit": {
+      "provides": [
+        "sources"
+      ],
+      "requires": []
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",
@@ -33,7 +33,8 @@
   "files": [
     "dist",
     "assets",
-    "extensions"
+    "extensions",
+    "schemas"
   ],
   "scripts": {
     "build": "tsc",
@@ -48,7 +49,7 @@
     "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.234",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.300",
     "@inkjs/ui": "^2.0.0",
     "@inquirer/prompts": "^8.5.2",
     "@types/react": "^19.3.0",
@@ -66,6 +67,7 @@
     "@mozilla/readability": "^0.6.0",
     "@types/node": "^24.0.0",
     "@types/turndown": "^5.0.6",
+    "ajv": "^8.20.0",
     "eslint": "^10.9.1",
     "fflate": "^0.8.3",
     "globals": "^17.11.0",
@@ -85,10 +87,10 @@
   },
   "peerDependencies": {
     "@mozilla/readability": ">=0.5.0",
+    "fflate": ">=0.8.0",
     "linkedom": ">=0.16.0",
-    "turndown": ">=7.0.0",
     "mammoth": ">=1.6.0",
-    "fflate": ">=0.8.0"
+    "turndown": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "@mozilla/readability": {

package/schemas/agent-kit-metadata.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json",
+  "title": "agent-kit's data in an extension's plugin.json",
+  "description": "What goes under metadata[\"agent-kit\"] in a Claude Code plugin's .claude-plugin/plugin.json, for agent-kit's gates, chats and catalog. Claude Code doesn't read metadata. Every field is optional.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "kit": {
+      "description": "The agent-kit versions it works with: comparators separated by spaces, all of which must hold (\">=0.22.0\", \">=0.22.0 <0.24.0\").",
+      "type": "string",
+      "pattern": "^\\s*(?:(?:>=|<=|>|<|=)?\\s*v?\\d+(?:\\.\\d+){0,2})(?:\\s+(?:>=|<=|>|<|=)?\\s*v?\\d+(?:\\.\\d+){0,2})*\\s*$"
+    },
+    "provides": { "description": "Capabilities it lets the agent use, by name only. Its capabilities' ids count as provided too.", "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "capabilities": {
+      "description": "What it lets the agent do, for the person: each one's skills and tools together, described per language. Its id is what requires names; neutral ids (lms-grading) let skills depend on what can be done, not on which extension does it.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/capability" }
+    },
+    "requires": { "description": "Capabilities another enabled extension must provide.", "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "requirements": {
+      "description": "Programs it needs on the computer, which the person installs: agent-kit checks them, says what's missing and how to install it, and never installs them. Without one the whole extension needs, it's off; without one only some capabilities need (for), those are.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/requirement" }
+    },
+    "readOnlyTools": {
+      "description": "Its tools that only read (short names): plan mode lets them through. Without it, plan mode asks its servers (readOnlyHint).",
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "labels": {
+      "description": "How the chat shows each tool (short name), per language (en, es, fr, de): {field} takes the call's input.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "propertyNames": { "enum": ["en", "es", "fr", "de"] },
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["label"],
+          "properties": {
+            "label": { "type": "string", "minLength": 1 },
+            "phrase": {
+              "description": "How it counts in a folded summary: once, and {n} times.",
+              "type": "array",
+              "prefixItems": [{ "type": "string" }, { "type": "string" }],
+              "minItems": 2,
+              "maxItems": 2
+            }
+          }
+        }
+      }
+    },
+    "help": { "description": "What it says about itself in a session, for the agent to tell the person.", "type": "string" },
+    "catalog": {
+      "description": "How a catalog shows it: images inside its folder (SVG, PNG, JPEG or WebP).",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "logo": { "description": "Square.", "$ref": "#/$defs/image" },
+        "banner": { "description": "Wide, about 3:1.", "$ref": "#/$defs/image" }
+      }
+    }
+  },
+  "$defs": {
+    "requirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "program", "install"],
+      "properties": {
+        "name": { "description": "What the person reads: Docker.", "type": "string", "minLength": 1 },
+        "program": { "description": "Its bare name, found on the PATH (on Windows with PATHEXT's extensions): never a path.", "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]*$" },
+        "version": {
+          "description": "How to check its version: run with these arguments only (options or version, no shell), the first x.y.z it prints compared with min.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["args", "min"],
+          "properties": {
+            "args": { "type": "array", "items": { "type": "string", "pattern": "^(--?[A-Za-z][A-Za-z0-9-]*|version)$" } },
+            "min": { "type": "string", "pattern": "^\\d+(\\.\\d+){0,2}$" }
+          }
+        },
+        "install": {
+          "description": "How to install it on each system: a command, or a link (url, the fallback).",
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": { "windows": { "type": "string", "minLength": 1 }, "macos": { "type": "string", "minLength": 1 }, "linux": { "type": "string", "minLength": 1 }, "url": { "type": "string", "pattern": "^https?://" } }
+        },
+        "for": { "description": "The capabilities (ids it provides) that need it; without it, the whole extension does.", "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "texts"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+        "skills": { "description": "Its skills, by their folder in the extension's skills/.", "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "tools": { "description": "Its tools, by short name (of any of its servers).", "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "texts": {
+          "description": "Its label and description per language (en, es, fr, de); English is shown where its language is missing.",
+          "type": "object",
+          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label"],
+            "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "image": {
+      "type": "string",
+      "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+\\.(?:svg|png|jpe?g|webp)$"
+    }
+  }
+}