@falkenslab/agent-kit 0.23.0 → 0.25.0

package/dist/extensions/awareness/catalog.js

@@ -0,0 +1,92 @@
+import { tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { describeCapability } from "../../core/extensions.js";
+import { extensionCatalog, knownMarketplaces, marketplacesDir } from "../../core/extensionCatalog.js";
+import { extensionOptionStates, listInstalled } from "../../core/externalExtensions.js";
+import { updateMarketplace } from "../../core/marketplaces.js";
+/**
+ * The agent as an advisor on extensions (#64): `extensions_catalog` tells it what's installed and
+ * how it stands, what its catalogs offer (from their copies on this computer, instant and offline),
+ * and, with `refresh`, what's new in them, so it can suggest an extension the person lacks. It
+ * never installs, enables or configures anything: refreshing renews the catalogs' copies only, so
+ * the tool stays read-only for plan mode.
+ */
+const ok = (text) => ({ content: [{ type: "text", text }] });
+/** How long ago an ISO date was, as the model reads it. */
+function age(iso, now) {
+    const days = Math.floor((now - Date.parse(iso)) / 86_400_000);
+    return Number.isNaN(days) ? "at an unknown time" : days <= 0 ? "today" : days === 1 ? "yesterday" : `${days} days ago`;
+}
+/** A catalog entry in one line: what installs it, what it is and does, what it needs, where it talks to, how it stands here. */
+function describeEntry(entry) {
+    const parts = [`- **${entry.spec}**${entry.version ? ` ${entry.version}` : ""}: ${entry.description || "(no description)"}`];
+    if (entry.capabilities.length)
+        parts.push(`Can: ${entry.capabilities.map(({ id, label }) => `${label} (${id})`).join(", ")}.`);
+    if (entry.requirements.length)
+        parts.push(`Needs on the computer: ${entry.requirements.map(({ name, for: needed }) => (needed.length ? `${name} (for ${needed.join(", ")})` : name)).join(", ")}.`);
+    if (entry.remote.length)
+        parts.push(`Talks to ${entry.remote.join(", ")}.`);
+    if (entry.topics.length)
+        parts.push(`Topics: ${entry.topics.join(", ")}.`);
+    parts.push(entry.installed ? (entry.update ? `Installed, with an update here: \`/extensions update ${entry.plugin.name}\`.` : "Installed.") : `Not installed: \`/extensions install ${entry.spec}\`.`);
+    return parts.join(" ");
+}
+/** The awareness's catalog tool, over the agent's extension folders and its own marketplace and topics. */
+export function createCatalogTool(config, session) {
+    const dirs = config.extensionDirs;
+    const official = config.officialMarketplace;
+    const topics = config.catalogTopics;
+    // At most one fetch per marketplace and session: a second "what's new" answers from that copy.
+    const refreshed = new Set();
+    return tool("extensions_catalog", "Your extensions and your catalogs: what's installed here and how it stands (running, or off and why, options missing), what the catalogs you know offer (from their copies on this computer, with each copy's age) and, with `refresh: true`, what's new in them online. With `words`, only what matches (name, description, capabilities, topics). Read-only: it never installs, enables or configures anything; installing is the person's, with `/extensions install <name>@<marketplace>`.", {
+        words: z.string().optional().describe("A few words of the task or extension to look for, e.g. `grading rubrics` or `weather`. Without them, everything."),
+        refresh: z.boolean().optional().describe("Fetch the catalogs again from their source first, and say what's new: only when the person asks what's new, or the copies are over a week old."),
+    }, async ({ words, refresh }) => {
+        if (!dirs || !marketplacesDir(dirs))
+            return ok("This agent has no folder for extensions: it can't install any. Say so if the person asks for one.");
+        const now = Date.now();
+        const sections = [];
+        // What's installed, and how it stands in this session.
+        const facts = await session().catch(() => undefined);
+        const running = new Set(facts?.extensions.active.map(({ name }) => name) ?? []);
+        const off = new Map(facts?.extensions.inactive.map(({ name, reason }) => [name, reason]) ?? []);
+        const installed = (await listInstalled(dirs)).filter((extension) => !extension.shadowed);
+        const installedLines = await Promise.all(installed.map(async (extension) => {
+            const state = !extension.lock.enabled ? "disabled (`/extensions enable " + extension.name + "`)" : running.has(extension.name) ? "running" : off.has(extension.name) ? `off: it ${off.get(extension.name)}` : "enabled, from the next session";
+            const missing = (await extensionOptionStates(extension).catch(() => [])).filter(({ option, set }) => option.required && !set).map(({ key }) => key);
+            const can = (extension.manifest?.capabilities ?? []).map((capability) => describeCapability(capability, "en").label);
+            return `- **${extension.name}**${extension.manifest?.version ? ` ${extension.manifest.version}` : ""} (${extension.scope} scope): ${state}.${can.length ? ` Can: ${can.join(", ")}.` : ""}${missing.length ? ` Options to set: ${missing.join(", ")} (\`/extensions config ${extension.name}\`; a secret through the agent's settings or \`extension config\`, never in the chat).` : ""}`;
+        }));
+        sections.push(`## Installed here\n\n${installedLines.join("\n") || "None."}`);
+        // Fetching the catalogs again, when asked: what's new, compared with the copies before.
+        let before = [];
+        const failed = [];
+        if (refresh) {
+            before = await extensionCatalog(dirs, { ...(official ? { official } : {}), ...(topics?.length ? { topics } : {}), language: "en" }).catch(() => []);
+            for (const marketplace of await knownMarketplaces(dirs, official).catch(() => [])) {
+                if (refreshed.has(marketplace.name))
+                    continue;
+                refreshed.add(marketplace.name);
+                await updateMarketplace(marketplacesDir(dirs), marketplace.name).catch(() => failed.push(marketplace.name));
+            }
+        }
+        const known = await knownMarketplaces(dirs, official).catch(() => []);
+        const entries = await extensionCatalog(dirs, {
+            ...(official ? { official } : {}),
+            ...(topics?.length ? { topics } : {}),
+            ...(words?.trim() ? { words: words.trim().split(/\s+/) } : {}),
+            language: "en",
+        }).catch(() => []);
+        const copies = known.map((marketplace) => `${marketplace.name}${marketplace.official ? " (yours)" : ""}, copied ${age(marketplace.updated, now)}`).join("; ");
+        sections.push(`## Offered by your catalogs\n\n${known.length ? `From their copies on this computer: ${copies}.` : "No catalog is known: the person adds one with `/extensions` (a marketplace)."}${words?.trim() ? ` Matching "${words.trim()}".` : ""}\n\n${entries.map(describeEntry).join("\n") || "Nothing matches."}`);
+        if (refresh) {
+            const was = new Map(before.map((entry) => [entry.spec, entry.version]));
+            const added = entries.filter((entry) => !was.has(entry.spec));
+            const updates = entries.filter((entry) => entry.update);
+            const lines = [...added.map((entry) => `- New: **${entry.spec}**${entry.version ? ` ${entry.version}` : ""}: ${entry.description}`), ...updates.map((entry) => `- A newer version of **${entry.plugin.name}**: ${entry.version}.`)];
+            const unreachable = failed.length ? `\n\nCouldn't fetch ${failed.join(", ")} (no network, or it's unavailable): what's above is its copy on this computer.` : "";
+            sections.push(`## What's new online\n\n${lines.join("\n") || "Nothing new since the last copies."}${unreachable}`);
+        }
+        return ok(sections.join("\n\n"));
+    }, { annotations: { readOnlyHint: true } });
+}

package/dist/extensions/awareness/index.d.ts

@@ -3,7 +3,9 @@ import type { Extension } from "../../core/extensions.js";
 /** Absolute path of the awareness extension's plugin, next to `dist/` (or `src/` under tsx). */
 export declare function awarenessPluginRoot(): string;
 /** The "Who you are" section of the system prompt: name, version, what it is, the kit's version, and where to look. */
-export declare function identityPromptSection(identity: AgentIdentity): string;
+export declare function identityPromptSection(identity: AgentIdentity, options?: {
+    catalog?: boolean;
+}): string;
 /** The awareness extension's options. */
 export interface AwarenessOptions {
     /**

package/dist/extensions/awareness/index.js

@@ -3,12 +3,13 @@ import { fileURLToPath } from "node:url";
 import { agentKitVersion } from "../../core/version.js";
 import { awarenessToolLabels } from "./labels.js";
 import { createAwarenessServer } from "./tools.js";
+import { createCatalogTool } from "./catalog.js";
 /** Absolute path of the awareness extension's plugin, next to `dist/` (or `src/` under tsx). */
 export function awarenessPluginRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "extensions", "awareness");
 }
 /** The "Who you are" section of the system prompt: name, version, what it is, the kit's version, and where to look. */
-export function identityPromptSection(identity) {
+export function identityPromptSection(identity, options = {}) {
     const who = `${identity.name}${identity.version ? ` ${identity.version}` : ""}${identity.description ? `: ${identity.description}` : ""}`;
     return `## Who you are
 You are ${who}. You are built on agent-kit ${agentKitVersion()}, which provides your chat (its modes, keys and slash commands) and your built-in tools.
@@ -16,8 +17,14 @@ You are ${who}. You are built on agent-kit ${agentKitVersion()}, which provides
 - Your mode is the kit's (guided, interactive, autonomous or plan), not a permission mode you may see elsewhere: you don't know which one is on until \`about_me\` says.
 - When they ask about your domain (your own commands, configuration, folders), \`about_me\` with \`part: "guide"\`.
 - When they ask how to use you (the chat's modes, keys and commands, approvals, resuming, the command line), load the \`help\` skill.
-- Don't invent what none of them says.`;
+- Don't invent what none of them says.${options.catalog ? `\n${CATALOG_RULES}` : ""}`;
 }
+/**
+ * When the agent can install extensions (#64): look at its catalogs itself, suggest what fits in
+ * one sentence, and leave installing to the person. The tool is read-only; these are the rules.
+ */
+const CATALOG_RULES = `- When the person asks for something none of your tools or skills does well (or that an extension of yours that's off would do), call \`extensions_catalog\` with a few words of the task. If an extension there fits, suggest it in one sentence (what it adds, what it needs, and \`/extensions install <name>@<marketplace>\`) and go on with what you can do without it. Suggest only what it returns; never install, enable or configure an extension yourself; once the person declines one, don't suggest it again in this conversation.
+- When they ask what extensions they have, what one does, how to set it up or why it's off, call \`extensions_catalog\` and load the \`extensions\` skill; when they ask what's new, or its copies are over a week old, call it with \`refresh: true\`.`;
 /**
  * The awareness (#43): the agent knows who it is and what it is at each moment of a session,
  * and the person can ask it. A "Who you are" section, `about_me` (the session's facts, read
@@ -30,11 +37,13 @@ export function awareness(options = {}) {
         name: "awareness",
         plugin: awarenessPluginRoot(),
         missing: ({ spec }) => (spec.identity ? undefined : "needs `identity` in the spec"),
-        async contribute({ spec, session }) {
+        async contribute({ spec, session, config }) {
+            // The catalog only where the agent has a folder for extensions: elsewhere it can't install any (#64).
+            const catalog = Boolean(config.extensionDirs);
             return {
-                mcpServers: { awareness: createAwarenessServer(session, options.guide) },
-                promptSection: identityPromptSection(spec.identity),
-                readOnlyTools: ["mcp__awareness__about_me"],
+                mcpServers: { awareness: createAwarenessServer(session, options.guide, catalog ? [createCatalogTool(config, session)] : []) },
+                promptSection: identityPromptSection(spec.identity, { catalog }),
+                readOnlyTools: ["mcp__awareness__about_me", ...(catalog ? ["mcp__awareness__extensions_catalog"] : [])],
                 toolLabels: awarenessToolLabels(),
             };
         },

package/dist/extensions/awareness/labels.js

@@ -1,12 +1,15 @@
 import { getLanguage } from "../../core/messages/index.js";
 const TEXTS = {
-    en: { now: "Looking at itself", guide: "Reading its own guide", phrase: ["looked at itself", "looked at itself {n} times"] },
-    es: { now: "Mirándose a sí mismo", guide: "Leyendo su propia guía", phrase: ["se miró a sí mismo", "se miró a sí mismo {n} veces"] },
-    fr: { now: "Se regarde lui-même", guide: "Lit son propre guide", phrase: ["s'est regardé lui-même", "s'est regardé lui-même {n} fois"] },
-    de: { now: "Betrachtet sich selbst", guide: "Liest seine eigene Anleitung", phrase: ["sich selbst betrachtet", "sich selbst {n}-mal betrachtet"] },
+    en: { now: "Looking at itself", guide: "Reading its own guide", phrase: ["looked at itself", "looked at itself {n} times"], catalog: "Looking at its extensions", catalogNew: "Looking for new extensions", catalogPhrase: ["looked at its extensions", "looked at its extensions {n} times"] },
+    es: { now: "Mirándose a sí mismo", guide: "Leyendo su propia guía", phrase: ["se miró a sí mismo", "se miró a sí mismo {n} veces"], catalog: "Mirando sus extensiones", catalogNew: "Buscando extensiones nuevas", catalogPhrase: ["miró sus extensiones", "miró sus extensiones {n} veces"] },
+    fr: { now: "Se regarde lui-même", guide: "Lit son propre guide", phrase: ["s'est regardé lui-même", "s'est regardé lui-même {n} fois"], catalog: "Regarde ses extensions", catalogNew: "Cherche de nouvelles extensions", catalogPhrase: ["a regardé ses extensions", "a regardé ses extensions {n} fois"] },
+    de: { now: "Betrachtet sich selbst", guide: "Liest seine eigene Anleitung", phrase: ["sich selbst betrachtet", "sich selbst {n}-mal betrachtet"], catalog: "Sieht seine Erweiterungen an", catalogNew: "Sucht neue Erweiterungen", catalogPhrase: ["seine Erweiterungen angesehen", "seine Erweiterungen {n}-mal angesehen"] },
 };
 /** How the chat shows the awareness's tool (server `awareness`), in the kit's language. */
 export function awarenessToolLabels() {
     const texts = TEXTS[getLanguage()];
-    return { mcp__awareness__about_me: { label: (input) => (input.part === "guide" ? texts.guide : texts.now), phrase: texts.phrase } };
+    return {
+        mcp__awareness__about_me: { label: (input) => (input.part === "guide" ? texts.guide : texts.now), phrase: texts.phrase },
+        mcp__awareness__extensions_catalog: { label: (input) => (input.refresh ? texts.catalogNew : texts.catalog), phrase: texts.catalogPhrase },
+    };
 }

package/dist/extensions/awareness/tools.d.ts

@@ -1,5 +1,5 @@
 import type { SessionFacts } from "../../core/sessionFacts.js";
 /** The session's facts as the model reads them: markdown, in English (ADR-019). */
 export declare function describeSession(facts: SessionFacts): string;
-/** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
-export declare function createAwarenessServer(session: () => Promise<SessionFacts>, guide?: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+/** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide, and any more tools it's given (the catalog, #64). */
+export declare function createAwarenessServer(session: () => Promise<SessionFacts>, guide?: string, more?: readonly unknown[]): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/extensions/awareness/tools.js

@@ -44,8 +44,8 @@ export function describeSession(facts) {
     }
     return sections.join("\n\n");
 }
-/** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide. */
-export function createAwarenessServer(session, guide) {
+/** The awareness's MCP server: `about_me`, from the session's facts and the agent's guide, and any more tools it's given (the catalog, #64). */
+export function createAwarenessServer(session, guide, more = []) {
     const aboutMe = tool("about_me", "What you are right now: your mode and the ones the person can switch to, your extensions with their tools and the ones off (with why), your subagents, the commands the person can type, how full your context is. With `part: \"guide\"`, your own guide to your domain (your commands, configuration, folders). It changes during a session: call it whenever the person asks about you, rather than answering from memory.", { part: z.enum(["now", "guide"]).optional().describe("`now` (the default): what you are right now. `guide`: your own guide to your domain.") }, async ({ part }) => {
         if (part === "guide") {
             if (!guide)
@@ -54,5 +54,6 @@ export function createAwarenessServer(session, guide) {
         }
         return ok(describeSession(await session()));
     }, { annotations: { readOnlyHint: true } });
-    return createSdkMcpServer({ name: "awareness", version: "1.0.0", tools: [aboutMe] });
+    // Tools with different input schemas: as the sources' server does.
+    return createSdkMcpServer({ name: "awareness", version: "1.0.0", tools: [aboutMe, ...more] });
 }

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withTo
 export type { Mode, BaseSessionConfig, AgentSpec, AgentIdentity, PlanModeSpec } from "./core/agentSpec.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode, type ModeControl, type ExtensionsStatus } from "./core/session.js";
 export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
-export type { SessionFacts } from "./core/sessionFacts.js";
+export type { McpAuthentication, SessionFacts } from "./core/sessionFacts.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./extensions/knowledge/prompt.js";
 export { awareness, type AwarenessOptions } from "./extensions/awareness/index.js";
 export { sources, type SourcesOptions } from "./extensions/sources/index.js";
@@ -17,9 +17,9 @@ export { knowledge, type KnowledgeOptions } from "./extensions/knowledge/index.j
 export { memory, type MemoryOptions } from "./extensions/memory/index.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 { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type LocalServer, type RemoteServer, isRemoteServer, remoteHosts, remoteServerName, 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";
+export type { ExtensionAuth, ExtensionRestart, ExtensionSwitch, SignIn } from "./core/liveExtensions.js";
 export { packageCacheDir, type CachedPackage } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, type KnownMarketplace, type MarketplaceManifest, type MarketplacePlugin, type PluginSource, } from "./core/marketplaces.js";
 export { extensionCatalog, installExtension, restoreExtensions, updateExtension, type CatalogEntry } from "./core/extensionCatalog.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { knowledge } from "./extensions/knowledge/index.js";
 export { memory } from "./extensions/memory/index.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 { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, isRemoteServer, remoteHosts, remoteServerName, } from "./core/externalExtensions.js";
 export { packageCacheDir } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, } from "./core/marketplaces.js";
 export { extensionCatalog, installExtension, restoreExtensions, updateExtension } from "./core/extensionCatalog.js";

package/dist/tui/extensionCommand.js

@@ -2,11 +2,11 @@ import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, removeMarketplace, updateMarketplace, } from "../core/marketplaces.js";
-import { addExtension, extensionOptionStates, installTarget, folderSize, isGitSource, listInstalled, removeExtension, setExtensionEnabled, setExtensionOptions, } from "../core/externalExtensions.js";
+import { addExtension, extensionOptionStates, installTarget, folderSize, isGitSource, isRemoteServer, remoteHosts, listInstalled, removeExtension, setExtensionEnabled, setExtensionOptions, } from "../core/externalExtensions.js";
 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 { describeCapability, describeInLanguage } from "../core/extensions.js";
 import { getLanguage } from "../core/messages/index.js";
 export { chatExtensionsCommand, describe } from "../chat/extensions.js";
 /**
@@ -129,9 +129,12 @@ export async function runExtensionCommand(argv, options) {
                 // 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) => {
+                const lacking = (missing, remote = []) => {
                     for (const line of missing)
                         write(`It ${line}.`);
+                    // Where what the agent sends goes (#61).
+                    if (remote.length)
+                        write(`It talks to ${remote.join(", ")}: what the agent sends there leaves this computer.`);
                 };
                 // 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);
@@ -142,7 +145,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);
+                    lacking(result.missing, result.remote);
                     return true;
                 }
                 if (!isFolder && !isGitSource(source) && /^[A-Za-z0-9][\w.-]*(@[A-Za-z0-9][\w.-]*)?$/.test(source)) {
@@ -158,7 +161,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);
+                    lacking(result.missing, result.remote);
                     return true;
                 }
                 const subdir = value("path");
@@ -166,7 +169,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);
+                lacking(result.missing, result.remote);
                 return true;
             }
             case "remove":
@@ -402,10 +405,13 @@ 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),
@@ -431,7 +437,9 @@ async function info(extension) {
         ...field("Options", Object.entries(manifest.userConfig)
             .map(([key, option]) => `${key} (${[option.title, option.required && "required", option.sensitive && "secret"].filter(Boolean).join(", ")})`)
             .join(", ") || undefined),
-        ...field("Variables", Object.values(manifest.servers).flatMap((server) => Object.keys(server.env ?? {})).join(", ") || undefined),
+        ...field("Variables", Object.values(manifest.servers).flatMap((server) => (isRemoteServer(server) ? [] : Object.keys(server.env ?? {}))).join(", ") || undefined),
+        // Where what the agent sends goes (#61): a remote server's host.
+        ...field("Talks to", remoteHosts(manifest).join(", ") || undefined),
         ...field("Installed", `${extension.scope} scope, ${extension.lock.enabled ? "enabled" : "disabled"}, on ${extension.lock.installed}, from ${describe(extension).split("  from ")[1]}`),
         ...field("Data", (await stat(extension.dataDir).catch(() => null))?.isDirectory() ? `${extension.dataDir} (${formatSize(await folderSize(extension.dataDir))})` : undefined),
         ...field("README", (await stat(readme).catch(() => null))?.isFile() ? readme : undefined),

package/extensions/awareness/skills/extensions/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: extensions
+description: Helping the person with this agent's extensions - what each installed one lets you do, setting its options, why one is off, what the catalogs offer for a task, signing in to a remote one, installing, updating and removing, adding a catalog. Load it whenever the person asks about extensions, or when you're about to suggest one.
+---
+
+# Helping with extensions
+
+Extensions add what you can do: tools, skills and the know-how to use them (a Moodle classroom, a weather forecast, a lab). What's installed and what the catalogs offer come from `extensions_catalog`, read anew each time: never answer from memory. Answer in the language you reply in, briefly, with the exact command; commands are typed as written here. Without `extensions_catalog` among your tools, this agent has no folder for extensions and can't install any: say so, and suggest nothing.
+
+## What you never do
+
+- Install, enable, disable, configure or remove an extension yourself: the person does, with the commands below. You suggest and explain.
+- Ask for a secret (a token, a password) in the chat: what's typed there is kept in its history. Secrets are set in the agent's settings or from a terminal (`<agent> extension config <name> <key>`, which asks without showing it).
+- Suggest an extension the catalog didn't return, or one the person already declined in this conversation.
+
+## Suggesting one
+
+When the task needs what an extension does and it isn't installed, or it's off: one sentence with what it adds, what it needs (a program, a site, an account) and how to install it, then go on with what you can do without it.
+
+> The **weather** extension would give me today's forecast for your city; install it with `/extensions install weather@falkenslab` and tell me your city. Meanwhile, here's what I can plan without it…
+
+An extension that talks to a remote service sends what you give it there: say so when the person's data is involved.
+
+## Commands in the chat
+
+| Command | What it does |
+| --- | --- |
+| `/extensions` | What's running, what's off and why, what's installed |
+| `/extensions search <words>` | What the catalogs offer |
+| `/extensions install <name>@<marketplace>` | Installs one (one from a catalog that isn't the agent's own asks for confirmation) |
+| `/extensions reload` | Opens the session again with what's installed now, keeping the conversation |
+| `/extensions update [name]` | Updates one, or every one with a newer version |
+| `/extensions remove <name>` | Uninstalls one (`--delete-data` deletes its data too) |
+| `/extensions enable <name>` | Turns one on |
+| `/extensions disable <name>` | Turns one off, keeping it installed |
+| `/extensions config <name> [key=value…]` | Its options, and setting the ones that aren't secret |
+| `/extensions sign-in <name>` | Signs in to its remote service: gives the link to open |
+| `/extensions sign-out <name>` | Signs out of its remote service |
+| `/extensions trust` | Lets the workspace's extensions run |
+
+A new catalog (a marketplace) is added from a terminal: `<agent> extension marketplace add <owner/repo>`.
+
+## Why one is off
+
+`extensions_catalog` and `/extensions` give the reason; explain it and its remedy in plain words:
+
+- **An option without a value** (its site, its account): `/extensions config <name> <key>=<value>`, or the settings for a secret.
+- **A program missing on the computer** (Docker, ffmpeg): what it is, and the install command for this system the reason gives. The extension never installs it.
+- **It needs signing in**: `/extensions sign-in <name>`, then open the link.
+- **It requires another extension's capability**: install or enable the one that provides it.
+- **Its files changed** or **its workspace isn't trusted**: reinstall it, or `/extensions trust`.
+- **This agent's kit version is outside its range**: an update of the agent or of the extension.
+
+## What's new
+
+`extensions_catalog` with `refresh: true` fetches the catalogs again and says what's new: extensions added since the last copy, and newer versions of installed ones (`/extensions update`). Without network it answers from the copies on this computer and says how old they are.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.23.0",
+  "version": "0.25.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,6 +11,12 @@
       "type": "string",
       "pattern": "^\\s*(?:(?:>=|<=|>|<|=)?\\s*v?\\d+(?:\\.\\d+){0,2})(?:\\s+(?:>=|<=|>|<|=)?\\s*v?\\d+(?:\\.\\d+){0,2})*\\s*$"
     },
+    "description": {
+      "description": "Its description in other languages than English, which stays plugin.json's own description (Claude Code reads that one).",
+      "type": "object",
+      "propertyNames": { "enum": ["es", "fr", "de"] },
+      "additionalProperties": { "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.",

package/schemas/marketplace-catalog.schema.json

@@ -35,7 +35,14 @@
       "properties": {
         "name": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
         "version": { "description": "Its plugin.json's, the same as its marketplace entry's.", "type": "string", "minLength": 1 },
-        "description": { "type": "string" },
+        "description": { "description": "In English: its marketplace entry's, else its plugin.json's.", "type": "string" },
+        "descriptions": {
+          "description": "Its description per language, English among them; only when it has one in another language.",
+          "type": "object",
+          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
+          "required": ["en"],
+          "additionalProperties": { "type": "string" }
+        },
         "category": { "type": ["string", "null"] },
         "topics": {
           "description": "Its plugin.json's keywords and its entry's tags, keywords and category, lowercased, without repeats.",
@@ -47,6 +54,13 @@
         "license": { "type": ["string", "null"] },
         "homepage": { "$ref": "#/$defs/url" },
         "readme": { "$ref": "#/$defs/url" },
+        "readmes": {
+          "description": "Its README per language (README.md, README.es.md…), as URLs; only when it has one in another language.",
+          "type": "object",
+          "propertyNames": { "enum": ["en", "es", "fr", "de"] },
+          "required": ["en"],
+          "additionalProperties": { "$ref": "#/$defs/url" }
+        },
         "install": {
           "type": "object",
           "additionalProperties": false,
@@ -66,6 +80,12 @@
           "type": "array",
           "items": { "$ref": "https://falkenslab.github.io/agent-kit/schemas/agent-kit-metadata.schema.json#/$defs/requirement" }
         },
+        "remote": {
+          "description": "The hosts its remote MCP servers talk to (type http or sse in its .mcp.json): what an agent sends there leaves the computer. Only when it has some.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
         "logo": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" },
         "banner": { "description": "A URL anyone can load.", "$ref": "#/$defs/url" }
       }