@falkenslab/agent-kit 0.33.0 → 0.34.0

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[];
 }
@@ -251,6 +253,14 @@ export declare function createChatController(options: Options | SessionOpener, s
      * 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";
@@ -501,11 +553,28 @@ 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 });
+            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/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/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.33.0",
+  "version": "0.34.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",