@falkenslab/agent-kit 0.22.0 → 0.23.0

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, 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,6 +93,7 @@ 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 : "",
@@ -102,10 +105,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 +324,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 +400,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 +430,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 +484,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 +515,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 +532,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 } 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":
@@ -402,9 +412,15 @@ async function info(extension) {
         ...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.23.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",

package/schemas/agent-kit-metadata.schema.json

@@ -11,9 +11,18 @@
       "type": "string",
       "pattern": "^\\s*(?:(?:>=|<=|>|<|=)?\\s*v?\\d+(?:\\.\\d+){0,2})(?:\\s+(?:>=|<=|>|<|=)?\\s*v?\\d+(?:\\.\\d+){0,2})*\\s*$"
     },
-    "provides": { "description": "Capabilities it lets the agent use.", "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "provides": { "description": "Capabilities it lets the agent use, by name only. Its capabilities' ids count as provided too.", "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "capabilities": {
+      "description": "What it lets the agent do, for the person: each one's skills and tools together, described per language. Its id is what requires names; neutral ids (lms-grading) let skills depend on what can be done, not on which extension does it.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/capability" }
+    },
     "requires": { "description": "Capabilities another enabled extension must provide.", "type": "array", "items": { "type": "string", "minLength": 1 } },
-    "needs": { "description": "Programs it needs on the computer's PATH.", "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "requirements": {
+      "description": "Programs it needs on the computer, which the person installs: agent-kit checks them, says what's missing and how to install it, and never installs them. Without one the whole extension needs, it's off; without one only some capabilities need (for), those are.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/requirement" }
+    },
     "readOnlyTools": {
       "description": "Its tools that only read (short names): plan mode lets them through. Without it, plan mode asks its servers (readOnlyHint).",
       "type": "array",
@@ -54,6 +63,55 @@
     }
   },
   "$defs": {
+    "requirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "program", "install"],
+      "properties": {
+        "name": { "description": "What the person reads: Docker.", "type": "string", "minLength": 1 },
+        "program": { "description": "Its bare name, found on the PATH (on Windows with PATHEXT's extensions): never a path.", "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]*$" },
+        "version": {
+          "description": "How to check its version: run with these arguments only (options or version, no shell), the first x.y.z it prints compared with min.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["args", "min"],
+          "properties": {
+            "args": { "type": "array", "items": { "type": "string", "pattern": "^(--?[A-Za-z][A-Za-z0-9-]*|version)$" } },
+            "min": { "type": "string", "pattern": "^\\d+(\\.\\d+){0,2}$" }
+          }
+        },
+        "install": {
+          "description": "How to install it on each system: a command, or a link (url, the fallback).",
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": { "windows": { "type": "string", "minLength": 1 }, "macos": { "type": "string", "minLength": 1 }, "linux": { "type": "string", "minLength": 1 }, "url": { "type": "string", "pattern": "^https?://" } }
+        },
+        "for": { "description": "The capabilities (ids it provides) that need it; without it, the whole extension does.", "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "texts"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+        "skills": { "description": "Its skills, by their folder in the extension's skills/.", "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "tools": { "description": "Its tools, by short name (of any of its servers).", "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "texts": {
+          "description": "Its label and description per language (en, es, fr, de); English is shown where its language is missing.",
+          "type": "object",
+          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label"],
+            "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }
+          }
+        }
+      }
+    },
     "image": {
       "type": "string",
       "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+\\.(?:svg|png|jpe?g|webp)$"

package/schemas/marketplace-catalog.schema.json

@@ -56,6 +56,16 @@
             "agentKit": { "description": "After the agent's own command (<agent> …).", "type": "string" }
           }
         },
+        "capabilities": {
+          "description": "What it lets the agent do: its metadata[\"agent-kit\"].capabilities as it declares them, texts in every language it gives.",
+          "type": "array",
+          "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/capability" }
+        },
+        "requirements": {
+          "description": "The programs it needs on the computer: its metadata[\"agent-kit\"].requirements as it declares them.",
+          "type": "array",
+          "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/requirement" }
+        },
         "logo": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" },
         "banner": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" }
       }