@falkenslab/agent-kit 0.31.0 → 0.33.0

package/dist/core/claudeAuth.js

@@ -1,27 +1,140 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { claudeBinaryRequests, unpackedClaudeExecutable } from "./packaged.js";
+/*
+ * Signing in to Claude without ever touching a credential (ADR-009, #90). Anthropic's terms
+ * (https://code.claude.com/docs/en/legal-and-compliance, "Authentication and credential use")
+ * say an Agent SDK developer may not collect, store or intermediate Claude.ai credentials or
+ * session tokens: a Claude account signs in through Anthropic's own flow, in the unmodified
+ * Claude Code binary. The SDK ships that binary, so the kit runs its `auth status` and
+ * `auth login` and nothing else: the binary opens Anthropic's page and keeps the credentials
+ * itself (`~/.claude/.credentials.json`, the Keychain on macOS), where the SDK's sessions find
+ * them. The kit never reads, returns or stores a token. An API key (`ANTHROPIC_API_KEY`) is
+ * allowed, and so is a person's own `CLAUDE_CODE_OAUTH_TOKEN`: both are their setting, not
+ * something the kit collects.
+ */
 /**
- * Pure lookup, no I/O and no console output of any kind — safe to call from a
- * headless/non-interactive consumer (a server, an Electron main process) as much as from a
- * terminal one.
- *
- * Checks, in order: `ANTHROPIC_API_KEY` (a complete authentication path on its own — API
- * billing instead of subscription, so nothing else is checked when it's set),
- * `CLAUDE_CODE_OAUTH_TOKEN`, then `config.claudeCodeOAuthToken` if the caller passed one.
- * Returns `true` and (for the `config` case) sets `CLAUDE_CODE_OAUTH_TOKEN` on the process
- * as a side effect once a token is found — the SDK's own subprocess reads that env var
- * directly, never anything this kit passes it explicitly; `false` when none of the three
- * has one. Getting a token in that case (e.g. by walking the user through
- * `claude setup-token`) is a terminal-UX concern, not this function's — see
- * `ensureClaudeAuth()` in tui/claudeAuth.ts, which calls this first and only falls back to
- * that interactive flow when it returns `false`.
+ * The Claude Code binary the Agent SDK ships (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>`),
+ * unmodified: the copy unpacked next to the archive when the agent runs packaged, or else the
+ * one resolved from `node_modules` as the SDK resolves it. `undefined` when it isn't installed.
+ * `resolve` and the platform are replaceable for tests.
  */
