@falkenslab/agent-kit 0.21.0 → 0.23.0

package/dist/core/elicitation.d.ts

@@ -0,0 +1,54 @@
+import type { ElicitationRequest, ElicitationResult } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * MCP elicitation in the kit's chats (#58): an MCP server asks the person for something in the
+ * middle of a tool (a form, or a page to open), and the answer goes back to the server, never
+ * through the model. The SDK hands each request to `onElicitation` (without one it declines
+ * them all); the kit's asks through the interaction port: a whole form when the port can show
+ * one (`askForm`, the web and desktop chats), field by field with its usual panels otherwise
+ * (the terminal), and the response file as for any checkpoint. Nothing the person answers is
+ * written to the transcript or the session log; an autonomous session, with no one to ask,
+ * declines.
+ */
+/** One field of a form a server asks for, from its JSON Schema (MCP's flat, primitive one). */
+export interface FormField {
+    key: string;
+    title: string;
+    description?: string;
+    type: "string" | "number" | "integer" | "boolean";
+    /** The values it may take (a choice), and what each is called, when the schema names them. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** Several of `options` (an array of an enum). */
+    multiple?: boolean;
+    required: boolean;
+    default?: string | number | boolean | string[];
+    minimum?: number;
+    maximum?: number;
+}
+/** A form a server asks for, as the port shows it. */
+export interface FormRequest {
+    /** Who asks: the MCP server's name (the person must always see it). */
+    server: string;
+    message: string;
+    fields: FormField[];
+}
+/** The person's answer to a form: its values when accepted. */
+export type FormAnswer = {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, string | number | boolean | string[]>;
+};
+/** A form's fields from MCP's `requestedSchema`: an object of primitive properties. */
+export declare function formFields(schema: Record<string, unknown> | undefined): FormField[];
+/** A typed value for `field` from what the person typed, or why it isn't one. */
+export declare function fieldValue(field: FormField, typed: string): string | number | boolean | string[] | {
+    problem: string;
+};
+/**
+ * The session's `onElicitation`: in every mode but autonomous (`asks()`), the request goes to the
+ * person through the interaction port; otherwise, or with no port, it's declined.
+ */
+export declare function createElicitationHandler(runDir: string, asks: () => boolean): (request: ElicitationRequest, options: {
+    signal: AbortSignal;
+}) => Promise<ElicitationResult>;

package/dist/core/elicitation.js

