@falkenslab/agent-kit 0.21.0 → 0.23.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/extensionRequirements.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The programs an extension needs on the computer (#63): Docker for a lab, ffmpeg for videos.
+ * The kit installs an extension's files and never a program (ADR-025): it checks them, says what's
+ * missing, what for and how to install it on this system, and keeps off only what needs them.
+ */
+/** A program an extension needs on the computer, and how the person installs it. */
+export interface ExtensionRequirement {
+    /** What the person reads: "Docker". */
+    name: string;
+    /** The program, by its bare name, found on the `PATH` (`docker`; on Windows with `PATHEXT`'s extensions). */
+    program: string;
+    /** How to check its version: its arguments (options or `version` only) and the oldest it works with. */
+    version?: {
+        args: string[];
+        min: string;
+    };
+    /** How to install it on each system: a command, or a link. */
+    install: {
+        windows?: string;
+        macos?: string;
+        linux?: string;
+        url?: string;
+    };
+    /** The capabilities that need it (its manifest's ids); without them, the whole extension does. */
+    for: string[];
+}
+/** What checking a requirement found. */
+export interface RequirementCheck {
+    requirement: ExtensionRequirement;
+    /** On the `PATH`. */
+    found: boolean;
+    /** The version it said, when it was asked and said one. */
+    version?: string;
+    /** There, and new enough (or its version couldn't be read). */
+    ok: boolean;
+}
+/** A manifest's `requirements`: each as given, for `requirementsProblem()` to judge. */
+export declare function parseRequirements(raw: unknown): ExtensionRequirement[];
+/**
+ * Why an extension's requirements can't be checked safely or don't hold together (a program given
+ * as a path, a version argument that isn't an option, a capability it doesn't provide), or nothing.
+ */
+export declare function requirementsProblem(requirements: readonly ExtensionRequirement[], provides: readonly string[]): string | undefined;
+/** Where a program is on the `PATH`, as a shell would find it (with `PATHEXT`'s extensions on Windows), or nothing. */
+export declare function findOnPath(program: string, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/** Whether `version` is `min` or later, comparing x.y.z (missing parts are 0). */
+export declare function atLeast(version: string, min: string): boolean;
+/**
+ * Checks one requirement: finds its program on the `PATH` and, when it says how, runs it with its
+ * version arguments only: no shell, nothing else on the command line, and stopped after
+ * `timeoutMs`. A Windows script (`.cmd`, `.bat`) can't run without a shell, and a program that
+ * says no version can't be compared: either counts as there.
+ */
+export declare function checkRequirement(requirement: ExtensionRequirement, options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RequirementCheck>;
+/** Checks an extension's requirements, all at once. */
+export declare function checkRequirements(requirements: readonly ExtensionRequirement[], options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RequirementCheck[]>;
+/** How to install a requirement on this system: its command, else its link. */
+export declare function installHint(requirement: ExtensionRequirement, platform?: NodeJS.Platform): string | undefined;
+/** What's missing, as a reason reads ("Docker (docker 24.0.0 or later), which isn't on this computer: install it with …"). */
+export declare function describeMissing(check: RequirementCheck, platform?: NodeJS.Platform): string;

package/dist/core/extensionRequirements.js

@@ -0,0 +1,112 @@
+import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+/** A program's name: a bare one, never a path, so the check can only find it on the `PATH`. */
+const PROGRAM = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+/** A version check's arguments: options and `version`, never what would do something (`docker run …`). */
+const VERSION_ARG = /^(--?[A-Za-z][A-Za-z0-9-]*|version)$/;
+const VERSION = /^\d+(\.\d+){0,2}$/;
+/** A manifest's `requirements`: each as given, for `requirementsProblem()` to judge. */
+export function parseRequirements(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const text = (value) => (typeof value === "string" && value ? value : undefined);
+    return raw.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const { name, program, version, install, for: needed } = item;
+        const programName = text(program);
+        if (!programName)
+            return [];
+        const check = version && typeof version === "object" ? version : undefined;
+        const how = install && typeof install === "object" ? install : {};
+        return [
+            {
+                name: text(name) ?? programName,
+                program: programName,
+                ...(check ? { version: { args: Array.isArray(check.args) ? check.args.map(String) : [], min: String(check.min ?? "") } } : {}),
+                install: Object.fromEntries(["windows", "macos", "linux", "url"].flatMap((key) => (text(how[key]) ? [[key, text(how[key])]] : []))),
+                for: Array.isArray(needed) ? needed.filter((id) => typeof id === "string") : [],
+            },
+        ];
+    });
+}
+/**
+ * Why an extension's requirements can't be checked safely or don't hold together (a program given
+ * as a path, a version argument that isn't an option, a capability it doesn't provide), or nothing.
+ */
+export function requirementsProblem(requirements, provides) {
+    for (const requirement of requirements) {
+        if (!PROGRAM.test(requirement.program))
+            return `needs the program "${requirement.program}", which isn't a bare name found on the PATH`;
+        if (requirement.version) {
+            const unsafe = requirement.version.args.find((arg) => !VERSION_ARG.test(arg));
+            if (unsafe !== undefined)
+                return `checks ${requirement.program}'s version with "${unsafe}": only options (--version, -v) or version`;
+            if (!VERSION.test(requirement.version.min))
+                return `wants ${requirement.program} ${requirement.version.min || "(no version)"}, which isn't a version like 24.0.0`;
+        }
+        const unknown = requirement.for.find((id) => !provides.includes(id));
+        if (unknown)
+            return `needs ${requirement.program} for ${unknown}, a capability it doesn't provide`;
+    }
+    return undefined;
+}
+/** Where a program is on the `PATH`, as a shell would find it (with `PATHEXT`'s extensions on Windows), or nothing. */
+export async function findOnPath(program, env = process.env) {
+    const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+    const extensions = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").map((extension) => extension.toLowerCase())] : [""];
+    for (const dir of dirs) {
+        for (const extension of extensions) {
+            const file = path.join(dir, `${program}${extension}`);
+            if (await stat(file).then((entry) => entry.isFile(), () => false))
+                return file;
+        }
+    }
+    return undefined;
+}
+/** Whether `version` is `min` or later, comparing x.y.z (missing parts are 0). */
+export function atLeast(version, min) {
+    const parts = (value) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const [a, b] = [parts(version), parts(min)];
+    for (let index = 0; index < 3; index++)
+        if ((a[index] ?? 0) !== (b[index] ?? 0))
+            return (a[index] ?? 0) > (b[index] ?? 0);
+    return true;
+}
+/**
+ * Checks one requirement: finds its program on the `PATH` and, when it says how, runs it with its
+ * version arguments only: no shell, nothing else on the command line, and stopped after
+ * `timeoutMs`. A Windows script (`.cmd`, `.bat`) can't run without a shell, and a program that
+ * says no version can't be compared: either counts as there.
+ */
+export async function checkRequirement(requirement, options = {}) {
+    const file = PROGRAM.test(requirement.program) ? await findOnPath(requirement.program, options.env) : undefined;
+    if (!file)
+        return { requirement, found: false, ok: false };
+    if (!requirement.version || /\.(cmd|bat)$/i.test(file))
+        return { requirement, found: true, ok: true };
+    const said = await new Promise((resolve) => {
+        execFile(file, requirement.version.args, { timeout: options.timeoutMs ?? 5000, windowsHide: true, shell: false, ...(options.env ? { env: options.env } : {}) }, (_error, stdout, stderr) => resolve(`${stdout ?? ""}\n${stderr ?? ""}`));
+    });
+    const version = said.match(/\d+\.\d+(?:\.\d+)?/)?.[0];
+    return { requirement, found: true, ...(version ? { version } : {}), ok: !version || atLeast(version, requirement.version.min) };
+}
+/** Checks an extension's requirements, all at once. */
+export function checkRequirements(requirements, options = {}) {
+    return Promise.all(requirements.map((requirement) => checkRequirement(requirement, options)));
+}
+/** How to install a requirement on this system: its command, else its link. */
+export function installHint(requirement, platform = process.platform) {
+    const system = platform === "win32" ? requirement.install.windows : platform === "darwin" ? requirement.install.macos : requirement.install.linux;
+    return system ?? requirement.install.url;
+}
+/** What's missing, as a reason reads ("Docker (docker 24.0.0 or later), which isn't on this computer: install it with …"). */
+export function describeMissing(check, platform = process.platform) {
+    const { requirement } = check;
+    const wanted = `${requirement.name} (${requirement.program}${requirement.version ? ` ${requirement.version.min} or later` : ""})`;
+    const state = check.found ? `, and this computer has ${check.version}` : ", which isn't on this computer";
+    const hint = installHint(requirement, platform);
+    const how = !hint ? "" : /^https?:\/\//.test(hint) ? `: see ${hint}` : `: install it with \`${hint}\``;
+    return `${wanted}${state}${how}`;
+}

package/dist/core/extensions.d.ts

@@ -1,10 +1,11 @@
 import type { HookCallbackMatcher, HookEvent, McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentSpec, BaseSessionConfig, Mode } from "./agentSpec.js";
+import { type Language } from "./language.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"`:
+ * 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 +58,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. */
@@ -84,27 +91,93 @@ export interface Extension {
     external?: boolean;
     /** An installed one's scope folder, where its lock is (its plugin is elsewhere when it's linked). */
     installedIn?: string;
+    /** What it can't do on this computer (#63): capabilities whose programs are missing, with why. They aren't provided, and their skills are left out. */
+    unavailable?: {
+        capabilities: string[];
+        reason: 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. */
     contribute(context: ExtensionContext): Promise<ExtensionContribution>;
 }
+/** How a capability reads to the person, in one language. */
+export interface CapabilityText {
+    label: string;
+    description: string;
+}
+/**
+ * Something the agent does well with an extension (#62): the skills that say how and the tools
+ * that do it, described for the person. Its `id` is what `requires` names, neutral (`lms-grading`,
+ * not `moodle-grading`), so an agent's skills depend on what can be done, not on which extension
+ * does it.
+ */
+export interface ExtensionCapability {
+    id: string;
+    /** Its skills, by their folder in the extension's `skills/`. */
+    skills: string[];
+    /** Its tools, by short name (of any of its servers). */
+    tools: string[];
+    /** Its label and description, by language. */
+    texts: Partial<Record<Language, CapabilityText>>;
+}
+/** A capability as a person reads it: its id, and its texts in their language. */
+export interface DescribedCapability extends CapabilityText {
+    id: string;
+}
+/** A manifest's `capabilities`: what has an id, with its lists and texts as far as they're well formed. */
+export declare function parseCapabilities(raw: unknown): ExtensionCapability[];
+/** A capability's texts in `language`: English when it has none there, then any it has, then its id. */
+export declare function describeCapability(capability: ExtensionCapability, language: Language): DescribedCapability;
+/**
+ * Why an extension's capabilities don't hold (an id twice, a skill it doesn't have), or nothing.
+ * Its tools can't be checked here: only a running server lists them, so `/extensions` says when
+ * one is missing.
+ */
+export declare function capabilitiesProblem(pluginRoot: string, capabilities: readonly ExtensionCapability[]): Promise<string | undefined>;
 /** An extension's manifest, as the kit reads it. */
 export interface ExtensionManifest {
     name: string;
     description: string;
-    /** Capabilities it lets the agent use. */
+    /** Capabilities it lets the agent use: its `provides`, and its `capabilities`' ids. */
     provides: string[];
     /** Capabilities it needs another enabled extension to provide. */
     requires: string[];
+    /** What it lets the agent do, described for the person (#62). */
+    capabilities: ExtensionCapability[];
 }
 /** Reads an extension's manifest from its plugin. */
 export declare function readExtensionManifest(pluginRoot: string): ExtensionManifest;
+/** An active extension as a view lists it: its capabilities in the session's language, with their tools by full name. */
+export interface AboutExtension {
+    description: string;
+    provides: string[];
+    capabilities: (DescribedCapability & {
+        tools: string[];
+    })[];
+    /** What it can't do on this computer, with why (#63). */
+    unavailable: (DescribedCapability & {
+        reason: string;
+    })[];
+    /** Its MCP servers, by name. */
+    servers: string[];
+}
+/** What a view says of an active extension: its capabilities' tools under each of its servers' names. */
+export declare function aboutExtension(manifest: ExtensionManifest, servers: readonly string[], language: Language, unavailable?: readonly UnavailableCapability[]): AboutExtension;
+/** What a manifest provides: its `provides` and its capabilities' ids, once each. */
+export declare function providedBy(provides: readonly string[] | undefined, capabilities: readonly ExtensionCapability[]): string[];
+/** A capability an active extension has but can't use on this computer, with why (#63). */
+export interface UnavailableCapability {
+    capability: ExtensionCapability;
+    reason: string;
+}
 /** The extensions a session runs with, and the ones it can't, with why. */
 export interface ResolvedExtensions {
+    /** Each with its manifest as the session sees it (without what's unavailable here) and what's unavailable. */
     active: {
         extension: Extension;
         manifest: ExtensionManifest;
+        unavailable: UnavailableCapability[];
     }[];
     inactive: {
         name: string;

package/dist/core/extensions.js

@@ -2,17 +2,76 @@ import { readFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { frontmatter } from "./pluginAgents.js";
+import { SUPPORTED_LANGUAGES } from "./language.js";
 /** The folder `option` names for this session's `config`, if any. */
 export function folderOf(option, config) {
     return typeof option === "function" ? option(config) : option;
 }
+/** A manifest's `capabilities`: what has an id, with its lists and texts as far as they're well formed. */
+export function parseCapabilities(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const names = (value) => (Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : []);
+    return raw.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const { id, skills, tools, texts } = item;
+        if (typeof id !== "string" || !id)
+            return [];
+        const byLanguage = Object.fromEntries(Object.entries(texts && typeof texts === "object" ? texts : {}).flatMap(([language, text]) => {
+            const { label, description } = (text ?? {});
+            return SUPPORTED_LANGUAGES.includes(language) && typeof label === "string" && label ? [[language, { label, description: typeof description === "string" ? description : "" }]] : [];
+        }));
+        return [{ id, skills: names(skills), tools: names(tools), texts: byLanguage }];
+    });
+}
+/** A capability's texts in `language`: English when it has none there, then any it has, then its id. */
+export function describeCapability(capability, language) {
+    const text = capability.texts[language] ?? capability.texts.en ?? Object.values(capability.texts)[0];
+    return { id: capability.id, label: text?.label ?? capability.id, description: text?.description ?? "" };
+}
+/**
+ * Why an extension's capabilities don't hold (an id twice, a skill it doesn't have), or nothing.
+ * Its tools can't be checked here: only a running server lists them, so `/extensions` says when
+ * one is missing.
+ */
+export async function capabilitiesProblem(pluginRoot, capabilities) {
+    const seen = new Set();
+    for (const capability of capabilities) {
+        if (seen.has(capability.id))
+            return `declares the capability ${capability.id} twice`;
+        seen.add(capability.id);
+        for (const skill of capability.skills) {
+            const found = await readFile(path.join(pluginRoot, "skills", skill, "SKILL.md"), "utf8").then(() => true, () => false);
+            if (!found)
+                return `names the skill ${skill} in its capability ${capability.id}, and has no skills/${skill}/SKILL.md`;
+        }
+    }
+    return undefined;
+}
 /** 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 ?? [] };
+    const kit = raw.metadata?.["agent-kit"];
+    const capabilities = parseCapabilities(kit?.capabilities);
+    return { name: raw.name, description: raw.description ?? "", provides: providedBy(kit?.provides, capabilities), requires: kit?.requires ?? [], capabilities };
+}
+/** What a view says of an active extension: its capabilities' tools under each of its servers' names. */
+export function aboutExtension(manifest, servers, language, unavailable = []) {
+    return {
+        description: manifest.description,
+        provides: manifest.provides,
+        capabilities: manifest.capabilities.map((capability) => ({ ...describeCapability(capability, language), tools: servers.flatMap((server) => capability.tools.map((tool) => `mcp__${server}__${tool}`)) })),
+        unavailable: unavailable.map(({ capability, reason }) => ({ ...describeCapability(capability, language), reason })),
+        servers: [...servers],
+    };
+}
+/** What a manifest provides: its `provides` and its capabilities' ids, once each. */
+export function providedBy(provides, capabilities) {
+    return [...new Set([...(provides ?? []), ...capabilities.map((capability) => capability.id)])];
 }
 /**
  * Which of the `extensions` run in this session, in the order given: those the session lacks
@@ -23,14 +82,18 @@ 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 read = readExtensionManifest(extension.plugin);
+        if (read.name !== extension.name)
+            throw new Error(`The extension "${extension.name}" has the plugin "${read.name}": they must have the same name.`);
+        // What it can't do here isn't provided: what requires it is left out, as for a missing extension.
+        const unavailable = (extension.unavailable ?? []).flatMap(({ capabilities, reason }) => capabilities.map((id) => ({ capability: read.capabilities.find((capability) => capability.id === id) ?? { id, skills: [], tools: [], texts: {} }, reason })));
+        const off = new Set(unavailable.map(({ capability }) => capability.id));
+        const manifest = off.size ? { ...read, provides: read.provides.filter((id) => !off.has(id)), capabilities: read.capabilities.filter((capability) => !off.has(capability.id)) } : read;
         const reason = extension.missing?.(context);
         if (reason)
             inactive.push({ name: extension.name, reason });
         else
-            active.push({ extension, manifest });
+            active.push({ extension, manifest, unavailable });
     }
     // Requirements: drop what can't be met, again and again, since dropping one may starve another.
     for (let changed = true; changed;) {
@@ -50,7 +113,16 @@ export function resolveExtensions(extensions, context) {
 }
 /** 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(", ")}.` : ""}`);
+    // A capability by its id and, when it has one, its English label (the model reads English, ADR-019).
+    const provided = (manifest) => manifest.provides.map((id) => {
+        const capability = manifest.capabilities.find((candidate) => candidate.id === id);
+        const label = capability ? describeCapability(capability, "en").label : id;
+        return label === id ? id : `${id} (${label})`;
+    });
+    const lines = resolved.active.map(({ manifest, unavailable }) => {
+        const cant = unavailable.map(({ capability, reason }) => `\n  - ${describeCapability(capability, "en").label} (${capability.id}) isn't available on this computer: it ${reason}. If the person asks for it, tell them what to install.`);
+        return `- **${manifest.name}**: ${manifest.description}${manifest.provides.length ? ` Provides: ${provided(manifest).join(", ")}.` : ""}${cant.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")}`;
 }