@falkenslab/agent-kit 0.22.0 → 0.24.0

package/dist/core/externalExtensions.d.ts

@@ -1,7 +1,8 @@
-import type { Extension } from "./extensions.js";
+import { type Extension, type ExtensionCapability } from "./extensions.js";
 import type { Language } from "./language.js";
 import { type ToolPhrase } from "./messages/index.js";
 import { type ExtensionOption, type OptionValue } from "./extensionOptions.js";
+import { checkRequirements, type ExtensionRequirement } from "./extensionRequirements.js";
 import { type CachedPackage } from "./npxPackages.js";
 /**
  * External extensions (ADR-025, #37): installed into an agent, for all its projects (the
@@ -48,19 +49,28 @@ export interface ExtensionAuthor {
  */
 export interface ExternalManifest {
     name: string;
+    /** Its description in English: `plugin.json`'s, which Claude Code reads. */
     description: string;
+    /** Its description in other languages (#67), from `metadata["agent-kit"].description`. */
+    descriptions: Partial<Record<Language, string>>;
     version?: string;
     author?: ExtensionAuthor;
     homepage?: string;
     repository?: string;
     license?: string;
     keywords?: string[];
+    /** What it lets the agent use: its `provides` and its capabilities' ids. */
     provides: string[];
     requires: string[];
+    /** What it lets the agent do, described for the person (#62): skills and tools together. */
+    capabilities: ExtensionCapability[];
     /** The agent-kit versions it works with, e.g. `">=0.19.0 <0.21.0"`. */
     kit?: string;
-    /** Programs it needs on this computer, found on the `PATH` (`"docker"`, `"python3"`): without one it's off, saying which. */
-    needs: string[];
+    /**
+     * Programs it needs on this computer (#63): checked when it loads, never installed. Without one
+     * the whole extension needs, it's off; without one only some capabilities need, those are.
+     */
+    requirements: ExtensionRequirement[];
     /** Its MCP servers, by name (`mcp__<name>__<tool>`), from the plugin's `.mcp.json` or `plugin.json`. */
     servers: Record<string, PluginServer>;
     /**
@@ -188,6 +198,13 @@ export declare function loadExternalExtensions(dirs: ExtensionDirs): Promise<{
 /** Why an installed extension can't load, or its manifest when it can. */
 /** Whether a program is on the `PATH`, as a shell would find it (with `PATHEXT`'s extensions on Windows). */
 export declare function onPath(program: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** A requirement this computer lacks, as the person reads it: what it is, what for, and how to install it. */
+export declare function missingRequirement(check: Awaited<ReturnType<typeof checkRequirements>>[number]): string;
+/** What an installed extension can't do on this computer, and why: its capabilities whose requirements are missing (#63). */
+export interface UnavailableCapabilities {
+    capabilities: string[];
+    reason: string;
+}
 /** Whether `source` names a git repository rather than a folder. */
 export declare function isGitSource(source: string): boolean;
 /**
@@ -212,6 +229,7 @@ export declare function addExtension(source: string, scopeDir: string, options?:
     name: string;
     replaced: boolean;
     commit?: string;
+    missing: string[];
 }>;
 /**
  * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left

package/dist/core/externalExtensions.js

@@ -5,12 +5,14 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { capabilitiesProblem, parseCapabilities, parseDescriptions, providedBy } from "./extensions.js";
 import { getLanguage } from "./messages/index.js";
 import { truncate } from "./toolLabels.js";
 import { agentKitVersion } from "./version.js";
 import { outsideArchive } from "./packaged.js";
 import { extensionSecretsPath, missingOptions, optionsNamed, parseOptionValue, parseUserConfig, readOptionValues, removeSecrets, storeOptionValues } from "./extensionOptions.js";
 import { isTrusted } from "./workspaceTrust.js";
+import { checkRequirements, describeMissing, findOnPath, parseRequirements, requirementsProblem } from "./extensionRequirements.js";
 import { cachedPackageDir, cachedPackageProblem, cachePackage, npxServer, packageCacheDir, packageSpec } from "./npxPackages.js";
 export const LOCK_FILE = "extensions.lock.json";
 /**
@@ -91,9 +93,11 @@ export async function readExternalManifest(dir) {
     const author = raw.author;
     // `repository` may be a URL or `{ url }`, as in package.json.
     const repository = typeof raw.repository === "string" ? raw.repository : raw.repository?.url;
+    const capabilities = parseCapabilities(kit.capabilities);
     return {
         name,
         description: typeof raw.description === "string" ? raw.description : "",
+        descriptions: parseDescriptions(kit.description),
         ...text("version"),
         ...(author && typeof author === "object" && typeof author.name === "string"
             ? { author: { name: author.name, ...(author.email ? { email: author.email } : {}), ...(author.url ? { url: author.url } : {}) } }
@@ -102,10 +106,11 @@ export async function readExternalManifest(dir) {
         ...(typeof repository === "string" ? { repository } : {}),
         ...text("license"),
         ...(Array.isArray(raw.keywords) ? { keywords: raw.keywords.filter((keyword) => typeof keyword === "string") } : {}),
-        provides: kit.provides ?? [],
+        provides: providedBy(kit.provides, capabilities),
         requires: kit.requires ?? [],
+        capabilities,
         ...(kit.kit ? { kit: kit.kit } : {}),
-        needs: Array.isArray(kit.needs) ? kit.needs.filter((program) => typeof program === "string") : [],
+        requirements: parseRequirements(kit.requirements),
         servers: await pluginServers(dir, raw),
         ...(Array.isArray(kit.readOnlyTools) ? { readOnlyTools: kit.readOnlyTools.filter((tool) => typeof tool === "string") } : {}),
         labels: kit.labels ?? {},
@@ -320,12 +325,13 @@ function manifestToolLabels(manifest) {
     }));
 }
 /** The extension an installed one makes: its servers started through the launcher, its rules from its manifest. */
-function externalExtension(installed, manifest, cache) {
+function externalExtension(installed, manifest, cache, unavailable = []) {
     return {
         name: manifest.name,
         plugin: installed.dir,
         external: true,
         installedIn: installed.scopeDir,
+        ...(unavailable.length ? { unavailable } : {}),
         async contribute() {
             const servers = {};
             if (Object.keys(manifest.servers).length)
@@ -395,23 +401,19 @@ export async function loadExternalExtensions(dirs) {
         if (typeof reason === "string")
             off.push({ name: installed.name, reason });
         else
-            extensions.push(externalExtension(installed, reason, cache));
+            extensions.push(externalExtension(installed, reason.manifest, cache, reason.unavailable));
     }
     return { extensions, off, untrusted };
 }
 /** 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 async function onPath(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 found = await stat(path.join(dir, `${program}${extension}`)).then((entry) => entry.isFile(), () => false);
-            if (found)
-                return true;
-        }
-    }
-    return false;
+    return (await findOnPath(program, env)) !== undefined;
+}
+/** A requirement this computer lacks, as the person reads it: what it is, what for, and how to install it. */
+export function missingRequirement(check) {
+    const needed = check.requirement.for.length ? ` for ${check.requirement.for.join(", ")}` : "";
+    return `needs ${describeMissing(check)}${needed}`;
 }
 async function problem(installed, cache) {
     let manifest;
@@ -429,16 +431,22 @@ async function problem(installed, cache) {
         return `is installed as "${installed.name}" but its manifest says "${manifest.name}"`;
     if (manifest.kit && !inKitRange(agentKitVersion(), manifest.kit))
         return `works with agent-kit ${manifest.kit}, and this agent runs ${agentKitVersion()}`;
-    const missing = [];
-    for (const program of manifest.needs)
-        if (!(await onPath(program)))
-            missing.push(program);
-    if (missing.length)
-        return `needs ${missing.join(", ")}, which ${missing.length === 1 ? "isn't" : "aren't"} on this computer (on the PATH)`;
+    const requirements = requirementsProblem(manifest.requirements, manifest.provides);
+    if (requirements)
+        return requirements;
+    // A program the whole extension needs keeps it off; one only some capabilities need, those (#63).
+    const checks = (await checkRequirements(manifest.requirements)).filter((check) => !check.ok);
+    const whole = checks.filter((check) => !check.requirement.for.length);
+    if (whole.length)
+        return whole.map((check) => missingRequirement(check)).join("; ");
+    const unavailable = checks.map((check) => ({ capabilities: check.requirement.for, reason: `needs ${describeMissing(check)}` }));
+    const capabilities = await capabilitiesProblem(installed.dir, manifest.capabilities);
+    if (capabilities)
+        return capabilities;
     const options = optionsProblem(manifest, await readOptionValues(installed.privateDir, installed.name, manifest.userConfig, installed.lock.options));
     if (options)
         return options;
-    return (await serversProblem(manifest, installed.dir, { cache, locked: installed.lock.packages })) ?? manifest;
+    return (await serversProblem(manifest, installed.dir, { cache, locked: installed.lock.packages })) ?? { manifest, unavailable };
 }
 const exec = promisify(execFile);
 /** Whether `source` names a git repository rather than a folder. */
@@ -477,9 +485,11 @@ export async function addExtension(source, scopeDir, options = {}) {
         if (options.subdir)
             from = path.join(from, options.subdir);
         const manifest = await readExternalManifest(from);
-        const servers = await serversProblem(manifest, from);
+        const servers = (await serversProblem(manifest, from)) ?? (await capabilitiesProblem(from, manifest.capabilities)) ?? requirementsProblem(manifest.requirements, manifest.provides);
         if (servers)
             throw new Error(`${manifest.name} can't be installed: it ${servers}.`);
+        // What it needs and this computer lacks: said, never installed, and it installs anyway (#63).
+        const missing = (await checkRequirements(manifest.requirements)).filter((check) => !check.ok).map((check) => missingRequirement(check));
         const target = path.join(scopeDir, manifest.name);
         // Replacing what's installed there would delete the source itself.
         if (path.resolve(from) === path.resolve(target))
@@ -506,12 +516,12 @@ export async function addExtension(source, scopeDir, options = {}) {
             }
             lock[manifest.name] = { source: origin, ...provenance, sha256, stored: true, ...locked, enabled: true, installed: new Date().toISOString() };
             await writeLock(scopeDir, lock);
-            return { name: manifest.name, replaced, ...(commit ? { commit } : {}) };
+            return { name: manifest.name, replaced, missing, ...(commit ? { commit } : {}) };
         }
         if (options.link) {
             lock[manifest.name] = { source: from, linked: true, sha256: "", ...locked, enabled: true, installed: new Date().toISOString() };
             await writeLock(scopeDir, lock);
-            return { name: manifest.name, replaced };
+            return { name: manifest.name, replaced, missing };
         }
         await cp(from, target, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
         lock[manifest.name] = {
@@ -523,7 +533,7 @@ export async function addExtension(source, scopeDir, options = {}) {
             installed: new Date().toISOString(),
         };
         await writeLock(scopeDir, lock);
-        return { name: manifest.name, replaced, ...(commit ? { commit } : {}) };
+        return { name: manifest.name, replaced, missing, ...(commit ? { commit } : {}) };
     }
     finally {
         if (clone)

package/dist/core/liveExtensions.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionsStatus } from "./session.js";
+import { type ExtensionCapability, type UnavailableCapability } from "./extensions.js";
 import type { SessionLive, StaticSessionFacts } from "./sessionFacts.js";
 import type { ToolLabels } from "./toolLabels.js";
 /**
@@ -43,6 +44,9 @@ export interface LiveExtension {
     agents: string[];
     description: string;
     provides: string[];
+    capabilities: ExtensionCapability[];
+    /** What it can't do on this computer (#63). */
+    unavailable: UnavailableCapability[];
     help: string[];
 }
 /** The session's own lists the switch keeps in step: the same objects the gates, the chat and the view read. */

package/dist/core/liveExtensions.js

@@ -1,5 +1,6 @@
 import { cp, lstat, mkdir, readdir, rm, symlink, unlink } from "node:fs/promises";
 import path from "node:path";
+import { aboutExtension, describeCapability } from "./extensions.js";
 import { hashExtension, listInstalled, readLock } from "./externalExtensions.js";
 import { cachedPackagesIntact, packageCacheDir } from "./npxPackages.js";
 /**
@@ -122,9 +123,17 @@ function follow(extension, enabled, targets) {
         targets.allowedSubagentTypes.push(...extension.agents);
         Object.assign(targets.toolLabels, extension.toolLabels);
         status.active.push(extension.name);
-        status.about[extension.name] = { description: extension.description, provides: extension.provides };
+        status.about[extension.name] = aboutExtension({ name: extension.name, description: extension.description, provides: extension.provides, requires: [], capabilities: extension.capabilities }, extension.servers, facts.language, extension.unavailable);
         status.inactive = status.inactive.filter((entry) => entry.name !== extension.name);
-        facts.extensions.active.push({ name: extension.name, description: extension.description, provides: extension.provides, servers: extension.servers, help: extension.help });
+        facts.extensions.active.push({
+            name: extension.name,
+            description: extension.description,
+            provides: extension.provides,
+            capabilities: extension.capabilities.map((capability) => describeCapability(capability, "en")),
+            unavailable: extension.unavailable.map(({ capability, reason }) => ({ ...describeCapability(capability, "en"), reason })),
+            servers: extension.servers,
+            help: extension.help,
+        });
         facts.extensions.inactive = facts.extensions.inactive.filter((entry) => entry.name !== extension.name);
     }
     else {

package/dist/core/marketplaces.d.ts

@@ -119,4 +119,5 @@ export declare function installFromMarketplace(dir: string, spec: string, scopeD
     replaced: boolean;
     commit?: string;
     marketplace: string;
+    missing: string[];
 }>;

package/dist/core/messages/de.js

@@ -28,6 +28,9 @@ export const de = {
     extensionsRunning: (names) => `Aktiv: ${names}`,
     extensionsNone: "(keine Erweiterungen)",
     extensionOff: (name, reason) => `${name} ist aus: ${reason}`,
+    extensionCan: (name) => `Was dein Agent mit ${name} kann:`,
+    capabilityToolsMissing: (tools) => `(sein Server bietet ${tools} nicht an)`,
+    capabilityUnavailable: (label, reason) => `${label}: auf diesem Computer nicht verfügbar: ${reason}`,
     extensionsInstalled: "Installiert:",
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}, in derselben Sitzung)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}: die Sitzung wird mit derselben Unterhaltung neu geöffnet)`,
@@ -47,6 +50,7 @@ export const de = {
     extensionsNoMatch: "(keine Erweiterung passt: /extensions search mit anderen Wörtern, oder ohne, um alle zu sehen)",
     extensionIsInstalled: "(installiert)",
     extensionUpdateAvailable: (installed) => `(installiert: ${installed}, Update verfügbar)`,
+    extensionLacks: (name, what) => `(${name}: ${what})`,
     extensionInstalled: (name) => `(${name} installiert: in einem neuen Gespräch da, oder sofort mit /extensions reload, ohne dieses zu verlieren)`,
     extensionUpdated: (name, from, to) => `(${name} aktualisiert, ${from} → ${to}: in einem neuen Gespräch da, oder sofort mit /extensions reload)`,
     extensionsUpToDate: "(alle Erweiterungen aus einem Marketplace sind aktuell)",

package/dist/core/messages/en.d.ts

@@ -37,6 +37,12 @@ export interface Messages {
     extensionsRunning(names: string): string;
     extensionsNone: string;
     extensionOff(name: string, reason: string): string;
+    /** Before an active extension's capabilities (#62), one per line after it. */
+    extensionCan(name: string): string;
+    /** A capability's tools its server doesn't offer in this session. */
+    capabilityToolsMissing(tools: string): string;
+    /** A capability that isn't available on this computer (#63), with why (in English, as every reason). */
+    capabilityUnavailable(label: string, reason: string): string;
     extensionsInstalled: string;
     /** An installed extension turned off or on in the running session (#49). */
     extensionSwitched(name: string, enabled: boolean): string;
@@ -60,6 +66,8 @@ export interface Messages {
     extensionIsInstalled: string;
     extensionUpdateAvailable(installed: string): string;
     extensionInstalled(name: string): string;
+    /** After installing: a program it needs that this computer lacks (#63); `what` is the reason, in English. */
+    extensionLacks(name: string, what: string): string;
     extensionUpdated(name: string, from: string, to: string): string;
     extensionsUpToDate: string;
     extensionRemoved(name: string, withData: boolean): string;

package/dist/core/messages/en.js

@@ -27,6 +27,9 @@ export const en = {
     extensionsRunning: (names) => `Running with: ${names}`,
     extensionsNone: "(no extensions)",
     extensionOff: (name, reason) => `${name} is off: it ${reason}`,
+    extensionCan: (name) => `What ${name} lets your agent do:`,
+    capabilityToolsMissing: (tools) => `(its server doesn't offer ${tools})`,
+    capabilityUnavailable: (label, reason) => `${label}: not on this computer, it ${reason}`,
     extensionsInstalled: "Installed:",
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}, in this same session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}: the session reopens, with the same conversation)`,
@@ -47,6 +50,7 @@ export const en = {
     extensionIsInstalled: "(installed)",
     extensionUpdateAvailable: (installed) => `(installed: ${installed}, update available)`,
     extensionInstalled: (name) => `(${name} installed: it's there in a new conversation, or now with /extensions reload, keeping this one)`,
+    extensionLacks: (name, what) => `(${name} ${what})`,
     extensionUpdated: (name, from, to) => `(${name} updated, ${from} → ${to}: it's there in a new conversation, or now with /extensions reload)`,
     extensionsUpToDate: "(every extension from a marketplace is up to date)",
     extensionRemoved: (name, withData) => `(${name} removed${withData ? ", with its data" : "; its data is kept for a reinstall"})`,

package/dist/core/messages/es.js

@@ -28,6 +28,9 @@ export const es = {
     extensionsRunning: (names) => `Funcionando con: ${names}`,
     extensionsNone: "(ninguna extensión)",
     extensionOff: (name, reason) => `${name} está desactivada: ${reason}`,
+    extensionCan: (name) => `Lo que tu agente puede hacer con ${name}:`,
+    capabilityToolsMissing: (tools) => `(su servidor no ofrece ${tools})`,
+    capabilityUnavailable: (label, reason) => `${label}: no disponible en este ordenador: ${reason}`,
     extensionsInstalled: "Instaladas:",
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}, en esta misma sesión)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}: la sesión se reabre, con la misma conversación)`,
@@ -47,6 +50,7 @@ export const es = {
     extensionsNoMatch: "(ninguna extensión coincide: /extensions search con otras palabras, o sin ninguna para verlas todas)",
     extensionIsInstalled: "(instalada)",
     extensionUpdateAvailable: (installed) => `(instalada: ${installed}, hay actualización)`,
+    extensionLacks: (name, what) => `(${name}: ${what})`,
     extensionInstalled: (name) => `(${name} instalada: está en una conversación nueva, o ya con /extensions reload, sin perder esta)`,
     extensionUpdated: (name, from, to) => `(${name} actualizada, ${from} → ${to}: está en una conversación nueva, o ya con /extensions reload)`,
     extensionsUpToDate: "(todas las extensiones de un marketplace están al día)",

package/dist/core/messages/fr.js

@@ -28,6 +28,9 @@ export const fr = {
     extensionsRunning: (names) => `En service : ${names}`,
     extensionsNone: "(aucune extension)",
     extensionOff: (name, reason) => `${name} est désactivée : ${reason}`,
+    extensionCan: (name) => `Ce que votre agent peut faire avec ${name} :`,
+    capabilityToolsMissing: (tools) => `(son serveur ne propose pas ${tools})`,
+    capabilityUnavailable: (label, reason) => `${label} : indisponible sur cet ordinateur : ${reason}`,
     extensionsInstalled: "Installées :",
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"}, dans cette même session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"} : la session se rouvre, avec la même conversation)`,
@@ -47,6 +50,7 @@ export const fr = {
     extensionsNoMatch: "(aucune extension ne correspond : /extensions search avec d'autres mots, ou sans pour toutes les voir)",
     extensionIsInstalled: "(installée)",
     extensionUpdateAvailable: (installed) => `(installée : ${installed}, mise à jour disponible)`,
+    extensionLacks: (name, what) => `(${name} : ${what})`,
     extensionInstalled: (name) => `(${name} installée : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload, en gardant celle-ci)`,
     extensionUpdated: (name, from, to) => `(${name} mise à jour, ${from} → ${to} : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload)`,
     extensionsUpToDate: "(toutes les extensions d'un marketplace sont à jour)",

package/dist/core/session.d.ts

@@ -1,6 +1,7 @@
 import type { Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import { type TranscriptLogger } from "./hooks/transcriptLogger.js";
 import { type ModeControl } from "./modeControl.js";
+import { type AboutExtension } from "./extensions.js";
 import { type ExtensionDirs, type InstalledExtension } from "./externalExtensions.js";
 import type { ToolLabels } from "./toolLabels.js";
 import type { AgentSpec, BaseSessionConfig } from "./agentSpec.js";
@@ -65,14 +66,13 @@ export interface ExtensionsStatus {
     /** The names of the extensions this session runs with, the kit's and the agent's too. */
     active: string[];
     /** What each active one is, from its manifest: for a view that lists them. */
-    about: Record<string, {
-        description: string;
-        provides: string[];
-    }>;
+    about: Record<string, AboutExtension>;
     inactive: {
         name: string;
         reason: string;
     }[];
+    /** The running session's tools, as the model names them (empty until it has started): what a capability's tools are checked against. */
+    sessionTools?: () => readonly string[];
 }
 /**
  * The CLI's folder for a project, where it keeps each session's transcript and large tool

package/dist/core/session.js

@@ -13,7 +13,7 @@ import { createManualLoginServer } from "./tools/manualLogin.js";
 import { createTimeServer } from "./tools/time.js";
 import { TODO_TOOL } from "./todos.js";
 import { createModeControl } from "./modeControl.js";
-import { extensionsPromptSection, resolveExtensions, skillsMissingCapabilities } from "./extensions.js";
+import { aboutExtension, describeCapability, extensionsPromptSection, resolveExtensions, skillsMissingCapabilities } from "./extensions.js";
 import { allowAnyMcpTool } from "./mcpPermissions.js";
 import { pluginAgents } from "./pluginAgents.js";
 import { outsideArchive, unpackedClaudeExecutable } from "./packaged.js";
@@ -130,7 +130,11 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     // `requires` a capability no active extension provides is left out; since the SDK's
     // `skillOverrides` doesn't reach plugin skills (confirmed empirically), leaving one out takes
     // a list: the plugins' skills and the project's, without it.
-    const missingCapabilities = await skillsMissingCapabilities(pluginRoots, resolved.capabilities);
+    // And the skills of a capability that isn't available on this computer (#63).
+    const missingCapabilities = [
+        ...(await skillsMissingCapabilities(pluginRoots, resolved.capabilities)),
+        ...resolved.active.flatMap(({ manifest, unavailable }) => unavailable.flatMap(({ capability }) => capability.skills.map((skill) => `${manifest.name}:${skill}`))),
+    ];
     const requested = spec.skills === "plugins" ? await pluginSkills(pluginRoots) : spec.skills;
     const offeredSkills = missingCapabilities.length && (requested === undefined || requested === "all")
         ? [...(await pluginSkills(pluginRoots)), ...((spec.settingSources ?? ["project"]).includes("project") ? await projectSkills(config.projectDir) : [])]
@@ -352,7 +356,8 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         untrusted: external.untrusted.map((installed) => ({ name: installed.name, ...(installed.manifest?.version ? { version: installed.manifest.version } : {}), source: installed.lock.marketplace ?? installed.lock.source })),
         installed: await listInstalled(extensionDirs),
         active: resolved.active.map(({ extension }) => extension.name),
-        about: Object.fromEntries(resolved.active.map(({ extension, manifest }) => [extension.name, { description: manifest.description, provides: manifest.provides }])),
+        about: Object.fromEntries(resolved.active.map(({ extension, manifest, unavailable }, index) => [extension.name, aboutExtension(manifest, Object.keys(added[index]?.mcpServers ?? {}), language, unavailable)])),
+        sessionTools: () => late.view?.controls().tools ?? [],
         inactive: resolved.inactive,
     };
     // What the session is, for the extensions that ask (sessionFacts.ts, #43).
@@ -361,10 +366,12 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         kitVersion: agentKitVersion(),
         language,
         extensions: {
-            active: resolved.active.map(({ extension, manifest }, index) => ({
+            active: resolved.active.map(({ extension, manifest, unavailable }, index) => ({
                 name: extension.name,
                 description: manifest.description,
                 provides: manifest.provides,
+                capabilities: manifest.capabilities.map((capability) => describeCapability(capability, "en")),
+                unavailable: unavailable.map(({ capability, reason }) => ({ ...describeCapability(capability, "en"), reason })),
                 servers: Object.keys(added[index]?.mcpServers ?? {}),
                 help: added[index]?.helpLines ?? [],
             })),
@@ -379,7 +386,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     registerSessionView(sdkOptions, late.view);
     // Turning an installed extension off and on while the session runs (#49), and restarting its
     // servers when its options change (#55).
-    const liveExtensions = resolved.active.flatMap(({ extension, manifest }, index) => {
+    const liveExtensions = resolved.active.flatMap(({ extension, manifest, unavailable }, index) => {
         const installed = installedDirs.get(extension.name);
         if (!installed)
             return [];
@@ -396,6 +403,8 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 agents: Object.keys(fromPlugins).filter((agent) => agent.startsWith(`${extension.name}:`)),
                 description: manifest.description,
                 provides: manifest.provides,
+                capabilities: manifest.capabilities,
+                unavailable,
                 help: contribution?.helpLines ?? [],
             },
         ];

package/dist/core/sessionFacts.d.ts

@@ -1,5 +1,6 @@
 import type { McpServerStatus, Options, SlashCommand } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentIdentity, Mode } from "./agentSpec.js";
+import type { DescribedCapability } from "./extensions.js";
 import type { Language } from "./language.js";
 import type { ModeControl } from "./modeControl.js";
 import type { ContextUsage } from "./runner.js";
@@ -20,10 +21,15 @@ export interface SessionFacts {
     switchableModes: Mode[];
     /** The extensions running (with their tools and what they say about themselves here), and the ones off, with why. */
     extensions: {
+        /** Each with its capabilities (#62), in English: what the model reads. */
         active: {
             name: string;
             description: string;
             provides: string[];
+            capabilities: DescribedCapability[];
+            unavailable: (DescribedCapability & {
+                reason: string;
+            })[];
             tools: string[];
             help: string[];
         }[];

package/dist/extensions/awareness/tools.js

@@ -17,9 +17,13 @@ export function describeSession(facts) {
     const sections = [`# You, right now\n\nYou are ${who}, on agent-kit ${facts.kitVersion}.`];
     const others = facts.switchableModes.filter((mode) => mode !== facts.mode);
     sections.push(`## Mode\n\nYou are in **${facts.mode}** mode now. ${facts.switchableModes.length > 1 ? `The person can switch it with Shift+Tab to ${others.join(" or ")}.` : "It can't be switched in this session."}`);
-    const active = facts.extensions.active.map(({ name, description, tools, help }) => {
+    const active = facts.extensions.active.map(({ name, description, capabilities, unavailable, tools, help }) => {
         const toolList = tools.length ? ` Tools: ${tools.map(short).join(", ")}.` : "";
-        return `- **${name}**: ${description}${toolList}${help.map((line) => `\n  ${line}`).join("")}`;
+        // What it lets you do, as the person reads it in /extensions (#62).
+        const can = capabilities.map(({ id, label, description: what }) => `\n  - Can: ${label} (${id})${what ? `: ${what}` : ""}`).join("");
+        // What it can't do on this computer, and what to install (#63).
+        const cant = unavailable.map(({ id, label, reason }) => `\n  - Can't here: ${label} (${id}): it ${reason}.`).join("");
+        return `- **${name}**: ${description}${toolList}${can}${cant}${help.map((line) => `\n  ${line}`).join("")}`;
     });
     const inactive = facts.extensions.inactive.map(({ name, reason }) => `- **${name}** is off: it ${reason}.`);
     sections.push(`## Extensions\n\n${[...active, ...inactive].join("\n") || "None."}`);

package/dist/index.d.ts

@@ -15,7 +15,8 @@ export { awareness, type AwarenessOptions } from "./extensions/awareness/index.j
 export { sources, type SourcesOptions } from "./extensions/sources/index.js";
 export { knowledge, type KnowledgeOptions } from "./extensions/knowledge/index.js";
 export { memory, type MemoryOptions } from "./extensions/memory/index.js";
-export { readExtensionManifest, type Extension, type ExtensionContext, type ExtensionContribution, type ExtensionManifest, type FolderOption, } from "./core/extensions.js";
+export { describeCapability, readExtensionManifest, type AboutExtension, type CapabilityText, type DescribedCapability, type Extension, type ExtensionCapability, type ExtensionContext, type ExtensionContribution, type ExtensionManifest, type FolderOption, type UnavailableCapability, } from "./core/extensions.js";
+export { checkRequirements, type ExtensionRequirement, type RequirementCheck } from "./core/extensionRequirements.js";
 export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type InstalledExtension, type LockEntry, type ExtensionOptionState, } from "./core/externalExtensions.js";
 export type { ExtensionOption, OptionValue } from "./core/extensionOptions.js";
 export type { ExtensionRestart, ExtensionSwitch } from "./core/liveExtensions.js";

package/dist/index.js

@@ -15,7 +15,8 @@ export { awareness } from "./extensions/awareness/index.js";
 export { sources } from "./extensions/sources/index.js";
 export { knowledge } from "./extensions/knowledge/index.js";
 export { memory } from "./extensions/memory/index.js";
-export { readExtensionManifest, } from "./core/extensions.js";
+export { describeCapability, readExtensionManifest, } from "./core/extensions.js";
+export { checkRequirements } from "./core/extensionRequirements.js";
 export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, } from "./core/externalExtensions.js";
 export { packageCacheDir } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, } from "./core/marketplaces.js";

package/dist/tui/extensionCommand.js

@@ -6,6 +6,8 @@ import { addExtension, extensionOptionStates, installTarget, folderSize, isGitSo
 import { describe, describeOptions } from "../chat/extensions.js";
 import { extensionCatalog, knownMarketplaces as catalogMarketplaces, restoreExtensions, updateExtension } from "../core/extensionCatalog.js";
 import { trustWorkspace } from "../core/workspaceTrust.js";
+import { describeCapability, describeInLanguage } from "../core/extensions.js";
+import { getLanguage } from "../core/messages/index.js";
 export { chatExtensionsCommand, describe } from "../chat/extensions.js";
 /**
  * The `extension` command an agent exposes in its own binary (#37), e.g. `captain extension add
@@ -126,6 +128,11 @@ export async function runExtensionCommand(argv, options) {
                 const packages = installTarget(options.dirs, scope);
                 // Installed into the workspace by the person: trusted there as it is.
                 const trusted = async (name) => void (scope === "project" && (await trustWorkspace(options.dirs, [name])));
+                // What it needs and this computer lacks (#63): said, never installed.
+                const lacking = (missing) => {
+                    for (const line of missing)
+                        write(`It ${line}.`);
+                };
                 // A plugin of a marketplace, unless it's a folder here or a git URL.
                 const isFolder = await stat(path.resolve(source)).then((found) => found.isDirectory(), () => false);
                 if (flag("link")) {
@@ -135,6 +142,7 @@ export async function runExtensionCommand(argv, options) {
                     await trusted(result.name);
                     await configure(result.name, dir);
                     write(`Linked ${result.name} in the ${scope} scope: it runs from ${path.resolve(source)}, whose files aren't checked. A rebuild takes effect when its server starts again (a new session, or \`/extensions disable\` and \`enable\` in the chat).`);
+                    lacking(result.missing);
                     return true;
                 }
                 if (!isFolder && !isGitSource(source) && /^[A-Za-z0-9][\w.-]*(@[A-Za-z0-9][\w.-]*)?$/.test(source)) {
@@ -150,6 +158,7 @@ export async function runExtensionCommand(argv, options) {
                     await trusted(result.name);
                     await configure(result.name, dir);
                     write(`${result.replaced ? "Reinstalled" : "Installed"} ${result.name} from ${result.marketplace} in the ${scope} scope (${dir})${result.commit ? `, at ${result.commit.slice(0, 12)}` : ""}. It's enabled: it runs from the next session.`);
+                    lacking(result.missing);
                     return true;
                 }
                 const subdir = value("path");
@@ -157,6 +166,7 @@ export async function runExtensionCommand(argv, options) {
                 await trusted(result.name);
                 await configure(result.name, dir);
                 write(`${result.replaced ? "Reinstalled" : "Installed"} ${result.name} in the ${scope} scope (${dir})${result.commit ? `, at ${result.commit.slice(0, 12)}` : ""}. It's enabled: it runs from the next session.`);
+                lacking(result.missing);
                 return true;
             }
             case "remove":
@@ -392,19 +402,28 @@ async function info(extension) {
     if (!manifest)
         return [describe(extension), "Its manifest can't be read."];
     const author = manifest.author ? [manifest.author.name, manifest.author.email && `<${manifest.author.email}>`, manifest.author.url && `(${manifest.author.url})`].filter(Boolean).join(" ") : undefined;
-    const readme = path.join(extension.dir, "README.md");
+    // Its README in the kit's language when it has one (README.es.md), else the English (#67).
+    const language = getLanguage();
+    const translated = path.join(extension.dir, `README.${language}.md`);
+    const readme = language !== "en" && (await stat(translated).catch(() => null))?.isFile() ? translated : path.join(extension.dir, "README.md");
     const field = (label, value) => (value ? [`${label.padEnd(13)}${value}`] : []);
     return [
-        `${manifest.name}${manifest.version ? ` ${manifest.version}` : ""}: ${manifest.description}`,
+        `${manifest.name}${manifest.version ? ` ${manifest.version}` : ""}: ${describeInLanguage(manifest.description, manifest.descriptions, language)}`,
         ...field("Author", author),
         ...field("License", manifest.license),
         ...field("Homepage", manifest.homepage),
         ...field("Repository", manifest.repository),
         ...field("Keywords", manifest.keywords?.join(", ")),
         ...field("Works with", manifest.kit && `agent-kit ${manifest.kit}`),
+        // What it lets the agent do (#62), in the kit's language: one per line.
+        ...manifest.capabilities.flatMap((capability, index) => {
+            const { id, label, description } = describeCapability(capability, getLanguage());
+            return field(index ? "" : "Can do", `${label} (${id})${description ? `: ${description}` : ""}`);
+        }),
         ...field("Provides", manifest.provides.join(", ") || undefined),
         ...field("Requires", manifest.requires.join(", ") || undefined),
-        ...field("Needs", manifest.needs.join(", ") || undefined),
+        // The programs it needs on this computer (#63), one per line, with what for.
+        ...manifest.requirements.flatMap((requirement, index) => field(index ? "" : "Needs", `${requirement.name} (${requirement.program}${requirement.version ? ` ${requirement.version.min} or later` : ""})${requirement.for.length ? ` for ${requirement.for.join(", ")}` : ""}`)),
         ...field("Servers", Object.keys(manifest.servers).join(", ") || undefined),
         ...field("Only read", manifest.readOnlyTools
             ? `${manifest.readOnlyTools.join(", ") || "none"} (its manifest)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",