@falkenslab/agent-kit 0.24.0 → 0.25.0

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>;
+}>;

package/dist/extensions/awareness/catalog.js

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

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

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

package/dist/extensions/awareness/index.js

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

package/dist/extensions/awareness/labels.js

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

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

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

package/dist/extensions/awareness/tools.js

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

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withTo
 export type { Mode, BaseSessionConfig, AgentSpec, AgentIdentity, PlanModeSpec } from "./core/agentSpec.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode, type ModeControl, type ExtensionsStatus } from "./core/session.js";
 export { runQuery, type AgentEvent, type AgentRun, type SessionUsage, type ContextUsage } from "./core/runner.js";
-export type { SessionFacts } from "./core/sessionFacts.js";
+export type { McpAuthentication, SessionFacts } from "./core/sessionFacts.js";
 export { knowledgePluginRoot, knowledgePromptSection } from "./extensions/knowledge/prompt.js";
 export { awareness, type AwarenessOptions } from "./extensions/awareness/index.js";
 export { sources, type SourcesOptions } from "./extensions/sources/index.js";
@@ -17,9 +17,9 @@ export { knowledge, type KnowledgeOptions } from "./extensions/knowledge/index.j
 export { memory, type MemoryOptions } from "./extensions/memory/index.js";
 export { describeCapability, readExtensionManifest, type AboutExtension, type CapabilityText, type DescribedCapability, type Extension, type ExtensionCapability, type ExtensionContext, type ExtensionContribution, type ExtensionManifest, type FolderOption, type UnavailableCapability, } from "./core/extensions.js";
 export { checkRequirements, type ExtensionRequirement, type RequirementCheck } from "./core/extensionRequirements.js";
-export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type InstalledExtension, type LockEntry, type ExtensionOptionState, } from "./core/externalExtensions.js";
+export { addExtension, codeStoreDir, installTarget, scopePrivateDir, extensionDataDir, extensionOptionStates, setExtensionOptions, removeExtension, setExtensionEnabled, listInstalled, readExternalManifest, type ExtensionAuthor, type ExtensionDirs, type ExtensionScope, type ExternalManifest, type ExternalToolLabel, type PluginServer, type LocalServer, type RemoteServer, isRemoteServer, remoteHosts, remoteServerName, type InstalledExtension, type LockEntry, type ExtensionOptionState, } from "./core/externalExtensions.js";
 export type { ExtensionOption, OptionValue } from "./core/extensionOptions.js";
-export type { ExtensionRestart, ExtensionSwitch } from "./core/liveExtensions.js";
+export type { ExtensionAuth, ExtensionRestart, ExtensionSwitch, SignIn } from "./core/liveExtensions.js";
 export { packageCacheDir, type CachedPackage } from "./core/npxPackages.js";
 export { addMarketplace, findPlugin, inspectMarketplace, installFromMarketplace, listMarketplaces, readMarketplaceManifest, removeMarketplace, resolvePluginSource, updateMarketplace, type KnownMarketplace, type MarketplaceManifest, type MarketplacePlugin, type PluginSource, } from "./core/marketplaces.js";
 export { extensionCatalog, installExtension, restoreExtensions, updateExtension, type CatalogEntry } from "./core/extensionCatalog.js";