nexus-ai-pro 2.4.0 → 2.6.0

package/dist/context-hub/signing.js

@@ -0,0 +1,88 @@
+import { canonicalJson } from '../prompts/version.js';
+import { decodeBase64, encodeBase64 } from '../utils/base64.js';
+const subtle = () => globalThis.crypto.subtle;
+const ED25519 = { name: 'Ed25519' };
+export async function generateContextKey(keyId) {
+    const pair = await subtle().generateKey(ED25519, true, ['sign', 'verify']);
+    const publicKey = await subtle().exportKey('jwk', pair.publicKey);
+    const privateKey = await subtle().exportKey('jwk', pair.privateKey);
+    const id = keyId ?? (await keyIdOf(publicKey));
+    return { keyId: id, signer: await ed25519Signer(id, pair.privateKey), publicKey, privateKey };
+}
+export async function ed25519Signer(keyId, privateKey) {
+    const key = isCryptoKey(privateKey)
+        ? privateKey
+        : await subtle().importKey('jwk', privateKey, ED25519, false, ['sign']);
+    return { keyId, sign: async (data) => new Uint8Array(await subtle().sign(ED25519, key, data)) };
+}
+export async function ed25519Keyring(keys) {
+    const imported = new Map();
+    for (const [keyId, key] of Object.entries(keys)) {
+        imported.set(keyId, isCryptoKey(key) ? key : await subtle().importKey('jwk', key, ED25519, false, ['verify']));
+    }
+    return {
+        async verify(keyId, data, signature) {
+            const key = imported.get(keyId);
+            if (!key)
+                return false;
+            try {
+                return await subtle().verify(ED25519, key, signature, data);
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+export async function contextDigest(content) {
+    const text = canonicalJson({ format: 'nexus-context-signature', formatVersion: 1, ...content });
+    const digest = await subtle().digest('SHA-256', new TextEncoder().encode(text));
+    return `sha256:${hexOf(new Uint8Array(digest))}`;
+}
+export async function signDigest(signer, digest, at) {
+    const signature = await signer.sign(new TextEncoder().encode(digest));
+    return {
+        keyId: signer.keyId,
+        algorithm: 'Ed25519',
+        digest,
+        signature: toBase64Url(signature),
+        signedAt: at.toISOString(),
+    };
+}
+export async function verifiedBy(keyring, digest, signatures = []) {
+    const data = new TextEncoder().encode(digest);
+    for (const signature of signatures) {
+        if (signature?.algorithm !== 'Ed25519' || signature.digest !== digest)
+            continue;
+        let bytes;
+        try {
+            bytes = fromBase64Url(signature.signature);
+        }
+        catch {
+            continue;
+        }
+        if (await keyring.verify(signature.keyId, data, bytes))
+            return signature;
+    }
+    return undefined;
+}
+async function keyIdOf(publicKey) {
+    const digest = await subtle().digest('SHA-256', new TextEncoder().encode(String(publicKey.x)));
+    return hexOf(new Uint8Array(digest).subarray(0, 8));
+}
+function hexOf(bytes) {
+    let hex = '';
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}
+function isCryptoKey(value) {
+    return typeof value.algorithm === 'object' && Array.isArray(value.usages);
+}
+function toBase64Url(bytes) {
+    return encodeBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(text) {
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/');
+    return decodeBase64(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+}

package/dist/doctor/index.d.ts

@@ -42,8 +42,10 @@ export interface DoctorDeployment {
     replicas: number;
     /**
      * The stores and shared state it uses, by any name: a checkpointer, the operation store, the
-     * server's state, tenant usage, a rate-limit store, a circuit store, a cache. Each is reported when
-     * it keeps its state in process memory, where each replica would see only its own.
+     * server's state, tenant usage, a rate-limit store, a circuit store, a cache, a tracer. Each is
+     * reported when it keeps its state in process memory, where each replica would see only its own,
+     * and when it lacks an opt-in setting a deployment needs: a Redis operation store without its
+     * dispatch index, or a tracer writing to a persistent store without incremental tracing.
      */
     stores?: Record<string, unknown>;
 }

package/dist/doctor/index.js

@@ -54,6 +54,7 @@ export async function diagnose(options = {}) {
     await run('queue', 'Operation queue and leases', () => queueCheck(options.operations, now(), options.maxQueueAgeMs));
     await run('health', 'Provider health', () => healthCheck(options.ai));
     await run('topology', 'Settings that only work in one process', () => topologyCheck(options.deployment));
+    await run('settings', 'Opt-in settings a deployment needs', () => settingsCheck(options.deployment));
     const failures = checks.filter((check) => check.status === 'fail').length;
     const warnings = checks.filter((check) => check.status === 'warn').length;
     return { checks, ok: failures === 0, failures, warnings };
@@ -235,3 +236,31 @@ function topologyCheck(deployment) {
         hint: 'Use the Redis, Postgres, or SQLite adapter for each, or run one replica.',
     };
 }
+function settingsCheck(deployment) {
+    const stores = Object.entries(deployment?.stores ?? {});
+    if (stores.length === 0)
+        return { status: 'skip', detail: 'No stores described.' };
+    const findings = [];
+    const hints = new Set();
+    for (const [name, value] of stores) {
+        const kind = kindOf(value);
+        if (kind === 'RedisOperationStore' && value.indexed === false) {
+            findings.push(`${name} is a RedisOperationStore without index: true, so finding queued work reads every record and a long queue slows every claim`);
+            hints.add('Give the Redis operation store index: true once every worker sharing its prefix runs 2.2 or later, then call reindex() once.');
+        }
+        if (kind === 'Tracer') {
+            const tracer = value;
+            const store = kindOf(tracer.store);
+            if (tracer.incremental === false && store && store !== 'MemoryTraceStore') {
+                findings.push(`${name} writes to a ${store} without incremental, so a trace is written when its root finishes and a replica that dies mid-run loses it`);
+                hints.add('Create the Tracer with incremental: true, and close what a dead process left with closeAbandonedRuns().');
+            }
+        }
+    }
+    if (findings.length === 0)
+        return { status: 'ok', detail: 'No store lacks a setting a deployment needs.' };
+    return { status: 'warn', detail: `${findings.join('; ')}.`, hint: [...hints].join(' ') };
+}
+function kindOf(value) {
+    return value?.constructor?.name;
+}

package/dist/evaluate/threads.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Evaluation of whole conversations. A simulated user holds a conversation with an agent for each
+ * goal in a dataset, and thread evaluators score the conversation: whether the goal was met, each
+ * turn, and the turn where it went wrong. A multi-turn agent is then compared between versions as a
+ * single-turn one is, with `evaluate()` and `compareExperiments()`.
+ */
+import type { LLMJudge } from '../evals/judge.js';
+import type { Evaluator } from '../types/evaluate.js';
+import type { CompletionRequest, Message } from '../types/messages.js';
+import type { EvaluationTarget } from './run.js';
+/** One turn of a conversation. */
+export interface ThreadTurn {
+    /** Who spoke. */
+    role: 'user' | 'assistant';
+    /** What they said. */
+    content: string;
+    /** For an assistant turn, how long the agent took, in milliseconds. */
+    latencyMs?: number;
+    /**
+     * For an assistant turn, every message the agent added: its tool calls, their results, and the
+     * answer. The agent is given them back on later turns, and an evaluator can read its trajectory.
+     */
+    messages?: Message[];
+}
+/** Why a conversation ended. */
+export type ThreadEnding = 'goal' | 'gave-up' | 'max-turns' | 'error';
+/** A finished conversation: what a conversation target returns, and what thread evaluators read. */
+export interface Thread {
+    /** Every turn, in order. */
+    turns: ThreadTurn[];
+    /**
+     * `goal` when the user said its goal was met, `gave-up` when it said it never would be, `max-turns`
+     * when the turn limit ended it, and `error` when the agent failed.
+     */
+    ended: ThreadEnding;
+    /** The agent's error, when it failed. */
+    error?: string;
+}
+/** What a conversation is about: the user's goal, and optionally who they are and how they open. */
+export interface ThreadInputs {
+    /** What the user wants, in their words or the dataset's. */
+    goal: string;
+    /** Who the user is and how they talk, such as "an impatient customer who writes in short lines". */
+    persona?: string;
+    /** The user's first message, instead of letting the simulated user write it. */
+    opening?: string;
+}
+/** What a simulated user sees when it writes its next message. */
+export interface SimulatedUserContext {
+    /** The goal. */
+    goal: string;
+    /** The persona, when the example gives one. */
+    persona?: string;
+    /** The conversation so far. Empty for the first message. */
+    turns: readonly ThreadTurn[];
+    /** Aborted when the evaluation is cancelled or times out. */
+    signal?: AbortSignal;
+}
+/** A simulated user's move: its next message, or the end of the conversation and why. */
+export type SimulatedUserReply = {
+    message: string;
+} | {
+    done: 'goal' | 'gave-up';
+};
+/** Plays the user in a conversation. */
+export interface SimulatedUser {
+    /** The next move, given the conversation so far. */
+    next(context: SimulatedUserContext): Promise<SimulatedUserReply> | SimulatedUserReply;
+}
+/** A model client, as the judges take one. */
+export interface SimulatedUserClient {
+    /** Runs one completion. */
+    complete(request: CompletionRequest): Promise<{
+        content: string;
+    }>;
+}
+/** Options for `simulatedUser()`. */
+export interface SimulatedUserOptions {
+    /** The client the user's model is called through. */
+    client: SimulatedUserClient;
+    /** The model that plays the user. */
+    model: string;
+    /** A persona for every conversation, when the examples give none. */
+    persona?: string;
+    /** Sampling temperature. Defaults to 0, so a conversation repeats. */
+    temperature?: number;
+    /** Output token limit for each message. Defaults to 300. */
+    maxTokens?: number;
+    /** Replaces the instructions the model is given. `{goal}` and `{persona}` are filled in. */
+    instructions?: string;
+}
+/**
+ * A simulated user driven by a model: it is told the goal and the persona, sees the conversation
+ * with the roles turned around, and writes the next message, or says it is done and why.
+ */
+export declare function simulatedUser(options: SimulatedUserOptions): SimulatedUser;
+/**
+ * A user that follows a script, for deterministic tests: its messages in order, then `done`. A
+ * function decides each move itself.
+ */
+export declare function scriptedUser(script: {
+    messages: readonly string[];
+    done?: 'goal' | 'gave-up';
+} | SimulatedUser['next']): SimulatedUser;
+/** What a thread agent is told besides the conversation. */
+export interface ThreadAgentContext<I extends ThreadInputs = ThreadInputs> {
+    /** The example's inputs. */
+    inputs: I;
+    /** The turn, counted from 1. */
+    turn: number;
+    /** Names this conversation, the same on every turn and new for every conversation: a thread id. */
+    conversationId: string;
+    /** Aborted when the evaluation is cancelled or times out. */
+    signal?: AbortSignal;
+}
+/**
+ * What a thread agent answers: the reply, or the reply and every message the agent added on the way,
+ * such as its tool calls and their results. Those are given back to it on later turns.
+ */
+export type ThreadAgentReply = string | {
+    content: string;
+    messages?: Message[];
+};
+/**
+ * The agent a conversation target talks to. It is given the conversation so far, with its own earlier
+ * turns as it recorded them, and answers the user's newest message.
+ */
+export type ThreadAgent<I extends ThreadInputs = ThreadInputs> = (messages: readonly Message[], context: ThreadAgentContext<I>) => Promise<ThreadAgentReply> | ThreadAgentReply;
+/** Options for `conversationTarget()`. */
+export interface ConversationTargetOptions<I extends ThreadInputs = ThreadInputs> {
+    /** The user, or a user per example, such as one with the example's own persona. */
+    user: SimulatedUser | ((inputs: I) => SimulatedUser);
+    /** The most user messages a conversation may have. Defaults to 10. */
+    maxTurns?: number;
+}
+/**
+ * An `evaluate()` target that holds a conversation per example: the simulated user speaks, the agent
+ * answers, until the user says it is done or the turn limit is reached. It returns the `Thread`.
+ */
+export declare function conversationTarget<I extends ThreadInputs = ThreadInputs>(agent: ThreadAgent<I>, options: ConversationTargetOptions<I>): EvaluationTarget<I>;
+/** A graph a thread agent can drive: one that takes `{ messages }`, as `createAgent()` builds. */
+export interface ThreadGraph {
+    /** Runs one turn. */
+    invoke(input: {
+        messages: Message[];
+    }, options?: {
+        threadId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        state: unknown;
+    }>;
+}
+/**
+ * An agent from `createAgent()`, or any graph that takes `{ messages }` and ends with an `answer`, as
+ * a thread agent. Each turn runs on the conversation's thread with the transcript so far, and the
+ * messages the run added to its `messages` are recorded with the turn. The agent therefore sees its
+ * own tool calls on later turns, as it does with a real user, without needing a checkpointer.
+ */
+export declare function graphThreadAgent(graph: ThreadGraph): ThreadAgent;
+/** The conversation as text, for a judge or a person. */
+export declare function formatThread(thread: Thread): string;
+/**
+ * Whether the user said its goal was met: 1 when the conversation ended on `goal`, otherwise 0, with
+ * how it ended as the comment. Key `goal_reached`.
+ */
+export declare function goalReached(): Evaluator<ThreadInputs>;
+/**
+ * Whether the goal was met, in a judge's opinion of the whole conversation, not the user's. Key
+ * `goal_completion`, with the judge's rationale as the comment.
+ */
+export declare function goalCompletion(judge: Pick<LLMJudge, 'evaluate'>): Evaluator<ThreadInputs>;
+/** How many times the assistant spoke: fewer is better. Key `turns`; compare with `lowerIsBetter: ['turns']`. */
+export declare function turnCount(): Evaluator<ThreadInputs>;
+/** Options for `turnScores()`. */
+export interface TurnScoresOptions {
+    /** The score's key. Defaults to `turn_score`. */
+    key?: string;
+    /** A turn scoring below this went wrong. Defaults to 0.5. */
+    threshold?: number;
+}
+/**
+ * Scores every assistant turn with an evaluator of single answers, and the conversation by their
+ * mean. The evaluator sees each turn as an example of its own: the user's message as the input, the
+ * conversation before it in `metadata.history`, and the turn as the output. The score's metadata holds
+ * each turn's score, and `wentWrongAt`, the first turn below the threshold, counted from 1.
+ */
+export declare function turnScores<I = unknown>(evaluator: Evaluator<I>, options?: TurnScoresOptions): Evaluator<ThreadInputs>;

package/dist/evaluate/threads.js

@@ -0,0 +1,187 @@
+const USER_INSTRUCTIONS = `You are playing a user who is talking to an assistant. Stay in character.
+Your goal: {goal}
+{persona}
+Write only your next message to the assistant, as the user would. Give details the assistant asks for when your goal needs them.
+When the assistant has fully achieved your goal, reply with exactly: DONE: GOAL
+When you are sure the assistant will never achieve it, reply with exactly: DONE: GAVE UP`;
+const DONE = /^\s*DONE:\s*(GOAL|GAVE[\s-]*UP)\b/i;
+export function simulatedUser(options) {
+    return {
+        async next(context) {
+            const instructions = (options.instructions ?? USER_INSTRUCTIONS)
+                .replace('{goal}', context.goal)
+                .replace('{persona}', context.persona ?? options.persona ?? '');
+            const messages = [
+                { role: 'system', content: instructions },
+                ...context.turns.map((turn) => ({
+                    role: turn.role === 'assistant' ? 'user' : 'assistant',
+                    content: turn.content,
+                })),
+            ];
+            if (context.turns.length === 0)
+                messages.push({ role: 'user', content: 'Begin the conversation.' });
+            const response = await options.client.complete({
+                model: options.model,
+                messages,
+                temperature: options.temperature ?? 0,
+                maxTokens: options.maxTokens ?? 300,
+                ...(context.signal ? { signal: context.signal } : {}),
+            });
+            const done = DONE.exec(response.content ?? '');
+            if (done)
+                return { done: /^GOAL$/i.test(done[1]) ? 'goal' : 'gave-up' };
+            return { message: (response.content ?? '').trim() };
+        },
+    };
+}
+export function scriptedUser(script) {
+    if (typeof script === 'function')
+        return { next: script };
+    return {
+        next: ({ turns }) => {
+            const said = turns.filter((turn) => turn.role === 'user').length;
+            const message = script.messages[said];
+            return message === undefined ? { done: script.done ?? 'goal' } : { message };
+        },
+    };
+}
+export function conversationTarget(agent, options) {
+    const maxTurns = options.maxTurns ?? 10;
+    return async (inputs, context) => {
+        const user = typeof options.user === 'function' ? options.user(inputs) : options.user;
+        const turns = [];
+        const conversationId = `${context.example.id}:${context.run}:${globalThis.crypto.randomUUID()}`;
+        const ask = async () => user.next({
+            goal: inputs.goal,
+            ...(inputs.persona === undefined ? {} : { persona: inputs.persona }),
+            turns,
+            ...(context.signal ? { signal: context.signal } : {}),
+        });
+        let move = inputs.opening === undefined ? await ask() : { message: inputs.opening };
+        for (let turn = 1;; turn += 1) {
+            if ('done' in move)
+                return { turns, ended: move.done };
+            if (turn > maxTurns)
+                return { turns, ended: 'max-turns' };
+            turns.push({ role: 'user', content: move.message });
+            const started = performance.now();
+            try {
+                const reply = await agent(transcriptOf(turns), {
+                    inputs,
+                    turn,
+                    conversationId,
+                    ...(context.signal ? { signal: context.signal } : {}),
+                });
+                const latencyMs = Math.round(performance.now() - started);
+                turns.push(typeof reply === 'string'
+                    ? { role: 'assistant', content: reply, latencyMs }
+                    : {
+                        role: 'assistant',
+                        content: reply.content,
+                        latencyMs,
+                        ...(reply.messages ? { messages: reply.messages } : {}),
+                    });
+            }
+            catch (error) {
+                return {
+                    turns,
+                    ended: 'error',
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+            move = await ask();
+        }
+    };
+}
+function transcriptOf(turns) {
+    return turns.flatMap((turn) => turn.role === 'assistant' && turn.messages?.length ? turn.messages : [{ role: turn.role, content: turn.content }]);
+}
+export function graphThreadAgent(graph) {
+    return async (messages, context) => {
+        const result = await graph.invoke({ messages: [...messages] }, { threadId: context.conversationId, ...(context.signal ? { signal: context.signal } : {}) });
+        const state = result.state;
+        const content = typeof state?.answer === 'string' ? state.answer : JSON.stringify(result.state);
+        const after = Array.isArray(state?.messages) ? state.messages : undefined;
+        return after && after.length > messages.length ? { content, messages: after.slice(messages.length) } : content;
+    };
+}
+function threadOf(context) {
+    const output = context.output;
+    return output && Array.isArray(output.turns) ? output : undefined;
+}
+export function formatThread(thread) {
+    return thread.turns.map((turn) => `${turn.role === 'user' ? 'User' : 'Assistant'}: ${turn.content}`).join('\n\n');
+}
+export function goalReached() {
+    return (context) => {
+        const thread = threadOf(context);
+        const reached = thread?.ended === 'goal';
+        return {
+            key: 'goal_reached',
+            score: reached ? 1 : 0,
+            passed: reached,
+            comment: thread ? `ended: ${thread.ended}${thread.error ? ` (${thread.error})` : ''}` : 'no conversation',
+        };
+    };
+}
+export function goalCompletion(judge) {
+    return async (context) => {
+        const thread = threadOf(context);
+        if (!thread)
+            return { key: 'goal_completion', score: 0, passed: false, comment: 'no conversation' };
+        const verdict = await judge.evaluate({
+            actual: formatThread(thread),
+            query: context.example.inputs.goal,
+            rubric: "The text is a conversation between a user and an assistant. Score whether the assistant achieved the user's goal, given as the question, by the end of the conversation.",
+        });
+        return {
+            key: 'goal_completion',
+            score: verdict.score,
+            passed: verdict.passed,
+            ...(verdict.rationale ? { comment: verdict.rationale } : {}),
+        };
+    };
+}
+export function turnCount() {
+    return (context) => ({
+        key: 'turns',
+        score: threadOf(context)?.turns.filter((turn) => turn.role === 'assistant').length ?? 0,
+    });
+}
+export function turnScores(evaluator, options = {}) {
+    const key = options.key ?? 'turn_score';
+    const threshold = options.threshold ?? 0.5;
+    return async (context) => {
+        const thread = threadOf(context);
+        const scores = [];
+        for (const [index, turn] of (thread?.turns ?? []).entries()) {
+            if (turn.role !== 'assistant')
+                continue;
+            const history = thread.turns.slice(0, index);
+            const question = [...history].reverse().find((item) => item.role === 'user')?.content ?? '';
+            const example = {
+                ...context.example,
+                id: `${context.example.id}#${scores.length + 1}`,
+                inputs: question,
+                metadata: { ...context.example.metadata, history, goal: context.example.inputs.goal },
+            };
+            scores.push(numeric(await evaluator({ ...context, example, output: turn.content })));
+        }
+        const mean = scores.length ? scores.reduce((sum, score) => sum + score, 0) / scores.length : 0;
+        const wrong = scores.findIndex((score) => score < threshold);
+        return {
+            key,
+            score: mean,
+            metadata: { turns: scores, ...(wrong === -1 ? {} : { wentWrongAt: wrong + 1 }) },
+            ...(wrong === -1 ? {} : { comment: `turn ${wrong + 1} scored ${scores[wrong].toFixed(2)}` }),
+        };
+    };
+}
+function numeric(result) {
+    if (typeof result === 'number')
+        return result;
+    if (typeof result === 'boolean')
+        return result ? 1 : 0;
+    const first = Array.isArray(result) ? result[0] : result;
+    return first?.score ?? 0;
+}

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?.())]);
         },
     };
 }