@falkenslab/agent-kit 0.24.0 → 0.26.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,6 +35,13 @@ 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}`) : "";
@@ -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,12 @@ 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)));
+        // The claude.ai connectors the agent lets in, apart from installed extensions (#70).
+        if (status?.connectors?.allowed.length)
+            lines.push(t().connectorsAllowed(status.connectors.allowed.map((name) => name.replace(/^claude\.ai /, "")).join(", ")));
+        if (status?.connectors?.missing.length)
+            lines.push(t().connectorsMissing(status.connectors.missing.join(", ")));
         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/agentSpec.d.ts

@@ -44,6 +44,22 @@ export interface BaseSessionConfig {
      * catalog and `extension search` show only those with one of them. Without it, every one.
      */
     catalogTopics?: string[];
+    /**
+     * The claude.ai connectors of the person's account this agent lets in (#70), by the name
+     * claude.ai shows them (`["Canva", "Notion"]`, any case): those already signed in on claude.ai,
+     * nothing to install. None by default: the kit keeps them out, since they're the account's
+     * integrations, not the agent's. When the session opens, the kit asks the account which it has
+     * (a few seconds) and lets in only these; one asked for that isn't there is said in `/extensions`.
+     */
+    claudeAiConnectors?: string[];
+    /**
+     * What a call to a remote MCP server does (#70): an installed extension's `http`/`sse` server, one
+     * of the agent's own, or a claude.ai connector. What the model sends one leaves the computer, so
+     * an agent handling sensitive data (students') may keep it from them. `"allow"` (the default)
+     * lets it go on; `"ask"` asks the person before each call, saying where it goes (blocked when no
+     * one can be asked, as in autonomous mode); `"deny"` blocks it.
+     */
+    remoteServers?: "allow" | "ask" | "deny";
     /**
      * Directories where the agent reads, searches and writes with the file tools (Write/Edit,
      * scoped — see hooks/fileScopeGate.ts), e.g. a folder of its own notes. Setting one gives the

package/dist/core/claudeAiConnectors.d.ts

@@ -0,0 +1,35 @@
+import { type Options } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * The claude.ai connectors an agent lets in (#70): the person's account's integrations (Canva,
+ * Notion…), which the kit keeps out by default (`disableClaudeAiConnectors`, ADR-018). The SDK
+ * lets them in all or none, and lets one out only by its name (`deniedMcpServers`); an allowlist
+ * would have to list every other server of the session exactly (confirmed empirically, CLI
+ * 2.1.300). So the kit asks the account which it has, when the session opens, and denies by name
+ * the ones the agent didn't choose; a gate blocks a call to any other (one added since).
+ *
+ * `toggleMcpServer()` is never used for them: it saves the switch in the person's own Claude Code
+ * config for the folder (`~/.claude.json`, `disabledMcpServers`), not only in the session
+ * (confirmed empirically, CLI 2.1.300).
+ */
+/** The name the SDK gives a claude.ai connector's server: `claude.ai <Name>`. */
+export declare const CONNECTOR_PREFIX = "claude.ai ";
+/** The prefix of a server's tools as the model names them: `claude.ai Claude Docs` → `mcp__claude_ai_Claude_Docs__`. */
+export declare function serverToolPrefix(server: string): string;
+/** Whether a tool is a claude.ai connector's. */
+export declare function isConnectorTool(tool: string): boolean;
+/** What the agent chose, set against what the account has: the servers to let in, to deny, and the names it asked for that aren't there. */
+export interface ConnectorChoice {
+    allowed: string[];
+    denied: string[];
+    missing: string[];
+}
+/** Chooses among the account's connectors (`found`, as the SDK names them) the ones the agent wants, by the name claude.ai shows (any case). */
+export declare function chooseConnectors(found: readonly string[], wanted: readonly string[]): ConnectorChoice;
+/**
+ * The account's claude.ai connectors, by the names the SDK gives them: a session that sends no
+ * message, opened in `cwd` with connectors on, its servers' status read and closed. A few seconds;
+ * an empty list when it can't tell (no login, no network), so nothing is let in.
+ */
+export declare function discoverConnectors(cwd: string, options?: Pick<Options, "pathToClaudeCodeExecutable" | "env"> & {
+    timeoutMs?: number;
+}): Promise<string[]>;

package/dist/core/claudeAiConnectors.js

@@ -0,0 +1,76 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * The claude.ai connectors an agent lets in (#70): the person's account's integrations (Canva,
+ * Notion…), which the kit keeps out by default (`disableClaudeAiConnectors`, ADR-018). The SDK
+ * lets them in all or none, and lets one out only by its name (`deniedMcpServers`); an allowlist
+ * would have to list every other server of the session exactly (confirmed empirically, CLI
+ * 2.1.300). So the kit asks the account which it has, when the session opens, and denies by name
+ * the ones the agent didn't choose; a gate blocks a call to any other (one added since).
+ *
+ * `toggleMcpServer()` is never used for them: it saves the switch in the person's own Claude Code
+ * config for the folder (`~/.claude.json`, `disabledMcpServers`), not only in the session
+ * (confirmed empirically, CLI 2.1.300).
+ */
+/** The name the SDK gives a claude.ai connector's server: `claude.ai <Name>`. */
+export const CONNECTOR_PREFIX = "claude.ai ";
+/** The prefix of a server's tools as the model names them: `claude.ai Claude Docs` → `mcp__claude_ai_Claude_Docs__`. */
+export function serverToolPrefix(server) {
+    return `mcp__${server.replace(/[^A-Za-z0-9_-]/g, "_")}__`;
+}
+/** Whether a tool is a claude.ai connector's. */
+export function isConnectorTool(tool) {
+    // `claude.ai <Name>` becomes `mcp__claude_ai_<Name>__`: the prefix up to the name.
+    return tool.startsWith("mcp__claude_ai_");
+}
+/** Chooses among the account's connectors (`found`, as the SDK names them) the ones the agent wants, by the name claude.ai shows (any case). */
+export function chooseConnectors(found, wanted) {
+    const label = (server) => (server.startsWith(CONNECTOR_PREFIX) ? server.slice(CONNECTOR_PREFIX.length) : server).toLowerCase();
+    const asked = new Set(wanted.map(label));
+    const allowed = found.filter((server) => asked.has(label(server)));
+    const present = new Set(allowed.map(label));
+    return { allowed, denied: found.filter((server) => !asked.has(label(server))), missing: wanted.filter((name) => !present.has(label(name))) };
+}
+/**
+ * The account's claude.ai connectors, by the names the SDK gives them: a session that sends no
+ * message, opened in `cwd` with connectors on, its servers' status read and closed. A few seconds;
+ * an empty list when it can't tell (no login, no network), so nothing is let in.
+ */
+export async function discoverConnectors(cwd, options = {}) {
+    let release = () => { };
+    const done = new Promise((resolve) => (release = resolve));
+    // A conversation that never sends a message, ended when the look is over: the session only starts its servers.
+    const prompt = { [Symbol.asyncIterator]: () => ({ next: () => done.then(() => ({ done: true, value: undefined })) }) };
+    const session = query({
+        prompt,
+        options: {
+            cwd,
+            settingSources: ["project"],
+            tools: [],
+            settings: { autoMemoryEnabled: false, disableClaudeAiConnectors: false },
+            ...(options.pathToClaudeCodeExecutable ? { pathToClaudeCodeExecutable: options.pathToClaudeCodeExecutable } : {}),
+            ...(options.env ? { env: options.env } : {}),
+        },
+    });
+    void (async () => {
+        for await (const message of session)
+            void message;
+    })().catch(() => undefined);
+    try {
+        const connectors = async () => (await session.mcpServerStatus()).filter((server) => server.scope === "claudeai" || server.name.startsWith(CONNECTOR_PREFIX));
+        // Connectors come from the account after the session starts: wait until none is pending.
+        const deadline = Date.now() + (options.timeoutMs ?? 10_000);
+        let found = await connectors().catch(() => []);
+        while (Date.now() < deadline && (!found.length || found.some((server) => server.status === "pending"))) {
+            await new Promise((resolve) => setTimeout(resolve, 400));
+            found = await connectors().catch(() => []);
+        }
+        return found.map((server) => server.name);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        release();
+        session.close();
+    }
+}

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
@@ -42,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<{
@@ -72,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,7 +1,7 @@
 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, describeInLanguage } from "./extensions.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,16 +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 }));
-            const description = describeInLanguage(plugin.description ?? manifest?.description ?? "", manifest?.descriptions, getLanguage());
-            return { ...(version ? { version } : {}), keywords: manifest?.keywords ?? [], ...(logo ? { logo } : {}), ...(banner ? { banner } : {}), capabilities, requirements, description };
+            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: [], description: plugin.description ?? "" };
+    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) {
@@ -83,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());
@@ -92,7 +93,7 @@ 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;
@@ -117,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. */

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;
@@ -230,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