@falkenslab/agent-kit 0.21.0 → 0.23.0

package/dist/core/externalExtensions.d.ts

@@ -1,14 +1,17 @@
-import type { Extension } from "./extensions.js";
+import { type Extension, type ExtensionCapability } 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 { checkRequirements, type ExtensionRequirement } from "./extensionRequirements.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
+ * 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).
@@ -42,7 +45,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;
@@ -53,20 +56,37 @@ export interface ExternalManifest {
     repository?: string;
     license?: string;
     keywords?: string[];
+    /** What it lets the agent use: its `provides` and its capabilities' ids. */
     provides: string[];
     requires: string[];
+    /** What it lets the agent do, described for the person (#62): skills and tools together. */
+    capabilities: ExtensionCapability[];
     /** The agent-kit versions it works with, e.g. `">=0.19.0 <0.21.0"`. */
     kit?: string;
-    /** Programs it needs on this computer, found on the `PATH` (`"docker"`, `"python3"`): without one it's off, saying which. */
-    needs: string[];
+    /**
+     * Programs it needs on this computer (#63): checked when it loads, never installed. Without one
+     * the whole extension needs, it's off; without one only some capabilities need, those are.
+     */
+    requirements: ExtensionRequirement[];
     /** 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 {
@@ -79,10 +99,22 @@ export interface LockEntry {
     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; 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;
@@ -95,11 +127,34 @@ export declare const LOCK_FILE = "extensions.lock.json";
  * 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
@@ -114,8 +169,10 @@ export interface InstalledExtension {
     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. */
+    /** 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;
@@ -133,10 +190,18 @@ 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). */
 export declare function onPath(program: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** A requirement this computer lacks, as the person reads it: what it is, what for, and how to install it. */
+export declare function missingRequirement(check: Awaited<ReturnType<typeof checkRequirements>>[number]): string;
+/** What an installed extension can't do on this computer, and why: its capabilities whose requirements are missing (#63). */
+export interface UnavailableCapabilities {
+    capabilities: string[];
+    reason: string;
+}
 /** Whether `source` names a git repository rather than a folder. */
 export declare function isGitSource(source: string): boolean;
 /**
@@ -145,7 +210,9 @@ export declare function isGitSource(source: string): boolean;
  * 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; its data folder stays. With `link`, a folder is registered where it is
- * instead, to develop it: not copied, and its files not checked.
+ * 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;
@@ -153,10 +220,13 @@ export declare function addExtension(source: string, scopeDir: string, options?:
     marketplace?: string;
     origin?: string;
     link?: boolean;
+    packages?: string;
+    store?: string;
 }): Promise<{
     name: string;
     replaced: boolean;
     commit?: string;
+    missing: string[];
 }>;
 /**
  * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left
@@ -164,8 +234,28 @@ export declare function addExtension(source: string, scopeDir: string, options?:
  */
 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[]>;