@falkenslab/agent-kit 0.21.0 → 0.22.0

package/dist/core/workspaceTrust.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readLock } from "./externalExtensions.js";
+/**
+ * Trusting a workspace's extensions (#57): a project's scope comes with the project, from whoever
+ * shared it (a clone, a download), and its extensions' servers run code on this computer. They
+ * run only once the person trusts them in that workspace: what's trusted is each one's code (its
+ * files' SHA-256 and its npx packages'), kept in the agent's folder, outside the project, so a
+ * project can't trust itself. Another version (a changed lock, an update from someone else) asks
+ * again; turning one on or off, or its options, don't. What the person installs into the
+ * project's scope themselves is trusted as they install it. The agent's own scope is the
+ * person's: it never asks.
+ */
+const TRUST_FILE = ".trust.json";
+/** What's trusted of an extension: its code, its files' hash and its npx packages'. */
+export function codeHash(lock) {
+    const packages = Object.entries(lock.packages ?? {})
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([spec, cached]) => `${spec}=${cached.sha256}`);
+    // A linked one has no hash of its own: its folder is what's trusted.
+    return createHash("sha256").update([lock.linked ? `linked:${path.resolve(lock.source)}` : lock.sha256, ...packages].join("\n")).digest("hex");
+}
+async function readTrust(agentDir) {
+    try {
+        return JSON.parse(await readFile(path.join(agentDir, TRUST_FILE), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+/** The workspace a project scope is, as the trust file names it. */
+const workspaceKey = (projectScope) => path.resolve(projectScope);
+/** Whether an extension of a project's scope is trusted in that workspace, with the code its lock has now. */
+export async function isTrusted(agentDir, projectScope, name, lock) {
+    return (await readTrust(agentDir))[workspaceKey(projectScope)]?.[name] === codeHash(lock);
+}
+/** Trusts these extensions of a project's scope, with the code their lock has now. */
+export async function trust(agentDir, projectScope, entries) {
+    const file = await readTrust(agentDir);
+    const workspace = (file[workspaceKey(projectScope)] ??= {});
+    for (const [name, lock] of Object.entries(entries))
+        workspace[name] = codeHash(lock);
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(path.join(agentDir, TRUST_FILE), `${JSON.stringify(file, null, 2)}\n`, "utf8");
+}
+/**
+ * Trusts a workspace's extensions (its project scope's, all or `names`) with the code its lock
+ * has now: what the person does when the chat asks, or with `extension trust`. The names trusted.
+ */
+export async function trustWorkspace(dirs, names) {
+    if (!dirs.agent || !dirs.project)
+        return [];
+    const lock = await readLock(dirs.project);
+    const entries = Object.fromEntries(Object.entries(lock).filter(([name]) => !names || names.includes(name)));
+    await trust(dirs.agent, dirs.project, entries);
+    return Object.keys(entries);
+}

package/dist/index.d.ts

@@ -16,8 +16,13 @@ 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, extensionDataDir, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type InstalledExtension, type LockEntry, } from "./core/externalExtensions.js";
+export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type InstalledExtension, type LockEntry, type ExtensionOptionState, } from "./core/externalExtensions.js";
+export type { ExtensionOption, OptionValue } from "./core/extensionOptions.js";
+export type { ExtensionRestart, ExtensionSwitch } from "./core/liveExtensions.js";
+export { packageCacheDir, type CachedPackage } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, type KnownMarketplace, type MarketplaceManifest, type MarketplacePlugin, type PluginSource, } from "./core/marketplaces.js";
+export { extensionCatalog, installExtension, restoreExtensions, updateExtension, type CatalogEntry } from "./core/extensionCatalog.js";
+export { trustWorkspace } from "./core/workspaceTrust.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";
@@ -37,6 +42,7 @@ export { createFileScopeGate, checkFileScope, type FileScope } from "./core/hook
 export { createPlanGate, checkPlanScope, type PlanScope } from "./core/hooks/planGate.js";
 export { askForDecision, askForManualIntervention, askForChoice, askForText, type ChoiceAnswer } from "./core/hooks/humanInput.js";
 export { setInteractionPort, getInteractionPort, type InteractionPort, type ApprovalPrompt, type ChoiceSettings } from "./core/interaction.js";
+export { formFields, type FormAnswer, type FormField, type FormRequest } from "./core/elicitation.js";
 export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";
 export { createHumanApprovalServer, DEFAULT_HUMAN_APPROVAL_TEXTS, type HumanApprovalTexts } from "./core/tools/humanApproval.js";
 export { createManualLoginServer, type ManualInterventionTexts } from "./core/tools/manualLogin.js";

package/dist/index.js

@@ -16,8 +16,11 @@ 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, extensionDataDir, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, } from "./core/externalExtensions.js";
+export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, } from "./core/externalExtensions.js";
+export { packageCacheDir } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, } from "./core/marketplaces.js";
+export { extensionCatalog, installExtension, restoreExtensions, updateExtension } from "./core/extensionCatalog.js";
+export { trustWorkspace } from "./core/workspaceTrust.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";
@@ -38,6 +41,7 @@ export { createFileScopeGate, checkFileScope } from "./core/hooks/fileScopeGate.
 export { createPlanGate, checkPlanScope } from "./core/hooks/planGate.js";
 export { askForDecision, askForManualIntervention, askForChoice, askForText } from "./core/hooks/humanInput.js";
 export { setInteractionPort, getInteractionPort } from "./core/interaction.js";
+export { formFields } from "./core/elicitation.js";
 export { terminalInteractionPort, setSharedReadline, getSharedReadline } from "./tui/terminalInteraction.js";
 // The checkpoints answer on the terminal by default, as they always have; a non-terminal
 // host replaces the port with its own (or null, to answer through the response file only).

package/dist/tui/extensionCommand.d.ts

@@ -8,10 +8,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>`
  *
@@ -27,6 +31,10 @@ export declare function runExtensionCommand(argv: readonly string[], options: {
     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. */
+    /** The topics of the extensions `search` shows (#59), as the agent's `catalogTopics`; without it, every one. */
+    catalogTopics?: string[];
+    /** Asks the person (a confirmation, an option's value); by default on the terminal, and nothing without one. */
     ask?: (question: string) => Promise<string>;
+    /** Asks for a secret (a sensitive option), without echo; by default on the terminal. */
+    askSecret?: (question: string) => Promise<string>;
 }): Promise<boolean>;

package/dist/tui/extensionCommand.js

@@ -1,9 +1,11 @@
 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";
 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 +15,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 +43,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 +55,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,12 +121,19 @@ 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])));
                 // 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).`);
                     return true;
                 }
@@ -110,12 +146,16 @@ 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.`);
                     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.`);
                 return true;
             }
@@ -130,7 +170,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 +180,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 +279,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 +349,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 "";
@@ -265,7 +406,15 @@ async function info(extension) {
         ...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("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.22.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": {