@falkenslab/agent-kit 0.23.0 → 0.25.0

package/dist/core/externalExtensions.js

@@ -5,15 +5,42 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { capabilitiesProblem, parseCapabilities, providedBy } from "./extensions.js";
+import { capabilitiesProblem, parseCapabilities, parseDescriptions, providedBy } from "./extensions.js";
 import { getLanguage } from "./messages/index.js";
 import { truncate } from "./toolLabels.js";
 import { agentKitVersion } from "./version.js";
 import { outsideArchive } from "./packaged.js";
-import { extensionSecretsPath, missingOptions, optionsNamed, parseOptionValue, parseUserConfig, readOptionValues, removeSecrets, storeOptionValues } from "./extensionOptions.js";
+import { 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
@@ -97,6 +124,7 @@ export async function readExternalManifest(dir) {
     return {
         name,
         description: typeof raw.description === "string" ? raw.description : "",
+        descriptions: parseDescriptions(kit.description),
         ...text("version"),
         ...(author && typeof author === "object" && typeof author.name === "string"
             ? { author: { name: author.name, ...(author.email ? { email: author.email } : {}), ...(author.url ? { url: author.url } : {}) } }
@@ -154,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;
 }
@@ -200,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}")`;
@@ -221,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;
@@ -311,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]) => {
@@ -320,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. */
@@ -333,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.
@@ -358,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] } : {}),
             };
         },
@@ -372,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`;
@@ -489,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))
@@ -515,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] = {
@@ -532,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;

package/dist/core/liveExtensions.js

@@ -97,6 +97,10 @@ export function createExtensionRestart(extensions, targets) {
         const reconnect = targets.controls().reconnectMcpServer;
         if (!extension || !reconnect || !extension.servers.length)
             return false;
+        // A remote server's URL and headers are fixed when the session opens: restarting it would keep
+        // the old values (#61), so its options take opening the session again.
+        if (extension.remoteServers.length)
+            return false;
         try {
             for (const server of extension.servers)
                 await reconnect(server);
@@ -108,6 +112,71 @@ export function createExtensionRestart(extensions, targets) {
         }
     };
 }
+/** Signing in and out for a session's installed extensions. */
+export function createExtensionAuth(extensions, targets) {
+    const remote = (name) => extensions.find((candidate) => candidate.name === name)?.remoteServers ?? [];
+    const statuses = async () => {
+        const status = targets.controls().mcpServerStatus;
+        return new Map(status ? (await status().catch(() => [])).map((server) => [server.name, server.status]) : []);
+    };
+    return {
+        async needed() {
+            const now = await statuses();
+            return extensions.filter((extension) => extension.remoteServers.some((server) => now.get(server) === "needs-auth")).map((extension) => extension.name);
+        },
+        async signIn(name, callbackUrl) {
+            const extension = extensions.find((candidate) => candidate.name === name);
+            if (!extension)
+                return { status: "unavailable", reason: "not-running" };
+            if (!extension.remoteServers.length)
+                return { status: "unavailable", reason: "not-remote" };
+            const controls = targets.controls();
+            const now = await statuses();
+            const pending = extension.remoteServers.filter((server) => now.get(server) === "needs-auth");
+            if (!pending.length)
+                return { status: "signed-in" };
+            if (callbackUrl) {
+                if (!controls.mcpSubmitOAuthCallbackUrl || !controls.reconnectMcpServer)
+                    return { status: "unavailable", reason: "unsupported" };
+                // A pasted callback stores the token, but the session stays needs-auth until the server
+                // reconnects (confirmed empirically, CLI 2.1.300).
+                for (const server of pending) {
+                    await controls.mcpSubmitOAuthCallbackUrl(server, callbackUrl);
+                    await controls.reconnectMcpServer(server);
+                }
+                return (await this.connected(name, 5000)) ? { status: "signed-in" } : { status: "open", links: [] };
+            }
+            if (!controls.mcpAuthenticate)
+                return { status: "unavailable", reason: "unsupported" };
+            const links = [];
+            for (const server of pending) {
+                const started = await controls.mcpAuthenticate(server);
+                if (started.authUrl)
+                    links.push({ server, url: started.authUrl });
+            }
+            return { status: "open", links };
+        },
+        async connected(name, timeoutMs = 0) {
+            const servers = remote(name);
+            for (const start = Date.now();; await new Promise((resolve) => setTimeout(resolve, 500))) {
+                const now = await statuses();
+                if (servers.length && servers.every((server) => now.get(server) === "connected"))
+                    return true;
+                if (Date.now() - start >= timeoutMs)
+                    return false;
+            }
+        },
+        async signOut(name) {
+            const servers = remote(name);
+            const clear = targets.controls().mcpClearAuth;
+            if (!servers.length || !clear)
+                return false;
+            for (const server of servers)
+                await clear(server);
+            return true;
+        },
+    };
+}
 /** The kit's lists, as the extension is now. */
 function follow(extension, enabled, targets) {
     const without = (list, items) => {

package/dist/core/marketplaces.d.ts

@@ -120,4 +120,5 @@ export declare function installFromMarketplace(dir: string, spec: string, scopeD
     commit?: string;
     marketplace: string;
     missing: string[];
+    remote: string[];
 }>;

package/dist/core/messages/de.js

@@ -35,7 +35,7 @@ export const de = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}, in derselben Sitzung)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "aktiviert" : "deaktiviert"}: die Sitzung wird mit derselben Unterhaltung neu geöffnet)`,
     extensionNotInstalled: (name) => `(${name} ist nicht installiert: /extensions listet sie auf)`,
