@falkenslab/agent-kit 0.18.0 → 0.20.0

package/dist/{tui → chat}/runs.d.ts

@@ -1,5 +1,7 @@
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
-import type { ModeControl } from "../core/session.js";
+import type { ExtensionsStatus, ModeControl } from "../core/session.js";
+import type { ToolLabels } from "../core/toolLabels.js";
+import type { ExtensionSwitch } from "../core/liveExtensions.js";
 import { type RunFolder, type RunSummary } from "../core/runs.js";
 /**
  * Builds the session's options for a run folder, e.g.
@@ -10,11 +12,19 @@ import { type RunFolder, type RunSummary } from "../core/runs.js";
 export type SessionOpener = (run: RunFolder) => Promise<Options | {
     options: Options;
     modeControl?: ModeControl;
+    toolLabels?: ToolLabels;
+    extensions?: ExtensionsStatus;
+    apis?: Record<string, Record<string, unknown>>;
+    switchExtension?: ExtensionSwitch;
 }>;
 export interface OpenedSession {
     run: RunFolder;
     options: Options;
     modeControl?: ModeControl;
+    toolLabels?: ToolLabels;
+    extensions?: ExtensionsStatus;
+    apis?: Record<string, Record<string, unknown>>;
+    switchExtension?: ExtensionSwitch;
 }
 /** The run a chat starts with: the latest one with `--continue` (if any), a new one otherwise. */
 export declare function firstRun(runsDir: string, argv?: readonly string[]): Promise<RunFolder>;

package/dist/{tui → chat}/runs.js

