@falkenslab/agent-kit 0.23.0 → 0.25.0

package/README.md

@@ -9,6 +9,8 @@
 [![license](https://img.shields.io/npm/l/@falkenslab/agent-kit)](LICENSE)
 [![docs](https://img.shields.io/badge/docs-falkenslab.github.io%2Fagent--kit-4453b8)](https://falkenslab.github.io/agent-kit/)
 
+**[📖 Documentation](https://falkenslab.github.io/agent-kit/)** · [📖 Documentación en español](https://falkenslab.github.io/agent-kit/es/)
+
 A foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (human oversight, safety, memory and a good terminal interface), so each concrete agent only has to write what belongs to its own domain: what it knows how to do, with which tools, and how it talks.
 
 ## What an agent built with it can do

package/dist/chat/chatController.d.ts

@@ -9,6 +9,7 @@ import { type ExtensionsStatus, type ModeControl } from "../core/session.js";
 import { type Todo } from "../core/todos.js";
 import { type ToolLabels } from "../core/toolLabels.js";
 import type { ToolPhrase } from "../core/messages/index.js";
+import type { SignIn } from "../core/liveExtensions.js";
 import { type ExtensionOptionState, type ExtensionScope } from "../core/externalExtensions.js";
 import { type CatalogEntry } from "../core/extensionCatalog.js";
 import { type SessionOpener } from "./runs.js";
@@ -268,12 +269,21 @@ export declare function createChatController(options: Options | SessionOpener, s
      * installed until `confirmed`: the result says which (`confirm`), for the view to ask the
      * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
      */
+    /**
+     * Signs in to an installed extension's remote servers (#61): gives the person the links (never
+     * opens a browser), then says when the sign-in finishes. With `callbackUrl`, the address the
+     * browser ended on (from another computer), finishes it instead.
+     */
+    signInExtension(name: string, callbackUrl?: string): Promise<SignIn>;
+    /** Signs out of an installed extension's remote servers (#61). */
+    signOutExtension(name: string): Promise<boolean>;
     installExtension(spec: string, options?: {
         scope?: ExtensionScope;
         confirmed?: boolean;
     }): Promise<{
         name?: string;
         missing?: string[];
+        remote?: string[];
         confirm?: {
             marketplace: string;
             description?: string;

package/dist/chat/chatController.js

@@ -315,6 +315,10 @@ export async function createChatController(options, settings = {}) {
                 await controller.removeExtension(action.name, { deleteData: action.deleteData });
             else if (action.type === "trust")
                 await controller.trustWorkspace();
+            else if (action.type === "sign-in")
+                await controller.signInExtension(action.name, action.callbackUrl);
+            else if (action.type === "sign-out")
+                await controller.signOutExtension(action.name);
             else
                 await controller.reopen();
         }
@@ -595,6 +599,37 @@ export async function createChatController(options, settings = {}) {
          * installed until `confirmed`: the result says which (`confirm`), for the view to ask the
          * person. The running session is untouched: it's there in a new conversation, or with `reopen()`.
          */
+        /**
+         * Signs in to an installed extension's remote servers (#61): gives the person the links (never
+         * opens a browser), then says when the sign-in finishes. With `callbackUrl`, the address the
+         * browser ended on (from another computer), finishes it instead.
+         */
+        async signInExtension(name, callbackUrl) {
+            const auth = current.extensionAuth;
+            const result = auth ? await auth.signIn(name, callbackUrl) : { status: "unavailable", reason: "not-running" };
+            if (result.status === "unavailable")
+                notice(t().extensionSignInUnavailable(name));
+            else if (result.status === "signed-in")
+                notice(callbackUrl ? t().extensionSignedIn(name) : t().extensionAlreadySignedIn(name));
+            else {
+                for (const link of result.links)
+                    notice(t().extensionSignInOpen(name, link.url));
+                notice(t().extensionSignInPaste(name));
+                // Waits in the background: the person signs in in their browser, whenever they do.
+                void auth.connected(name, 5 * 60_000).then((done) => {
+                    notice(done ? t().extensionSignedIn(name) : t().extensionSignInWaiting(name));
+                    if (done)
+                        extensionNotices.push(`<system-reminder>The user signed in to the ${name} extension: its remote tools are available now.</system-reminder>`);
+                });
+            }
+            return result;
+        },
+        /** Signs out of an installed extension's remote servers (#61). */
+        async signOutExtension(name) {
+            const done = (await current.extensionAuth?.signOut(name).catch(() => false)) ?? false;
+            notice(done ? t().extensionSignedOut(name) : t().extensionSignInUnavailable(name));
+            return done;
+        },
         async installExtension(spec, options = {}) {
             if (!current.extensions)
                 throw new Error("This chat's session has no extensions folder.");
@@ -608,7 +643,10 @@ export async function createChatController(options, settings = {}) {
             // What it needs and this computer lacks (#63): the person installs it, the kit never does.
             for (const line of result.missing)
                 notice(t().extensionLacks(result.name, line));
-            return { name: result.name, missing: result.missing };
+            // Where what the agent sends goes (#61).
+            if (result.remote.length)
+                notice(t().extensionTalksTo(result.name, result.remote.join(", ")));
+            return { name: result.name, missing: result.missing, remote: result.remote };
         },
         /** Updates one installed extension from its marketplace, or every one with a newer version there; the names updated. */
         async updateExtension(name) {

package/dist/chat/extensions.d.ts

@@ -25,6 +25,15 @@ export type ExtensionAction = {
     type: "reload";
 } | {
     type: "trust";
+}
+/** Signing in to an extension's remote servers (#61), or finishing it with the callback URL pasted from another computer. */
+ | {
+    type: "sign-in";
+    name: string;
+    callbackUrl?: string;
+} | {
+    type: "sign-out";
+    name: string;
 };
 /** One line for a catalog entry: what installs it, its version, whether it's installed or has an update, what it is. */
 export declare function describeEntry(entry: CatalogEntry): string;

package/dist/chat/extensions.js

@@ -35,10 +35,17 @@ export function describeCapabilities(status) {
         ];
     });
 }
+/** The running extensions whose remote servers need the person to sign in (#61). */
+async function needingSignIn(status) {
+    const waiting = new Set((await status.serverStatus?.().catch(() => []))?.filter((server) => server.status === "needs-auth").map((server) => server.name));
+    if (!waiting.size)
+        return [];
+    return status.active.filter((name) => status.about[name]?.servers.some((server) => waiting.has(server)));
+}
 /** One line for a catalog entry: what installs it, its version, whether it's installed or has an update, what it is. */
 export function describeEntry(entry) {
     const state = entry.installed ? (entry.update ? ` ${t().extensionUpdateAvailable(entry.installed.manifest?.version ?? "?")}` : ` ${t().extensionIsInstalled}`) : "";
-    return `${entry.spec}${entry.version ? ` ${entry.version}` : ""}${state}${entry.plugin.description ? `  ${entry.plugin.description}` : ""}`;
+    return `${entry.spec}${entry.version ? ` ${entry.version}` : ""}${state}${entry.description ? `  ${entry.description}` : ""}`;
 }
 /** An installed extension's options, one line each: its value, its default, or whether a sensitive one is set (never its value). */
 export async function describeOptions(extension) {
@@ -78,6 +85,11 @@ export async function chatExtensionsCommand(line, status, canReopen) {
         return canReopen ? { lines: [], action: { type: "reload" } } : { lines: [t().extensionsCantReopen] };
     if (verb === "trust" && !name)
         return canReopen ? { lines: [], action: { type: "trust" } } : { lines: [t().extensionsCantReopen] };
+    // Signing in happens in the running session: no reopening (#61).
+    if (verb === "sign-in" && name)
+        return { lines: [], action: { type: "sign-in", name, ...(extra[0] ? { callbackUrl: extra[0] } : {}) } };
+    if (verb === "sign-out" && name)
+        return { lines: [], action: { type: "sign-out", name } };
     if (action?.toLowerCase() === "config" && name) {
         const installed = (status?.installed ?? []).find((extension) => extension.name === name && !extension.shadowed);
         if (!installed)
@@ -107,7 +119,7 @@ export async function chatExtensionsCommand(line, status, canReopen) {
     if (!action) {
         const lines = [status?.active.length ? t().extensionsRunning(status.active.join(", ")) : t().extensionsNone];
         if (status)
-            lines.push(...describeCapabilities(status));
+            lines.push(...describeCapabilities(status), ...(await needingSignIn(status)).map((extension) => t().extensionNeedsSignIn(extension)));
         for (const { name: off, reason } of status?.inactive ?? [])
             lines.push(t().extensionOff(off, reason));
         if (status?.installed.length)

package/dist/chat/runs.d.ts

@@ -1,7 +1,7 @@
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
 import type { ExtensionsStatus, ModeControl } from "../core/session.js";
 import type { ToolLabels } from "../core/toolLabels.js";
-import type { ExtensionRestart, ExtensionSwitch } from "../core/liveExtensions.js";
+import type { ExtensionAuth, ExtensionRestart, ExtensionSwitch } from "../core/liveExtensions.js";
 import { type RunFolder, type RunSummary } from "../core/runs.js";
 /**
  * Builds the session's options for a run folder, e.g.
@@ -17,6 +17,7 @@ export type SessionOpener = (run: RunFolder) => Promise<Options | {
     apis?: Record<string, Record<string, unknown>>;
     switchExtension?: ExtensionSwitch;
     restartExtension?: ExtensionRestart;
+    extensionAuth?: ExtensionAuth;
 }>;
 export interface OpenedSession {
     run: RunFolder;
@@ -27,6 +28,7 @@ export interface OpenedSession {
     apis?: Record<string, Record<string, unknown>>;
     switchExtension?: ExtensionSwitch;
     restartExtension?: ExtensionRestart;
+    extensionAuth?: ExtensionAuth;
 }
 /** The run a chat starts with: the latest one with `--continue` (if any), a new one otherwise. */
 export declare function firstRun(runsDir: string, argv?: readonly string[]): Promise<RunFolder>;

package/dist/chat/runs.js

@@ -13,7 +13,7 @@ export async function firstRun(runsDir, argv = process.argv.slice(2)) {
 export async function openSession(opener, run) {
     const opened = await opener(run);
     // The SDK's Options has no "options" field: this is buildSessionOptions()'s result.
-    return "options" in opened ? { run, options: opened.options, modeControl: opened.modeControl, toolLabels: opened.toolLabels, extensions: opened.extensions, apis: opened.apis, switchExtension: opened.switchExtension, restartExtension: opened.restartExtension } : { run, options: opened };
+    return "options" in opened ? { run, options: opened.options, modeControl: opened.modeControl, toolLabels: opened.toolLabels, extensions: opened.extensions, apis: opened.apis, switchExtension: opened.switchExtension, restartExtension: opened.restartExtension, extensionAuth: opened.extensionAuth } : { run, options: opened };
 }
 /** A run's date for a person, in the kit's language. */
 export function runDate(date) {

package/dist/core/extensionCatalog.d.ts

@@ -1,5 +1,6 @@
 import { type ExtensionDirs, type ExtensionScope, type InstalledExtension } from "./externalExtensions.js";
 import { type DescribedCapability } from "./extensions.js";
+import type { Language } from "./language.js";
 import { type KnownMarketplace, type MarketplacePlugin } from "./marketplaces.js";
 /**
  * The agent's catalog of extensions (#56): what its known marketplaces offer, what's installed
@@ -22,6 +23,8 @@ export interface CatalogEntry {
     /** From the agent's own marketplace: installed without a confirmation. */
     official: boolean;
     plugin: MarketplacePlugin;
+    /** What it is, in the kit's language (#67): its own there, else the marketplace entry's, else its `plugin.json`'s, in English. */
+    description: string;
     /** The version it offers: its `plugin.json`'s when the marketplace has its folder, else the marketplace's entry's. */
     version?: string;
     /** Installed (and used: not shadowed), from wherever it came. */
@@ -40,14 +43,17 @@ export interface CatalogEntry {
         name: string;
         for: string[];
     }[];
+    /** The hosts its remote servers talk to (#61): what the agent sends there leaves the computer. */
+    remote: string[];
 }
 /** Whether `offered` is newer than `installed` (x.y.z); a version that can't be compared isn't. */
 export declare function isNewer(offered: string | undefined, installed: string | undefined): boolean;
-/** Everything the known marketplaces offer, matching `words` (in its name, description, category, tags or keywords) when given. */
+/** Everything the known marketplaces offer, matching `words` (in its name, description, category, tags or keywords) when given; its texts in `language` (the kit's by default). */
 export declare function extensionCatalog(dirs: ExtensionDirs, options?: {
     official?: string;
     words?: readonly string[];
     topics?: readonly string[];
+    language?: Language;
 }): Promise<CatalogEntry[]>;
 /** Whether installing `spec` needs the person's confirmation first: a plugin of a marketplace that isn't the agent's own. */
 export declare function needsConfirmation(dirs: ExtensionDirs, spec: string, official?: string): Promise<{
@@ -70,6 +76,7 @@ export declare function installExtension(dirs: ExtensionDirs, spec: string, opti
     marketplace: string;
     commit?: string;
     missing: string[];
+    remote: string[];
 }>;
 /**
  * Updates an installed extension from the marketplace it came from: a fresh copy of the

package/dist/core/extensionCatalog.js

@@ -1,10 +1,10 @@
 import { mkdtemp, rm, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { addExtension, codeStoreDir, hashExtension, inKitRange, installTarget, isGitSource, listInstalled, readExternalManifest, readLock, storedCodeDir } from "./externalExtensions.js";
+import { addExtension, remoteHosts, codeStoreDir, hashExtension, inKitRange, installTarget, isGitSource, listInstalled, readExternalManifest, readLock, storedCodeDir } from "./externalExtensions.js";
 import { cachePackage, cachedPackageDir } from "./npxPackages.js";
 import { trustWorkspace } from "./workspaceTrust.js";
-import { describeCapability } from "./extensions.js";
+import { describeCapability, describeInLanguage } from "./extensions.js";
 import { getLanguage } from "./messages/index.js";
 import { addMarketplace, findPlugin, installFromMarketplace, listMarketplaces, resolvePluginSource, updateMarketplace } from "./marketplaces.js";
 /**
@@ -51,7 +51,7 @@ const IMAGE = /\.(svg|png|jpe?g|webp)$/i;
  * the version (its `plugin.json` wins over the entry, as Claude Code computes it), its keywords,
  * and its look, an image inside its folder only.
  */
-async function offered(marketplace, plugin) {
+async function offered(marketplace, plugin, language) {
     try {
         const resolved = resolvePluginSource(marketplace, plugin);
         if ("source" in resolved && !isGitSource(resolved.source) && (await stat(resolved.source).catch(() => null))?.isDirectory()) {
@@ -66,15 +66,17 @@ async function offered(marketplace, plugin) {
             };
             const [logo, banner] = [await image(manifest?.catalog?.logo), await image(manifest?.catalog?.banner)];
             const version = manifest?.version ?? plugin.version;
-            const capabilities = (manifest?.capabilities ?? []).map((capability) => describeCapability(capability, getLanguage()));
+            const capabilities = (manifest?.capabilities ?? []).map((capability) => describeCapability(capability, language));
             const requirements = (manifest?.requirements ?? []).map((requirement) => ({ name: requirement.name, for: requirement.for }));
-            return { ...(version ? { version } : {}), keywords: manifest?.keywords ?? [], ...(logo ? { logo } : {}), ...(banner ? { banner } : {}), capabilities, requirements };
+            const description = describeInLanguage(plugin.description ?? manifest?.description ?? "", manifest?.descriptions, language);
+            const remote = manifest ? remoteHosts(manifest) : [];
+            return { ...(version ? { version } : {}), keywords: manifest?.keywords ?? [], ...(logo ? { logo } : {}), ...(banner ? { banner } : {}), capabilities, requirements, description, remote };
         }
     }
     catch {
         // A source the kit doesn't install: the entry's own fields.
     }
-    return { ...(plugin.version ? { version: plugin.version } : {}), keywords: [], capabilities: [], requirements: [] };
+    return { ...(plugin.version ? { version: plugin.version } : {}), keywords: [], capabilities: [], requirements: [], description: plugin.description ?? "", remote: [] };
 }
 /** Whether `offered` is newer than `installed` (x.y.z); a version that can't be compared isn't. */
 export function isNewer(offered, installed) {
@@ -82,7 +84,7 @@ export function isNewer(offered, installed) {
         return false;
     return inKitRange(offered, `>${installed.split("-")[0]}`);
 }
-/** Everything the known marketplaces offer, matching `words` (in its name, description, category, tags or keywords) when given. */
+/** Everything the known marketplaces offer, matching `words` (in its name, description, category, tags or keywords) when given; its texts in `language` (the kit's by default). */
 export async function extensionCatalog(dirs, options = {}) {
     const installed = (await listInstalled(dirs)).filter((extension) => !extension.shadowed);
     const words = (options.words ?? []).map((word) => word.toLowerCase());
@@ -91,12 +93,12 @@ export async function extensionCatalog(dirs, options = {}) {
     const entries = [];
     for (const marketplace of await knownMarketplaces(dirs, options.official)) {
         for (const plugin of marketplace.manifest?.plugins ?? []) {
-            const look = await offered(marketplace, plugin);
+            const look = await offered(marketplace, plugin, options.language ?? getLanguage());
             const topics = [...new Set([...look.keywords, ...(plugin.tags ?? []), ...(plugin.keywords ?? []), ...(plugin.category ? [plugin.category] : [])].map((topic) => topic.toLowerCase()))];
             if (wanted && !topics.some((topic) => wanted.has(topic)))
                 continue;
             // Its capabilities count too: a search for "grading" finds what grades.
-            const text = [plugin.name, plugin.description, ...topics, ...look.capabilities.flatMap(({ id, label, description }) => [id, label, description])].join(" ").toLowerCase();
+            const text = [plugin.name, plugin.description, look.description, ...topics, ...look.capabilities.flatMap(({ id, label, description }) => [id, label, description])].join(" ").toLowerCase();
             if (!words.every((word) => text.includes(word)))
                 continue;
             const version = look.version;
@@ -104,6 +106,7 @@ export async function extensionCatalog(dirs, options = {}) {
             const fromHere = mine?.lock.marketplace === `${plugin.name}@${marketplace.name}`;
             entries.push({
                 spec: `${plugin.name}@${marketplace.name}`,
+                description: look.description,
                 marketplace: marketplace.name,
                 official: marketplace.official,
                 plugin,
@@ -115,6 +118,7 @@ export async function extensionCatalog(dirs, options = {}) {
                 ...(look.banner ? { banner: look.banner } : {}),
                 capabilities: look.capabilities,
                 requirements: look.requirements,
+                remote: look.remote,
             });
         }
     }

package/dist/core/extensionOptions.d.ts

@@ -52,5 +52,10 @@ export declare function missingOptions(declared: Record<string, ExtensionOption>
 export declare function storeOptionValues(scopeDir: string, name: string, declared: Record<string, ExtensionOption>, stored: Record<string, OptionValue>, changes: Record<string, OptionValue | undefined>): Promise<Record<string, OptionValue>>;
 /** Removes an extension's sensitive values. */
 export declare function removeSecrets(scopeDir: string, name: string): Promise<void>;
+/**
+ * `${user_config.KEY}` in `text` replaced by its value: a list comma-separated, none as empty, as
+ * the launcher does for a local server. The kit's own, for a remote server's URL and headers (#61).
+ */
+export declare function fillOptions(text: string, values: Record<string, OptionValue>): string;
 /** The `${user_config.KEY}` a server's values name. */
 export declare function optionsNamed(values: readonly string[]): string[];

package/dist/core/extensionOptions.js

@@ -133,6 +133,16 @@ export async function storeOptionValues(scopeDir, name, declared, stored, change
 export async function removeSecrets(scopeDir, name) {
     await rm(extensionSecretsPath(scopeDir, name), { force: true });
 }
+/**
+ * `${user_config.KEY}` in `text` replaced by its value: a list comma-separated, none as empty, as
+ * the launcher does for a local server. The kit's own, for a remote server's URL and headers (#61).
+ */
+export function fillOptions(text, values) {
+    return text.replace(/\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => {
+        const value = values[key];
+        return value === undefined ? "" : Array.isArray(value) ? value.join(",") : String(value);
+    });
+}
 /** The `${user_config.KEY}` a server's values name. */
 export function optionsNamed(values) {
     return [...new Set(values.flatMap((value) => [...value.matchAll(/\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((match) => match[1])))];

package/dist/core/extensions.d.ts

@@ -64,6 +64,12 @@ export interface ExtensionContribution {
      * no `readOnlyTools`. A list in the manifest wins: its servers aren't here.
      */
     readOnlyHintServers?: string[];
+    /**
+     * Its MCP servers that are remote (#61), by session name: the SDK fixes their URL and headers
+     * when the session opens, so a changed option takes opening it again, and they may need the
+     * person to sign in.
+     */
+    remoteServers?: string[];
     /** Its MCP tools that ask the person themselves: interactive mode's step gate doesn't ask first. */
     selfAskingTools?: string[];
     /** How the chat shows its tools, by full name, in the kit's language: its line and how it counts in a folded group. */
@@ -135,6 +141,13 @@ export declare function describeCapability(capability: ExtensionCapability, lang
  * one is missing.
  */
 export declare function capabilitiesProblem(pluginRoot: string, capabilities: readonly ExtensionCapability[]): Promise<string | undefined>;
+/**
+ * A manifest's `metadata["agent-kit"].description` (#67): its description in other languages than
+ * English, which stays the top-level `description` Claude Code reads. Only languages the kit speaks.
+ */
+export declare function parseDescriptions(raw: unknown): Partial<Record<Language, string>>;
+/** An extension's description in `language`: its own there, else the English one. */
+export declare function describeInLanguage(english: string, descriptions: Partial<Record<Language, string>> | undefined, language: Language): string;
 /** An extension's manifest, as the kit reads it. */
 export interface ExtensionManifest {
     name: string;

package/dist/core/extensions.js

@@ -49,6 +49,19 @@ export async function capabilitiesProblem(pluginRoot, capabilities) {
     }
     return undefined;
 }
+/**
+ * A manifest's `metadata["agent-kit"].description` (#67): its description in other languages than
+ * English, which stays the top-level `description` Claude Code reads. Only languages the kit speaks.
+ */
+export function parseDescriptions(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    return Object.fromEntries(Object.entries(raw).filter(([language, text]) => SUPPORTED_LANGUAGES.includes(language) && typeof text === "string" && text.length > 0));
+}
+/** An extension's description in `language`: its own there, else the English one. */
+export function describeInLanguage(english, descriptions, language) {
+    return descriptions?.[language] ?? english;
+}
 /** Reads an extension's manifest from its plugin. */
 export function readExtensionManifest(pluginRoot) {
     const file = path.join(pluginRoot, ".claude-plugin", "plugin.json");

package/dist/core/externalExtensions.d.ts

@@ -26,12 +26,34 @@ export interface ExtensionDirs {
 /** One of the two scopes an extension can be installed in: the agent's or the project's. */
 export type ExtensionScope = keyof ExtensionDirs;
 /** One of a plugin's MCP servers, as its `.mcp.json` (or `plugin.json`'s `mcpServers`) declares it. */
-export interface PluginServer {
+/** A server the kit starts on this computer, through its launcher. */
+export interface LocalServer {
     command: string;
     args?: string[];
     /** Its variables: a value may take the agent's with `${VAR}`, and its folders with `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}`. */
     env?: Record<string, string>;
 }
+/**
+ * A remote server (#61), over HTTP or SSE: nothing runs here. `${user_config.KEY}` and `${VAR}` in
+ * its URL and headers take their values when the session opens.
+ */
+export interface RemoteServer {
+    type: "http" | "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+/** One of an extension's MCP servers, as its `.mcp.json` declares it. */
+export type PluginServer = LocalServer | RemoteServer;
+/** Whether a server is remote (#61). */
+export declare function isRemoteServer(server: PluginServer): server is RemoteServer;
+/**
+ * The name a session gives an extension's remote server: its own, prefixed with the extension's.
+ * The SDK's CLI keeps OAuth tokens by server name (confirmed empirically, CLI 2.1.300): a server
+ * named like one in the runner's own Claude Code would sign in with the runner's token.
+ */
+export declare function remoteServerName(extension: string, server: string): string;
+/** The hosts an extension's remote servers talk to, for the person to read before installing it. */
+export declare function remoteHosts(manifest: Pick<ExternalManifest, "servers">): string[];
 /** How the chat shows one of its tools in one language: `{field}` takes the call's input. */
 export interface ExternalToolLabel {
     label: string;
@@ -49,7 +71,10 @@ 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;
@@ -227,6 +252,7 @@ export declare function addExtension(source: string, scopeDir: string, options?:
     replaced: boolean;
     commit?: string;
     missing: string[];
+    remote: string[];
 }>;
 /**
  * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left