nexus-ai-pro 2.5.0 → 2.6.0

package/API_STABILITY.md

@@ -41,6 +41,42 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## 2.6 stage (2.6.0)
+
+Everything 2.6 adds is stable from the start and additive.
+
+New and stable:
+- `ToolDefinition.stream`, `ToolContext.progress`, and `ToolBody`; `tool()` with `stream`. The
+  AG-UI event name `tool_progress`, and the `progress` and `callId` fields of a tool run's metadata;
+- `McpClient.callTool()`'s `progress` option, and `notifications/progress` from `McpServer`;
+- `AgUiOptions.stateDeltas`, `messagesSnapshot`, and `frontendTools`, and `AgUiPatchOperation`;
+- `CreateAgentOptions.toolSource` and `ToolSourceContext`; `ClientToolDefinition`, the `clientTools`
+  channel, and the `AgentStopReason` member `client_tools`;
+- the `step` member of `GraphEvent`;
+- on `nexus-ai-pro/protocols/a2a`: `A2aTaskStore`, `A2aTaskRecord`, `A2aTaskQuery`,
+  `MemoryA2aTaskStore`, `storeA2aTasks()`; `A2aServerOptions.store`, `pushNotifications`,
+  `extendedCard`, `pollMs`, and `onError`; `A2aPushOptions` and `A2aPushNotificationConfig`; the
+  methods `ListTasks`, `SubscribeToTask`, the four push notification config methods, and
+  `GetExtendedAgentCard`; the client's new methods, `A2aListTasksOptions`, and `A2aTaskPage`; and
+  the error codes `pushNotificationNotSupported` and `extendedCardNotConfigured`.
+
+- on `nexus-ai-pro/protocols/acp`: `AcpSessionStore`, `AcpSessionRecord`, `MemoryAcpSessionStore`,
+  `storeAcpSessions()`, `AcpOptions.sessions` and `editor`, `AcpEditorBridge`, `AcpConnection`,
+  `AcpClientCapabilities`, `session/load`, image and audio blocks, and the fourth argument of
+  `AcpOptions.input`;
+- `nexus-ai-pro/protocols/acp/editor`: `acpEditor()`, `AcpEditor`, `AcpEditorOptions`, and the tool
+  names `editor_read_file`, `editor_write_file`, and `editor_run_command`.
+
+An AG-UI run reports a node's tasks running side by side as one step, and finishes every step it
+started before `RUN_FINISHED` or `RUN_ERROR`. A2A `ListTasks` refuses a status that is not a task
+state, and reads `TASK_STATE_UNSPECIFIED` and `UNRECOGNIZED` as no filter.
+
+A streamed A2A task now reports its move to `TASK_STATE_WORKING` as a status update, before its
+other events.
+
+`GraphEvent` and `AgentStopReason` gain members, as the compatibility rules allow in a minor
+release. Code that switches over either exhaustively should handle the new ones.
+
 ## 2.5 stage (2.5.0)
 
 Everything 2.5 adds is stable from the start and additive.

package/CHANGELOG.md