-export function resolveClaudeAuth(config = {}) {
-    if (process.env.ANTHROPIC_API_KEY)
-        return true;
-    if (process.env.CLAUDE_CODE_OAUTH_TOKEN)
-        return true;
-    if (config.claudeCodeOAuthToken) {
-        process.env.CLAUDE_CODE_OAUTH_TOKEN = config.claudeCodeOAuthToken;
+export function claudeExecutable(resolve = createRequire(import.meta.url).resolve, platform = process.platform, arch = process.arch) {
+    const unpacked = unpackedClaudeExecutable(resolve, platform, arch);
+    if (unpacked)
+        return unpacked;
+    for (const request of claudeBinaryRequests(platform, arch)) {
+        try {
+            const file = resolve(request);
+            if (existsSync(file))
+                return file;
+        }
+        catch {
+            // That package isn't installed: the next one.
+        }
+    }
+    return undefined;
+}
+/** The binary and its arguments as a process to spawn: a JavaScript file runs with this Node. */
+export function claudeCommand(executable, args) {
+    return /\.(c|m)?js$/i.test(executable) ? { file: process.execPath, args: [executable, ...args] } : { file: executable, args };
+}
+/**
+ * Whether the agent can reach Claude: true when the person's environment has `ANTHROPIC_API_KEY`
+ * or `CLAUDE_CODE_OAUTH_TOKEN` (their own setting); otherwise what the Claude Code binary says
+ * (`claude auth status --json`, its `loggedIn`). Never reads the credentials file, and prints
+ * nothing: safe from a server or an Electron main process. False when there is no binary.
+ */
+export async function claudeSignedIn(options = {}) {
+    if (process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN)
         return true;
+    const executable = options.executable ?? claudeExecutable();
+    if (!executable)
+        return false;
+    const command = claudeCommand(executable, ["auth", "status", "--json"]);
+    // Exit code 1 when signed out, with the same JSON (confirmed empirically): read it either way.
+    const output = await new Promise((resolve) => {
+        execFile(command.file, command.args, { timeout: 30_000, windowsHide: true }, (_error, stdout) => resolve(String(stdout ?? "")));
+    });
+    try {
+        return JSON.parse(output).loggedIn === true;
     }
-    return false;
+    catch {
+        return false;
+    }
+}
+/**
+ * Signs the person in to their Claude account through Anthropic's own flow, for a host without a
+ * terminal (a web page, a desktop app): runs `claude auth login` (`console: true` for an
+ * Anthropic Console account, billed by API usage) with plain pipes. The binary opens the browser
+ * itself; the host shows `url` as a link in case it didn't, and a box for the code Anthropic's
+ * page shows (`sendCode`). The binary keeps the credentials: the kit never sees a token. Throws
+ * when the binary isn't installed.
+ *
+ * Confirmed empirically (Claude Code 2.1.310): without a TTY, `auth login` prints "If the browser
+ * didn't open, visit: <url>" (the URL may come wrapped in OSC 8 hyperlink escapes) and then waits
+ * at "Paste code here if prompted >".
+ */
+export function startClaudeSignIn(options = {}) {
+    const executable = options.executable ?? claudeExecutable();
+    if (!executable)
+        throw new Error("Claude Code's binary, which the Agent SDK ships (@anthropic-ai/claude-agent-sdk-<platform>-<arch>), isn't installed.");
+    const command = claudeCommand(executable, ["auth", "login", ...(options.console ? ["--console"] : [])]);
+    const child = spawn(command.file, command.args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    let output = "";
+    let resolveUrl;
+    const url = new Promise((resolve) => (resolveUrl = resolve));
+    const read = (chunk) => {
+        output += chunk.toString("utf8");
+        // Anthropic's page as soon as it's all there; any other URL only once the binary has ended.
+        const found = signInUrl(output);
+        if (found?.includes("/oauth/authorize"))
+            resolveUrl(found);
+    };
+    child.stdout?.on("data", read);
+    child.stderr?.on("data", read);
+    // A write after the binary ended fails on the stream: nothing to tell then.
+    child.stdin?.on("error", () => { });
+    const ended = new Promise((resolve) => {
+        child.on("error", () => resolve());
+        child.on("close", () => resolve());
+    });
+    const done = ended.then(() => {
+        resolveUrl(signInUrl(output, true));
+        return claudeSignedIn(options);
+    });
+    return {
+        url,
+        sendCode(code) {
+            if (child.stdin?.writable)
+                child.stdin.write(`${code.trim()}\n`);
+        },
+        done,
+        cancel() {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill();
+        },
+    };
+}
+// An OSC sequence (a hyperlink's `ESC ] 8 ; ; URL ESC \`, a title), ended by BEL or ST.
+// eslint-disable-next-line no-control-regex -- ESC and BEL delimit terminal escapes, on purpose
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+// A CSI sequence (colors, cursor moves).
+// eslint-disable-next-line no-control-regex -- ESC starts the sequence
+const CSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex -- an OSC 8 hyperlink's target, between ESC/BEL delimiters
+const HYPERLINK_TARGET = /\x1b\]8;[^;\x07\x1b]*;(https:\/\/[^\x07\x1b]+)(?:\x07|\x1b\\)/g;
+/**
+ * The sign-in URL in what `claude auth login` printed so far: an OSC 8 hyperlink's target, or a
+ * URL in the text with its escapes removed, Anthropic's authorize page (`/oauth/authorize`)
+ * first. A URL in the text counts only once whitespace follows it (the rest may still be on its
+ * way), unless `complete` says the output is all there is.
+ */
+export function signInUrl(output, complete = false) {
+    const targets = [...output.matchAll(HYPERLINK_TARGET)].map((match) => match[1]);
+    const text = output.replace(OSC, " ").replace(CSI, "");
+    const inText = [...text.matchAll(complete ? /https:\/\/\S+/g : /https:\/\/\S+(?=\s)/g)].map((match) => match[0]);
+    const urls = [...targets, ...inText];
+    return urls.find((url) => url.includes("/oauth/authorize")) ?? urls[0];
 }

package/dist/core/hooks/transcriptLogger.d.ts

@@ -9,8 +9,8 @@ export interface TranscriptLogger {
 /**
  * Logs every tool call (request + result) as one JSON line, redacting `secrets` (e.g. a
  * domain-specific password — see `BaseSessionConfig.secrets`) plus
- * `CLAUDE_CODE_OAUTH_TOKEN`, which this kit always scrubs regardless of domain since it
- * owns the auth-token concept (see claudeAuth.ts).
+ * `CLAUDE_CODE_OAUTH_TOKEN` when the person's environment sets one, which this kit always
+ * scrubs regardless of domain (it never handles a token itself: see claudeAuth.ts).
  */
 export declare function createTranscriptLogger(transcriptPath: string, secrets?: readonly string[]): TranscriptLogger;
 /** Avoids bloating the transcript with large payloads (browser-tool screenshots/base64). */

package/dist/core/hooks/transcriptLogger.js

@@ -10,8 +10,8 @@ function redact(text, secrets) {
 /**
  * Logs every tool call (request + result) as one JSON line, redacting `secrets` (e.g. a
  * domain-specific password — see `BaseSessionConfig.secrets`) plus
- * `CLAUDE_CODE_OAUTH_TOKEN`, which this kit always scrubs regardless of domain since it
- * owns the auth-token concept (see claudeAuth.ts).
+ * `CLAUDE_CODE_OAUTH_TOKEN` when the person's environment sets one, which this kit always
+ * scrubs regardless of domain (it never handles a token itself: see claudeAuth.ts).
  */
 export function createTranscriptLogger(transcriptPath, secrets = []) {
     const allSecrets = [...secrets, process.env.CLAUDE_CODE_OAUTH_TOKEN].filter((s) => Boolean(s));

package/dist/core/mcpDepth.d.ts

@@ -0,0 +1,9 @@
+/**
+ * How deep in a chain of agents served over MCP this process is (ADR-027): an agent that serves
+ * itself reads it, and passes it on one higher to the servers it starts, so a loop (A asks B asks
+ * A) stops instead of spawning agents forever. An installed extension's server never gets it: its
+ * environment is stripped, and no server should depend on the kit's variables.
+ */
+export declare const MCP_DEPTH_ENV = "AGENT_KIT_MCP_DEPTH";
+/** The depth this process runs at: 0 when no agent served over MCP started it. */
+export declare function mcpDepth(): number;

package/dist/core/mcpDepth.js

@@ -0,0 +1,12 @@
+/**
+ * How deep in a chain of agents served over MCP this process is (ADR-027): an agent that serves
+ * itself reads it, and passes it on one higher to the servers it starts, so a loop (A asks B asks
+ * A) stops instead of spawning agents forever. An installed extension's server never gets it: its
+ * environment is stripped, and no server should depend on the kit's variables.
+ */
+export const MCP_DEPTH_ENV = "AGENT_KIT_MCP_DEPTH";
+/** The depth this process runs at: 0 when no agent served over MCP started it. */
+export function mcpDepth() {
+    const depth = Number(process.env[MCP_DEPTH_ENV]);
+    return Number.isInteger(depth) && depth > 0 ? depth : 0;
+}

package/dist/core/messages/de.js

@@ -194,12 +194,14 @@ export const de = {
         presentingPlan: "Plan vorlegen",
     },
     auth: {
-        noToken: "Es wurde kein Claude-Authentifizierungstoken gefunden",
-        noTokenDetail: "(weder die Umgebungsvariable CLAUDE_CODE_OAUTH_TOKEN noch ein im Code übergebenes).",
-        generateQuestion: 'Jetzt eines mit "claude setup-token" erzeugen? (erfordert ein Claude-Pro/Max-Abonnement)',
-        cantStart: "Der Agent kann ohne Token nicht starten. Setze CLAUDE_CODE_OAUTH_TOKEN von Hand (oder starte erneut und lass es erzeugen) und versuche es noch einmal.",
-        generatingHeading: "=== Claude-Authentifizierungstoken wird erzeugt ===",
-        browserWillOpen: "Zum Anmelden öffnet sich ein Browser; folge den Anweisungen, die der Befehl unten ausgibt.",
-        generated: "Token für diese Ausführung erzeugt. Speichere es selbst (z. B. CLAUDE_CODE_OAUTH_TOKEN im Profil deiner Shell), um diesen Schritt beim nächsten Mal zu überspringen.",
+        notSignedIn: "Du bist nicht bei Claude angemeldet",
+        notSignedInDetail: "Melde dich mit deinem Claude-Konto auf Anthropics eigener Seite an: Das übernimmt Claude Code, das mit diesem Agenten kommt, und es speichert die Anmeldung selbst. Oder setze ANTHROPIC_API_KEY, um einen API-Schlüssel zu verwenden.",
+        signInQuestion: "Jetzt mit deinem Claude-Konto anmelden?",
+        cantStart: "Der Agent kann ohne Claude nicht starten. Starte ihn erneut und melde dich an, oder setze ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Anmeldung bei Claude ===",
+        browserWillOpen: "Ein Browser öffnet sich mit Anthropics Anmeldeseite. Zeigt die Seite einen Code, füge ihn hier ein.",
+        signedIn: "Angemeldet. Claude Code speichert die Anmeldung, du wirst nicht erneut gefragt.",
+        notCompleted: "Die Anmeldung wurde nicht abgeschlossen. Starte den Agenten erneut, um es noch einmal zu versuchen, oder setze ANTHROPIC_API_KEY.",
+        noClaude: "Das Claude-Code-Programm, das mit dem Agent SDK kommt (@anthropic-ai/claude-agent-sdk-<Plattform>-<Architektur>), ist nicht installiert, daher ist keine Anmeldung möglich. Installiere den Agenten neu, oder setze ANTHROPIC_API_KEY.",
     },
 };

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

@@ -203,13 +203,15 @@ export interface Messages {
         presentingPlan: string;
     };
     auth: {
-        noToken: string;
-        noTokenDetail: string;
-        generateQuestion: string;
+        notSignedIn: string;
+        notSignedInDetail: string;
+        signInQuestion: string;
         cantStart: string;
-        generatingHeading: string;
+        signingInHeading: string;
         browserWillOpen: string;
-        generated: string;
+        signedIn: string;
+        notCompleted: string;
+        noClaude: string;
     };
 }
 export declare const en: Messages;

package/dist/core/messages/en.js

@@ -193,12 +193,14 @@ export const en = {
         presentingPlan: "Presenting the plan",
     },
     auth: {
-        noToken: "No Claude authentication token was found",
-        noTokenDetail: "(neither the CLAUDE_CODE_OAUTH_TOKEN environment variable, nor one passed in).",
-        generateQuestion: 'Generate one now with "claude setup-token" (requires a Claude Pro/Max subscription)?',
-        cantStart: "The agent can't start without a token. Set CLAUDE_CODE_OAUTH_TOKEN by hand (or run this again and accept generating it) and try again.",
-        generatingHeading: "=== Generating a Claude authentication token ===",
-        browserWillOpen: "A browser will open to log in; follow the instructions the command itself prints below.",
-        generated: "Token generated for this run. Save it yourself (e.g. CLAUDE_CODE_OAUTH_TOKEN in your shell profile) to skip this next time.",
+        notSignedIn: "You aren't signed in to Claude",
+        notSignedInDetail: "Sign in with your Claude account on Anthropic's own page: Claude Code, which comes with this agent, does it and keeps the sign-in itself. Or set ANTHROPIC_API_KEY to use an API key.",
+        signInQuestion: "Sign in with your Claude account now?",
+        cantStart: "The agent can't start without Claude. Run it again and sign in, or set ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Signing in to Claude ===",
+        browserWillOpen: "A browser will open on Anthropic's sign-in page. If the page shows a code, paste it here.",
+        signedIn: "Signed in. Claude Code keeps the sign-in, so this won't be asked again.",
+        notCompleted: "The sign-in didn't complete. Run the agent again to retry, or set ANTHROPIC_API_KEY.",
+        noClaude: "Claude Code's binary, which comes with the Agent SDK (@anthropic-ai/claude-agent-sdk-<platform>-<arch>), isn't installed, so there's no way to sign in. Reinstall the agent, or set ANTHROPIC_API_KEY.",
     },
 };

package/dist/core/messages/es.js

@@ -194,12 +194,14 @@ export const es = {
         presentingPlan: "Presentando el plan",
     },
     auth: {
-        noToken: "No se ha encontrado ningún token de autenticación de Claude",
-        noTokenDetail: "(ni la variable de entorno CLAUDE_CODE_OAUTH_TOKEN ni uno pasado por código).",
-        generateQuestion: '¿Generar uno ahora con "claude setup-token"? (requiere una suscripción Claude Pro/Max)',
-        cantStart: "El agente no puede arrancar sin un token. Define CLAUDE_CODE_OAUTH_TOKEN a mano (o vuelve a ejecutarlo y acepta generarlo) e inténtalo de nuevo.",
-        generatingHeading: "=== Generando un token de autenticación de Claude ===",
-        browserWillOpen: "Se abrirá un navegador para iniciar sesión; sigue las instrucciones que el propio comando muestra abajo.",
-        generated: "Token generado para esta ejecución. Guárdalo tú (p. ej. CLAUDE_CODE_OAUTH_TOKEN en el perfil de tu shell) para no repetir esto la próxima vez.",
+        notSignedIn: "No has iniciado sesión en Claude",
+        notSignedInDetail: "Inicia sesión con tu cuenta de Claude en la propia página de Anthropic: lo hace Claude Code, que viene con este agente, y guarda él mismo la sesión. O define ANTHROPIC_API_KEY para usar una API key.",
+        signInQuestion: "¿Iniciar sesión ahora con tu cuenta de Claude?",
+        cantStart: "El agente no puede arrancar sin Claude. Vuelve a ejecutarlo e inicia sesión, o define ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Iniciando sesión en Claude ===",
+        browserWillOpen: "Se abrirá un navegador en la página de inicio de sesión de Anthropic. Si la página muestra un código, pégalo aquí.",
+        signedIn: "Sesión iniciada. Claude Code la guarda, así que no se volverá a pedir.",
+        notCompleted: "El inicio de sesión no se completó. Vuelve a ejecutar el agente para reintentarlo, o define ANTHROPIC_API_KEY.",
+        noClaude: "No está instalado el binario de Claude Code que trae el Agent SDK (@anthropic-ai/claude-agent-sdk-<plataforma>-<arquitectura>), así que no hay cómo iniciar sesión. Reinstala el agente, o define ANTHROPIC_API_KEY.",
     },
 };

package/dist/core/messages/fr.js

@@ -194,12 +194,14 @@ export const fr = {
         presentingPlan: "Présentation du plan",
     },
     auth: {
-        noToken: "Aucun jeton d'authentification Claude n'a été trouvé",
-        noTokenDetail: "(ni la variable d'environnement CLAUDE_CODE_OAUTH_TOKEN, ni un jeton passé par le code).",
-        generateQuestion: 'En générer un maintenant avec "claude setup-token" ? (nécessite un abonnement Claude Pro/Max)',
-        cantStart: "L'agent ne peut pas démarrer sans jeton. Définissez CLAUDE_CODE_OAUTH_TOKEN à la main (ou relancez et acceptez de le générer), puis réessayez.",
-        generatingHeading: "=== Génération d'un jeton d'authentification Claude ===",
-        browserWillOpen: "Un navigateur va s'ouvrir pour vous connecter ; suivez les instructions que la commande affiche ci-dessous.",
-        generated: "Jeton généré pour cette exécution. Enregistrez-le vous-même (par ex. CLAUDE_CODE_OAUTH_TOKEN dans le profil de votre shell) pour éviter cette étape la prochaine fois.",
+        notSignedIn: "Tu n'es pas connecté à Claude",
+        notSignedInDetail: "Connecte-toi avec ton compte Claude sur la page d'Anthropic : c'est Claude Code, fourni avec cet agent, qui s'en charge et garde lui-même la connexion. Ou définis ANTHROPIC_API_KEY pour utiliser une clé d'API.",
+        signInQuestion: "Se connecter maintenant avec ton compte Claude ?",
+        cantStart: "L'agent ne peut pas démarrer sans Claude. Relance-le et connecte-toi, ou définis ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Connexion à Claude ===",
+        browserWillOpen: "Un navigateur va s'ouvrir sur la page de connexion d'Anthropic. Si la page affiche un code, colle-le ici.",
+        signedIn: "Connecté. Claude Code garde la connexion : on ne te la redemandera pas.",
+        notCompleted: "La connexion n'a pas abouti. Relance l'agent pour réessayer, ou définis ANTHROPIC_API_KEY.",
+        noClaude: "Le binaire de Claude Code fourni avec l'Agent SDK (@anthropic-ai/claude-agent-sdk-<plateforme>-<architecture>) n'est pas installé : impossible de se connecter. Réinstalle l'agent, ou définis ANTHROPIC_API_KEY.",
     },
 };