@@ -0,0 +1,120 @@
+import { askForChoice, askForDecision, askForManualIntervention, askForText } from "./hooks/humanInput.js";
+import { getInteractionPort } from "./interaction.js";
+import { t } from "./messages/index.js";
+/** A form's fields from MCP's `requestedSchema`: an object of primitive properties. */
+export function formFields(schema) {
+    const properties = (schema?.properties ?? {});
+    const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
+    return Object.entries(properties).map(([key, property]) => {
+        const items = property.items;
+        const multiple = property.type === "array";
+        const choices = (multiple ? items : property) ?? {};
+        // A choice: `enum` (with `enumNames`), or `oneOf`/`anyOf` of `{ const, title }`.
+        const titled = (choices.oneOf ?? choices.anyOf);
+        const values = Array.isArray(choices.enum) ? choices.enum.map(String) : titled?.map((option) => String(option.const));
+        const names = Array.isArray(choices.enumNames) ? choices.enumNames.map(String) : titled?.map((option) => option.title ?? String(option.const));
+        const type = multiple ? "string" : (["number", "integer", "boolean"].includes(String(property.type)) ? property.type : "string");
+        return {
+            key,
+            title: typeof property.title === "string" ? property.title : key,
+            ...(typeof property.description === "string" ? { description: property.description } : {}),
+            type,
+            ...(values?.length ? { options: values.map((value, index) => ({ value, label: names?.[index] ?? value })) } : {}),
+            ...(multiple ? { multiple: true } : {}),
+            required: required.has(key),
+            ...(property.default !== undefined ? { default: property.default } : {}),
+            ...(typeof property.minimum === "number" ? { minimum: property.minimum } : {}),
+            ...(typeof property.maximum === "number" ? { maximum: property.maximum } : {}),
+        };
+    });
+}
+/** A typed value for `field` from what the person typed, or why it isn't one. */
+export function fieldValue(field, typed) {
+    const text = typed.trim();
+    if (field.type === "boolean")
+        return /^(y|yes|true|1|s|si|sí|oui|ja)$/i.test(text);
+    if (field.type === "number" || field.type === "integer") {
+        const number = Number(text);
+        if (!text || Number.isNaN(number) || (field.type === "integer" && !Number.isInteger(number)))
+            return { problem: t().elicitNotANumber(text) };
+        if ((field.minimum !== undefined && number < field.minimum) || (field.maximum !== undefined && number > field.maximum))
+            return { problem: t().elicitOutOfRange(field.minimum, field.maximum) };
+        return number;
+    }
+    return text;
+}
+/** Asks for a form field by field, with the port's usual panels: a choice for options and yes/no, text for the rest. */
+async function askFieldByField(runDir, request) {
+    const shown = await askForDecision(runDir, {
+        title: t().elicitTitle(request.server),
+        lines: [request.message, "", ...request.fields.map((field) => `- ${field.title}${field.required ? " *" : ""}${field.description ? `: ${field.description}` : ""}`)],
+        question: t().elicitQuestion,
+    });
+    if (shown === "n")
+        return { action: "decline" };
+    if (shown !== "y" && shown !== "")
+        return { action: "cancel" };
+    const content = {};
+    for (const field of request.fields) {
+        const prompt = { title: `${request.server}: ${field.title}${field.required ? " *" : ""}`, lines: field.description ? [field.description] : [] };
+        if (field.options || field.type === "boolean") {
+            const options = field.options ?? [
+                { value: "true", label: t().yes },
+                { value: "false", label: t().no },
+            ];
+            const answer = await askForChoice(runDir, prompt, options.map((option) => option.label), Boolean(field.multiple));
+            const chosen = answer.chosen.map((label) => options.find((option) => option.label === label).value);
+            if (!chosen.length) {
+                if (field.required)
+                    return { action: "decline" };
+                continue;
+            }
+            content[field.key] = field.multiple ? chosen : field.type === "boolean" ? chosen[0] === "true" : field.type === "string" ? chosen[0] : Number(chosen[0]);
+            continue;
+        }
+        // Typed: asked again while it isn't a value of its type.
+        for (let tries = 0;; tries++) {
+            const typed = await askForText(runDir, tries ? { ...prompt, lines: [...prompt.lines, t().elicitAgain] } : prompt);
+            if (!typed.trim()) {
+                if (field.required)
+                    return { action: "decline" };
+                break;
+            }
+            const value = fieldValue(field, typed);
+            if (typeof value === "object" && !Array.isArray(value)) {
+                if (tries >= 2)
+                    return { action: "decline" };
+                continue;
+            }
+            content[field.key] = value;
+            break;
+        }
+    }
+    return { action: "accept", content };
+}
+/** A page a server asks the person to open (a sign-in elsewhere): shown, never opened for them; only https, or http on this computer. */
+async function askToOpen(runDir, request) {
+    const url = request.url ?? "";
+    const safe = /^https:\/\//i.test(url) || /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(url);
+    if (!safe)
+        return { action: "decline" };
+    const answer = await askForManualIntervention(runDir, { title: t().elicitUrlTitle(request.serverName), lines: [request.message, "", url], question: t().elicitUrlQuestion });
+    return answer === "n" || answer === "q" ? { action: "decline" } : { action: "accept" };
+}
+/**
+ * The session's `onElicitation`: in every mode but autonomous (`asks()`), the request goes to the
+ * person through the interaction port; otherwise, or with no port, it's declined.
+ */
+export function createElicitationHandler(runDir, asks) {
+    return async (request, { signal }) => {
+        const port = getInteractionPort();
+        if (!asks() || !port)
+            return { action: "decline" };
+        if (request.mode === "url")
+            return await askToOpen(runDir, request);
+        const form = { server: request.displayName ?? request.serverName, message: request.message, fields: formFields(request.requestedSchema) };
+        if (port.askForm)
+            return await port.askForm(form, signal);
+        return await askFieldByField(runDir, form);
+    };
+}

package/dist/core/extensionCatalog.d.ts

