@falkenslab/agent-kit 0.22.0 → 0.24.0

package/README.md

@@ -1,8 +1,5 @@
 <h1>
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-readme-dark.svg">
-    <img src="docs/assets/logo-readme.svg" alt="agent-kit" height="64">
-  </picture>
+  <img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/logo-readme-any.svg" alt="agent-kit" height="64">
 </h1>
 
 [![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)

package/dist/chat/chatController.d.ts

@@ -273,6 +273,7 @@ export declare function createChatController(options: Options | SessionOpener, s
         confirmed?: boolean;
     }): Promise<{
         name?: string;
+        missing?: string[];
         confirm?: {
             marketplace: string;
             description?: string;

package/dist/chat/chatController.js

@@ -605,7 +605,10 @@ export async function createChatController(options, settings = {}) {
             const result = await installFromCatalog(current.extensions.dirs, spec, { ...official, ...(options.scope ? { scope: options.scope } : {}) });
             await refreshInstalled();
             notice(t().extensionInstalled(result.name));
-            return { name: result.name };
+            // What it needs and this computer lacks (#63): the person installs it, the kit never does.
+            for (const line of result.missing)
+                notice(t().extensionLacks(result.name, line));
+            return { name: result.name, missing: result.missing };
         },
         /** Updates one installed extension from its marketplace, or every one with a newer version there; the names updated. */
         async updateExtension(name) {

package/dist/chat/extensions.d.ts

@@ -3,6 +3,12 @@ import type { ExtensionsStatus } from "../core/session.js";
 import { type CatalogEntry } from "../core/extensionCatalog.js";
 /** One line for an installed extension: name and version, scope, on or off, its author, where it came from. */
 export declare function describe(extension: InstalledExtension): string;
+/**
+ * What the active extensions let the agent do (#62), in the session's language: a heading per
+ * extension with capabilities, a line per capability, and the tools a capability names that its
+ * server doesn't offer, once the session has started and knows them.
+ */
+export declare function describeCapabilities(status: ExtensionsStatus): string[];
 /** What the chat does for `/extensions install|update|remove|reload` (#56). */
 export type ExtensionAction = {
     type: "install";

package/dist/chat/extensions.js

@@ -12,10 +12,33 @@ export function describe(extension) {
     const author = extension.manifest?.author ? `  by ${extension.manifest.author.name}` : "";
     return `${extension.name}${version}  [${extension.scope}]  ${state}${author}  from ${source}`;
 }
+/**
+ * What the active extensions let the agent do (#62), in the session's language: a heading per
+ * extension with capabilities, a line per capability, and the tools a capability names that its
+ * server doesn't offer, once the session has started and knows them.
+ */
+export function describeCapabilities(status) {
+    const offered = new Set(status.sessionTools?.() ?? []);
+    return status.active.flatMap((name) => {
+        const capabilities = status.about[name]?.capabilities ?? [];
+        const unavailable = status.about[name]?.unavailable ?? [];
+        if (!capabilities.length && !unavailable.length)
+            return [];
+        return [
+            t().extensionCan(name),
+            ...capabilities.map(({ label, description, tools }) => {
+                const missing = offered.size ? [...new Set(tools.filter((tool) => !offered.has(tool)).map((tool) => tool.replace(/^mcp__.+?__/, "")))] : [];
+                return `  - ${label}${description ? `: ${description}` : ""}${missing.length ? ` ${t().capabilityToolsMissing(missing.join(", "))}` : ""}`;
+            }),
+            // What it can't do on this computer, with what to install (#63).
+            ...unavailable.map(({ label, reason }) => `  - ${t().capabilityUnavailable(label, reason)}`),
+        ];
+    });
+}
 /** One line for a catalog entry: what installs it, its version, whether it's installed or has an update, what it is. */
 export function describeEntry(entry) {
     const state = entry.installed ? (entry.update ? ` ${t().extensionUpdateAvailable(entry.installed.manifest?.version ?? "?")}` : ` ${t().extensionIsInstalled}`) : "";
-    return `${entry.spec}${entry.version ? ` ${entry.version}` : ""}${state}${entry.plugin.description ? `  ${entry.plugin.description}` : ""}`;
+    return `${entry.spec}${entry.version ? ` ${entry.version}` : ""}${state}${entry.description ? `  ${entry.description}` : ""}`;
 }
 /** An installed extension's options, one line each: its value, its default, or whether a sensitive one is set (never its value). */
 export async function describeOptions(extension) {
@@ -83,6 +106,8 @@ export async function chatExtensionsCommand(line, status, canReopen) {
     }
     if (!action) {
         const lines = [status?.active.length ? t().extensionsRunning(status.active.join(", ")) : t().extensionsNone];
+        if (status)
+            lines.push(...describeCapabilities(status));
         for (const { name: off, reason } of status?.inactive ?? [])
             lines.push(t().extensionOff(off, reason));
         if (status?.installed.length)

package/dist/core/extensionCatalog.d.ts

@@ -1,4 +1,5 @@
 import { type ExtensionDirs, type ExtensionScope, type InstalledExtension } from "./externalExtensions.js";
+import { type DescribedCapability } from "./extensions.js";
 import { type KnownMarketplace, type MarketplacePlugin } from "./marketplaces.js";
 /**
  * The agent's catalog of extensions (#56): what its known marketplaces offer, what's installed
@@ -21,6 +22,8 @@ export interface CatalogEntry {
     /** From the agent's own marketplace: installed without a confirmation. */
     official: boolean;
     plugin: MarketplacePlugin;
+    /** What it is, in the kit's language (#67): its own there, else the marketplace entry's, else its `plugin.json`'s, in English. */
+    description: string;
     /** The version it offers: its `plugin.json`'s when the marketplace has its folder, else the marketplace's entry's. */
     version?: string;
     /** Installed (and used: not shadowed), from wherever it came. */
@@ -32,6 +35,13 @@ export interface CatalogEntry {
     /** Its logo and banner (#59), as files of the marketplace's copy, when it has them. */
     logo?: string;
     banner?: string;
+    /** What it lets the agent do (#62), in the kit's language: from its `plugin.json` when the marketplace has its folder. */
+    capabilities: DescribedCapability[];
+    /** The programs it needs on the computer (#63), by name ("Docker"), with the capabilities that need them (none: all of it). */
+    requirements: {
+        name: string;
+        for: string[];
+    }[];
 }
 /** Whether `offered` is newer than `installed` (x.y.z); a version that can't be compared isn't. */
 export declare function isNewer(offered: string | undefined, installed: string | undefined): boolean;
@@ -61,6 +71,7 @@ export declare function installExtension(dirs: ExtensionDirs, spec: string, opti
     replaced: boolean;
     marketplace: string;
     commit?: string;
+    missing: string[];
 }>;
 /**
  * Updates an installed extension from the marketplace it came from: a fresh copy of the

package/dist/core/extensionCatalog.js

@@ -4,6 +4,8 @@ import path from "node:path";
 import { addExtension, codeStoreDir, hashExtension, inKitRange, installTarget, isGitSource, listInstalled, readExternalManifest, readLock, storedCodeDir } from "./externalExtensions.js";
 import { cachePackage, cachedPackageDir } from "./npxPackages.js";
 import { trustWorkspace } from "./workspaceTrust.js";
+import { describeCapability, describeInLanguage } from "./extensions.js";
+import { getLanguage } from "./messages/index.js";
 import { addMarketplace, findPlugin, installFromMarketplace, listMarketplaces, resolvePluginSource, updateMarketplace } from "./marketplaces.js";
 /**
  * The agent's catalog of extensions (#56): what its known marketplaces offer, what's installed
@@ -64,13 +66,16 @@ async function offered(marketplace, plugin) {
             };
             const [logo, banner] = [await image(manifest?.catalog?.logo), await image(manifest?.catalog?.banner)];
             const version = manifest?.version ?? plugin.version;
-            return { ...(version ? { version } : {}), keywords: manifest?.keywords ?? [], ...(logo ? { logo } : {}), ...(banner ? { banner } : {}) };
+            const capabilities = (manifest?.capabilities ?? []).map((capability) => describeCapability(capability, getLanguage()));
+            const requirements = (manifest?.requirements ?? []).map((requirement) => ({ name: requirement.name, for: requirement.for }));
+            const description = describeInLanguage(plugin.description ?? manifest?.description ?? "", manifest?.descriptions, getLanguage());
+            return { ...(version ? { version } : {}), keywords: manifest?.keywords ?? [], ...(logo ? { logo } : {}), ...(banner ? { banner } : {}), capabilities, requirements, description };
         }
     }
     catch {
         // A source the kit doesn't install: the entry's own fields.
     }
-    return { ...(plugin.version ? { version: plugin.version } : {}), keywords: [] };
+    return { ...(plugin.version ? { version: plugin.version } : {}), keywords: [], capabilities: [], requirements: [], description: plugin.description ?? "" };
 }
 /** Whether `offered` is newer than `installed` (x.y.z); a version that can't be compared isn't. */
 export function isNewer(offered, installed) {
@@ -91,7 +96,8 @@ export async function extensionCatalog(dirs, options = {}) {
             const topics = [...new Set([...look.keywords, ...(plugin.tags ?? []), ...(plugin.keywords ?? []), ...(plugin.category ? [plugin.category] : [])].map((topic) => topic.toLowerCase()))];
             if (wanted && !topics.some((topic) => wanted.has(topic)))
                 continue;
-            const text = [plugin.name, plugin.description, ...topics].join(" ").toLowerCase();
+            // Its capabilities count too: a search for "grading" finds what grades.
+            const text = [plugin.name, plugin.description, look.description, ...topics, ...look.capabilities.flatMap(({ id, label, description }) => [id, label, description])].join(" ").toLowerCase();
             if (!words.every((word) => text.includes(word)))
                 continue;
             const version = look.version;
@@ -99,6 +105,7 @@ export async function extensionCatalog(dirs, options = {}) {
             const fromHere = mine?.lock.marketplace === `${plugin.name}@${marketplace.name}`;
             entries.push({
                 spec: `${plugin.name}@${marketplace.name}`,
+                description: look.description,
                 marketplace: marketplace.name,
                 official: marketplace.official,
                 plugin,
@@ -108,6 +115,8 @@ export async function extensionCatalog(dirs, options = {}) {
                 topics,
                 ...(look.logo ? { logo: look.logo } : {}),
                 ...(look.banner ? { banner: look.banner } : {}),
+                capabilities: look.capabilities,
+                requirements: look.requirements,
             });
         }
     }

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,5 +1,6 @@
 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";
 /**
@@ -90,27 +91,100 @@ 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>;
+/**
+ * A manifest's `metadata["agent-kit"].description` (#67): its description in other languages than
+ * English, which stays the top-level `description` Claude Code reads. Only languages the kit speaks.
+ */
+export declare function parseDescriptions(raw: unknown): Partial<Record<Language, string>>;
+/** An extension's description in `language`: its own there, else the English one. */
+export declare function describeInLanguage(english: string, descriptions: Partial<Record<Language, string>> | undefined, language: Language): string;
 /** 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,10 +2,66 @@ 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;
+}
+/**
+ * A manifest's `metadata["agent-kit"].description` (#67): its description in other languages than
+ * English, which stays the top-level `description` Claude Code reads. Only languages the kit speaks.
+ */
+export function parseDescriptions(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    return Object.fromEntries(Object.entries(raw).filter(([language, text]) => SUPPORTED_LANGUAGES.includes(language) && typeof text === "string" && text.length > 0));
+}
+/** An extension's description in `language`: its own there, else the English one. */
+export function describeInLanguage(english, descriptions, language) {
+    return descriptions?.[language] ?? english;
+}
 /** Reads an extension's manifest from its plugin. */
 export function readExtensionManifest(pluginRoot) {
     const file = path.join(pluginRoot, ".claude-plugin", "plugin.json");
@@ -13,7 +69,22 @@ export function readExtensionManifest(pluginRoot) {
     if (!raw.name)
         throw new Error(`${file} has no "name".`);
     const kit = raw.metadata?.["agent-kit"];
-    return { name: raw.name, description: raw.description ?? "", provides: kit?.provides ?? [], requires: kit?.requires ?? [] };
+    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
@@ -24,14 +95,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;) {
@@ -51,7 +126,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")}`;
 }