package/dist/core/packaged.d.ts

@@ -1,5 +1,11 @@
 /** A path inside `…/app.asar/…`, as the unpacked copy next to it (`…/app.asar.unpacked/…`); any other path as it is. */
 export declare function outsideArchive(file: string): string;
+/**
+ * The module requests that name the SDK's CLI binary on this platform, in the SDK's order:
+ * `@anthropic-ai/claude-agent-sdk-<platform>-<arch>/claude[.exe]`, both libcs on Linux (musl
+ * first when the system runs on it, as the SDK decides).
+ */
+export declare function claudeBinaryRequests(platform?: NodeJS.Platform, arch?: string, musl?: boolean): string[];
 /**
  * The SDK's CLI binary unpacked next to the archive, when the kit runs packaged: the SDK would
  * resolve it inside `app.asar`, where it can't be executed, and its first turn would hang with

package/dist/core/packaged.js

@@ -11,6 +11,22 @@ const ARCHIVE = /([\\/])app\.asar([\\/])/;
 export function outsideArchive(file) {
     return file.replace(ARCHIVE, "$1app.asar.unpacked$2");
 }
+/**
+ * The module requests that name the SDK's CLI binary on this platform, in the SDK's order:
+ * `@anthropic-ai/claude-agent-sdk-<platform>-<arch>/claude[.exe]`, both libcs on Linux (musl
+ * first when the system runs on it, as the SDK decides).
+ */
+export function claudeBinaryRequests(platform = process.platform, arch = process.arch, musl = platform === "linux" && runsOnMusl()) {
+    const packages = platform === "linux" ? (musl ? [`linux-${arch}-musl`, `linux-${arch}`] : [`linux-${arch}`, `linux-${arch}-musl`]) : [`${platform}-${arch}`];
+    return packages.map((suffix) => `@anthropic-ai/claude-agent-sdk-${suffix}/claude${platform === "win32" ? ".exe" : ""}`);
+}
+/** A Linux whose C library is musl (Alpine): Node's report names no glibc version there. */
+function runsOnMusl() {
+    if (process.platform !== "linux")
+        return false;
+    const report = process.report?.getReport();
+    return Boolean(report?.header) && report?.header?.glibcVersionRuntime === undefined;
+}
 /**
  * The SDK's CLI binary unpacked next to the archive, when the kit runs packaged: the SDK would
  * resolve it inside `app.asar`, where it can't be executed, and its first turn would hang with
@@ -19,11 +35,10 @@ export function outsideArchive(file) {
  * when not packaged, or when the build didn't unpack it: then the SDK finds its own.
  */
 export function unpackedClaudeExecutable(resolve = createRequire(import.meta.url).resolve, platform = process.platform, arch = process.arch) {
-    const packages = platform === "linux" ? [`linux-${arch}`, `linux-${arch}-musl`] : [`${platform}-${arch}`];
-    for (const suffix of packages) {
+    for (const request of claudeBinaryRequests(platform, arch)) {
         let file;
         try {
-            file = resolve(`@anthropic-ai/claude-agent-sdk-${suffix}/claude${platform === "win32" ? ".exe" : ""}`);
+            file = resolve(request);
         }
         catch {
             continue;

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { setTheme, getTheme, DEFAULT_THEME, type Theme, type ThemeColor } from "
 export { isExitPromptError } from "./tui/promptErrors.js";
 export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";
-export { resolveClaudeAuth, type ClaudeAuthConfig } from "./core/claudeAuth.js";
+export { claudeExecutable, claudeSignedIn, startClaudeSignIn, type ClaudeAuthOptions, type ClaudeSignIn } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, withToolResults, quietResults, type ToolResult, type ToolDescriber, type ToolLabel, type ToolLabels, } from "./core/toolLabels.js";
 export type { Mode, BaseSessionConfig, AgentSpec, AgentIdentity, PlanModeSpec, ExtensionGateSpec } from "./core/agentSpec.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { setTheme, getTheme, DEFAULT_THEME } from "./tui/theme.js";
 export { isExitPromptError } from "./tui/promptErrors.js";
 export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";
-export { resolveClaudeAuth } from "./core/claudeAuth.js";
+export { claudeExecutable, claudeSignedIn, startClaudeSignIn } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, withToolResults, quietResults, } from "./core/toolLabels.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";

package/dist/mcp/index.d.ts

@@ -0,0 +1 @@
+export { serveMcp, type ServeMcpSettings } from "./serveMcp.js";

package/dist/mcp/index.js

@@ -0,0 +1 @@
+export { serveMcp } from "./serveMcp.js";

package/dist/mcp/serveMcp.d.ts

@@ -0,0 +1,28 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { AgentIdentity } from "../core/agentSpec.js";
+import { type ChatSettings } from "../chat/chatController.js";
+import { type SessionOpener } from "../chat/runs.js";
+/** What `serveMcp()` needs besides how to open a session. */
+export interface ServeMcpSettings {
+    /** Where the runs are: a `session_id` names one of them. */
+    runsDir: string;
+    /** Who the agent is: the server's name and version, and what the `ask` tool says it does. */
+    identity: AgentIdentity;
+    /** How many agents served over MCP may chain before `ask` refuses (default 3). */
+    maxDepth?: number;
+    /** How often a turn reports it's still running, so a client's tool timeout doesn't cut it (default 15 s). */
+    progressIntervalMs?: number;
+    /** The transport: stdio by default. */
+    transport?: Transport;
+    /** Runs the agent: the SDK's by default; another for tests. */
+    runQuery?: ChatSettings["runQuery"];
+}
+/**
+ * Serves an agent as an MCP server (ADR-027), so another agent (Claude Code, Claude Desktop,
+ * another one on the kit) drives it whole: its prompt, extensions and guardrails stay in its own
+ * process. One tool, `ask`; a `session_id` names a run, so a conversation goes on across calls.
+ *
+ * Autonomous mode only: nobody can answer a checkpoint here, and the calling model must never
+ * answer for the human. Resolves when the client disconnects.
+ */
+export declare function serveMcp(opener: SessionOpener, settings: ServeMcpSettings): Promise<void>;

package/dist/mcp/serveMcp.js

@@ -0,0 +1,177 @@
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getInteractionPort, setInteractionPort } from "../core/interaction.js";
+import { MCP_DEPTH_ENV, mcpDepth } from "../core/mcpDepth.js";
+import { createRunFolder, readRunSession } from "../core/runs.js";
+import { createChatController } from "../chat/chatController.js";
+import { openSession } from "../chat/runs.js";
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_PROGRESS_INTERVAL_MS = 15_000;
+/** Sessions kept open between turns: each is a process. One closed is opened again by its `session_id`. */
+const MAX_OPEN_SESSIONS = 4;
+/**
+ * Serves an agent as an MCP server (ADR-027), so another agent (Claude Code, Claude Desktop,
+ * another one on the kit) drives it whole: its prompt, extensions and guardrails stay in its own
+ * process. One tool, `ask`; a `session_id` names a run, so a conversation goes on across calls.
+ *
+ * Autonomous mode only: nobody can answer a checkpoint here, and the calling model must never
+ * answer for the human. Resolves when the client disconnects.
+ */
+export async function serveMcp(opener, settings) {
+    const { runsDir, identity } = settings;
+    const maxDepth = settings.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const interval = settings.progressIntervalMs ?? DEFAULT_PROGRESS_INTERVAL_MS;
+    const depth = mcpDepth();
+    // What this function takes over in the process, given back when it ends. Over stdio, stdout
+    // belongs to the transport: whatever else prints goes to stderr.
+    const previousDepth = process.env[MCP_DEPTH_ENV];
+    const previousPort = getInteractionPort();
+    const { log, info, debug } = console;
+    const stdio = !settings.transport;
+    process.env[MCP_DEPTH_ENV] = String(depth + 1);
+    setInteractionPort(null); // the response file alone: no keyboard here
+    if (stdio)
+        console.log = console.info = console.debug = console.error;
+    const restore = () => {
+        if (previousDepth === undefined)
+            delete process.env[MCP_DEPTH_ENV];
+        else
+            process.env[MCP_DEPTH_ENV] = previousDepth;
+        setInteractionPort(previousPort);
+        if (stdio)
+            Object.assign(console, { log, info, debug });
+    };
+    async function open(run) {
+        const opened = await openSession(opener, run);
+        if (opened.modeControl?.mode !== "autonomous")
+            throw new Error(`serveMcp() serves autonomous mode only, and this session opened in ${opened.modeControl?.mode ?? "no known mode"}: nobody can answer a checkpoint over MCP.`);
+        return opened;
+    }
+    // Opened at the start to refuse a wrong mode at once; the first new conversation uses it.
+    let spare;
+    try {
+        spare = await open(await createRunFolder(runsDir));
+    }
+    catch (error) {
+        restore();
+        throw error;
+    }
+    const sessions = new Map();
+    const busy = new Set();
+    async function controllerOf(opened) {
+        return await createChatController(opened.options, {
+            sessionLogPath: path.join(opened.run.dir, "session.log"),
+            promptSuggestions: false,
+            ...(opened.modeControl ? { modeControl: opened.modeControl } : {}),
+            ...(opened.toolLabels ? { toolLabels: opened.toolLabels } : {}),
+            ...(settings.runQuery ? { runQuery: settings.runQuery } : {}),
+        });
+    }
+    /** The session a `session_id` names, opened again if it isn't: only a run of this agent's. */
+    async function reopen(id) {
+        const running = sessions.get(id);
+        if (running)
+            return running;
+        const dir = path.join(runsDir, id);
+        const sessionId = /^[\w-]+$/.test(id) ? await readRunSession(dir) : null;
+        if (!sessionId)
+            throw new Error(`Unknown session_id: ${id}.`);
+        return await controllerOf(await open({ dir, sessionId }));
+    }
+    function closeIdleSessions() {
+        for (const [id, controller] of sessions) {
+            if (sessions.size <= MAX_OPEN_SESSIONS)
+                return;
+            if (busy.has(id))
+                continue;
+            controller.close();
+            sessions.delete(id);
+        }
+    }
+    const server = new McpServer({ name: identity.name, version: identity.version ?? "0.0.0" });
+    server.registerTool("ask", {
+        description: `Ask ${identity.name}${identity.description ? `, ${identity.description},` : ""} to do something, and get its reply. Without session_id it starts a new conversation; with the session_id of an earlier reply it goes on with that one.`,
+        inputSchema: { message: z.string().min(1).describe("What to ask, in plain words."), session_id: z.string().optional().describe("The session_id of an earlier reply, to go on with that conversation.") },
+    }, async ({ message, session_id: requested }, extra) => {
+        if (depth >= maxDepth)
+            throw new Error(`Too many agents chained over MCP (the limit is ${maxDepth}).`);
+        if (requested !== undefined && busy.has(requested))
+            throw new Error(`Session ${requested} is busy with another turn; wait for it to end.`);
+        if (requested !== undefined)
+            busy.add(requested);
+        let id = requested;
+        try {
+            let controller;
+            if (requested !== undefined)
+                controller = await reopen(requested);
+            else {
+                const opened = spare ?? (await open(await createRunFolder(runsDir)));
+                spare = null;
+                id = path.basename(opened.run.dir);
+                busy.add(id);
+                controller = await controllerOf(opened);
+            }
+            // Last in the map: the least recently used are closed first.
+            sessions.delete(id);
+            sessions.set(id, controller);
+            const token = extra._meta?.progressToken;
+            let progress = 0;
+            let activity;
+            const report = () => {
+                if (token === undefined)
+                    return;
+                void extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: ++progress, ...(activity ? { message: activity } : {}) } }).catch(() => undefined);
+            };
+            let failure = null;
+            const stopListening = controller.onEvent((chat) => {
+                if (chat.type !== "agent")
+                    return;
+                const event = chat.event;
+                if (event.type === "action" || event.type === "subagent-action") {
+                    activity = controller.formatAction(event.toolName, event.input);
+                    report();
+                }
+                else if (event.type === "turn-end" && event.failed)
+                    failure = event.errorText || "The turn failed.";
+            });
+            const heartbeat = setInterval(report, interval);
+            const interrupt = () => controller.interrupt();
+            extra.signal.addEventListener("abort", interrupt, { once: true });
+            try {
+                await controller.turn(message);
+            }
+            finally {
+                clearInterval(heartbeat);
+                stopListening();
+                extra.signal.removeEventListener("abort", interrupt);
+            }
+            if (failure)
+                throw new Error(failure);
+            return { content: [{ type: "text", text: controller.lastReply() }, { type: "text", text: `session_id: ${id}` }] };
+        }
+        finally {
+            if (id !== undefined)
+                busy.delete(id);
+            closeIdleSessions();
+        }
+    });
+    return await new Promise((resolve, reject) => {
+        server.server.onclose = () => {
+            for (const controller of sessions.values())
+                controller.close();
+            sessions.clear();
+            restore();
+            resolve();
+        };
+        const transport = settings.transport ?? new StdioServerTransport();
+        // The stdio transport doesn't see its client leave: stdin ending is how it does.
+        if (stdio)
+            process.stdin.once("end", () => void server.close());
+        server.connect(transport).catch((error) => {
+            restore();
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}