@@ -0,0 +1,103 @@
+import { type ExtensionDirs, type ExtensionScope, type InstalledExtension } from "./externalExtensions.js";
+import { type DescribedCapability } from "./extensions.js";
+import { type KnownMarketplace, type MarketplacePlugin } from "./marketplaces.js";
+/**
+ * The agent's catalog of extensions (#56): what its known marketplaces offer, what's installed
+ * from them and what has a newer version, and installing and updating from it. The kit's
+ * command and the chats (terminal, web, desktop) share it, so a person without a shell can do
+ * what `extension add`, `search` and `update` do.
+ */
+/** Where an agent keeps its marketplaces: with its extensions (the project's when it has no scope of its own). */
+export declare function marketplacesDir(dirs: ExtensionDirs): string | undefined;
+/**
+ * The marketplaces the agent knows, its `official` one among them: added without asking the
+ * first time, and a folder one copied afresh each time (it's the agent's own code).
+ */
+export declare function knownMarketplaces(dirs: ExtensionDirs, official?: string): Promise<KnownMarketplace[]>;
+/** One extension a marketplace offers, and how it stands in the agent. */
+export interface CatalogEntry {
+    /** `<name>@<marketplace>`, what installs it. */
+    spec: string;
+    marketplace: string;
+    /** From the agent's own marketplace: installed without a confirmation. */
+    official: boolean;
+    plugin: MarketplacePlugin;
+    /** The version it offers: its `plugin.json`'s when the marketplace has its folder, else the marketplace's entry's. */
+    version?: string;
+    /** Installed (and used: not shadowed), from wherever it came. */
+    installed?: InstalledExtension;
+    /** Installed from this marketplace with an older version than it offers. */
+    update: boolean;
+    /** What it's about and who it's for (#59): its `plugin.json`'s `keywords` and its entry's `tags`, `keywords` and `category`, lowercased. */
+    topics: string[];
+    /** Its logo and banner (#59), as files of the marketplace's copy, when it has them. */
+    logo?: string;
+    banner?: string;
+    /** What it lets the agent do (#62), in the kit's language: from its `plugin.json` when the marketplace has its folder. */
+    capabilities: DescribedCapability[];
+    /** The programs it needs on the computer (#63), by name ("Docker"), with the capabilities that need them (none: all of it). */
+    requirements: {
+        name: string;
+        for: string[];
+    }[];
+}
+/** Whether `offered` is newer than `installed` (x.y.z); a version that can't be compared isn't. */
+export declare function isNewer(offered: string | undefined, installed: string | undefined): boolean;
+/** Everything the known marketplaces offer, matching `words` (in its name, description, category, tags or keywords) when given. */
+export declare function extensionCatalog(dirs: ExtensionDirs, options?: {
+    official?: string;
+    words?: readonly string[];
+    topics?: readonly string[];
+}): Promise<CatalogEntry[]>;
+/** Whether installing `spec` needs the person's confirmation first: a plugin of a marketplace that isn't the agent's own. */
+export declare function needsConfirmation(dirs: ExtensionDirs, spec: string, official?: string): Promise<{
+    marketplace: KnownMarketplace;
+    plugin: MarketplacePlugin;
+} | undefined>;
+/**
+ * Installs a plugin of a known marketplace (`<name>@<marketplace>`, or a name only one offers)
+ * into a scope: the agent's by default (the project's when it has none), the packages its npx
+ * servers run into the agent's cache. Asking the person first, for one that isn't the agent's
+ * own (`needsConfirmation()`), is the caller's.
+ */
+export declare function installExtension(dirs: ExtensionDirs, spec: string, options?: {
+    scope?: ExtensionScope;
+    official?: string;
+}): Promise<{
+    name: string;
+    scope: ExtensionScope;
+    replaced: boolean;
+    marketplace: string;
+    commit?: string;
+    missing: string[];
+}>;
+/**
+ * Updates an installed extension from the marketplace it came from: a fresh copy of the
+ * marketplace, then installed again in the same scope (its data and options kept). One that
+ * didn't come from a marketplace is installed again with `extension add`.
+ */
+export declare function updateExtension(dirs: ExtensionDirs, name: string, options?: {
+    official?: string;
+}): Promise<{
+    name: string;
+    from?: string;
+    to?: string;
+    scope: ExtensionScope;
+}>;
+/**
+ * Gets what a workspace's lock lists and this computer lacks (#57): each extension's code into
+ * the agent's store, from where it came (its marketplace, its git repository at its commit, its
+ * folder), checked against the lock's hash, and the packages its npx servers run into the
+ * agent's cache. It trusts nothing: the workspace still asks before they run. What can't be got
+ * says why (a marketplace the agent doesn't know, another version there now, a folder that isn't
+ * on this computer).
+ */
+export declare function restoreExtensions(dirs: ExtensionDirs, options?: {
+    official?: string;
+}): Promise<{
+    restored: string[];
+    failed: {
+        name: string;
+        reason: string;
+    }[];
+}>;