-    extensionsUsage: "(Verwendung: /extensions, enable|disable <Name>, config <Name> [Schlüssel=Wert…], search [Wörter], install <Name>, update [Name], remove <Name> [--delete-data], reload, trust)",
+    extensionsUsage: "(Verwendung: /extensions, enable|disable <Name>, config <Name> [Schlüssel=Wert…], search [Wörter], install <Name>, update [Name], remove <Name> [--delete-data], reload, trust, sign-in <Name> [Rückruf-URL], sign-out <Name>)",
     extensionsCantReopen: "(dieser Chat kann seine Sitzung nicht neu öffnen: im Terminal aktivieren oder deaktivieren und neu starten)",
     extensionOptions: (name) => `Optionen von ${name}:`,
     extensionNoOptions: (name) => `(${name} hat keine Optionen)`,
@@ -51,6 +51,15 @@ export const de = {
     extensionIsInstalled: "(installiert)",
     extensionUpdateAvailable: (installed) => `(installiert: ${installed}, Update verfügbar)`,
     extensionLacks: (name, what) => `(${name}: ${what})`,
+    extensionTalksTo: (name, hosts) => `(${name} spricht mit ${hosts}: was dein Agent dorthin sendet, verlässt diesen Computer)`,
+    extensionNeedsSignIn: (name) => `${name} braucht deine Anmeldung: /extensions sign-in ${name}`,
+    extensionSignInOpen: (name, url) => `(zum Anmelden bei ${name} öffne ${url} : sobald du dort fertig bist, ist sie hier verbunden)`,
+    extensionSignInPaste: (name) => `(auf einem anderen Computer? Füge die Adresse ein, bei der der Browser landet: /extensions sign-in ${name} <diese Adresse>)`,
+    extensionSignedIn: (name) => `(bei ${name} angemeldet: ihre Werkzeuge sind bereit)`,
+    extensionSignInWaiting: (name) => `(warte noch auf die Anmeldung bei ${name}; /extensions sign-in ${name} gibt den Link erneut)`,
+    extensionAlreadySignedIn: (name) => `(${name} ist bereits angemeldet)`,
+    extensionSignInUnavailable: (name) => `(bei ${name} kann man sich hier nicht anmelden: sie läuft nicht in dieser Sitzung, hat keinen entfernten Server, oder das SDK dieses Agenten kann es nicht)`,
+    extensionSignedOut: (name) => `(bei ${name} abgemeldet: sie bittet dich, dich erneut anzumelden)`,
     extensionInstalled: (name) => `(${name} installiert: in einem neuen Gespräch da, oder sofort mit /extensions reload, ohne dieses zu verlieren)`,
     extensionUpdated: (name, from, to) => `(${name} aktualisiert, ${from} → ${to}: in einem neuen Gespräch da, oder sofort mit /extensions reload)`,
     extensionsUpToDate: "(alle Erweiterungen aus einem Marketplace sind aktuell)",

package/dist/core/messages/en.d.ts

@@ -68,6 +68,20 @@ export interface Messages {
     extensionInstalled(name: string): string;
     /** After installing: a program it needs that this computer lacks (#63); `what` is the reason, in English. */
     extensionLacks(name: string, what: string): string;
+    /** After installing one with remote servers (#61): the hosts it talks to. */
+    extensionTalksTo(name: string, hosts: string): string;
+    /** In /extensions: a running extension whose remote server needs the person to sign in. */
+    extensionNeedsSignIn(name: string): string;
+    /** The link to sign in to an extension's remote server. */
+    extensionSignInOpen(name: string, url: string): string;
+    /** How to finish signing in from another computer. */
+    extensionSignInPaste(name: string): string;
+    extensionSignedIn(name: string): string;
+    /** Signing in hasn't finished after a while. */
+    extensionSignInWaiting(name: string): string;
+    extensionAlreadySignedIn(name: string): string;
+    extensionSignInUnavailable(name: string): string;
+    extensionSignedOut(name: string): string;
     extensionUpdated(name: string, from: string, to: string): string;
     extensionsUpToDate: string;
     extensionRemoved(name: string, withData: boolean): string;

package/dist/core/messages/en.js

@@ -34,7 +34,7 @@ export const en = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}, in this same session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "enabled" : "disabled"}: the session reopens, with the same conversation)`,
     extensionNotInstalled: (name) => `(${name} isn't installed: /extensions lists them)`,
-    extensionsUsage: "(usage: /extensions, enable|disable <name>, config <name> [key=value…], search [words], install <name>, update [name], remove <name> [--delete-data], reload, trust)",
+    extensionsUsage: "(usage: /extensions, enable|disable <name>, config <name> [key=value…], search [words], install <name>, update [name], remove <name> [--delete-data], reload, trust, sign-in <name> [callback URL], sign-out <name>)",
     extensionsCantReopen: "(this chat can't reopen its session: enable or disable it from the terminal, and start again)",
     extensionOptions: (name) => `${name}'s options:`,
     extensionNoOptions: (name) => `(${name} has no options)`,
@@ -51,6 +51,15 @@ export const en = {
     extensionUpdateAvailable: (installed) => `(installed: ${installed}, update available)`,
     extensionInstalled: (name) => `(${name} installed: it's there in a new conversation, or now with /extensions reload, keeping this one)`,
     extensionLacks: (name, what) => `(${name} ${what})`,
+    extensionTalksTo: (name, hosts) => `(${name} talks to ${hosts}: what your agent sends there leaves this computer)`,
+    extensionNeedsSignIn: (name) => `${name} needs you to sign in: /extensions sign-in ${name}`,
+    extensionSignInOpen: (name, url) => `(to sign in to ${name}, open ${url} : when you're done there, it's connected here)`,
+    extensionSignInPaste: (name) => `(on another computer? Paste the address the browser ends on: /extensions sign-in ${name} <that address>)`,
+    extensionSignedIn: (name) => `(signed in to ${name}: its tools are ready)`,
+    extensionSignInWaiting: (name) => `(still waiting for the sign-in to ${name}; /extensions sign-in ${name} gives the link again)`,
+    extensionAlreadySignedIn: (name) => `(${name} is already signed in)`,
+    extensionSignInUnavailable: (name) => `(${name} can't be signed in to here: it isn't running in this session, has no remote server, or this agent's SDK can't sign in)`,
+    extensionSignedOut: (name) => `(signed out of ${name}: it will ask you to sign in again)`,
     extensionUpdated: (name, from, to) => `(${name} updated, ${from} → ${to}: it's there in a new conversation, or now with /extensions reload)`,
     extensionsUpToDate: "(every extension from a marketplace is up to date)",
     extensionRemoved: (name, withData) => `(${name} removed${withData ? ", with its data" : "; its data is kept for a reinstall"})`,

package/dist/core/messages/es.js

@@ -35,7 +35,7 @@ export const es = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}, en esta misma sesión)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activada" : "desactivada"}: la sesión se reabre, con la misma conversación)`,
     extensionNotInstalled: (name) => `(${name} no está instalada: /extensions las lista)`,
