@falkenslab/agent-kit 0.32.0 → 0.34.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

@@ -89,6 +89,8 @@ export interface TranscriptCall {
         isError: boolean;
         text: string;
     } | null;
+    /** An MCP result's `_meta`, untouched: data for this view, which the model never sees (absent when the tool returned none). */
+    meta?: Record<string, unknown>;
     /** What a subagent it started did, by label. */
     children: string[];
 }
@@ -246,6 +248,19 @@ 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>;
+    /**
+     * A message for the agent while a turn runs (#92), without stopping it: it joins the turn at
+     * its next tool call, or is answered right after when no call is left, and it stays in the
+     * transcript where it was sent. The turn `send()` is waiting for lasts until it's answered.
+     * False, and nothing sent, when no turn is running (use `send()`) and for a slash command or
+     * an exit line, which wait for the turn to end.
+     */
+    steer(raw: string): Promise<boolean>;
     /** 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

@@ -4,7 +4,7 @@ import { getInteractionPort, setInteractionPort } from "../core/interaction.js";
 import { getLanguage, switchLanguage, t } from "../core/messages/index.js";
 import { LANGUAGE_NAMES } from "../core/language.js";
 import { runQuery } from "../core/runner.js";
-import { createRunFolder, listRuns, readConversation, readRunSession } from "../core/runs.js";
+import { createRunFolder, listRuns, readConversationSteps, readRunSession } from "../core/runs.js";
 import { createInputQueue, togglePlanMode } from "../core/session.js";
 import { hasOpenTodos, parseTodos, TODO_TOOL } from "../core/todos.js";
 import { withToolLabels, withToolPhrases, withToolResults } from "../core/toolLabels.js";
@@ -96,15 +96,18 @@ export async function createChatController(options, settings = {}) {
         addEntry({ id: nextId++, kind: "notice", tone, text });
         emit({ type: "notice", tone, text });
     }
+    // A reply of its own coming: the answer to a message sent into the turn, after a `turn-end`.
+    let newReply = false;
     /** What the agent does, into the transcript. */
     function record(event) {
         const last = state.transcript.at(-1);
         switch (event.type) {
             case "text":
-                if (last?.kind === "agent")
+                if (last?.kind === "agent" && !newReply)
                     update({ transcript: [...state.transcript.slice(0, -1), { ...last, text: last.text + event.text }] });
                 else
                     addEntry({ id: nextId++, kind: "agent", text: event.text });
+                newReply = false;
                 return;
             case "action": {
                 const todos = event.toolName === TODO_TOOL ? parseTodos(event.input) : null;
@@ -129,7 +132,7 @@ export async function createChatController(options, settings = {}) {
                     ? entry
                     : {
                         ...entry,
-                        calls: entry.calls.map((call) => call.id !== id ? call : event.type === "tool-result" ? { ...call, result: { isError: event.isError, text: event.text } } : { ...call, children: [...call.children, label] }),
+                        calls: entry.calls.map((call) => call.id !== id ? call : event.type === "tool-result" ? { ...call, result: { isError: event.isError, text: event.text }, ...(event.meta ? { meta: event.meta } : {}) } : { ...call, children: [...call.children, label] }),
                     });
                 update({ transcript, ...(label ? { subagentActivity: label } : {}) });
                 return;
@@ -160,9 +163,17 @@ export async function createChatController(options, settings = {}) {
     let readError = null;
     let unsubscribeMode;
     let interrupted = false;
+    // A message sent into this turn (`steer()`): its `turn-end` may not be the last, so the turn
+    // ends at `session-idle`, once a `turn-end` has come after the latest message sent. Before
+    // that, an idle is an earlier one, still on its way.
+    let steered = false;
+    let awaitingIdle = false;
     function finishTurn() {
         const done = turnDone;
         turnDone = null;
+        newReply = false;
+        steered = false;
+        awaitingIdle = false;
         done?.();
     }
     /** The commands the session has, and the chat's own, into the state: when it opens, and when an extension is switched in it. */
@@ -214,12 +225,25 @@ export async function createChatController(options, settings = {}) {
                     const { value, done } = await events.next();
                     if (own !== generation || done)
                         break;
+                    if (value.type === "session-idle") {
+                        if (awaitingIdle)
+                            finishTurn();
+                        continue;
+                    }
                     if (value.type !== "prompt-suggestion")
                         logRenderer.render(value);
                     record(value);
                     emit({ type: "agent", event: value });
-                    if (value.type === "turn-end")
-                        finishTurn();
+                    if (value.type === "turn-end") {
+                        if (!steered)
+                            finishTurn();
+                        else {
+                            awaitingIdle = true;
+                            newReply = true;
+                            // What's left to answer can be interrupted too.
+                            interrupted = false;
+                        }
+                    }
                 }
             }
             catch (error) {
@@ -238,6 +262,12 @@ export async function createChatController(options, settings = {}) {
     // Extensions turned off or on in the running session, told to the model with the next message
     // too: the prompt's Extensions section still says what the session opened with.
     const extensionNotices = [];
+    /** A line with what the model hasn't been told yet before it: each note goes once. */
+    function withNotices(line) {
+        const notices = [languageNotice, ...extensionNotices.splice(0)].filter(Boolean);
+        languageNotice = null;
+        return notices.length ? `${notices.join("\n")}\n\n${line}` : line;
+    }
     async function runTurn(line) {
         interrupted = false;
         const from = state.transcript.length;
@@ -246,9 +276,7 @@ export async function createChatController(options, settings = {}) {
         update({ busy: true, turnStartedAt: startedAt, activity: null, subagentActivity: null, suggestion: null });
         emit({ type: "turn-start" });
         const finished = new Promise((resolve) => (turnDone = resolve));
-        const notices = [languageNotice, ...extensionNotices.splice(0)].filter(Boolean);
-        queue.push(notices.length ? `${notices.join("\n")}\n\n${line}` : line);
-        languageNotice = null;
+        queue.push(withNotices(line));
         await finished;
         logRenderer.endLine();
         latestReply = state.transcript.slice(from).flatMap((entry) => (entry.kind === "agent" ? [entry.text] : [])).join("").trim();
@@ -264,10 +292,26 @@ export async function createChatController(options, settings = {}) {
     async function showConversation(folder, fromResume) {
         if (!folder.sessionId)
             return;
-        const messages = await readConversation(folder.dir);
+        const steps = await readConversationSteps(folder.dir);
+        const messages = steps.filter((step) => step.role !== "tool");
         const [summary] = (await listRuns(path.dirname(folder.dir))).filter((other) => path.resolve(other.dir) === path.resolve(folder.dir));
         const updatedAt = summary?.updatedAt ?? new Date();
-        const replayed = messages.map((message) => ({ id: nextId++, kind: message.role === "user" ? "user" : "agent", text: message.text }));
+        const replayed = [];
+        for (const step of steps) {
+            if (step.role !== "tool") {
+                replayed.push({ id: nextId++, kind: step.role === "user" ? "user" : "agent", text: step.text });
+                continue;
+            }
+            if (step.toolName === TODO_TOOL)
+                continue;
+            // A call the session ended in the middle of has no result; `null` would read as still running.
+            const call = { id: step.id, toolName: step.toolName, label: formatAction(step.toolName, step.input), result: step.result ?? { isError: false, text: "" }, children: [], ...(step.meta ? { meta: step.meta } : {}) };
+            const last = replayed.at(-1);
+            if (last?.kind === "tools")
+                last.calls.push(call);
+            else
+                replayed.push({ id: nextId++, kind: "tools", calls: [call] });
+        }
         update({ transcript: fromResume ? replayed : [...state.transcript, ...replayed], turns: (fromResume ? 0 : state.turns) + messages.filter((message) => message.role === "user").length });
         emit({ type: "conversation", messages, updatedAt, fromResume });
     }
@@ -364,6 +408,20 @@ export async function createChatController(options, settings = {}) {
         }
         await controller.trustWorkspace();
     }
+    /** A line of the person's, in the session log, the transcript and to the views. */
+    function showLine(line) {
+        log(`${promptLabel}${line}\n`);
+        addEntry({ id: nextId++, kind: "user", text: line });
+        emit({ type: "user", text: line });
+    }
+    /** A line of the person's, kept for ↑/↓. */
+    async function remember(line) {
+        if (!settings.historyPath)
+            return;
+        historyEntries = capHistory([...historyEntries, { text: line, timestamp: new Date().toISOString() }], historyLimit);
+        update({ history: historyEntries.map((entry) => entry.text) });
+        await saveHistory(settings.historyPath, historyEntries);
+    }
     // A choice in place of the prompt, when the view doesn't ask it itself.
     let choiceResolve = null;
     function pick(title, options) {
@@ -455,14 +513,8 @@ export async function createChatController(options, settings = {}) {
             const line = raw.trim();
             if (!line)
                 return;
-            log(`${promptLabel}${line}\n`);
-            addEntry({ id: nextId++, kind: "user", text: line });
-            emit({ type: "user", text: line });
-            if (settings.historyPath) {
-                historyEntries = capHistory([...historyEntries, { text: line, timestamp: new Date().toISOString() }], historyLimit);
-                update({ history: historyEntries.map((entry) => entry.text) });
-                await saveHistory(settings.historyPath, historyEntries);
-            }
+            showLine(line);
+            await remember(line);
             const lower = line.toLowerCase();
             if (exitCommands.has(lower))
                 return "exit";
@@ -493,6 +545,36 @@ 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;
+            showLine(line);
+            await runTurn(line);
+        },
+        /**
+         * A message for the agent while a turn runs (#92), without stopping it: it joins the turn at
+         * its next tool call, or is answered right after when no call is left, and it stays in the
+         * transcript where it was sent. The turn `send()` is waiting for lasts until it's answered.
+         * False, and nothing sent, when no turn is running (use `send()`) and for a slash command or
+         * an exit line, which wait for the turn to end.
+         */
+        async steer(raw) {
+            const line = raw.trim();
+            if (!line || !turnDone || exitCommands.has(line.toLowerCase()) || slashCommandToken(line))
+                return false;
+            showLine(line);
+            queue.push(withNotices(line), { priority: "next" });
+            steered = true;
+            // Any idle on its way is from before this message.
+            awaitingIdle = false;
+            await remember(line);
+            return true;
+        },
         /** 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/core/runner.d.ts

@@ -43,13 +43,16 @@ export type AgentEvent =
 }
 /** What one of the main agent's tool calls returned, paired with its `action` by
  * `toolUseId`, as plain text (images and other non-text parts left out). Subagents'
- * results stay out, as their actions do. A console log ignores it. */
+ * results stay out, as their actions do. A console log ignores it. `meta` is an MCP
+ * result's `_meta`, untouched: data for the client, which the model never sees and the kit
+ * doesn't interpret (absent when the tool returned none). */
  | {
     type: "tool-result";
     toolUseId: string;
     toolName: string;
     isError: boolean;
     text: string;
+    meta?: Record<string, unknown>;
 }
 /** One or more MCP servers failed to connect at session startup. */
  | {
@@ -88,6 +91,12 @@ export type AgentEvent =
  | {
     type: "prompt-suggestion";
     suggestion: string;
+}
+/** Nothing is left to answer. It arrives once, after the last `turn-end`: a message sent
+ * into a running turn with no tool call left gets a `turn-end` of its own, so a `turn-end`
+ * doesn't say the work is over, and this does (confirmed empirically, SDK 0.3.300). */
+ | {
+    type: "session-idle";
 };
 /**
  * Running totals for the whole `query()` session so far, not for one turn: the SDK's own
@@ -114,6 +123,12 @@ export interface SessionUsage {
 export declare function visibleErrors(errors: readonly string[]): string[];
 /** A tool result's content as plain text: its text parts joined, anything else skipped. */
 export declare function toolResultText(content: unknown): string;
+/**
+ * An MCP result's `_meta`, from what holds it: a stream message's `tool_use_result` or a stored
+ * entry's `mcpMeta` (confirmed empirically, SDK 0.3.300: neither `tool_result` nor a
+ * `PostToolUse` hook carries it).
+ */
+export declare function toolResultMeta(holder: unknown): Record<string, unknown> | undefined;
 /** How full the session's context window is (see `AgentRun.contextUsage()`). */
 export interface ContextUsage {
     /** 0-100. */

package/dist/core/runner.js

@@ -19,6 +19,17 @@ export function toolResultText(content) {
         .map((part) => part.text)
         .join("\n");
 }
+/**
+ * An MCP result's `_meta`, from what holds it: a stream message's `tool_use_result` or a stored
+ * entry's `mcpMeta` (confirmed empirically, SDK 0.3.300: neither `tool_result` nor a
+ * `PostToolUse` hook carries it).
+ */
+export function toolResultMeta(holder) {
+    if (typeof holder !== "object" || holder === null)
+        return undefined;
+    const meta = holder._meta;
+    return typeof meta === "object" && meta !== null && !Array.isArray(meta) ? meta : undefined;
+}
 /**
  * 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.
@@ -66,7 +77,9 @@ async function restoreSavedSwitches(result, options) {
  * `close`, `supportedCommands`) is passed through unchanged.
  */
 export function runQuery(prompt, options) {
-    const result = query({ prompt, options });
+    // The session's state, for `session-idle`: the CLI only reports it when asked (confirmed
+    // empirically, SDK 0.3.300). `env` replaces the subprocess environment, so the rest goes on.
+    const result = query({ prompt, options: { ...options, env: { ...(options.env ?? process.env), CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1" } } });
     // What the session is, for an extension that asks (sessionFacts.ts): the controls now, the
     // tools and skills when the session starts.
     const view = sessionViewOf(options);
@@ -95,6 +108,11 @@ export function runQuery(prompt, options) {
                 yield { type: "info", text: message.content, level: message.level };
                 continue;
             }
+            if (message.type === "system" && message.subtype === "session_state_changed") {
+                if (message.state === "idle")
+                    yield { type: "session-idle" };
+                continue;
+            }
             if (message.type === "system" && message.subtype === "local_command_output") {
                 yield { type: "info", text: message.content, level: "local-command" };
                 continue;
@@ -124,13 +142,15 @@ export function runQuery(prompt, options) {
                 continue;
             }
             if (message.type === "user" && message.parent_tool_use_id === null && Array.isArray(message.message.content)) {
+                // One result per message in practice; were there several, `tool_use_result` couldn't be told apart.
+                const meta = message.message.content.filter((block) => block.type === "tool_result").length === 1 ? toolResultMeta(message.tool_use_result) : undefined;
                 for (const block of message.message.content) {
                     if (block.type !== "tool_result")
                         continue;
                     const toolName = toolNames.get(block.tool_use_id);
                     if (!toolName)
                         continue;
-                    yield { type: "tool-result", toolUseId: block.tool_use_id, toolName, isError: block.is_error === true, text: toolResultText(block.content) };
+                    yield { type: "tool-result", toolUseId: block.tool_use_id, toolName, isError: block.is_error === true, text: toolResultText(block.content), ...(meta ? { meta } : {}) };
                 }
             }
             if (message.type === "prompt_suggestion") {

package/dist/core/runs.d.ts

@@ -23,6 +23,20 @@ export interface ConversationMessage {
     role: "user" | "assistant";
     text: string;
 }
+/** One tool call of the main agent's in a kept conversation, with what came back. */
+export interface ConversationToolCall {
+    role: "tool";
+    id: string;
+    toolName: string;
+    input: unknown;
+    /** Null when the session ended before the result. */
+    result: {
+        isError: boolean;
+        text: string;
+    } | null;
+    /** An MCP result's `_meta`, as the live `tool-result` event has it. */
+    meta?: Record<string, unknown>;
+}
 /** A folder name for a new run, e.g. "2026-09-09T16-50-12-345Z" (sorts by date). */
 export declare function runFolderName(date?: Date): string;
 /** Creates a new, empty run folder under `runsDir`. */
@@ -47,6 +61,8 @@ export declare function createRunStore(dir: string): SessionStore;
 export declare function entryText(entry: SessionStoreEntry): ConversationMessage | null;
 /** The human's messages and the agent's replies in a run's conversation, in order. */
 export declare function readConversation(dir: string): Promise<ConversationMessage[]>;
+/** A run's conversation with the main agent's tool calls in their place: what a view shows of a resumed one. */
+export declare function readConversationSteps(dir: string): Promise<(ConversationMessage | ConversationToolCall)[]>;
 /** The runs under `runsDir` that kept a conversation, newest first; runs without `session.json` are left out. */
 export declare function listRuns(runsDir: string): Promise<RunSummary[]>;
 /** `--continue` among the process's arguments: start by resuming the latest run. */

package/dist/core/runs.js

@@ -1,5 +1,6 @@
 import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { toolResultMeta, toolResultText } from "./runner.js";
 const CONVERSATION = "conversation.jsonl";
 const SUBAGENTS = "subagents";
 const SESSION = "session.json";
@@ -133,6 +134,13 @@ export function createRunStore(dir) {
 }
 /** A transcript entry's text when it's something the human wrote or the agent replied, or null. */
 export function entryText(entry) {
+    // A message sent into a running turn is kept as a queued command, not as a user entry
+    // (confirmed empirically, SDK 0.3.300).
+    const queued = entry.type === "attachment" ? entry.attachment : undefined;
+    if (queued?.type === "queued_command" && queued.commandMode === "prompt" && typeof queued.prompt === "string") {
+        const text = humanText(queued.prompt);
+        return text ? { role: "user", text } : null;
+    }
     if (entry.type !== "user" && entry.type !== "assistant")
         return null;
     if (entry.isMeta || entry.isSidechain)
@@ -151,18 +159,52 @@ export function entryText(entry) {
             .map((part) => part.text ?? "")
             .join("");
     }
+    const shown = humanText(text);
+    return shown ? { role: entry.type, text: shown } : null;
+}
+/** A message's text as a person reads it, or null when nothing of it is theirs. */
+function humanText(raw) {
     // The kit's own notes to the model (a plan-mode switch) go before the human's words.
-    text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>\s*/g, "");
+    const text = raw.replace(/<system-reminder>[\s\S]*?<\/system-reminder>\s*/g, "");
     // Slash commands and the CLI's own notes arrive as tagged text, not as the human's words.
-    if (!text.trim() || /^\s*<[a-z-]+>/.test(text))
-        return null;
-    return { role: entry.type, text };
+    return !text.trim() || /^\s*<[a-z-]+>/.test(text) ? null : text;
 }
 /** The human's messages and the agent's replies in a run's conversation, in order. */
 export async function readConversation(dir) {
     const entries = (await readEntries(path.join(dir, CONVERSATION))) ?? [];
     return entries.map(entryText).filter((message) => message !== null);
 }
+/** A run's conversation with the main agent's tool calls in their place: what a view shows of a resumed one. */
+export async function readConversationSteps(dir) {
+    const entries = (await readEntries(path.join(dir, CONVERSATION))) ?? [];
+    const steps = [];
+    const calls = new Map();
+    for (const entry of entries) {
+        const message = entryText(entry);
+        if (message)
+            steps.push(message);
+        const content = entry.message?.content;
+        if (entry.isSidechain || !Array.isArray(content))
+            continue;
+        for (const part of content) {
+            if (entry.type === "assistant" && part.type === "tool_use" && part.id && part.name && !calls.has(part.id)) {
+                const call = { role: "tool", id: part.id, toolName: part.name, input: part.input, result: null };
+                calls.set(part.id, call);
+                steps.push(call);
+            }
+            else if (entry.type === "user" && part.type === "tool_result" && part.tool_use_id) {
+                const call = calls.get(part.tool_use_id);
+                if (!call)
+                    continue;
+                call.result = { isError: part.is_error === true, text: toolResultText(part.content) };
+                const meta = toolResultMeta(entry.mcpMeta);
+                if (meta)
+                    call.meta = meta;
+            }
+        }
+    }
+    return steps;
+}
 /** The runs under `runsDir` that kept a conversation, newest first; runs without `session.json` are left out. */
 export async function listRuns(runsDir) {
     let names;

package/dist/core/session.d.ts

@@ -118,11 +118,17 @@ export declare function pluginSkills(roots: readonly string[]): Promise<string[]
  *
  * With `modeControl`, each message goes after the note on a plan-mode switch the model
  * hasn't been told about yet (`ModeControl.takeNotice()`).
+ *
+ * `push(text, { priority: "next" })` is for a turn already running: the message joins it at its
+ * next tool boundary without stopping it, or gets a turn of its own when no tool call is left
+ * (confirmed empirically, SDK 0.3.300; `"now"` would cut the running tool).
  */
 export declare function createInputQueue(options?: {
     modeControl?: ModeControl;
 }): {
-    push: (text: string) => void;
+    push: (text: string, delivery?: {
+        priority?: "next";
+    }) => void;
     end: () => void;
     iterable: AsyncIterable<SDKUserMessage>;
 };

package/dist/core/session.js

@@ -609,6 +609,10 @@ async function projectSkills(projectDir) {
  *
  * With `modeControl`, each message goes after the note on a plan-mode switch the model
  * hasn't been told about yet (`ModeControl.takeNotice()`).
+ *
+ * `push(text, { priority: "next" })` is for a turn already running: the message joins it at its
+ * next tool boundary without stopping it, or gets a turn of its own when no tool call is left
+ * (confirmed empirically, SDK 0.3.300; `"now"` would cut the running tool).
  */
 export function createInputQueue(options = {}) {
     const pending = [];
@@ -616,8 +620,8 @@ export function createInputQueue(options = {}) {
     let ended = false;
     async function* generator() {
         while (!ended) {
-            const text = pending.shift();
-            if (text === undefined) {
+            const next = pending.shift();
+            if (next === undefined) {
                 await new Promise((resolve) => {
                     wake = resolve;
                 });
@@ -625,15 +629,16 @@ export function createInputQueue(options = {}) {
             }
             yield {
                 type: "user",
-                message: { role: "user", content: text },
+                message: { role: "user", content: next.text },
                 parent_tool_use_id: null,
+                ...(next.priority ? { priority: next.priority } : {}),
             };
         }
     }
     return {
-        push(text) {
+        push(text, delivery = {}) {
             const notice = options.modeControl?.takeNotice?.();
-            pending.push(notice ? `${notice}\n\n${text}` : text);
+            pending.push({ text: notice ? `${notice}\n\n${text}` : text, ...delivery });
             wake?.();
             wake = null;
         },

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/dist/tui/consoleRenderer.js

@@ -59,6 +59,7 @@ export function createConsoleRenderer(options = {}) {
             case "subagent-action":
             case "tool-result":
             case "prompt-suggestion":
+            case "session-idle":
                 return;
             case "mcp-error":
                 writeLine(ui.warn(t().mcpFailed(event.failedServers.join(", "))));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.32.0",
+  "version": "0.34.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",