@falkenslab/agent-kit 0.32.0 → 0.33.0

package/README.md

@@ -120,7 +120,7 @@ See [everything he can do](https://falkenslab.github.io/agent-kit/docs/examples/
 | 🧩 Extensions | Claude Code plugins with MCP servers (local, npm, remote with OAuth), skills, commands and subagents; scopes, a lock, workspace trust, options, marketplaces and a catalog |
 | 🛡️ Security | A file scope gate, denied paths, subagent gates, a remote-servers gate, isolation from the runner's own Claude Code, redacted transcripts |
 | 🤖 Subagents | Declared types only, in the foreground, without Bash for the main agent |
-| 🖥️ Interfaces | A full-screen Ink chat, a plain readline chat, a progress view, a wizard, themes; a chat controller for desktop apps and web pages |
+| 🖥️ Interfaces | A full-screen Ink chat, a plain readline chat, a progress view, a wizard, themes; a chat controller for desktop apps and web pages; an MCP server, so other agents can ask it things |
 | 🌐 Languages | English, Spanish, French and German, for the interface, the replies and the extensions' servers |
 
 Every export, with what it takes and what it gives, is in the [API reference](https://falkenslab.github.io/agent-kit/docs/api).

package/dist/chat/chatController.d.ts

@@ -246,6 +246,11 @@ export declare function createChatController(options: Options | SessionOpener, s
      * resolved when it ends. An unknown slash command is caught before it reaches the model.
      */
     send(raw: string): Promise<"exit" | void>;
+    /**
+     * A turn that doesn't come from the person's keyboard (another agent's, over MCP): the text
+     * goes to the agent as it is, never read as one of the chat's commands (`/extensions`, `/resume`).
+     */
+    turn(raw: string): Promise<void>;
     /** Stops the turn running, if any. */
     interrupt(): void;
     /** Switches to a mode the session allows; says so when it can't. */

package/dist/chat/chatController.js

@@ -493,6 +493,19 @@ export async function createChatController(options, settings = {}) {
             }
             await runTurn(line);
         },
+        /**
+         * A turn that doesn't come from the person's keyboard (another agent's, over MCP): the text
+         * goes to the agent as it is, never read as one of the chat's commands (`/extensions`, `/resume`).
+         */
+        async turn(raw) {
+            const line = raw.trim();
+            if (!line)
+                return;
+            log(`${promptLabel}${line}\n`);
+            addEntry({ id: nextId++, kind: "user", text: line });
+            emit({ type: "user", text: line });
+            await runTurn(line);
+        },
         /** Stops the turn running, if any. */
         interrupt() {
             if (!state.busy || interrupted)

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",
@@ -30,6 +30,17 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "assets",
@@ -52,6 +63,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.300",
     "@inkjs/ui": "^2.0.0",
     "@inquirer/prompts": "^8.5.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/react": "^19.3.0",
     "ink": "^6.8.0",
     "isomorphic-git": "^1.44.5",