@@ -4,6 +4,106 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-10-11
+
+Protocols complete, and progress on every stream.
+
+### Added
+
+- **Tool progress, end to end.**
+  - A `ToolDefinition` can have `stream`: an async generator that yields progress and returns the
+    result. `tool()` takes one instead of `execute`, and gives it an `execute` that runs the stream,
+    so it works wherever a tool is executed. `ToolExecutor` runs a stream itself.
+  - `ToolContext.progress` reports progress from any tool. An agent sets it, and turns each report
+    into a `progress` tool event while the tool runs.
+  - Progress reaches the event stream and the server's run events; AG-UI, as a `CUSTOM`
+    `tool_progress` event; A2A, as a working status update with the progress as data; ACP, as an
+    update of the tool call in progress; traces, in the tool run's `metadata.progress`; and the
+    studio's run view.
+  - MCP: `McpServer` runs `stream` tools and sends `notifications/progress` for a call that names a
+    `progressToken`. `McpClient.callTool()` takes a `progress` listener, and the tools from
+    `toNexusTools()` pass a remote tool's progress to the agent.
+
+- **AG-UI, complete**, each part opt-in on `AgUiOptions`:
+  - `stateDeltas` reports state as it changes: a `STATE_SNAPSHOT` after the first step, then a
+    `STATE_DELTA` with an RFC 6902 JSON Patch after every step that changed it, appending to arrays
+    item by item. `AgUiPatchOperation` is its type.
+  - `messagesSnapshot` sends the whole transcript as `MESSAGES_SNAPSHOT` before the run finishes.
+  - `frontendTools` offers the tools the frontend sends to the model. The frontend runs a call to one,
+    and the next run's messages carry its result.
+- **Tools the client runs.** An agent's input may carry `clientTools`, each a `ClientToolDefinition`.
+  The model is offered them; a call to one ends the turn with the new `stopReason: 'client_tools'`
+  once the agent's own calls of that step have run, and the client's result continues it. A client
+  tool never replaces a tool of the agent's own.
+- **Tools that depend on the run.** `CreateAgentOptions.toolSource` supplies tools per run, from a
+  `ToolSourceContext`, offered and run like `tools`, under the same permission policy.
+- **A2A, durable and complete.**
+  - Tasks and conversations live in an `A2aTaskStore`: `MemoryA2aTaskStore` by default, or
+    `storeA2aTasks()` over any long-term `Store`, so a task paused for an answer survives a restart
+    and another replica finishes it.
+  - `ListTasks` by context and state, a page at a time; `SubscribeToTask` on any replica; and a
+    cancel that stands against the replica running the task.
+  - Push notifications, with `pushNotifications`: each state change POSTed to a task's webhook,
+    with the caller's token and signed as the server's operation webhooks are. A webhook must be
+    `https` and not a private address, unless `allowPrivateNetworks` is set.
+  - `GetExtendedAgentCard`, with `extendedCard`, for authenticated callers.
+  - The client gains `extendedCard()`, `listTasks()`, `subscribe()`, `setPushNotification()`,
+    `listPushNotifications()`, `deletePushNotification()`, and `push` and `returnImmediately` when
+    sending.
+- **ACP, durable and complete.**
+  - Sessions live in an `AcpSessionStore`: `MemoryAcpSessionStore` by default, or
+    `storeAcpSessions()` over any long-term `Store`. The agent offers `session/load`, replays the
+    conversation, and asks again a question it was waiting on.
+  - A prompt can carry images and audio, which reach the model as content parts.
+  - `acpEditor()`, on the new `nexus-ai-pro/protocols/acp/editor`, gives an agent the editor's files,
+    terminal, and MCP servers, as tools from its `toolSource`, each declaring what it touches.
+    `serveAcp()` takes it as `editor`, and detaches it when the editor closes its end.
+- **Interoperability, proven.**
+  - A browser in CI: `npm run test:browser` serves the build to headless Chromium, which imports
+    every kernel entry point and runs a graph, an agent, and AG-UI. It runs in `npm test`.
+  - The previous minor on the other side of the wire: a 2.5 client against a 2.6 server, and the
+    other way round, on the server's HTTP API and A2A, and one harness across both releases for
+    AG-UI and ACP.
+  - A nightly `Interoperability` workflow drives each protocol with its reference client:
+    `@ag-ui/client`, `@a2a-js/sdk`, and `@agentclientprotocol/sdk`.
+- **A `step` graph event.** `GraphRunOptions.onEvent` receives `step` after each superstep, with the
+  state after it.
+
+### Fixed
+
+- AG-UI: a run that paused inside a node left that node's step open, so a strict client refused its
+  `RUN_FINISHED`; and a node's tasks running side by side each started the same step. A node's tasks
+  are now one step, and every step still open is finished before the run finishes or fails. Found by
+  the reference client.
+- A2A: `ListTasks` without a status filter, as the reference SDK sends it (`UNRECOGNIZED`), matched
+  no task. An unset filter now filters nothing, and an unknown state is refused as invalid.
+- MCP: the stdio transport's `close()` killed the server without waiting for it, so what the process
+  held, such as its working directory, could outlive the close. It now waits up to two seconds for
+  the process to exit.
+
+### Proof
+
+- Headless Chromium imports every kernel entry point and runs a graph, an agent with a streaming
+  tool, and AG-UI. A 2.5 client and a 2.6 server pass the protocol suites in both directions, and the
+  reference clients of AG-UI, A2A, and ACP each drive this release's servers through a whole run.
+- An ACP session paused on a question survives the agent's restart, on memory and SQLite; the
+  editor reopens it, sees the conversation replayed, and answers. An image and audio reach the model.
+  Through the bridge, an agent reads, writes (after the person allows it), and runs the tests in the
+  editor, and searches docs through an MCP server the editor offered, started as a real process.
+- An A2A task paused for an approval survives a restart and is finished by another replica, sending
+  its email once, on the memory, SQLite, Postgres, and Redis stores. A running task is followed where
+  it runs and from another replica; a cancel on one replica stands against the other. Every state
+  change reaches the webhook, signed and with the caller's token, and nine webhook URLs that point
+  into the agent's own network or are not https are refused.
+- An AG-UI client applying a run's snapshot and its deltas rebuilds the final state exactly, with
+  each new message one `add`. A frontend tool is offered to the model beside the agent's own; the
+  agent runs its own call, waits without calling the model again, and continues from the page's
+  result in the next run. A page cannot shadow the agent's tool, and without the options the events
+  are what they were.
+- A tool that will not go on until a reader has seen its first report finishes on every stream: the
+  event stream, the server's events, AG-UI, A2A, ACP, and MCP. Its reports arrive in order, after the
+  call and before the result, and its traced run keeps them.
+
 ## [2.5.0] - 2026-10-09
 
 Graduation finished, and conversations evaluated.