@@ -13,7 +13,7 @@ export async function firstRun(runsDir, argv = process.argv.slice(2)) {
 export async function openSession(opener, run) {
     const opened = await opener(run);
     // The SDK's Options has no "options" field: this is buildSessionOptions()'s result.
-    return "options" in opened ? { run, options: opened.options, modeControl: opened.modeControl } : { run, options: opened };
+    return "options" in opened ? { run, options: opened.options, modeControl: opened.modeControl, toolLabels: opened.toolLabels, extensions: opened.extensions, apis: opened.apis, switchExtension: opened.switchExtension } : { run, options: opened };
 }
 /** A run's date for a person, in the kit's language. */
 export function runDate(date) {

package/dist/core/agentSpec.d.ts

@@ -1,5 +1,6 @@
+import type { ExtensionDirs } from "./externalExtensions.js";
 import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig, SettingSource } from "@anthropic-ai/claude-agent-sdk";
-import type { KnowledgeStore, PageType } from "./knowledgeStore.js";
+import type { Extension } from "./extensions.js";
 /**
  * The human-supervision spectrum every agent built on this kit shares, independent of
  * domain: "interactive" pauses before every single action, "guided" only pauses before a
@@ -23,25 +24,24 @@ export type Mode = "interactive" | "guided" | "autonomous" | "plan";
  */
 export interface BaseSessionConfig {
     mode: Mode;
-    /** Project root (the session's cwd): the folder under which the agent's notes, sources and runs live. */
+    /** Project root (the session's cwd): the folder under which the agent's folders and runs live. */
     projectDir: string;
     /**
-     * Where the agent writes its own notes (the "wiki"). Setting this or `sourcesDir` is what
-     * gives the session the file tools (Read/Write/Edit/Glob/Grep, scoped — see
-     * hooks/fileScopeGate.ts); without either, the agent has no file access at all.
+     * Where extensions are installed for this agent (#37): `agent` for all its projects (e.g.
+     * `~/.miyagi/extensions`), `project` for this one (e.g. `<projectDir>/extensions`), which wins.
+     * The enabled ones whose files match their lock run with the session; `runExtensionCommand()`
+     * installs them.
      */
-    knowledgeDir?: string;
+    extensionDirs?: ExtensionDirs;
     /**
-     * Original files, kept as obtained and apart from the notes in `knowledgeDir`: material
-     * the user drops in, plus whatever the agent saves with `save_to_sources` (downloaded
-     * documents, transcripts...). The agent can read and search it but never edit it — Write/
-     * Edit are scoped to `knowledgeDir` — and `save_to_sources` never overwrites.
+     * Directories where the agent reads, searches and writes with the file tools (Write/Edit,
+     * scoped — see hooks/fileScopeGate.ts), e.g. a folder of its own notes. Setting one gives the
+     * session all five file tools; an extension's folders (the sources, the knowledge base) come
+     * with the extension.
      */
-    sourcesDir?: string;
-    /** Directories besides `knowledgeDir`/`sourcesDir` where Write/Edit are allowed (see hooks/fileScopeGate.ts). */
     extraWritableDirs?: string[];
     /**
-     * Directories besides `sourcesDir`/`extraWritableDirs` the agent may read and search (Read,
+     * Directories besides `extraWritableDirs` and the extensions' folders the agent may read and search (Read,
      * Glob, Grep), never write. Read and Glob reach nothing else on the disk but what the kit
      * knows the agent needs (see hooks/fileScopeGate.ts).
      */
@@ -77,29 +77,21 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
     /** The system prompt for this run — everything role/mode/domain-specific lives behind this call. */
     buildSystemPrompt(config: TConfig): string;
     /**
-     * Who the agent is. With it, the kit tells the model its name, version and what it is, plus
-     * agent-kit's version, and offers the `agent-help` skill, which answers how to use the
-     * agent: the kit's chat (modes, keys, slash commands, resuming) and `helpGuide`. Without
-     * it, neither.
+     * Who the agent is: its name, version and what it is. The `awareness` extension tells the
+     * model (with agent-kit's version), and needs it; the session's facts carry it too.
      */
     identity?: AgentIdentity;
-    /**
-     * Absolute path of a markdown guide to the agent's own domain (its commands, configuration,
-     * folders), which the `agent-help` skill includes. Only with `identity`.
-     */
-    helpGuide?: string;
     /**
      * MCP servers this agent always registers (e.g. Playwright for a browser-driving
      * agent), on top of the generic ones `buildSessionOptions()` wires up itself when
-     * applicable (human approval, manual intervention, save-to-knowledge) — those aren't
-     * part of the spec because they're driven by `mode` plus this spec's own
-     * `manualInterventionTexts`/`knowledgeDir`/`sourcesDir`, not by anything else
-     * domain-specific.
+     * applicable (human approval, manual intervention) and the extensions' — those aren't
+     * part of this method because they're driven by `mode`, this spec's own
+     * `manualInterventionTexts` and its `extensions`.
      */
     buildMcpServers(config: TConfig, runDir: string): Record<string, McpServerConfig>;
     /**
      * Local plugin roots (skills/commands, SDK "local" plugin type) to load, in the order
-     * given, when the session has file tools (`config.knowledgeDir`/`config.sourcesDir`). Absolute paths; `buildSessionOptions()`
+     * given. Absolute paths; `buildSessionOptions()`
      * doesn't know or care where they live on disk.
      */
     pluginRoots(config: TConfig): string[];
@@ -123,28 +115,14 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      * over a permissive `canUseTool` — a disallowed tool never even reaches that callback.
      */
     disallowedTools?: string[];
-    /** Overrides this kit's generic `save_to_sources` tool description (registered whenever `config.sourcesDir` is set) with domain-specific wording. */
-    saveToSourcesDescription?: string;
-    /**
-     * The built-in knowledge base (see knowledge.ts): when `config.knowledgeDir` is set, the kit
-     * appends its "Knowledge base" rules to the system prompt, loads its plugin (skills
-     * knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
-     * /knowledge:lint) and its `knowledge_*` tools, the only way into the knowledge base (ADR-024).
-     * On by default; `false` makes `knowledgeDir` a folder of the agent's own notes, kept with the
-     * file tools under rules it writes itself.
-     */
-    knowledgeBase?: boolean;
-    /**
-     * The agent's own page types for the built-in knowledge base, besides the kit's
-     * (summary, concept, entity, synthesis): each with its folder (`""` for the root), index
-     * section, description (told to the model) and template.
-     */
-    knowledgePageTypes?: PageType[];
     /**
-     * The knowledge base's store, instead of the kit's over markdown files in `knowledgeDir`
-     * (e.g. a database or a vector store implementing `KnowledgeStore`).
+     * The extensions the agent runs with (ADR-025), in order, each made with its own options: the
+     * kit's through their factories (`awareness()`, `sources({ dir })`, `knowledge({ dir })`,
+     * `memory({ dir })`), the agent's own as `Extension` objects (its plugin and what it brings).
+     * An extension the session lacks something for (its folder), or whose required capabilities
+     * nothing enabled provides, is left out, and the prompt says why. None by default.
      */
-    knowledgeStore?(config: TConfig): KnowledgeStore;
+    extensions?: Extension[];
     /**
      * Whether the kit tells the agent (and each subagent) to reply in the resolved language
      * (`config.language`, `--language`, the system's), following the human if they write in
@@ -166,7 +144,7 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
      * The skills the agent offers (the SDK's `skills`): names, or `plugin:skill` for a
      * plugin's. Default `"all"`, every skill found: the SDK's own (about twenty, whatever
      * `settingSources` says), the project's, the plugins'. `"plugins"` offers only those of the
-     * plugins the session loads (`pluginRoots`, the knowledge base's, agent-help's), without
+     * plugins the session loads (`pluginRoots`, the extensions'), without
      * naming them. A list keeps the rest out of each turn's context; the knowledge base's own
      * skills are added to it when the knowledge base is on. A context filter, not a sandbox.
      */
@@ -217,8 +195,8 @@ export interface AgentIdentity {
 export interface PlanModeSpec<TConfig extends BaseSessionConfig = BaseSessionConfig> {
     /**
      * Whether `filePath` (absolute) is a plan file Write/Edit may touch in plan mode, e.g.
-     * `drafts/<slug>/plan.md`. It must also be writable under the file scope (`knowledgeDir`
-     * or `extraWritableDirs`), which still applies.
+     * `drafts/<slug>/plan.md`. It must also be writable under the file scope (`extraWritableDirs`),
+     * which still applies.
      */
     isPlanFile?(filePath: string, config: TConfig): boolean;
     /**

package/dist/core/extensions.d.ts

@@ -0,0 +1,128 @@
+import type { HookCallbackMatcher, HookEvent, McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentSpec, BaseSessionConfig, Mode } from "./agentSpec.js";
+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"`:
+ * 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 })`…);
+ * `buildSessionOptions()` puts the contributions of the active ones together, so the core names
+ * none of them. The kit's own (awareness, knowledge, sources, memory) live in
+ * `src/extensions/<name>/`, their plugin in `extensions/<name>/`; the core never imports them
+ * (an ESLint rule keeps it so), and no extension imports another: each owns its data, and the
+ * model connects them through their tools (#30).
+ */
+/** A folder an extension's options name: a path, or one worked out from the session's config (its project). */
+export type FolderOption<TConfig extends BaseSessionConfig = BaseSessionConfig> = string | ((config: TConfig) => string | undefined);
+/** The folder `option` names for this session's `config`, if any. */
+export declare function folderOf<TConfig extends BaseSessionConfig>(option: FolderOption<TConfig> | undefined, config: BaseSessionConfig): string | undefined;
+/** What an extension sees of the session it's contributing to. */
+export interface ExtensionContext<TConfig extends BaseSessionConfig = BaseSessionConfig> {
+    config: TConfig;
+    spec: AgentSpec<TConfig>;
+    /** This run's folder. */
+    runDir: string;
+    mode: Mode;
+    /** A person can be asked (not autonomous): tools that ask them may exist. */
+    interactive: boolean;
+    /**
+     * What the session's active extensions provide (their manifests' `provides`), for one that
+     * works differently beside another (the knowledge base beside the sources). Known once the
+     * extensions are resolved: empty in `missing()`.
+     */
+    capabilities: ReadonlySet<string>;
+    /**
+     * What the session is at the moment of the call (#43): its mode now, the extensions running
+     * and off, their tools, the subagents, skills, commands and context. The core's facts, read
+     * anew on every call; for a tool, not for `contribute()`, which runs before the session exists.
+     */
+    session(): Promise<SessionFacts>;
+}
+/** What an extension brings to a session. Every part is optional. */
+export interface ExtensionContribution {
+    /** MCP servers, by name (`mcp__<name>__<tool>`). */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** A section of the system prompt, after the agent's own and the list of extensions. */
+    promptSection?: string;
+    /** Built-in file tools it needs the session to have (`Read`, `Glob`, `Grep`…). */
+    fileTools?: string[];
+    /** Folders the file tools may read and search, never write (a sources folder). */
+    readOnlyDirs?: string[];
+    /** Folders reached only through its own tools, never the file tools, and what to use instead. */
+    toolOnlyDirs?: {
+        dir: string;
+        instead: string;
+    }[];
+    /** Its MCP tools that only read: plan mode lets them through. */
+    readOnlyTools?: 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. */
+    toolLabels?: ToolLabels;
+    /**
+     * Its hooks, by event, run after the kit's own: an internal extension's only (the memory
+     * hears the person's messages with `UserPromptSubmit`).
+     */
+    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    /** What it says about itself in this session (its commands, its folder), for the agent to tell the person (`SessionFacts`). */
+    helpLines?: string[];
+    /** What the session hands back to the host (e.g. the knowledge base's store), by name. */
+    api?: Record<string, unknown>;
+}
+/**
+ * An internal extension: its plugin (whose manifest gives its name, description and
+ * capabilities), what it needs from the session, and what it brings.
+ */
+export interface Extension {
+    /** Its name, the same as its plugin's (`plugin.json`'s `name`). */
+    name: string;
+    /** Its plugin's root: `.claude-plugin/plugin.json`, and its skills and commands, if any. */
+    plugin: string;
+    /** Installed rather than shipped in a package (#37): its subagents get no `Bash`, and no plugin hook runs. */
+    external?: boolean;
+    /** 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. */
+    contribute(context: ExtensionContext): Promise<ExtensionContribution>;
+}
+/** An extension's manifest, as the kit reads it. */
+export interface ExtensionManifest {
+    name: string;
+    description: string;
+    /** Capabilities it lets the agent use. */
+    provides: string[];
+    /** Capabilities it needs another enabled extension to provide. */
+    requires: string[];
+}
+/** Reads an extension's manifest from its plugin. */
+export declare function readExtensionManifest(pluginRoot: string): ExtensionManifest;
+/** The extensions a session runs with, and the ones it can't, with why. */
+export interface ResolvedExtensions {
+    active: {
+        extension: Extension;
+        manifest: ExtensionManifest;
+    }[];
+    inactive: {
+        name: string;
+        reason: string;
+    }[];
+    /** What the active ones provide. */
+    capabilities: Set<string>;
+}
+/**
+ * Which of the `extensions` run in this session, in the order given: those the session lacks
+ * something for are left out, and so are those requiring a capability no active one provides,
+ * until nothing more drops out.
+ */
+export declare function resolveExtensions(extensions: readonly Extension[], context: ExtensionContext): ResolvedExtensions;
+/** The prompt's "Extensions" section: what's on, and what isn't and why (ADR-025). */
+export declare function extensionsPromptSection(resolved: ResolvedExtensions): string;
+/**
+ * The skills of the plugins in `roots` whose frontmatter `requires` a capability not in
+ * `capabilities`, as the SDK names them (`<plugin>:<folder>`): the session leaves them out.
+ */
+export declare function skillsMissingCapabilities(roots: readonly string[], capabilities: ReadonlySet<string>): Promise<string[]>;
+/** A SKILL.md's `requires:` from its frontmatter: `requires: a`, `requires: [a, b]`, `a, b` or a YAML list. */
+export declare function requiredCapabilities(skill: string): string[];

package/dist/core/extensions.js

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { frontmatter } from "./pluginAgents.js";
+/** The folder `option` names for this session's `config`, if any. */
+export function folderOf(option, config) {
+    return typeof option === "function" ? option(config) : option;
+}
+/** Reads an extension's manifest from its plugin. */
+export function readExtensionManifest(pluginRoot) {
+    const file = path.join(pluginRoot, ".claude-plugin", "plugin.json");
+    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 ?? [] };
+}
+/**
+ * Which of the `extensions` run in this session, in the order given: those the session lacks
+ * something for are left out, and so are those requiring a capability no active one provides,
+ * until nothing more drops out.
+ */
+export function resolveExtensions(extensions, context) {
+    const inactive = [];
+    let active = [];
+    for (const extension of extensions) {
+        const manifest = readExtensionManifest(extension.plugin);
+        if (manifest.name !== extension.name)
+            throw new Error(`The extension "${extension.name}" has the plugin "${manifest.name}": they must have the same name.`);
+        const reason = extension.missing?.(context);
+        if (reason)
+            inactive.push({ name: extension.name, reason });
+        else
+            active.push({ extension, manifest });
+    }
+    // Requirements: drop what can't be met, again and again, since dropping one may starve another.
+    for (let changed = true; changed;) {
+        changed = false;
+        const provided = new Set(active.flatMap(({ manifest }) => manifest.provides));
+        for (const entry of active) {
+            const unmet = entry.manifest.requires.filter((capability) => !provided.has(capability));
+            if (!unmet.length)
+                continue;
+            inactive.push({ name: entry.extension.name, reason: `requires ${unmet.join(", ")}, which no enabled extension provides` });
+            active = active.filter((other) => other !== entry);
+            changed = true;
+            break;
+        }
+    }
+    return { active, inactive, capabilities: new Set(active.flatMap(({ manifest }) => manifest.provides)) };
+}
+/** The prompt's "Extensions" section: what's on, and what isn't and why (ADR-025). */
+export function extensionsPromptSection(resolved) {
+    const lines = resolved.active.map(({ manifest }) => `- **${manifest.name}**: ${manifest.description}${manifest.provides.length ? ` Provides: ${manifest.provides.join(", ")}.` : ""}`);
+    const off = resolved.inactive.map(({ name, reason }) => `- **${name}** isn't available: it ${reason}. If the person asks for what it does, tell them why.`);
+    return `## Extensions\nWhat you can do besides your own tools comes from these extensions; their sections below say how to use them.\n${[...lines, ...off].join("\n")}`;
+}
+/**
+ * The skills of the plugins in `roots` whose frontmatter `requires` a capability not in
+ * `capabilities`, as the SDK names them (`<plugin>:<folder>`): the session leaves them out.
+ */
+export async function skillsMissingCapabilities(roots, capabilities) {
+    const missing = [];
+    for (const root of roots) {
+        let plugin;
+        try {
+            plugin = JSON.parse(await readFile(path.join(root, ".claude-plugin", "plugin.json"), "utf8")).name;
+        }
+        catch {
+            continue;
+        }
+        const folders = await readdir(path.join(root, "skills"), { withFileTypes: true }).catch(() => []);
+        for (const folder of folders.filter((entry) => entry.isDirectory())) {
+            const text = await readFile(path.join(root, "skills", folder.name, "SKILL.md"), "utf8").catch(() => "");
+            const required = requiredCapabilities(text);
+            if (required.some((capability) => !capabilities.has(capability)))
+                missing.push(`${plugin}:${folder.name}`);
+        }
+    }
+    return missing;
+}
+/** A SKILL.md's `requires:` from its frontmatter: `requires: a`, `requires: [a, b]`, `a, b` or a YAML list. */
+export function requiredCapabilities(skill) {
+    const value = frontmatter(skill).fields.requires;
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : value.split(",")).map((item) => item.trim()).filter(Boolean);
+}

package/dist/core/externalExtensions.d.ts

@@ -0,0 +1,143 @@
+import type { Extension } from "./extensions.js";
+import type { Language } from "./language.js";
+import { type ToolPhrase } from "./messages/index.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).
+ */
+/** The two folders an agent installs extensions into; either may be left out. */
+export interface ExtensionDirs {
+    /** The agent's, for all its projects, e.g. `~/.miyagi/extensions`. */
+    agent?: string;
+    /** The project's, for this one only, e.g. `<projectDir>/extensions`: it wins over the agent's. */
+    project?: string;
+}
+/** One of the two scopes an extension can be installed in: the agent's or the project's. */
+export type ExtensionScope = keyof ExtensionDirs;
+/** One of a plugin's MCP servers, as its `.mcp.json` (or `plugin.json`'s `mcpServers`) declares it. */
+export interface PluginServer {
+    command: string;
+    args?: string[];
+    /** Its variables: a value may take the agent's with `${VAR}`. */
+    env?: Record<string, string>;
+}
+/** How the chat shows one of its tools in one language: `{field}` takes the call's input. */
+export interface ExternalToolLabel {
+    label: string;
+    phrase?: ToolPhrase;
+}
+/** Who made an extension, as Claude Code's `plugin.json` has it. */
+export interface ExtensionAuthor {
+    name: string;
+    email?: string;
+    url?: string;
+}
+/**
+ * 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).
+ */
+export interface ExternalManifest {
+    name: string;
+    description: string;
+    version?: string;
+    author?: ExtensionAuthor;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    provides: string[];
+    requires: string[];
+    /** 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[];
+    /** 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' 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;
+}
+/** One extension in a scope's lock. */
+export interface LockEntry {
+    /** Where it came from: a folder, or a git URL (with `#ref` when given). */
+    source: string;
+    /** The commit it was cloned at, for a git source. */
+    commit?: string;
+    /** The marketplace it was installed from (`<name>@<marketplace>`), if any. */
+    marketplace?: string;
+    /** SHA-256 over its files, checked when it loads. */
+    sha256: string;
+    enabled: boolean;
+    /** When it was installed, ISO 8601 in UTC. */
+    installed: string;
+}
+export declare const LOCK_FILE = "extensions.lock.json";
+/** 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. */
+export declare function hashExtension(dir: string): Promise<string>;
+/**
+ * Whether `version` (x.y.z) is in `range`: comparators separated by spaces, all of which must
+ * hold (`>=0.19.0 <0.21.0`, `=0.19.2`, `0.19.2`).
+ */
+export declare function inKitRange(version: string, range: string): boolean;
+/** One installed extension, as the scopes and their locks list it. */
+export interface InstalledExtension {
+    name: string;
+    scope: ExtensionScope;
+    dir: string;
+    lock: LockEntry;
+    /** Also installed in the project's scope, which wins: this one isn't used. */
+    shadowed: boolean;
+    /** Its manifest, when it can be read. */
+    manifest?: ExternalManifest;
+}
+/** Every extension installed in the scopes, the project's first. */
+export declare function listInstalled(dirs: ExtensionDirs): Promise<InstalledExtension[]>;
+/** The launcher that starts an external extension's server with a clean environment. */
+export declare function extensionLauncherPath(): string;
+/** The installed extensions a session runs with, and those it can't (with why). Disabled ones are neither. */
+export declare function loadExternalExtensions(dirs: ExtensionDirs): Promise<{
+    extensions: Extension[];
+    off: {
+        name: string;
+        reason: string;
+    }[];
+}>;
+/** 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>;
+/** Whether `source` names a git repository rather than a folder. */
+export declare function isGitSource(source: string): boolean;
+/**
+ * Installs an extension into a scope from a folder or a git repository (`url#ref`, `sha` to pin
+ * 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.
+ */
+export declare function addExtension(source: string, scopeDir: string, options?: {
+    subdir?: string;
+    sha?: string;
+    marketplace?: string;
+    origin?: 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>;
+/** 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>;