package/dist/core/extensionCatalog.js

@@ -0,0 +1,235 @@
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { addExtension, codeStoreDir, hashExtension, inKitRange, installTarget, isGitSource, listInstalled, readExternalManifest, readLock, storedCodeDir } from "./externalExtensions.js";
+import { cachePackage, cachedPackageDir } from "./npxPackages.js";
+import { trustWorkspace } from "./workspaceTrust.js";
+import { describeCapability } from "./extensions.js";
+import { getLanguage } from "./messages/index.js";
+import { addMarketplace, findPlugin, installFromMarketplace, listMarketplaces, resolvePluginSource, updateMarketplace } from "./marketplaces.js";
+/**
+ * The agent's catalog of extensions (#56): what its known marketplaces offer, what's installed
+ * from them and what has a newer version, and installing and updating from it. The kit's
+ * command and the chats (terminal, web, desktop) share it, so a person without a shell can do
+ * what `extension add`, `search` and `update` do.
+ */
+/** Where an agent keeps its marketplaces: with its extensions (the project's when it has no scope of its own). */
+export function marketplacesDir(dirs) {
+    return dirs.agent ?? dirs.project;
+}
+/**
+ * The marketplaces the agent knows, its `official` one among them: added without asking the
+ * first time, and a folder one copied afresh each time (it's the agent's own code).
+ */
+export async function knownMarketplaces(dirs, official) {
+    const dir = marketplacesDir(dirs);
+    if (!dir)
+        throw new Error("This agent has no folder for extensions.");
+    // Calls at the same time share one look (a page asking for several images at once): two copies
+    // of the same marketplace taken together would clash.
+    const key = path.resolve(dir);
+    const pending = looking.get(key);
+    if (pending)
+        return pending;
+    const look = lookAt(dir, official).finally(() => looking.delete(key));
+    looking.set(key, look);
+    return look;
+}
+const looking = new Map();
+async function lookAt(dir, official) {
+    const known = await listMarketplaces(dir);
+    if (official && !(isGitSource(official) && known.some((marketplace) => marketplace.official))) {
+        await addMarketplace(official, dir, { official: true });
+        return listMarketplaces(dir);
+    }
+    return known;
+}
+/** The images a catalog shows: these types only. */
+const IMAGE = /\.(svg|png|jpe?g|webp)$/i;
+/**
+ * What a marketplace offers of a plugin, from its folder in the marketplace's copy when it has one:
+ * the version (its `plugin.json` wins over the entry, as Claude Code computes it), its keywords,
+ * and its look, an image inside its folder only.
+ */
+async function offered(marketplace, plugin) {
+    try {
+        const resolved = resolvePluginSource(marketplace, plugin);
+        if ("source" in resolved && !isGitSource(resolved.source) && (await stat(resolved.source).catch(() => null))?.isDirectory()) {
+            const manifest = await readExternalManifest(resolved.source).catch(() => undefined);
+            const image = async (relative) => {
+                if (!relative || !IMAGE.test(relative))
+                    return undefined;
+                const file = path.resolve(resolved.source, relative);
+                if (path.relative(resolved.source, file).startsWith("..") || !(await stat(file).catch(() => null))?.isFile())
+                    return undefined;
+                return file;
+            };
+            const [logo, banner] = [await image(manifest?.catalog?.logo), await image(manifest?.catalog?.banner)];
+            const version = manifest?.version ?? plugin.version;
+            const capabilities = (manifest?.capabilities ?? []).map((capability) => describeCapability(capability, getLanguage()));
+            const requirements = (manifest?.requirements ?? []).map((requirement) => ({ name: requirement.name, for: requirement.for }));
+            return { ...(version ? { version } : {}), keywords: manifest?.keywords ?? [], ...(logo ? { logo } : {}), ...(banner ? { banner } : {}), capabilities, requirements };
+        }
+    }
+    catch {
+        // A source the kit doesn't install: the entry's own fields.
+    }
+    return { ...(plugin.version ? { version: plugin.version } : {}), keywords: [], capabilities: [], requirements: [] };
+}
+/** Whether `offered` is newer than `installed` (x.y.z); a version that can't be compared isn't. */
+export function isNewer(offered, installed) {
+    if (!offered || !installed || !/^\d+\.\d+\.\d+/.test(offered) || !/^\d+\.\d+\.\d+/.test(installed))
+        return false;
+    return inKitRange(offered, `>${installed.split("-")[0]}`);
+}
+/** Everything the known marketplaces offer, matching `words` (in its name, description, category, tags or keywords) when given. */
+export async function extensionCatalog(dirs, options = {}) {
+    const installed = (await listInstalled(dirs)).filter((extension) => !extension.shadowed);
+    const words = (options.words ?? []).map((word) => word.toLowerCase());
+    // What the agent offers its users (#59): only what has one of its topics.
+    const wanted = options.topics?.length ? new Set(options.topics.map((topic) => topic.toLowerCase())) : undefined;
+    const entries = [];
+    for (const marketplace of await knownMarketplaces(dirs, options.official)) {
+        for (const plugin of marketplace.manifest?.plugins ?? []) {
+            const look = await offered(marketplace, plugin);
+            const topics = [...new Set([...look.keywords, ...(plugin.tags ?? []), ...(plugin.keywords ?? []), ...(plugin.category ? [plugin.category] : [])].map((topic) => topic.toLowerCase()))];
+            if (wanted && !topics.some((topic) => wanted.has(topic)))
+                continue;
+            // Its capabilities count too: a search for "grading" finds what grades.
+            const text = [plugin.name, plugin.description, ...topics, ...look.capabilities.flatMap(({ id, label, description }) => [id, label, description])].join(" ").toLowerCase();
+            if (!words.every((word) => text.includes(word)))
+                continue;
+            const version = look.version;
+            const mine = installed.find((extension) => extension.name === plugin.name);
+            const fromHere = mine?.lock.marketplace === `${plugin.name}@${marketplace.name}`;
+            entries.push({
+                spec: `${plugin.name}@${marketplace.name}`,
+                marketplace: marketplace.name,
+                official: marketplace.official,
+                plugin,
+                ...(version ? { version } : {}),
+                ...(mine ? { installed: mine } : {}),
+                update: Boolean(fromHere && isNewer(version, mine?.manifest?.version)),
+                topics,
+                ...(look.logo ? { logo: look.logo } : {}),
+                ...(look.banner ? { banner: look.banner } : {}),
+                capabilities: look.capabilities,
+                requirements: look.requirements,
+            });
+        }
+    }
+    return entries;
+}
+/** Whether installing `spec` needs the person's confirmation first: a plugin of a marketplace that isn't the agent's own. */
+export async function needsConfirmation(dirs, spec, official) {
+    await knownMarketplaces(dirs, official);
+    const found = await findPlugin(marketplacesDir(dirs), spec);
+    return found.marketplace.official ? undefined : found;
+}
+/**
+ * Installs a plugin of a known marketplace (`<name>@<marketplace>`, or a name only one offers)
+ * into a scope: the agent's by default (the project's when it has none), the packages its npx
+ * servers run into the agent's cache. Asking the person first, for one that isn't the agent's
+ * own (`needsConfirmation()`), is the caller's.
+ */
+export async function installExtension(dirs, spec, options = {}) {
+    const scope = options.scope ?? (dirs.agent ? "agent" : "project");
+    const scopeDir = dirs[scope];
+    if (!scopeDir)
+        throw new Error(`This agent has no ${scope} scope for extensions.`);
+    await knownMarketplaces(dirs, options.official);
+    const result = await installFromMarketplace(marketplacesDir(dirs), spec, scopeDir, installTarget(dirs, scope));
+    // Installed into a workspace by the person: trusted there as it is (#57).
+    if (scope === "project")
+        await trustWorkspace(dirs, [result.name]);
+    return { ...result, scope };
+}
+/**
+ * Updates an installed extension from the marketplace it came from: a fresh copy of the
+ * marketplace, then installed again in the same scope (its data and options kept). One that
+ * didn't come from a marketplace is installed again with `extension add`.
+ */
+export async function updateExtension(dirs, name, options = {}) {
+    const installed = (await listInstalled(dirs)).find((extension) => extension.name === name && !extension.shadowed);
+    if (!installed)
+        throw new Error(`${name} isn't installed.`);
+    const from = installed.lock.marketplace;
+    if (!from)
+        throw new Error(`${name} didn't come from a marketplace (${path.normalize(installed.lock.source)}): install it again from there to update it.`);
+    const marketplace = from.slice(from.indexOf("@") + 1);
+    await knownMarketplaces(dirs, options.official);
+    await updateMarketplace(marketplacesDir(dirs), marketplace);
+    await installFromMarketplace(marketplacesDir(dirs), from, installed.scopeDir, installTarget(dirs, installed.scope));
+    if (installed.scope === "project")
+        await trustWorkspace(dirs, [name]);
+    const after = (await listInstalled(dirs)).find((extension) => extension.name === name && extension.scopeDir === installed.scopeDir);
+    return { name, scope: installed.scope, ...(installed.manifest?.version ? { from: installed.manifest.version } : {}), ...(after?.manifest?.version ? { to: after.manifest.version } : {}) };
+}
+/**
+ * Gets what a workspace's lock lists and this computer lacks (#57): each extension's code into
+ * the agent's store, from where it came (its marketplace, its git repository at its commit, its
+ * folder), checked against the lock's hash, and the packages its npx servers run into the
+ * agent's cache. It trusts nothing: the workspace still asks before they run. What can't be got
+ * says why (a marketplace the agent doesn't know, another version there now, a folder that isn't
+ * on this computer).
+ */
+export async function restoreExtensions(dirs, options = {}) {
+    const restored = [];
+    const failed = [];
+    const store = codeStoreDir(dirs);
+    if (!dirs.project || !store)
+        return { restored, failed };
+    const target = installTarget(dirs, "project");
+    for (const [name, lock] of Object.entries(await readLock(dirs.project))) {
+        if (lock.linked)
+            continue;
+        try {
+            const stored = storedCodeDir(store, name, lock.sha256);
+            const have = (await stat(stored).catch(() => null))?.isDirectory() && (await hashExtension(stored)) === lock.sha256;
+            if (!have) {
+                // Installed again into a scratch scope, which puts its code in the store; its hash must be the lock's.
+                const scratch = await mkdtemp(path.join(os.tmpdir(), "agent-kit-restore-"));
+                try {
+                    if (lock.marketplace) {
+                        await knownMarketplaces(dirs, options.official);
+                        await installFromMarketplace(marketplacesDir(dirs), lock.marketplace, scratch, target);
+                    }
+                    else if (isGitSource(lock.source)) {
+                        await addExtension(lock.source, scratch, { ...target, ...(lock.commit ? { sha: lock.commit } : {}), ...(lock.subdir ? { subdir: lock.subdir } : {}) });
+                    }
+                    else if ((await stat(lock.source).catch(() => null))?.isDirectory()) {
+                        await addExtension(lock.source, scratch, target);
+                    }
+                    else {
+                        throw new Error(`it came from a folder that isn't on this computer (${lock.source})`);
+                    }
+                    const got = (await readLock(scratch))[name]?.sha256;
+                    if (got !== lock.sha256)
+                        throw new Error(`where it came from has another version now${lock.marketplace ? `: \`extension update ${name}\` takes it` : ""}`);
+                }
+                finally {
+                    await rm(scratch, { recursive: true, force: true });
+                }
+            }
+            // Its npx packages, the versions the lock names, checked against their hashes there.
+            const cache = target.packages;
+            for (const [spec, cached] of Object.entries(lock.packages ?? {})) {
+                const at = spec.lastIndexOf("@");
+                const [pkg, version] = [spec.slice(0, at), spec.slice(at + 1)];
+                if (!cache)
+                    throw new Error("this agent has no package cache");
+                const dir = cachedPackageDir(cache, pkg, version);
+                if ((await stat(dir).catch(() => null))?.isDirectory() && (await hashExtension(dir)) === cached.sha256)
+                    continue;
+                if ((await cachePackage(cache, pkg, version)).sha256 !== cached.sha256)
+                    throw new Error(`its package ${spec} isn't what the workspace locked`);
+            }
+            if (!have || Object.keys(lock.packages ?? {}).length)
+                restored.push(name);
+        }
+        catch (error) {
+            failed.push({ name, reason: error instanceof Error ? error.message.replace(/\.$/, "") : String(error) });
+        }
+    }
+    return { restored, failed };
+}

package/dist/core/extensionOptions.d.ts

@@ -0,0 +1,56 @@
+/**
+ * An installed extension's options (#55): what its `plugin.json` declares under `userConfig`, as
+ * Claude Code does, and the values the person gives them. Its servers take them as
+ * `${user_config.KEY}` in their `args` and `env`; the launcher puts the values in when it starts a
+ * server, read from disk then, so a value changed while a session runs reaches the server when
+ * it starts again (the chat restarts it: `reconnectMcpServer()`). Non-sensitive values live in the
+ * scope's lock; sensitive ones in a file of the scope's `.secrets/` folder, which the session's
+ * file tools never reach: neither is ever in the prompt, the transcript or a tool's result.
+ */
+/** A value an option takes: by its type, a list when it's `multiple`. */
+export type OptionValue = string | number | boolean | string[];
+/** One of an extension's options, as Claude Code's `userConfig` declares it. */
+export interface ExtensionOption {
+    type: "string" | "number" | "boolean" | "directory" | "file";
+    /** What it's called where the person is asked. */
+    title: string;
+    description: string;
+    /** Without a value (its own or a default), the extension doesn't run. */
+    required?: boolean;
+    default?: OptionValue;
+    /** A secret (a token, a password): asked without echo, kept apart, never shown back. */
+    sensitive?: boolean;
+    /** The values it may take, when it's a choice. */
+    options?: (string | number)[];
+    /** Several values (comma-separated where they're typed). */
+    multiple?: boolean;
+    /** A number's bounds. */
+    min?: number;
+    max?: number;
+}
+/**
+ * A manifest's `userConfig`, checked as Claude Code checks it (an option with an unknown field
+ * makes the plugin fail to load there): throws saying what's wrong.
+ */
+export declare function parseUserConfig(raw: unknown): Record<string, ExtensionOption>;
+/** A typed value for `option` from what the person typed; throws saying why it isn't one. */
+export declare function parseOptionValue(option: ExtensionOption, typed: string): OptionValue;
+/** A value as it goes into a server's argument or variable: a list comma-separated. */
+export declare function optionText(value: OptionValue | undefined): string;
+/** Where a scope keeps an extension's sensitive values: outside its plugin, its lock and its data. */
+export declare function extensionSecretsPath(scopeDir: string, name: string): string;
+/** The folder of a scope's sensitive values, which the session's file tools never reach. */
+export declare function secretsDir(scopeDir: string): string;
+/** The values an installed extension's options have now: what the person set (the lock's and the secrets'), else their defaults. */
+export declare function readOptionValues(scopeDir: string, name: string, declared: Record<string, ExtensionOption>, stored?: Record<string, OptionValue>): Promise<Record<string, OptionValue>>;
+/** The required options without a value. */
+export declare function missingOptions(declared: Record<string, ExtensionOption>, values: Record<string, OptionValue>): string[];
+/**
+ * Sets (or with `undefined`, clears) some of an extension's option values: the sensitive ones in
+ * its secrets file, the others returned for its lock entry (the caller writes the lock).
+ */
+export declare function storeOptionValues(scopeDir: string, name: string, declared: Record<string, ExtensionOption>, stored: Record<string, OptionValue>, changes: Record<string, OptionValue | undefined>): Promise<Record<string, OptionValue>>;
+/** Removes an extension's sensitive values. */
+export declare function removeSecrets(scopeDir: string, name: string): Promise<void>;
+/** The `${user_config.KEY}` a server's values name. */
+export declare function optionsNamed(values: readonly string[]): string[];