@@ -2104,7 +2204,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.5.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.6.0...HEAD
+[2.6.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.5.0...v2.6.0
 [2.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.2.0...v2.3.0

package/README.md

@@ -270,12 +270,18 @@ Shipped so far:
 - 2.5 graduation finished, and conversations evaluated: deployments that change atomically across
   replicas, revision worker pools, fair canaries judged on every run, and the studio out of
   experimental after a threat review; Postgres tenant usage; signed context named on every trace;
-  simulated users and thread evaluators; and a doctor that knows the opt-in settings.
+  simulated users and thread evaluators; and a doctor that knows the opt-in settings;
+- 2.6 protocols complete, and progress on every stream: a tool's progress reaching the event stream,
+  the protocols, traces, and the studio; AG-UI state deltas and frontend tools; A2A tasks and ACP
+  sessions that survive a restart, with push notifications, `session/load`, and the editor's files,
+  terminal, and MCP servers; and every protocol proven in a browser, against the previous release,
+  and against its reference client.
 
 Upgrading from 1.x: `npx nexus migrate src --write` moves your imports, and
 [MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers the rest.
-Next, 2.6 completes the agent protocols: tool progress on every stream, AG-UI deltas and frontend
-tools, A2A tasks and ACP sessions that survive a restart, and a browser in CI. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
+Next, 2.7 lets agents do more: provider tool search, an interpreter contract, workspace search,
+helpers that run beside the agent, and a container sandbox. Evaluation grows its own datasets and
+runs on workers, within a budget. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
 releases after it.
 
 ## Before Production

package/dist/agent/create-agent.d.ts

@@ -163,12 +163,44 @@ export interface CreateAgentOptions {
      * event once the model returns. Middleware sees the assembled response either way.
      */
     streamTokens?: boolean;
+    /**
+     * Tools that depend on the run, added to `tools` on every model call and run like them: an editor's
+     * file system for one session, or the MCP servers one user connected. A tool in `tools` wins over a
+     * source's tool of the same name.
+     */
+    toolSource?: (context: ToolSourceContext) => ToolDefinition[] | Promise<ToolDefinition[]>;
+}
+/** What a tool source is told about the run it supplies tools for. */
+export interface ToolSourceContext {
+    /** The run's thread. */
+    threadId: string;
+    /** The tenant the run is for. */
+    tenantId?: string;
+    /** Who the run is for. */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled. */
+    signal: AbortSignal;
+}
+/**
+ * A tool the client runs, such as one an AG-UI frontend offers: a name, a description, and a schema,
+ * with no implementation on the agent's side. Given in the input as `clientTools`, it is offered to
+ * the model like any tool. When the model calls one, the agent ends its turn with `stopReason:
+ * 'client_tools'`, and the client sends the result back in the next run's messages.
+ */
+export interface ClientToolDefinition {
+    /** The name the model calls it by. */
+    name: string;
+    /** What it does, written for the model. */
+    description: string;
+    /** JSON Schema for the arguments. */
+    parameters: Record<string, unknown>;
 }
 declare const agentChannels: () => {
     messages: import("../types/graph.js").Channel<Message[]>;
     iterations: import("../types/graph.js").Channel<number>;
     answer: import("../types/graph.js").Channel<string>;
     stopReason: import("../types/graph.js").Channel<AgentStopReason | undefined>;
+    clientTools: import("../types/graph.js").Channel<ClientToolDefinition[] | undefined>;
 };
 /** The agent's state channels, as a graph schema. */
 export type AgentChannels = ReturnType<typeof agentChannels>;
@@ -182,12 +214,15 @@ export type AgentState = {
     answer: string;
     /** Why the agent stopped. */
     stopReason?: AgentStopReason;
+    /** Tools the client runs, given in the input; see `ClientToolDefinition`. */
+    clientTools?: ClientToolDefinition[];
 };
 /**
  * `completed` when the model answered, `max_iterations` when it ran out of model calls, `stopped`
- * when a middleware ended the run through `context.stop()`.
+ * when a middleware ended the run through `context.stop()`, and `client_tools` when the model called
+ * a tool the client runs, which waits for the client's result.
  */
-export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped';
+export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped' | 'client_tools';
 /** An agent: a compiled graph over the agent's channels. */
 export type AgentGraph = CompiledGraph<AgentChannels>;
 /** Wraps a question into the state an agent starts from. */

package/dist/agent/create-agent.js

@@ -8,6 +8,7 @@ const agentChannels = () => ({
     iterations: counter(),
     answer: lastValue(''),
     stopReason: lastValue(undefined),
+    clientTools: lastValue(undefined),
 });
 export function agentInput(goal) {
     return { messages: [{ role: 'user', content: goal }] };
@@ -20,16 +21,33 @@ export function createAgent(options) {
     const executor = new ToolExecutor(options.tools ?? []);
     const middleware = options.middleware ?? [];
     const approvals = options.interruptOn ?? {};
+    const toolsFor = async (context) => {
+        if (!options.toolSource)
+            return executor;
+        const supplied = await options.toolSource({
+            threadId: context.threadId,
+            ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
+            ...(context.principal ? { principal: context.principal } : {}),
+            signal: context.signal,
+        });
+        return supplied.length ? new ToolExecutor([...supplied, ...executor.list()]) : executor;
+    };
     const graph = createGraph({ channels: agentChannels() })
         .addNode('model', async (context) => {
         const state = context.state;
+        const runTools = await toolsFor(context);
+        const clientTools = clientToolsOf(state, runTools);
+        if (clientTools.length > 0 && waitingOnClient(state.messages, clientTools)) {
+            return new Command({ update: { stopReason: 'client_tools' }, goto: END });
+        }
+        const offered = [...runTools.list(), ...clientTools];
         let request = {
             model: options.model ?? 'auto',
             messages: [
                 ...(options.systemPrompt ? [{ role: 'system', content: options.systemPrompt }] : []),
                 ...state.messages,
             ],
-            ...(options.tools?.length ? { tools: executor.list() } : {}),
+            ...(offered.length ? { tools: offered } : {}),
             ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
             ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
             ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
@@ -88,9 +106,28 @@ export function createAgent(options) {
                 goto: END,
             });
         }
+        const forClient = new Set(clientTools.map((item) => item.name));
+        const ours = calls.filter((call) => !forClient.has(call.function.name));
+        for (const call of calls) {
+            if (!forClient.has(call.function.name))
+                continue;
+            const parsed = parseArguments(call.function.arguments);
+            context.tool({
+                phase: 'start',
+                id: call.id,
+                name: call.function.name,
+                args: parsed.ok ? parsed.args : call.function.arguments,
+            });
+        }
+        if (ours.length === 0) {
+            return new Command({
+                update: { messages: [assistant], iterations: 1, stopReason: 'client_tools' },
+                goto: END,
+            });
+        }
         return new Command({
             update: { messages: [assistant], iterations: 1 },
-            goto: calls.map((call) => new Send('tools', call)),
+            goto: ours.map((call) => new Send('tools', call)),
         });
     }, { ends: ['tools', END] })
         .addNode('tools', async (context) => {
@@ -100,7 +137,8 @@ export function createAgent(options) {
             return { messages: [toolMessage(call, { ok: false, error: parsed.error })] };
         }
         let args = parsed.args;
-        const definition = executor.get(call.function.name);
+        const runTools = await toolsFor(context);
+        const definition = runTools.get(call.function.name);
         const capabilities = capabilitiesOf(definition, args);
         const description = {
             id: call.id,
@@ -159,13 +197,14 @@ export function createAgent(options) {
                 if (recheck.decision === 'deny')
                     return { ok: false, error: `Permission denied: ${recheck.reason}` };
             }
-            return executor.execute(description.name, current.args, {
+            return runTools.execute(description.name, current.args, {
                 toolCallId: call.id,
                 threadId: context.threadId,
                 ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
                 ...(context.principal ? { principal: context.principal } : {}),
                 signal: context.signal,
                 ...(context.store ? { store: context.store } : {}),
+                progress: (progress) => context.tool({ phase: 'progress', id: call.id, name: description.name, progress }),
             });
         };
         context.tool({ phase: 'start', id: call.id, name: description.name, args });
@@ -250,6 +289,25 @@ function parseArguments(raw) {
         return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
     }
 }
+function clientToolsOf(state, runTools) {
+    return (state.clientTools ?? []).filter((item) => typeof item?.name === 'string' && item.name !== '' && !runTools.has(item.name));
+}
+function waitingOnClient(messages, clientTools) {
+    const names = new Set(clientTools.map((item) => item.name));
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === 'user')
+            return false;
+        if (message.role !== 'assistant' || !message.toolCalls?.length)
+            continue;
+        const answered = new Set(messages
+            .slice(index + 1)
+            .filter((item) => item.role === 'tool')
+            .map((item) => item.toolCallId));
+        return message.toolCalls.some((call) => names.has(call.function.name) && !answered.has(call.id));
+    }
+    return false;
+}
 function hookContext(context, state, store) {
     return {
         state,

package/dist/agent/index.d.ts

@@ -1,6 +1,7 @@
 export { AgentLoop, type AgentModelClient as AgentLoopModelClient } from './loop.js';
 export { isToolOutput, tool, ToolExecutor, toolMessageContent, toolOutput } from './tool.js';
+export type { ToolBody } from './tool.js';
 export { limitToolCalls, redactMessages, type RedactOptions, summarizeHistory, type SummarizeOptions, } from './middleware/basic.js';
-export { agentAsTool, agentInput, type AgentApproval, type AgentApprovalPolicy, type AgentChannels, type AgentGraph, type AgentMiddleware, type AgentMiddlewareContext, type AgentModelCallContext, type AgentModelClient, type AgentState, type AgentStopReason, type AgentToolCall, type AgentToolResult, createAgent, type CreateAgentOptions, } from './create-agent.js';
+export { agentAsTool, agentInput, type AgentApproval, type AgentApprovalPolicy, type AgentChannels, type AgentGraph, type AgentMiddleware, type AgentMiddlewareContext, type AgentModelCallContext, type AgentModelClient, type AgentState, type AgentStopReason, type AgentToolCall, type AgentToolResult, type ClientToolDefinition, createAgent, type CreateAgentOptions, type ToolSourceContext, } from './create-agent.js';
 export type { AgentConfig, AgentResult, AgentStep, ToolExecutionResult } from '../types/agent.js';
 export type { ToolContext } from '../types/messages.js';

package/dist/agent/tool.d.ts

@@ -1,15 +1,30 @@
 import type { ContentPart, Message, ToolContext, ToolDefinition, ToolOutput } from '../types/messages.js';
 import type { ToolExecutionResult } from '../types/agent.js';
-/** Defines a tool the model can call, typing its arguments. */
+/** How a tool built with `tool()` runs: once, with `execute`, or reporting progress, with `stream`. */
+export type ToolBody<TArgs> = {
+    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
+    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
+    stream?: never;
+} | {
+    /**
+     * Runs the tool, yielding progress while it works and returning the result. See
+     * `ToolDefinition.stream`.
+     */
+    stream: (args: TArgs, context: ToolContext) => AsyncGenerator<unknown, unknown, undefined>;
+    execute?: never;
+};
+/**
+ * Defines a tool the model can call, typing its arguments. A tool given `stream` gets an `execute`
+ * too, which runs the stream and reports each yield to `context.progress`, so it works wherever a
+ * tool is executed.
+ */
 export declare function tool<TArgs extends Record<string, unknown> = Record<string, unknown>>(definition: {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
-    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
-    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
     /** What the tool does to the world, for a permission policy; see `ToolDefinition.capabilities`. */
     capabilities?: readonly string[] | ((args: TArgs) => readonly string[]);
-}): ToolDefinition;
+} & ToolBody<TArgs>): ToolDefinition;
 /**
  * Builds a tool's result as content: text, images, and asset references, in order. A string becomes
  * a text part. Returned from `execute`, it is sent as the tool message itself, so an image a tool

package/dist/agent/tool.js

@@ -1,10 +1,19 @@
 export function tool(definition) {
     const capabilities = definition.capabilities;
+    const stream = definition.stream;
+    const execute = definition.execute;
     return {
         name: definition.name,
         description: definition.description,
         parameters: definition.parameters,
-        execute: async (args, context) => definition.execute(args, context ?? {}),
+        ...(stream
+            ? {
+                stream: (args, context) => stream(args, context ?? {}),
+                execute: async (args, context) => drain(stream(args, context ?? {}), context?.progress),
+            }
+            : {
+                execute: async (args, context) => execute(args, context ?? {}),
+            }),
         ...(capabilities === undefined
             ? {}
             : {
@@ -31,6 +40,18 @@ export function toolMessageContent(result) {
         return result.result.content;
     return JSON.stringify(result.ok ? (result.result ?? null) : { error: result.error });
 }
+async function drain(generator, progress) {
+    for (;;) {
+        const step = await generator.next();
+        if (step.done)
+            return step.value;
+        try {
+            progress?.(step.value);
+        }
+        catch {
+        }
+    }
+}
 export class ToolExecutor {
     tools = new Map();
     constructor(tools = []) {
@@ -56,11 +77,13 @@ export class ToolExecutor {
         if (!toolDefinition) {
             return { ok: false, error: `Tool "${name}" is not registered` };
         }
-        if (!toolDefinition.execute) {
-            return { ok: false, error: `Tool "${name}" does not have an execute function` };
+        if (!toolDefinition.execute && !toolDefinition.stream) {
+            return { ok: false, error: `Tool "${name}" does not have an execute or stream function` };
         }
         try {
-            const result = await toolDefinition.execute(args, context);
+            const result = toolDefinition.stream
+                ? await drain(toolDefinition.stream(args, context), context?.progress)
+                : await toolDefinition.execute(args, context);
             return { ok: true, result };
         }
         catch (err) {

package/dist/graph/event-stream.js

@@ -265,6 +265,8 @@ function fromGraphEvent(event) {
             return [
                 { type: 'custom', step: event.step, node: event.node, taskId: event.taskId, data: event.data, namespace },
             ];
+        case 'step':
+            return [];
         case 'checkpoint':
             return [{ type: 'checkpoints', step: event.step, status: event.status, next: event.next, namespace }];
         case 'task_end':

package/dist/graph/graph.js

@@ -477,7 +477,10 @@ export class CompiledGraph {
         this.writers.add(writer);
         let failed = false;
         try {
-            yield* this.steps(threadId, runOptions, seed, (written, durable) => writer.persist(written, durable));
+            for await (const event of this.steps(threadId, runOptions, seed, (written, durable) => writer.persist(written, durable))) {
+                notify(runOptions, { type: 'step', step: event.step, status: event.status, state: event.state });
+                yield event;
+            }
         }
         catch (error) {
             failed = true;

package/dist/mcp/client.d.ts

@@ -61,6 +61,8 @@ export declare class McpClient {
     private readonly options;
     private readonly pending;
     private nextId;
+    /** Where each progress token's reports go, while its tool call runs. */
+    private readonly progress;
     private initialized;
     private connecting;
     private serverInfo;
@@ -80,7 +82,13 @@ export declare class McpClient {
      * Calls a tool. A tool that fails reports `isError` rather than throwing; a protocol failure
      * throws `McpError`.
      */
-    callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        progress?: (progress: {
+            progress: number;
+            total?: number;
+            message?: string;
+        }) => void;
+    }): Promise<McpToolResult>;
     /** Lists the server's resources. */
     listResources(): Promise<McpResourceDescriptor[]>;
     /** Reads a resource's content. */

package/dist/mcp/client.js

@@ -1,9 +1,10 @@
-import { isRequest, isResponse, LineDecoder, MCP_PROTOCOL_VERSION, McpError, } from './protocol.js';
+import { isNotification, isRequest, isResponse, LineDecoder, MCP_PROTOCOL_VERSION, McpError, } from './protocol.js';
 export class McpClient {
     transport;
     options;
     pending = new Map();
     nextId = 1;
+    progress = new Map();
     initialized = false;
     connecting;
     serverInfo = {};
@@ -38,10 +39,23 @@ export class McpClient {
         const result = (await this.request('tools/list'));
         return result?.tools ?? [];
     }
-    async callTool(name, args = {}) {
+    async callTool(name, args = {}, options = {}) {
         await this.connect();
-        const result = (await this.request('tools/call', { name, arguments: args }));
-        return { content: result?.content ?? [], ...(result?.isError ? { isError: true } : {}) };
+        const token = options.progress ? `progress-${this.nextId}` : undefined;
+        if (token && options.progress)
+            this.progress.set(token, options.progress);
+        try {
+            const result = (await this.request('tools/call', {
+                name,
+                arguments: args,
+                ...(token ? { _meta: { progressToken: token } } : {}),
+            }));
+            return { content: result?.content ?? [], ...(result?.isError ? { isError: true } : {}) };
+        }
+        finally {
+            if (token)
+                this.progress.delete(token);
+        }
     }
     async listResources() {
         await this.connect();
@@ -69,8 +83,9 @@ export class McpClient {
             name: options.prefix ? `${options.prefix}_${descriptor.name}` : descriptor.name,
             description: descriptor.description ?? `MCP tool ${descriptor.name}`,
             parameters: descriptor.inputSchema ?? { type: 'object', properties: {} },
-            execute: async (args) => {
-                const result = await this.callTool(descriptor.name, args);
+            execute: async (args, context) => {
+                const progress = context?.progress;
+                const result = await this.callTool(descriptor.name, args, progress ? { progress } : {});
                 const text = result.content
                     .map((part) => part.text ?? (part.type === 'text' ? '' : JSON.stringify(part)))
                     .filter(Boolean)
@@ -107,6 +122,16 @@ export class McpClient {
             this.settle(message.id, message.result, message.error ? new McpError(message.error.message, message.error.code, message.error.data) : undefined);
             return;
         }
+        if (isNotification(message) && message.method === 'notifications/progress') {
+            const params = (message.params ?? {});
+            const report = this.progress.get(String(params.progressToken));
+            report?.({
+                progress: typeof params.progress === 'number' ? params.progress : 0,
+                ...(typeof params.total === 'number' ? { total: params.total } : {}),
+                ...(typeof params.message === 'string' ? { message: params.message } : {}),
+            });
+            return;
+        }
         if (isRequest(message)) {
             void this.transport.send({
                 jsonrpc: '2.0',
@@ -221,9 +246,14 @@ export function createStdioTransport(options) {
         onClose(handler) {
             onClose = handler;
         },
-        close() {
-            child?.kill();
+        async close() {
+            const running = child;
             child = undefined;
+            if (!running || running.exitCode !== null || running.signalCode !== null)
+                return;
+            const exited = new Promise((resolve) => running.once('close', () => resolve()));
+            running.kill();
+            await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 2_000).unref?.())]);
         },
     };
 }