@falkenslab/agent-kit 0.20.0 → 0.22.0

package/dist/core/extensionOptions.js

@@ -0,0 +1,139 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+const TYPES = new Set(["string", "number", "boolean", "directory", "file"]);
+const FIELDS = new Set(["type", "title", "description", "required", "default", "sensitive", "options", "multiple", "min", "max"]);
+/**
+ * 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 function parseUserConfig(raw) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("its userConfig isn't an object");
+    const options = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            throw new Error(`its userConfig option "${key}" isn't a valid name (letters, digits and _)`);
+        if (!value || typeof value !== "object")
+            throw new Error(`its userConfig option "${key}" isn't an object`);
+        const option = value;
+        const unknown = Object.keys(option).filter((field) => !FIELDS.has(field));
+        if (unknown.length)
+            throw new Error(`its userConfig option "${key}" has unknown fields (${unknown.join(", ")})`);
+        if (typeof option.type !== "string" || !TYPES.has(option.type))
+            throw new Error(`its userConfig option "${key}" has no valid type (string, number, boolean, directory or file)`);
+        if (typeof option.description !== "string")
+            throw new Error(`its userConfig option "${key}" has no description`);
+        options[key] = { ...option, title: typeof option.title === "string" ? option.title : key };
+    }
+    return options;
+}
+/** A typed value for `option` from what the person typed; throws saying why it isn't one. */
+export function parseOptionValue(option, typed) {
+    const one = (text) => {
+        const value = text.trim();
+        if (option.type === "number") {
+            const number = Number(value);
+            if (!value || Number.isNaN(number))
+                throw new Error(`"${value}" isn't a number`);
+            if (option.min !== undefined && number < option.min)
+                throw new Error(`${number} is below ${option.min}`);
+            if (option.max !== undefined && number > option.max)
+                throw new Error(`${number} is above ${option.max}`);
+            if (option.options && !option.options.includes(number))
+                throw new Error(`${number} isn't one of ${option.options.join(", ")}`);
+            return number;
+        }
+        if (option.type === "boolean") {
+            if (/^(true|yes|y|1|on)$/i.test(value))
+                return true;
+            if (/^(false|no|n|0|off)$/i.test(value))
+                return false;
+            throw new Error(`"${value}" isn't true or false`);
+        }
+        if (option.options && !option.options.map(String).includes(value))
+            throw new Error(`"${value}" isn't one of ${option.options.join(", ")}`);
+        return option.type === "directory" || option.type === "file" ? path.resolve(value) : value;
+    };
+    if (option.multiple)
+        return typed.split(",").filter((part) => part.trim()).map((part) => String(one(part)));
+    return one(typed);
+}
+/** A value as it goes into a server's argument or variable: a list comma-separated. */
+export function optionText(value) {
+    return value === undefined ? "" : Array.isArray(value) ? value.join(",") : String(value);
+}
+/** Where a scope keeps an extension's sensitive values: outside its plugin, its lock and its data. */
+export function extensionSecretsPath(scopeDir, name) {
+    return path.join(scopeDir, ".secrets", `${name}.json`);
+}
+/** The folder of a scope's sensitive values, which the session's file tools never reach. */
+export function secretsDir(scopeDir) {
+    return path.join(scopeDir, ".secrets");
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+/** The values an installed extension's options have now: what the person set (the lock's and the secrets'), else their defaults. */
+export async function readOptionValues(scopeDir, name, declared, stored = {}) {
+    const secrets = (await readJson(extensionSecretsPath(scopeDir, name)));
+    const values = {};
+    for (const [key, option] of Object.entries(declared)) {
+        const value = option.sensitive ? secrets[key] : stored[key];
+        if (value !== undefined)
+            values[key] = value;
+        else if (option.default !== undefined)
+            values[key] = option.default;
+    }
+    return values;
+}
+/** The required options without a value. */
+export function missingOptions(declared, values) {
+    return Object.entries(declared)
+        .filter(([key, option]) => option.required && (values[key] === undefined || values[key] === ""))
+        .map(([key]) => key);
+}
+/**
+ * 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 async function storeOptionValues(scopeDir, name, declared, stored, changes) {
+    const next = { ...stored };
+    const file = extensionSecretsPath(scopeDir, name);
+    const secrets = (await readJson(file));
+    let secretsChanged = false;
+    for (const [key, value] of Object.entries(changes)) {
+        const option = declared[key];
+        if (!option)
+            throw new Error(`${name} has no option "${key}"`);
+        const target = option.sensitive ? secrets : next;
+        if (value === undefined)
+            delete target[key];
+        else
+            target[key] = value;
+        if (option.sensitive)
+            secretsChanged = true;
+    }
+    if (secretsChanged) {
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, `${JSON.stringify(secrets, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        await chmod(file, 0o600).catch(() => undefined);
+    }
+    return next;
+}
+/** Removes an extension's sensitive values. */
+export async function removeSecrets(scopeDir, name) {
+    await rm(extensionSecretsPath(scopeDir, name), { force: true });
+}
+/** The `${user_config.KEY}` a server's values name. */
+export function optionsNamed(values) {
+    return [...new Set(values.flatMap((value) => [...value.matchAll(/\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((match) => match[1])))];
+}

package/dist/core/extensions.d.ts

@@ -4,7 +4,7 @@ import type { ToolLabels } from "./toolLabels.js";
 import type { SessionFacts } from "./sessionFacts.js";
 /**
  * Extensions (ADR-025): what an agent is besides the kit's core. An extension is a Claude Code
- * plugin with the kit's data in its manifest (`.claude-plugin/plugin.json`, key `"agent-kit"`:
+ * plugin with the kit's data in its manifest (`.claude-plugin/plugin.json`, under `metadata["agent-kit"]`:
  * the capabilities it `provides` and `requires`), plus, for an internal one, the code that
  * says what it brings to a session. An agent enables the ones it wants (`AgentSpec.extensions`),
  * each made with its own options (the kit's through their factories, `knowledge({ dir })`…);
@@ -57,6 +57,12 @@ export interface ExtensionContribution {
     }[];
     /** Its MCP tools that only read: plan mode lets them through. */
     readOnlyTools?: string[];
+    /**
+     * Its MCP servers whose tools that only read plan mode learns from the servers themselves
+     * (`readOnlyHint`), asked while the session runs: an installed extension whose manifest lists
+     * no `readOnlyTools`. A list in the manifest wins: its servers aren't here.
+     */
+    readOnlyHintServers?: string[];
     /** Its MCP tools that ask the person themselves: interactive mode's step gate doesn't ask first. */
     selfAskingTools?: string[];
     /** How the chat shows its tools, by full name, in the kit's language: its line and how it counts in a folded group. */
@@ -82,6 +88,8 @@ export interface Extension {
     plugin: string;
     /** Installed rather than shipped in a package (#37): its subagents get no `Bash`, and no plugin hook runs. */
     external?: boolean;
+    /** An installed one's scope folder, where its lock is (its plugin is elsewhere when it's linked). */
+    installedIn?: string;
     /** Why it can't run in this session (e.g. "needs a folder (`dir`)"), or `undefined` when it can. */
     missing?(context: ExtensionContext): string | undefined;
     /** What it brings to the session, once it's active. */

package/dist/core/extensions.js

@@ -12,7 +12,8 @@ export function readExtensionManifest(pluginRoot) {
     const raw = JSON.parse(readFileSync(file, "utf8"));
     if (!raw.name)
         throw new Error(`${file} has no "name".`);
-    return { name: raw.name, description: raw.description ?? "", provides: raw["agent-kit"]?.provides ?? [], requires: raw["agent-kit"]?.requires ?? [] };
+    const kit = raw.metadata?.["agent-kit"];
+    return { name: raw.name, description: raw.description ?? "", provides: kit?.provides ?? [], requires: kit?.requires ?? [] };
 }
 /**
  * Which of the `extensions` run in this session, in the order given: those the session lacks

package/dist/core/externalExtensions.d.ts

@@ -1,15 +1,19 @@
 import type { Extension } from "./extensions.js";
 import type { Language } from "./language.js";
 import { type ToolPhrase } from "./messages/index.js";
+import { type ExtensionOption, type OptionValue } from "./extensionOptions.js";
+import { type CachedPackage } from "./npxPackages.js";
 /**
  * External extensions (ADR-025, #37): installed into an agent, for all its projects (the
  * agent's scope) or for one (the project's, which wins), from a folder or a git repository.
  * Each scope is a folder of extensions, one per subfolder, with a lock (`extensions.lock.json`)
  * that records where each came from, a SHA-256 over its files and whether it's enabled. An
  * extension is a Claude Code plugin as it is (#38): its MCP servers come from its `.mcp.json`,
- * and the kit starts each with Node through a launcher that leaves it only the system's
- * variables and its own `env`. The `"agent-kit"` key of its `plugin.json` is optional: it adds
- * what the kit's gates and chat can use (capabilities, read-only tools, labels, help).
+ * and the kit starts each with Node (an `npx` one from its package cache, #54) through a launcher that leaves it only the system's
+ * variables and its own `env`. The `metadata["agent-kit"]` of its `plugin.json` is optional: it adds
+ * what the kit's gates and chat can use (capabilities, read-only tools, labels, help). Each has a
+ * data folder of its own (`${CLAUDE_PLUGIN_DATA}`, as Claude Code gives a plugin), kept across
+ * sessions and updates; one being developed is linked rather than copied (#52).
  */
 /** The two folders an agent installs extensions into; either may be left out. */
 export interface ExtensionDirs {
@@ -24,7 +28,7 @@ export type ExtensionScope = keyof ExtensionDirs;
 export interface PluginServer {
     command: string;
     args?: string[];
-    /** Its variables: a value may take the agent's with `${VAR}`. */
+    /** Its variables: a value may take the agent's with `${VAR}`, and its folders with `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}`. */
     env?: Record<string, string>;
 }
 /** How the chat shows one of its tools in one language: `{field}` takes the call's input. */
@@ -40,7 +44,7 @@ export interface ExtensionAuthor {
 }
 /**
  * An external extension's manifest: its `plugin.json`, the plugin's own metadata (Claude Code's
- * fields, which its validator checks) and the kit's key (`"agent-kit"`, which it ignores).
+ * fields, which its validator checks) and the kit's data (`metadata["agent-kit"]`, which it doesn't read).
  */
 export interface ExternalManifest {
     name: string;
@@ -59,33 +63,91 @@ export interface ExternalManifest {
     needs: string[];
     /** Its MCP servers, by name (`mcp__<name>__<tool>`), from the plugin's `.mcp.json` or `plugin.json`. */
     servers: Record<string, PluginServer>;
-    /** Its tools that only read (short names, of any of its servers): plan mode lets them through. */
-    readOnlyTools: string[];
+    /**
+     * Its tools that only read (short names, of any of its servers): plan mode lets them through.
+     * Without the key, plan mode asks its servers which (their tools' `readOnlyHint`); with it, the
+     * list is the whole answer, even empty.
+     */
+    readOnlyTools?: string[];
     /** Its tools' chat labels, by short name (of any of its servers) and language (English when the kit's isn't there). */
     labels: Record<string, Partial<Record<Language, ExternalToolLabel>>>;
     /** What it says about itself in a session, for the agent to tell the person (`SessionFacts`). */
     help?: string;
+    /** Its options (`userConfig`, as Claude Code declares them, #55): its servers take them as `${user_config.KEY}`. */
+    userConfig: Record<string, ExtensionOption>;
+    /** How a catalog shows it (#59): its `logo` (square) and `banner` (wide), paths inside its folder, as its manifest gives them. */
+    catalog?: {
+        logo?: string;
+        banner?: string;
+    };
 }
 /** One extension in a scope's lock. */
 export interface LockEntry {
-    /** Where it came from: a folder, or a git URL (with `#ref` when given). */
+    /** Where it came from: a folder, or a git URL (with `#ref` when given). A linked one runs from there. */
     source: string;
+    /**
+     * Linked rather than copied (`extension add --link`), to develop it: it runs from its folder,
+     * whose files aren't checked, so a rebuild takes effect when its server starts again.
+     */
+    linked?: boolean;
     /** The commit it was cloned at, for a git source. */
     commit?: string;
+    /** The folder inside its source it was installed from (a git repository's subfolder). */
+    subdir?: string;
+    /**
+     * Its code is in the agent's store (`<agent scope>/.store/<name>/<hash>/`), not in its scope's
+     * folder (#57): a project's scope keeps only its lock, so a workspace shared with others carries
+     * what it uses and at which version, never the code itself (`restoreExtensions()` gets it).
+     */
+    stored?: boolean;
     /** The marketplace it was installed from (`<name>@<marketplace>`), if any. */
     marketplace?: string;
-    /** SHA-256 over its files, checked when it loads. */
+    /** SHA-256 over its files, checked when it loads; empty for a linked one. */
     sha256: string;
+    /** Its options' non-sensitive values (#55); the sensitive ones are in the scope's `.secrets/`. */
+    options?: Record<string, OptionValue>;
+    /** The npm packages its servers run with npx (#54), by `<package>@<version>`: in the agent's package cache, checked when it loads. */
+    packages?: Record<string, CachedPackage>;
     enabled: boolean;
     /** When it was installed, ISO 8601 in UTC. */
     installed: string;
 }
 export declare const LOCK_FILE = "extensions.lock.json";
+/**
+ * An installed extension's data folder: `${CLAUDE_PLUGIN_DATA}` in its servers' arguments and
+ * variables (a browser profile, a cache), in its scope, outside its plugin and its hash, so it's
+ * kept across sessions and updates. Created when a session starts it; removing the extension
+ * asks before deleting it.
+ */
+export declare function extensionDataDir(scopeDir: string, name: string): string;
+/**
+ * Where a scope keeps what's the person's, not the workspace's: its extensions' data and secrets
+ * (#57). The agent's scope, its own folder; a project's, a folder of its own in the agent's
+ * (`<agent scope>/.projects/<project>-<hash>/`), so nothing private travels with a project. An
+ * agent without a scope of its own keeps it in the project's.
+ */
+export declare function scopePrivateDir(dirs: ExtensionDirs, scope: ExtensionScope): string | undefined;
+/** The agent's store of extensions' code, by content (#57): where a project's scope keeps its extensions' code. */
+export declare function codeStoreDir(dirs: ExtensionDirs): string | undefined;
+/** Where a stored extension's code is: by its name and its files' hash. */
+export declare function storedCodeDir(store: string, name: string, sha256: string): string;
+/**
+ * How an install into `scope` is done: its npx packages into the agent's cache, and a project's
+ * code into the agent's store when the agent has a scope of its own.
+ */
+export declare function installTarget(dirs: ExtensionDirs, scope: ExtensionScope): {
+    packages?: string;
+    store?: string;
+};
 /** A scope's lock: its extensions by name. */
 export declare function readLock(scopeDir: string): Promise<Record<string, LockEntry>>;
 /** Reads an extension's manifest, checking what the kit needs from it. */
 export declare function readExternalManifest(dir: string): Promise<ExternalManifest>;
-/** SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. */
+/**
+ * SHA-256 over an extension's files (their paths and contents, in order), `.git` aside. A text
+ * file's line endings don't count (CRLF is taken as LF): git checks the same commit out with CRLF
+ * on one computer and LF on another, and a workspace's lock must match on both (#57).
+ */
 export declare function hashExtension(dir: string): Promise<string>;
 /**
  * Whether `version` (x.y.z) is in `range`: comparators separated by spaces, all of which must
@@ -96,7 +158,14 @@ export declare function inKitRange(version: string, range: string): boolean;
 export interface InstalledExtension {
     name: string;
     scope: ExtensionScope;
+    /** Its scope's folder, where its lock is. */
+    scopeDir: string;
+    /** Its plugin: in its scope's folder, or where it is when it's linked. */
     dir: string;
+    /** Its data folder (`${CLAUDE_PLUGIN_DATA}`), which may not exist yet: in its scope's private folder. */
+    dataDir: string;
+    /** Its scope's private folder (`scopePrivateDir()`): its data and secrets. */
+    privateDir: string;
     lock: LockEntry;
     /** Also installed in the project's scope, which wins: this one isn't used. */
     shadowed: boolean;
@@ -114,6 +183,7 @@ export declare function loadExternalExtensions(dirs: ExtensionDirs): Promise<{
         name: string;
         reason: string;
     }[];
+    untrusted: InstalledExtension[];
 }>;
 /** Why an installed extension can't load, or its manifest when it can. */
 /** Whether a program is on the `PATH`, as a shell would find it (with `PATHEXT`'s extensions on Windows). */
@@ -125,19 +195,52 @@ export declare function isGitSource(source: string): boolean;
  * a commit, and `subdir` for one inside it): copies its files (never runs a script), checks its
  * manifest, and locks it, enabled, with the marketplace it came from when it did (`origin`, for a
  * temporary folder, is what the lock says it came from). An extension with the same name in that
- * scope is replaced.
+ * scope is replaced; its data folder stays. With `link`, a folder is registered where it is
+ * instead, to develop it: not copied, and its files not checked. The packages its npx servers
+ * run are fetched into `packages` (#54), the agent's package cache (`packageCacheDir()`; by
+ * default the scope's).
  */
 export declare function addExtension(source: string, scopeDir: string, options?: {
     subdir?: string;
     sha?: string;
     marketplace?: string;
     origin?: string;
+    link?: boolean;
+    packages?: string;
+    store?: string;
 }): Promise<{
     name: string;
     replaced: boolean;
     commit?: string;
 }>;
-/** Removes an extension from a scope (its files and its lock entry); false when it wasn't there. */
-export declare function removeExtension(scopeDir: string, name: string): Promise<boolean>;
+/**
+ * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left
+ * where it is), and its data folder with `deleteData`; false when it wasn't there.
+ */
+export declare function removeExtension(scopeDir: string, name: string, options?: {
+    deleteData?: boolean;
+    privateDir?: string;
+}): Promise<boolean>;
+/** The size in bytes of the files under `dir` (0 when it doesn't exist). */
+export declare function folderSize(dir: string): Promise<number>;
 /** Enables or disables an installed extension in a scope; false when it isn't there. */
 export declare function setExtensionEnabled(scopeDir: string, name: string, enabled: boolean): Promise<boolean>;
+/**
+ * Sets an installed extension's options (#55), each from what the person typed (`undefined`
+ * clears it), checked against its `userConfig`: sensitive ones into the scope's secrets, the rest
+ * into its lock. A running session's servers take them when they start again.
+ */
+export declare function setExtensionOptions(where: string | InstalledExtension, name: string, typed: Record<string, string | undefined>): Promise<void>;
+/** One of an installed extension's options and its value now (a sensitive one's value is never given: only whether it's set). */
+export interface ExtensionOptionState {
+    key: string;
+    option: ExtensionOption;
+    /** Its value, when it has one and isn't sensitive. */
+    value?: OptionValue;
+    /** Whether it has a value (its own or its default). */
+    set: boolean;
+    /** Its value is its default, not one the person gave. */
+    isDefault: boolean;
+}
+/** An installed extension's options, as they are now. */
+export declare function extensionOptionStates(installed: InstalledExtension): Promise<ExtensionOptionState[]>;