@falkenslab/agent-kit 0.24.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,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,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
@@ -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

package/dist/core/externalExtensions.js

@@ -10,10 +10,37 @@ import { getLanguage } from "./messages/index.js";
 import { truncate } from "./toolLabels.js";
 import { agentKitVersion } from "./version.js";
 import { outsideArchive } from "./packaged.js";
-import { extensionSecretsPath, missingOptions, optionsNamed, parseOptionValue, parseUserConfig, readOptionValues, removeSecrets, storeOptionValues } from "./extensionOptions.js";
+import { extensionSecretsPath, fillOptions, missingOptions, optionsNamed, parseOptionValue, parseUserConfig, readOptionValues, removeSecrets, storeOptionValues } from "./extensionOptions.js";
 import { isTrusted } from "./workspaceTrust.js";
 import { checkRequirements, describeMissing, findOnPath, parseRequirements, requirementsProblem } from "./extensionRequirements.js";
 import { cachedPackageDir, cachedPackageProblem, cachePackage, npxServer, packageCacheDir, packageSpec } from "./npxPackages.js";
+/** Whether a server is remote (#61). */
+export function isRemoteServer(server) {
+    return "url" in server;
+}
+/**
+ * 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 function remoteServerName(extension, server) {
+    return `${extension}-${server}`;
+}
+/** The hosts an extension's remote servers talk to, for the person to read before installing it. */
+export function remoteHosts(manifest) {
+    return [
+        ...new Set(Object.values(manifest.servers).flatMap((server) => {
+            if (!isRemoteServer(server))
+                return [];
+            try {
+                return [new URL(server.url.replace(/\$\{[^}]*\}/g, "x")).host];
+            }
+            catch {
+                return [server.url];
+            }
+        })),
+    ];
+}
 export const LOCK_FILE = "extensions.lock.json";
 /**
  * An installed extension's data folder: `${CLAUDE_PLUGIN_DATA}` in its servers' arguments and
@@ -155,9 +182,20 @@ async function pluginServers(dir, raw) {
         throw new Error("its MCP servers aren't a JSON object.");
     const servers = {};
     for (const [name, server] of Object.entries(declared)) {
+        if (server && (server.type === "http" || server.type === "sse")) {
+            if (typeof server.url !== "string")
+                throw new Error(`its MCP server "${name}" has no url.`);
+            const headers = server.headers && typeof server.headers === "object" ? Object.fromEntries(Object.entries(server.headers).map(([key, value]) => [key, String(value)])) : undefined;
+            servers[name] = { type: server.type, url: server.url, ...(headers ? { headers } : {}) };
+            continue;
+        }
         if (!server || typeof server.command !== "string")
             throw new Error(`its MCP server "${name}" has no command.`);
-        servers[name] = { command: server.command, ...(Array.isArray(server.args) ? { args: server.args.map(String) } : {}), ...(server.env ? { env: server.env } : {}) };
+        servers[name] = {
+            command: server.command,
+            ...(Array.isArray(server.args) ? { args: server.args.map(String) } : {}),
+            ...(server.env ? { env: server.env } : {}),
+        };
     }
     return servers;
 }
@@ -201,6 +239,12 @@ function serverLaunch(name, server, folders, packages = {}) {
  */
 async function serversProblem(manifest, root, packages) {
     for (const [name, server] of Object.entries(manifest.servers)) {
+        if (isRemoteServer(server)) {
+            // Never in clear over the network: plain HTTP only to this computer (a server under development).
+            if (!/^https:\/\//i.test(server.url) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/i.test(server.url))
+                return `talks to its server "${name}" at ${server.url}: a remote server must be https (http only on localhost)`;
+            continue;
+        }
         const npx = npxServer(server);
         if (typeof npx === "string")
             return `${npx} (its server "${name}")`;
@@ -222,6 +266,8 @@ async function serversProblem(manifest, root, packages) {
 async function fetchServerPackages(manifest, cache) {
     const packages = {};
     for (const server of Object.values(manifest.servers)) {
+        if (isRemoteServer(server))
+            continue;
         const npx = npxServer(server);
         if (!npx || typeof npx === "string")
             continue;
@@ -312,8 +358,8 @@ export function extensionLauncherPath() {
     // Node runs it as another process: outside the archive when packaged (#42).
     return outsideArchive(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "extension-launcher.mjs"));
 }
-/** Its tools' chat labels in the kit's language, from its manifest: `{field}` takes the input; for each of its servers. */
-function manifestToolLabels(manifest) {
+/** Its tools' chat labels in the kit's language, from its manifest: `{field}` takes the input; for each of its servers, by their session names. */
+function manifestToolLabels(manifest, sessionServers) {
     const language = getLanguage();
     const fill = (template, input) => template.replace(/\{(\w+)\}/g, (_, field) => (input[field] === undefined ? "" : truncate(String(input[field]), 60)));
     return Object.fromEntries(Object.entries(manifest.labels).flatMap(([tool, byLanguage]) => {
@@ -321,7 +367,7 @@ function manifestToolLabels(manifest) {
         if (!texts)
             return [];
         const label = { label: (input) => fill(texts.label, input), ...(texts.phrase ? { phrase: texts.phrase } : {}) };
-        return Object.keys(manifest.servers).map((server) => [`mcp__${server}__${tool}`, label]);
+        return sessionServers.map((server) => [`mcp__${server}__${tool}`, label]);
     }));
 }
 /** The extension an installed one makes: its servers started through the launcher, its rules from its manifest. */
@@ -334,10 +380,27 @@ function externalExtension(installed, manifest, cache, unavailable = []) {
         ...(unavailable.length ? { unavailable } : {}),
         async contribute() {
             const servers = {};
+            const remote = [];
             if (Object.keys(manifest.servers).length)
                 await mkdir(installed.dataDir, { recursive: true });
+            const folders = { root: installed.dir, data: installed.dataDir };
+            // A remote server's options go into its URL and headers here, when the session opens: the
+            // SDK fixes them then, so a changed value takes opening the session again (#61).
+            const values = Object.values(manifest.servers).some(isRemoteServer) ? await readOptionValues(installed.privateDir, installed.name, manifest.userConfig, installed.lock.options) : {};
             for (const [name, server] of Object.entries(manifest.servers)) {
-                const launch = serverLaunch(name, server, { root: installed.dir, data: installed.dataDir }, { cache, locked: installed.lock.packages });
+                if (isRemoteServer(server)) {
+                    const fill = (text) => fillOptions(expand(text, folders), values);
+                    // A header naming an option without a value isn't sent: `Authorization: Bearer ` would
+                    // turn the server's OAuth off ("OAuth fallback is disabled when headers.Authorization is
+                    // set", confirmed empirically, CLI 2.1.300), so a token stays optional beside signing in.
+                    const unset = (text) => optionsNamed([text]).some((key) => values[key] === undefined || values[key] === "");
+                    const headers = Object.entries(server.headers ?? {}).filter(([, value]) => !unset(value));
+                    const sessionName = remoteServerName(manifest.name, name);
+                    servers[sessionName] = { type: server.type, url: fill(server.url), ...(headers.length ? { headers: Object.fromEntries(headers.map(([key, value]) => [key, fill(value)])) } : {}) };
+                    remote.push(sessionName);
+                    continue;
+                }
+                const launch = serverLaunch(name, server, folders, { cache, locked: installed.lock.packages });
                 if (typeof launch === "string")
                     continue; // checked when it loaded
                 // Its `env` reaches it (the SDK merges it with the agent's); the launcher removes the rest.
@@ -359,9 +422,10 @@ function externalExtension(installed, manifest, cache, unavailable = []) {
                 // Its manifest's list, or its servers' own word: the server is the code the kit trusts
                 // least, so its hints only fill the list's absence (ADR-025).
                 ...(manifest.readOnlyTools
-                    ? { readOnlyTools: Object.keys(manifest.servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)) }
+                    ? { readOnlyTools: Object.keys(servers).flatMap((server) => manifest.readOnlyTools.map((tool) => `mcp__${server}__${tool}`)) }
                     : { readOnlyTools: [], readOnlyHintServers: Object.keys(servers) }),
-                toolLabels: manifestToolLabels(manifest),
+                toolLabels: manifestToolLabels(manifest, Object.keys(servers)),
+                ...(remote.length ? { remoteServers: remote } : {}),
                 ...(manifest.help ? { helpLines: [manifest.help] } : {}),
             };
         },
@@ -373,7 +437,7 @@ function optionDefaults(declared) {
 }
 /** Why its options keep it from running (a server naming one it doesn't declare, a required one without a value), or nothing. */
 function optionsProblem(manifest, values) {
-    const named = optionsNamed(Object.values(manifest.servers).flatMap((server) => [server.command, ...(server.args ?? []), ...Object.values(server.env ?? {}).map(String)]));
+    const named = optionsNamed(Object.values(manifest.servers).flatMap((server) => isRemoteServer(server) ? [server.url, ...Object.values(server.headers ?? {})] : [server.command, ...(server.args ?? []), ...Object.values(server.env ?? {}).map(String)]));
     const undeclared = named.filter((key) => !manifest.userConfig[key]);
     if (undeclared.length)
         return `names ${undeclared.map((key) => "${user_config." + key + "}").join(", ")}, which its userConfig doesn't declare`;
@@ -490,6 +554,8 @@ export async function addExtension(source, scopeDir, options = {}) {
             throw new Error(`${manifest.name} can't be installed: it ${servers}.`);
         // What it needs and this computer lacks: said, never installed, and it installs anyway (#63).
         const missing = (await checkRequirements(manifest.requirements)).filter((check) => !check.ok).map((check) => missingRequirement(check));
+        // Where what the agent sends goes, for the person to know (#61).
+        const remote = remoteHosts(manifest);
         const target = path.join(scopeDir, manifest.name);
         // Replacing what's installed there would delete the source itself.
         if (path.resolve(from) === path.resolve(target))
@@ -516,12 +582,12 @@ export async function addExtension(source, scopeDir, options = {}) {
             }
             lock[manifest.name] = { source: origin, ...provenance, sha256, stored: true, ...locked, enabled: true, installed: new Date().toISOString() };
             await writeLock(scopeDir, lock);
-            return { name: manifest.name, replaced, missing, ...(commit ? { commit } : {}) };
+            return { name: manifest.name, replaced, missing, remote, ...(commit ? { commit } : {}) };
         }
         if (options.link) {
             lock[manifest.name] = { source: from, linked: true, sha256: "", ...locked, enabled: true, installed: new Date().toISOString() };
             await writeLock(scopeDir, lock);
-            return { name: manifest.name, replaced, missing };
+            return { name: manifest.name, replaced, missing, remote };
         }
         await cp(from, target, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
         lock[manifest.name] = {
@@ -533,7 +599,7 @@ export async function addExtension(source, scopeDir, options = {}) {
             installed: new Date().toISOString(),
         };
         await writeLock(scopeDir, lock);
-        return { name: manifest.name, replaced, missing, ...(commit ? { commit } : {}) };
+        return { name: manifest.name, replaced, missing, remote, ...(commit ? { commit } : {}) };
     }
     finally {
         if (clone)

package/dist/core/liveExtensions.d.ts

@@ -47,6 +47,8 @@ export interface LiveExtension {
     capabilities: ExtensionCapability[];
     /** What it can't do on this computer (#63). */
     unavailable: UnavailableCapability[];
+    /** Its remote servers, by session name (#61): their options apply when the session opens, and they may need signing in. */
+    remoteServers: string[];
     help: string[];
 }
 /** The session's own lists the switch keeps in step: the same objects the gates, the chat and the view read. */
@@ -78,3 +80,39 @@ export declare function createExtensionSwitch(extensions: readonly LiveExtension
 export type ExtensionRestart = (name: string) => Promise<boolean>;
 /** The restart for a session's installed extensions. */
 export declare function createExtensionRestart(extensions: readonly LiveExtension[], targets: LiveTargets): ExtensionRestart;
+/** Where signing in to an extension's remote servers stands (#61). */
+export type SignIn = 
+/** Its servers are connected: nothing to sign in to. */
+{
+    status: "signed-in";
+}
+/** The links the person opens to sign in, one per server that needs it. */
+ | {
+    status: "open";
+    links: {
+        server: string;
+        url: string;
+    }[];
+}
+/** It isn't running in this session, has no remote server, or the SDK can't sign in. */
+ | {
+    status: "unavailable";
+    reason: "not-running" | "not-remote" | "unsupported";
+};
+/** Signing in to installed extensions' remote servers, and out (#61). */
+export interface ExtensionAuth {
+    /** The running extensions whose remote servers need the person to sign in. */
+    needed(): Promise<string[]>;
+    /**
+     * Starts signing in to `name`'s servers that need it, giving the links to open: the SDK's CLI
+     * waits for the browser at its localhost callback. With `callbackUrl` (the address the browser
+     * ended on, pasted from another computer), finishes it instead, and reconnects.
+     */
+    signIn(name: string, callbackUrl?: string): Promise<SignIn>;
+    /** Whether all of `name`'s remote servers are connected, waiting up to `timeoutMs` for it. */
+    connected(name: string, timeoutMs?: number): Promise<boolean>;
+    /** Signs out of `name`'s remote servers; false when it can't be done here. */
+    signOut(name: string): Promise<boolean>;
+}
+/** Signing in and out for a session's installed extensions. */
+export declare function createExtensionAuth(extensions: readonly LiveExtension[], targets: Pick<LiveTargets, "controls">): ExtensionAuth;