-    extensionsUsage: "(uso: /extensions, enable|disable <nombre>, config <nombre> [clave=valor…], search [palabras], install <nombre>, update [nombre], remove <nombre> [--delete-data], reload, trust)",
+    extensionsUsage: "(uso: /extensions, enable|disable <nombre>, config <nombre> [clave=valor…], search [palabras], install <nombre>, update [nombre], remove <nombre> [--delete-data], reload, trust, sign-in <nombre> [URL de vuelta], sign-out <nombre>)",
     extensionsCantReopen: "(este chat no puede reabrir su sesión: actívala o desactívala desde la terminal y vuelve a empezar)",
     extensionOptions: (name) => `Opciones de ${name}:`,
     extensionNoOptions: (name) => `(${name} no tiene opciones)`,
@@ -51,6 +51,15 @@ export const es = {
     extensionIsInstalled: "(instalada)",
     extensionUpdateAvailable: (installed) => `(instalada: ${installed}, hay actualización)`,
     extensionLacks: (name, what) => `(${name}: ${what})`,
+    extensionTalksTo: (name, hosts) => `(${name} habla con ${hosts}: lo que tu agente le envíe sale de este ordenador)`,
+    extensionNeedsSignIn: (name) => `${name} necesita que inicies sesión: /extensions sign-in ${name}`,
+    extensionSignInOpen: (name, url) => `(para iniciar sesión en ${name}, abre ${url} : cuando termines allí, queda conectada aquí)`,
+    extensionSignInPaste: (name) => `(¿en otro ordenador? Pega la dirección en la que acaba el navegador: /extensions sign-in ${name} <esa dirección>)`,
+    extensionSignedIn: (name) => `(sesión iniciada en ${name}: sus herramientas están listas)`,
+    extensionSignInWaiting: (name) => `(sigo esperando el inicio de sesión en ${name}; /extensions sign-in ${name} vuelve a dar el enlace)`,
+    extensionAlreadySignedIn: (name) => `(${name} ya tiene la sesión iniciada)`,
+    extensionSignInUnavailable: (name) => `(no se puede iniciar sesión en ${name} aquí: no se ejecuta en esta sesión, no tiene servidor remoto, o el SDK de este agente no sabe hacerlo)`,
+    extensionSignedOut: (name) => `(sesión cerrada en ${name}: te pedirá que vuelvas a iniciarla)`,
     extensionInstalled: (name) => `(${name} instalada: está en una conversación nueva, o ya con /extensions reload, sin perder esta)`,
     extensionUpdated: (name, from, to) => `(${name} actualizada, ${from} → ${to}: está en una conversación nueva, o ya con /extensions reload)`,
     extensionsUpToDate: "(todas las extensiones de un marketplace están al día)",

package/dist/core/messages/fr.js

@@ -35,7 +35,7 @@ export const fr = {
     extensionSwitched: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"}, dans cette même session)`,
     extensionToggled: (name, enabled) => `(${name} ${enabled ? "activée" : "désactivée"} : la session se rouvre, avec la même conversation)`,
     extensionNotInstalled: (name) => `(${name} n'est pas installée : /extensions les liste)`,
-    extensionsUsage: "(usage : /extensions, enable|disable <nom>, config <nom> [clé=valeur…], search [mots], install <nom>, update [nom], remove <nom> [--delete-data], reload, trust)",
+    extensionsUsage: "(usage : /extensions, enable|disable <nom>, config <nom> [clé=valeur…], search [mots], install <nom>, update [nom], remove <nom> [--delete-data], reload, trust, sign-in <nom> [URL de retour], sign-out <nom>)",
     extensionsCantReopen: "(ce chat ne peut pas rouvrir sa session : activez-la ou désactivez-la depuis le terminal, puis recommencez)",
     extensionOptions: (name) => `Options de ${name} :`,
     extensionNoOptions: (name) => `(${name} n'a pas d'options)`,
@@ -51,6 +51,15 @@ export const fr = {
     extensionIsInstalled: "(installée)",
     extensionUpdateAvailable: (installed) => `(installée : ${installed}, mise à jour disponible)`,
     extensionLacks: (name, what) => `(${name} : ${what})`,
+    extensionTalksTo: (name, hosts) => `(${name} échange avec ${hosts} : ce que votre agent y envoie quitte cet ordinateur)`,
+    extensionNeedsSignIn: (name) => `${name} a besoin que vous vous connectiez : /extensions sign-in ${name}`,
+    extensionSignInOpen: (name, url) => `(pour vous connecter à ${name}, ouvrez ${url} : une fois terminé là-bas, elle est connectée ici)`,
+    extensionSignInPaste: (name) => `(sur un autre ordinateur ? Collez l'adresse où le navigateur arrive : /extensions sign-in ${name} <cette adresse>)`,
+    extensionSignedIn: (name) => `(connecté à ${name} : ses outils sont prêts)`,
+    extensionSignInWaiting: (name) => `(toujours en attente de la connexion à ${name} ; /extensions sign-in ${name} redonne le lien)`,
+    extensionAlreadySignedIn: (name) => `(${name} est déjà connectée)`,
+    extensionSignInUnavailable: (name) => `(impossible de se connecter à ${name} ici : elle ne tourne pas dans cette session, n'a pas de serveur distant, ou le SDK de cet agent ne sait pas le faire)`,
+    extensionSignedOut: (name) => `(déconnecté de ${name} : elle vous demandera de vous reconnecter)`,
     extensionInstalled: (name) => `(${name} installée : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload, en gardant celle-ci)`,
     extensionUpdated: (name, from, to) => `(${name} mise à jour, ${from} → ${to} : elle est là dans une nouvelle conversation, ou dès maintenant avec /extensions reload)`,
     extensionsUpToDate: "(toutes les extensions d'un marketplace sont à jour)",

package/dist/core/npxPackages.d.ts

@@ -1,4 +1,4 @@
-import type { ExtensionDirs, PluginServer } from "./externalExtensions.js";
+import type { ExtensionDirs, LocalServer } from "./externalExtensions.js";
 /**
  * Installed extensions' servers run with `npx` (#54): a `.mcp.json` that says
  * `npx -y <package>@<x.y.z>` runs as it is in Claude Code, and in the kit too, which doesn't run
@@ -32,7 +32,7 @@ export declare const packageSpec: (server: NpxServer) => string;
  * does but not as the kit can, or its package. Its command is `npx` (`npx.cmd`), its options
  * only `-y`/`--yes`, then `<package>@<x.y.z>` and the server's own arguments.
  */
-export declare function npxServer(server: PluginServer): NpxServer | string | undefined;
+export declare function npxServer(server: LocalServer): NpxServer | string | undefined;
 /** Where an agent keeps the packages its extensions' npx servers run: in its scope (the project's when it has none), shared by both. */
 export declare function packageCacheDir(dirs: ExtensionDirs): string | undefined;
 /** A package's folder in the cache. */

package/dist/core/runner.js

@@ -19,6 +19,22 @@ export function toolResultText(content) {
         .map((part) => part.text)
         .join("\n");
 }
+/**
+ * The SDK's sign-in methods for a remote MCP server behind OAuth, when its `Query` has them: they
+ * aren't in its typings (confirmed empirically, SDK 0.3.300; ADR-028), so each is checked first.
+ */
+function signInControls(result) {
+    const methods = result;
+    const call = (name) => (typeof methods[name] === "function" ? (...args) => methods[name].apply(result, args) : undefined);
+    const authenticate = call("mcpAuthenticate");
+    const submit = call("mcpSubmitOAuthCallbackUrl");
+    const clear = call("mcpClearAuth");
+    return {
+        ...(authenticate ? { mcpAuthenticate: (server) => authenticate(server) } : {}),
+        ...(submit ? { mcpSubmitOAuthCallbackUrl: (server, callbackUrl) => submit(server, callbackUrl) } : {}),
+        ...(clear ? { mcpClearAuth: (server) => clear(server) } : {}),
+    };
+}
 /**
  * Thin wrapper around the SDK's own `query()`: same two-argument shape (a plain string
  * for a one-shot run, or an `AsyncIterable<SDKUserMessage>` — see `createInputQueue()` —
@@ -38,6 +54,7 @@ export function runQuery(prompt, options) {
         reloadPlugins: () => result.reloadPlugins(),
         reconnectMcpServer: (server) => result.reconnectMcpServer(server),
         mcpServerStatus: () => result.mcpServerStatus(),
+        ...signInControls(result),
     });
     // The main agent's tool calls by id, to name the results that come back for them.
     const toolNames = new Map();

package/dist/core/session.d.ts

@@ -1,4 +1,4 @@
-import type { Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { McpServerStatus, Options, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import { type TranscriptLogger } from "./hooks/transcriptLogger.js";
 import { type ModeControl } from "./modeControl.js";
 import { type AboutExtension } from "./extensions.js";
@@ -7,7 +7,7 @@ import type { ToolLabels } from "./toolLabels.js";
 import type { AgentSpec, BaseSessionConfig } from "./agentSpec.js";
 import { type Language } from "./language.js";
 import { type RunFolder } from "./runs.js";
-import { type ExtensionRestart, type ExtensionSwitch } from "./liveExtensions.js";
+import { type ExtensionAuth, type ExtensionRestart, type ExtensionSwitch } from "./liveExtensions.js";
 /**
  * Builds the `options` object passed to the Agent SDK's `query()` — everything about
  * *how* the agent runs a session (system prompt, tools, MCP servers, hooks), independent
@@ -47,6 +47,8 @@ export declare function buildSessionOptions<TConfig extends BaseSessionConfig>(c
     switchExtension: ExtensionSwitch;
     /** Restarts an installed extension's servers in the running session, with its options as they are now (#55). */
     restartExtension: ExtensionRestart;
+    /** Signing in to installed extensions' remote servers, and out (#61). */
+    extensionAuth: ExtensionAuth;
 }>;
 export { createModeControl, togglePlanMode, type ModeControl } from "./modeControl.js";
 /** The extensions of a session: where they're installed, what's installed, what runs and what can't (with why). */
@@ -73,6 +75,8 @@ export interface ExtensionsStatus {
     }[];
     /** The running session's tools, as the model names them (empty until it has started): what a capability's tools are checked against. */
     sessionTools?: () => readonly string[];
+    /** Its MCP servers as they are now (empty until it has started): which remote ones need signing in (#61). */
+    serverStatus?: () => Promise<McpServerStatus[]>;
 }
 /**
  * The CLI's folder for a project, where it keeps each session's transcript and large tool

package/dist/core/session.js

@@ -22,7 +22,7 @@ import { replyLanguageInstruction } from "./language.js";
 import { chooseLanguage } from "./messages/index.js";
 import { createRunStore } from "./runs.js";
 import { createSessionView, registerSessionView } from "./sessionFacts.js";
-import { createExtensionRestart, createExtensionSwitch, mountPlugin } from "./liveExtensions.js";
+import { createExtensionAuth, createExtensionRestart, createExtensionSwitch, mountPlugin } from "./liveExtensions.js";
 import { secretsDir } from "./extensionOptions.js";
 import { createElicitationHandler } from "./elicitation.js";
 import { createReadOnlyHints } from "./readOnlyHints.js";
@@ -358,6 +358,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
         active: resolved.active.map(({ extension }) => extension.name),
         about: Object.fromEntries(resolved.active.map(({ extension, manifest, unavailable }, index) => [extension.name, aboutExtension(manifest, Object.keys(added[index]?.mcpServers ?? {}), language, unavailable)])),
         sessionTools: () => late.view?.controls().tools ?? [],
+        serverStatus: async () => (await late.view?.controls().mcpServerStatus?.().catch(() => [])) ?? [],
         inactive: resolved.inactive,
     };
     // What the session is, for the extensions that ask (sessionFacts.ts, #43).
@@ -405,6 +406,7 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
                 provides: manifest.provides,
                 capabilities: manifest.capabilities,
                 unavailable,
+                remoteServers: contribution?.remoteServers ?? [],
                 help: contribution?.helpLines ?? [],
             },
         ];
@@ -412,8 +414,9 @@ export async function buildSessionOptions(config, runDir, spec, options = {}) {
     const liveTargets = { readOnlyTools, allowedSubagentTypes, toolLabels, status: extensions, facts: viewBase, controls: () => late.view?.controls() ?? {} };
     const switchExtension = createExtensionSwitch(liveExtensions, liveTargets);
     const restartExtension = createExtensionRestart(liveExtensions, liveTargets);
+    const extensionAuth = createExtensionAuth(liveExtensions, liveTargets);
     const apis = Object.fromEntries(resolved.active.flatMap(({ extension }, index) => (added[index]?.api ? [[extension.name, added[index].api]] : [])));
-    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, switchExtension, restartExtension };
+    return { options: sdkOptions, transcriptLogger, transcriptPath, modeControl, language, toolLabels, extensions, apis, switchExtension, restartExtension, extensionAuth };
 }
 export { createModeControl, togglePlanMode } from "./modeControl.js";
 /** The Claude Code configuration folder the SDK's CLI uses: `CLAUDE_CONFIG_DIR`, or `~/.claude`. */

package/dist/core/sessionFacts.d.ts

@@ -71,6 +71,20 @@ export interface SessionLive {
     reconnectMcpServer?: (server: string) => Promise<void>;
     /** Its MCP servers as they are now: their tools and what each says of itself (plan mode's read-only hints). */
     mcpServerStatus?: () => Promise<McpServerStatus[]>;
+    /**
+     * Signing in to a remote server behind OAuth (#61): the SDK's `Query` has these, undocumented
+     * (in `sdk.mjs`, not in `sdk.d.ts`; confirmed empirically, SDK 0.3.300). Attached only when they
+     * exist, so a session whose SDK lacks them just can't sign in.
+     */
+    mcpAuthenticate?: (server: string) => Promise<McpAuthentication>;
+    mcpSubmitOAuthCallbackUrl?: (server: string, callbackUrl: string) => Promise<unknown>;
+    mcpClearAuth?: (server: string) => Promise<unknown>;
+}
+/** What starting a remote server's sign-in gives (the SDK's `mcpAuthenticate()`): the link for the person, and whether the CLI waits for its localhost callback. */
+export interface McpAuthentication {
+    authUrl?: string;
+    requiresUserAction?: boolean;
+    callbackExpected?: boolean;
 }
 /** The facts known when the options are built: everything but the mode and what only the running session knows. */
 export type StaticSessionFacts = Omit<SessionFacts, "mode" | "switchableModes" | "tools" | "commands" | "context" | "extensions"> & {

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

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { BaseSessionConfig } from "../../core/agentSpec.js";
+import type { SessionFacts } from "../../core/sessionFacts.js";
+/** The awareness's catalog tool, over the agent's extension folders and its own marketplace and topics. */
+export declare function createCatalogTool(config: BaseSessionConfig, session: () => Promise<SessionFacts>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    words: z.ZodOptional<z.ZodString>;
+    refresh: z.ZodOptional<z.ZodBoolean>;
+}>;