@hunterzhu/pulse-adapters 0.1.10 → 0.2.0

package/dist/mcp/stdio.js

@@ -0,0 +1,395 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
+import { matchesJsonSchema } from '@hunterzhu/pulse-tool-sdk';
+const DEFAULT_PROTOCOL_VERSION = '2025-11-25';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_LINE_BYTES = 4 * 1024 * 1024;
+function asRecord(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`MCP_PROTOCOL_ERROR:${label} must be an object`);
+    return value;
+}
+function asError(error) { return error instanceof Error ? error : new Error(String(error)); }
+function defaultMcpEnvironment(source) {
+    const safeKeys = new Set(['PATH', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT']);
+    return Object.fromEntries(Object.entries(source).filter(([key, value]) => safeKeys.has(key.toUpperCase()) && value !== undefined && !/(API_KEY|TOKEN|SECRET|PASSWORD|PRIVATE_KEY|AUTHORIZATION|BEARER|CREDENTIAL|COOKIE)/i.test(key) && key !== 'NODE_OPTIONS'));
+}
+function toJson(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new Error('MCP_TOOL_RESULT_NOT_JSON');
+        seen.add(value);
+        try {
+            return value.map((item) => toJson(item, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (typeof value === 'object') {
+        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+            throw new Error('MCP_TOOL_RESULT_NOT_JSON');
+        if (seen.has(value))
+            throw new Error('MCP_TOOL_RESULT_NOT_JSON');
+        seen.add(value);
+        try {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJson(item, seen)]));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    throw new Error('MCP_TOOL_RESULT_NOT_JSON');
+}
+/**
+ * Minimal MCP stdio client for the initialize lifecycle and tools capability.
+ * The subprocess uses newline-delimited JSON-RPC on stdout; stderr is never parsed as protocol.
+ */
+export class McpStdioClient {
+    options;
+    child;
+    pending = new Map();
+    requestIds = new WeakMap();
+    remoteTools = new Map();
+    nextId = 1;
+    buffer = '';
+    closed = false;
+    started = false;
+    decoder = new StringDecoder('utf8');
+    constructor(options) {
+        this.options = options;
+        if (!options.command.trim())
+            throw new Error('MCP_COMMAND_REQUIRED');
+        if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0))
+            throw new Error('MCP_TIMEOUT_MUST_BE_POSITIVE');
+        if (options.maxLineBytes !== undefined && (!Number.isInteger(options.maxLineBytes) || options.maxLineBytes <= 0))
+            throw new Error('MCP_MAX_LINE_BYTES_MUST_BE_POSITIVE');
+        if (options.maxToolPages !== undefined && (!Number.isInteger(options.maxToolPages) || options.maxToolPages < 1 || options.maxToolPages > 256))
+            throw new Error('MCP_MAX_TOOL_PAGES_MUST_BE_BETWEEN_1_AND_256');
+    }
+    /** Starts the child, negotiates the protocol, then discovers the remote tools. */
+    async connect() {
+        if (this.started)
+            throw new Error('MCP_CLIENT_ALREADY_STARTED');
+        this.started = true;
+        this.child = spawn(this.options.command, this.options.args ?? [], {
+            cwd: this.options.cwd,
+            // MCP servers are installed and enabled explicitly, but should not
+            // silently inherit provider credentials from the Pulse process.
+            env: { ...defaultMcpEnvironment(process.env), ...this.options.env },
+            shell: false,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child.stdout.on('data', (chunk) => this.consume(chunk));
+        // Drain stderr so a verbose server cannot block on a full pipe; keep diagnostics out of protocol handling.
+        this.child.stderr.on('data', () => undefined);
+        this.child.stdout.on('end', () => {
+            const tail = this.decoder.end();
+            if (tail)
+                this.buffer += tail;
+            if (this.buffer.trim())
+                this.fail(new Error('MCP_PROTOCOL_ERROR:unterminated stdout frame'));
+        });
+        this.child.on('error', (error) => this.fail(error));
+        this.child.on('exit', (code, signal) => this.fail(new Error(`MCP_SERVER_EXITED:${code ?? signal ?? 'unknown'}`)));
+        try {
+            const initializeResult = asRecord(await this.request('initialize', {
+                protocolVersion: this.options.protocolVersion ?? DEFAULT_PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: this.options.clientInfo ?? { name: 'pulse', version: '0.1.0' },
+            }), 'initialize result');
+            if (typeof initializeResult.protocolVersion !== 'string')
+                throw new Error('MCP_PROTOCOL_ERROR:initialize response has no protocolVersion');
+            this.notify('notifications/initialized');
+            await this.refreshTools();
+            return this.toToolDefinitions();
+        }
+        catch (error) {
+            await this.close();
+            throw error;
+        }
+    }
+    /** Refreshes and returns the server's complete paginated tools/list result. */
+    async refreshTools() {
+        this.ensureConnected();
+        const found = new Map();
+        const cursors = new Set();
+        let cursor;
+        let pageCount = 0;
+        const maxPages = this.options.maxToolPages ?? 32;
+        do {
+            if (++pageCount > maxPages)
+                throw new Error(`MCP_PROTOCOL_ERROR:tools/list exceeded ${maxPages} pages`);
+            const result = asRecord(await this.request('tools/list', cursor === undefined ? {} : { cursor }), 'tools/list result');
+            if (!Array.isArray(result.tools))
+                throw new Error('MCP_PROTOCOL_ERROR:tools/list result has no tools array');
+            for (const rawTool of result.tools) {
+                const tool = asRecord(rawTool, 'tool');
+                if (typeof tool.name !== 'string' || !tool.name)
+                    throw new Error('MCP_PROTOCOL_ERROR:tool has no name');
+                if (found.has(tool.name))
+                    throw new Error(`MCP_PROTOCOL_ERROR:duplicate tool ${tool.name}`);
+                const inputSchema = tool.inputSchema === undefined ? { type: 'object' } : asRecord(tool.inputSchema, `tool ${tool.name} inputSchema`);
+                found.set(tool.name, { ...tool, name: tool.name, ...(typeof tool.description === 'string' ? { description: tool.description } : {}), inputSchema });
+            }
+            const nextCursor = typeof result.nextCursor === 'string' && result.nextCursor.length > 0 ? result.nextCursor : undefined;
+            if (nextCursor !== undefined && (nextCursor === cursor || cursors.has(nextCursor)))
+                throw new Error('MCP_PROTOCOL_ERROR:tools/list cursor repeated');
+            if (cursor !== undefined)
+                cursors.add(cursor);
+            cursor = nextCursor;
+        } while (cursor !== undefined);
+        this.remoteTools.clear();
+        for (const [name, tool] of found)
+            this.remoteTools.set(name, tool);
+        return [...this.remoteTools.values()];
+    }
+    /** Calls one discovered remote tool and returns the JSON-compatible MCP result envelope. */
+    async callTool(name, arguments_, options = {}) {
+        this.ensureConnected();
+        if (!this.remoteTools.has(name))
+            throw new Error(`MCP_UNKNOWN_TOOL:${name}`);
+        if (options.signal?.aborted)
+            throw options.signal.reason instanceof Error ? options.signal.reason : new Error('MCP_TOOL_CALL_ABORTED');
+        const request = this.request('tools/call', { name, arguments: arguments_ }, options.timeoutMs);
+        let abortHandler;
+        const aborted = options.signal && new Promise((_, reject) => {
+            abortHandler = () => {
+                this.cancelRequest(request, 'MCP_TOOL_CALL_ABORTED');
+                reject(options.signal?.reason instanceof Error ? options.signal.reason : new Error('MCP_TOOL_CALL_ABORTED'));
+            };
+            options.signal?.addEventListener('abort', abortHandler, { once: true });
+            if (options.signal?.aborted)
+                abortHandler();
+        });
+        try {
+            const result = await (aborted ? Promise.race([request, aborted]) : request);
+            const record = asRecord(result, 'tools/call result');
+            if (record.isError === true)
+                throw new Error(`MCP_TOOL_ERROR:${JSON.stringify(record.content ?? record.structuredContent ?? record)}`);
+            return toJson(record);
+        }
+        finally {
+            if (abortHandler)
+                options.signal?.removeEventListener('abort', abortHandler);
+        }
+    }
+    /** Closes stdin, waits briefly for exit, then terminates a server that stays alive. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.rejectPending(new Error('MCP_CLIENT_CLOSED'));
+        const child = this.child;
+        if (!child || child.exitCode !== null || child.signalCode !== null)
+            return;
+        child.stdin.end();
+        const timeoutMs = this.options.shutdownTimeoutMs ?? 500;
+        await Promise.race([
+            new Promise((resolve) => child.once('exit', () => resolve())),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGTERM');
+            await Promise.race([
+                new Promise((resolve) => child.once('exit', () => resolve())),
+                new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+            ]);
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGKILL');
+        }
+    }
+    /** Exposes the discovered tools as Pulse ToolDefinitions, preserving each remote input schema. */
+    toToolDefinitions() {
+        const namespace = this.options.namespace ?? 'mcp';
+        return [...this.remoteTools.values()].map((tool) => {
+            const pulseName = `${namespace}.${tool.name}`;
+            return {
+                manifest: {
+                    name: pulseName,
+                    version: 'mcp-remote',
+                    description: tool.description ?? `MCP tool ${tool.name}`,
+                    inputSchema: tool.inputSchema,
+                    outputSchema: {},
+                    concurrencyClass: 'tool',
+                    locks: [],
+                    supportsAbortSignal: true,
+                    sideEffectPolicy: 'external',
+                    retrySafety: 'unsafe',
+                    defaultTimeoutMs: this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                    tags: ['mcp'],
+                },
+                validateInput: (input) => {
+                    if (!matchesJsonSchema(input, tool.inputSchema))
+                        throw new Error(`MCP_INVALID_TOOL_INPUT:${tool.name}`);
+                    return input;
+                },
+                execute: async (input, context) => this.callTool(tool.name, input, { signal: context.signal }),
+            };
+        });
+    }
+    consume(chunk) {
+        if (this.closed)
+            return;
+        this.buffer += this.decoder.write(chunk);
+        const maxBytes = this.options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+        let newline;
+        while ((newline = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, newline).replace(/\r$/, '');
+            this.buffer = this.buffer.slice(newline + 1);
+            if (Buffer.byteLength(line, 'utf8') > maxBytes) {
+                this.fail(new Error('MCP_FRAME_TOO_LARGE'));
+                return;
+            }
+            if (!line.trim())
+                continue;
+            this.receive(line);
+        }
+        if (Buffer.byteLength(this.buffer, 'utf8') > maxBytes)
+            this.fail(new Error('MCP_FRAME_TOO_LARGE'));
+    }
+    receive(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            this.fail(new Error('MCP_PROTOCOL_ERROR:invalid JSON frame'));
+            return;
+        }
+        let message;
+        try {
+            message = asRecord(parsed, 'message');
+        }
+        catch (error) {
+            this.fail(asError(error));
+            return;
+        }
+        if (message.jsonrpc !== '2.0') {
+            this.fail(new Error('MCP_PROTOCOL_ERROR:jsonrpc must be 2.0'));
+            return;
+        }
+        if (message.method === 'ping' && message.id !== undefined) {
+            this.write({ jsonrpc: '2.0', id: message.id, result: {} });
+            return;
+        }
+        if (message.id === undefined)
+            return; // Server notifications are advisory for this tools-only adapter.
+        if (typeof message.id !== 'number') {
+            this.fail(new Error('MCP_PROTOCOL_ERROR:response id must be numeric'));
+            return;
+        }
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pending.delete(message.id);
+        if (message.error !== undefined) {
+            const error = asRecord(message.error, 'JSON-RPC error');
+            pending.reject(new Error(`MCP_JSONRPC_ERROR:${String(error.code)}:${String(error.message)}`));
+        }
+        else if (!('result' in message))
+            pending.reject(new Error('MCP_PROTOCOL_ERROR:response has no result'));
+        else
+            pending.resolve(message.result);
+    }
+    request(method, params, timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS) {
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            return Promise.reject(new Error('MCP_TIMEOUT_MUST_BE_POSITIVE'));
+        if (this.closed || !this.child || !this.child.stdin.writable)
+            return Promise.reject(new Error('MCP_CLIENT_NOT_CONNECTED'));
+        const id = this.nextId++;
+        const message = { jsonrpc: '2.0', id, method, params };
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                this.notify('notifications/cancelled', { requestId: id, reason: `Timed out after ${timeoutMs}ms` });
+                reject(new Error(`MCP_REQUEST_TIMEOUT:${method}:${timeoutMs}`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            this.write(message, (error) => {
+                if (!error)
+                    return;
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(error);
+            });
+        });
+        this.requestIds.set(promise, id);
+        return promise;
+    }
+    cancelRequest(request, code) {
+        const id = this.requestIds.get(request);
+        const item = id === undefined ? undefined : this.pending.get(id);
+        if (id === undefined || !item)
+            return;
+        clearTimeout(item.timer);
+        this.pending.delete(id);
+        this.notify('notifications/cancelled', { requestId: id, reason: code });
+        item.reject(new Error(code));
+        void request.catch(() => undefined);
+    }
+    notify(method, params) {
+        if (!this.child || !this.child.stdin.writable || this.closed)
+            return;
+        this.write({ jsonrpc: '2.0', method, ...(params === undefined ? {} : { params }) });
+    }
+    write(message, callback) {
+        const child = this.child;
+        if (!child || !child.stdin.writable) {
+            callback?.(new Error('MCP_CLIENT_NOT_CONNECTED'));
+            return;
+        }
+        let encoded;
+        try {
+            encoded = `${JSON.stringify(message)}\n`;
+        }
+        catch (error) {
+            callback?.(asError(error));
+            return;
+        }
+        child.stdin.write(encoded, 'utf8', (error) => callback?.(error ?? undefined));
+    }
+    ensureConnected() {
+        if (!this.started || this.closed || !this.child || this.child.exitCode !== null || this.child.signalCode !== null)
+            throw new Error('MCP_CLIENT_NOT_CONNECTED');
+    }
+    rejectPending(error) {
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            this.pending.delete(id);
+            pending.reject(error);
+        }
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        this.rejectPending(error);
+        this.closed = true;
+        const child = this.child;
+        if (child && child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGTERM');
+            const forceTimer = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill('SIGKILL');
+            }, this.options.shutdownTimeoutMs ?? 500);
+            forceTimer.unref();
+        }
+    }
+}
+/** Starts one MCP server and returns a client plus Pulse-compatible tool definitions. */
+export async function createMcpStdioAdapter(options) {
+    const client = new McpStdioClient(options);
+    const tools = await client.connect();
+    return { client, tools };
+}
+/** Creates an opaque namespace suitable for using the server name in Pulse tool names. */
+export function mcpToolNamespace(serverName) {
+    const normalized = serverName.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+    return `mcp.${normalized || randomUUID().slice(0, 8)}`;
+}

package/dist/providers/anthropic.js

@@ -54,7 +54,10 @@ export class AnthropicAdapter {
                 throw await providerHttpErrorFromResponse(response);
             if (!streaming || !response.headers.get('content-type')?.includes('text/event-stream'))
                 return normalizeAnthropicResponse(await parseProviderJson(response));
-            const events = await consumeProviderSse(response);
+            const events = await consumeProviderSse(response, (event) => {
+                if (event.event === 'content_block_delta' && event.data?.delta?.type === 'text_delta' && typeof event.data.delta.text === 'string')
+                    params.onObservation?.(event.data.delta.text);
+            });
             const blocks = [];
             let stopReason;
             let usage = {};
@@ -72,7 +75,6 @@ export class AnthropicAdapter {
                     if (data.delta.type === 'text_delta' && typeof data.delta.text === 'string') {
                         block.type = 'text';
                         block.text = `${typeof block.text === 'string' ? block.text : ''}${data.delta.text}`;
-                        params.onObservation?.(data.delta.text);
                     }
                     if (data.delta.type === 'input_json_delta' && typeof data.delta.partial_json === 'string')
                         block.inputJson = `${typeof block.inputJson === 'string' ? block.inputJson : ''}${data.delta.partial_json}`;

package/dist/providers/normalize.d.ts

@@ -22,6 +22,6 @@ export declare function providerResponseError(detail: string): Error & {
 };
 export declare function parseProviderJson(response: Response): Promise<unknown>;
 /** Read provider SSE frames without treating incomplete tool arguments as executable input. */
-export declare function consumeProviderSse(response: Response): Promise<ProviderSseEvent[]>;
+export declare function consumeProviderSse(response: Response, onEvent?: (event: ProviderSseEvent) => void): Promise<ProviderSseEvent[]>;
 export declare function normalizeOpenAIResponse(response: any, toolNameAliases?: ReadonlyMap<string, string>): LLMResult;
 export declare function normalizeAnthropicResponse(response: any): LLMResult;

package/dist/providers/normalize.js

@@ -54,7 +54,7 @@ export async function parseProviderJson(response) {
     }
 }
 /** Read provider SSE frames without treating incomplete tool arguments as executable input. */
-export async function consumeProviderSse(response) {
+export async function consumeProviderSse(response, onEvent) {
     if (!response.body)
         throw providerResponseError('PROVIDER_STREAM_BODY_MISSING');
     const reader = response.body.getReader();
@@ -76,7 +76,9 @@ export async function consumeProviderSse(response) {
         catch {
             throw providerResponseError('PROVIDER_STREAM_INVALID_JSON');
         } })();
-        events.push({ ...(eventName === undefined ? {} : { event: eventName }), data });
+        const event = { ...(eventName === undefined ? {} : { event: eventName }), data };
+        events.push(event);
+        onEvent?.(event);
         eventName = undefined;
     };
     const consumeLines = (text) => {
@@ -114,8 +116,8 @@ export function normalizeOpenAIResponse(response, toolNameAliases) {
         throw providerResponseError('OpenAI response must contain at least one choice');
     const choice = providerRecord(root.choices[0], 'OpenAI choice');
     const message = providerRecord(choice.message, 'OpenAI message');
-    const toolCalls = message.tool_calls === undefined ? [] : normalizeOpenAIToolCalls(message.tool_calls, toolNameAliases);
-    const refusal = message.refusal === undefined ? undefined : requiredProviderString(message.refusal, 'OpenAI refusal');
+    const toolCalls = choice.finish_reason === 'length' || message.tool_calls === undefined ? [] : normalizeOpenAIToolCalls(message.tool_calls, toolNameAliases);
+    const refusal = message.refusal == null ? undefined : requiredProviderString(message.refusal, 'OpenAI refusal');
     const text = providerText(message.content, 'OpenAI message content');
     const finishReason = normalizeOpenAIFinishReason(choice.finish_reason, refusal, toolCalls.length > 0);
     const rawUsage = root.usage === undefined ? undefined : providerRecord(root.usage, 'OpenAI usage');
@@ -130,7 +132,7 @@ export function normalizeAnthropicResponse(response) {
     const blocks = root.content;
     const text = blocks.filter((block) => providerRecord(block, 'Anthropic content block').type === 'text').map((block) => requiredProviderString(providerRecord(block, 'Anthropic text block').text, 'Anthropic text block text')).join('');
     const toolBlocks = blocks.filter((block) => providerRecord(block, 'Anthropic content block').type === 'tool_use');
-    const toolCalls = toolBlocks.map((block, index) => {
+    const toolCalls = (root.stop_reason === 'max_tokens' ? [] : toolBlocks).map((block, index) => {
         const value = providerRecord(block, 'Anthropic tool block');
         return { toolCallId: `pulse-tool-${index + 1}`, name: requiredProviderString(value.name, 'Anthropic tool name'), input: parseJson(value.input) };
     });

package/dist/providers/openai-compat.js

@@ -22,14 +22,27 @@ export class OpenAICompatibleAdapter {
         const streaming = params.onObservation !== undefined;
         const { definitions: tools, aliases: toolNameAliases } = toolDefinitions(params.request);
         const includeReasoning = Boolean(this.config.reasoningEffort) && !this.reasoningUnsupported;
-        const body = { ...(params.model ?? this.config.defaultModel ? { model: params.model ?? this.config.defaultModel } : {}), ...((params.maxOutputTokens ?? this.config.maxOutputTokens) === undefined ? {} : { max_tokens: params.maxOutputTokens ?? this.config.maxOutputTokens }), ...(includeReasoning ? { reasoning_effort: this.config.reasoningEffort } : {}), messages: toMessages(params.request), ...(tools.length ? { tools, ...(this.config.toolChoice === undefined ? {} : { tool_choice: this.config.toolChoice }) } : {}), ...(params.outputSchema === undefined ? {} : { response_format: { type: 'json_schema', json_schema: { name: 'pulse_output', strict: true, schema: params.outputSchema } } }), ...(streaming ? { stream: true, stream_options: { include_usage: true } } : {}) };
+        const messages = toMessages(params.request);
+        const deepSeekJsonMode = params.outputSchema !== undefined && this.config.provider === 'deepseek';
+        if (deepSeekJsonMode)
+            messages.unshift({ role: 'system', content: `Return only a JSON object matching this schema. The application will validate the result:\n${JSON.stringify(params.outputSchema)}` });
+        const responseFormat = params.outputSchema === undefined ? undefined : deepSeekJsonMode
+            ? { type: 'json_object' }
+            : { type: 'json_schema', json_schema: { name: 'pulse_output', strict: true, schema: params.outputSchema } };
+        const body = { ...(params.model ?? this.config.defaultModel ? { model: params.model ?? this.config.defaultModel } : {}), ...((params.maxOutputTokens ?? this.config.maxOutputTokens) === undefined ? {} : { max_tokens: params.maxOutputTokens ?? this.config.maxOutputTokens }), ...(includeReasoning ? { reasoning_effort: this.config.reasoningEffort } : {}), messages, ...(tools.length ? { tools, ...(this.config.toolChoice === undefined ? {} : { tool_choice: this.config.toolChoice }) } : {}), ...(responseFormat === undefined ? {} : { response_format: responseFormat }), ...(streaming ? { stream: true, stream_options: { include_usage: true } } : {}) };
         try {
             const response = await fetch(`${this.baseURL.replace(/\/$/, '')}/chat/completions`, { method: 'POST', signal: params.signal, headers: { 'content-type': 'application/json', ...(this.config.apiKey ? { authorization: `Bearer ${this.config.apiKey}` } : {}), ...(this.config.extraHeaders ?? {}) }, body: JSON.stringify(body) });
             if (!response.ok)
                 throw await providerHttpErrorFromResponse(response);
             if (!streaming || !response.headers.get('content-type')?.includes('text/event-stream'))
                 return normalizeOpenAIResponse(await parseProviderJson(response), toolNameAliases);
-            const events = await consumeProviderSse(response);
+            const events = await consumeProviderSse(response, (event) => {
+                const delta = event.data?.choices?.[0]?.delta;
+                if (typeof delta?.content === 'string')
+                    params.onObservation?.(delta.content);
+                if (typeof delta?.refusal === 'string')
+                    params.onObservation?.(delta.refusal);
+            });
             const content = [];
             const refusals = [];
             const toolCalls = new Map();
@@ -42,11 +55,9 @@ export class OpenAICompatibleAdapter {
                 const delta = choice?.delta;
                 if (typeof delta?.content === 'string') {
                     content.push(delta.content);
-                    params.onObservation?.(delta.content);
                 }
                 if (typeof delta?.refusal === 'string') {
                     refusals.push(delta.refusal);
-                    params.onObservation?.(delta.refusal);
                 }
                 if (typeof choice?.finish_reason === 'string')
                     finishReason = choice.finish_reason;

package/dist/providers/runtime-executor.js

@@ -165,6 +165,8 @@ export function createModelEffectExecutor(config) {
                 const output = assignRuntimeToolCallIds(validateAdapterResult(await provider.executeAttempt({ request: projection, signal, model: attempt.candidate.id, ...(input.outputSchema === undefined ? {} : { outputSchema: input.outputSchema }), ...(typeof routeRequirements.maxOutputTokens === 'number' ? { maxOutputTokens: routeRequirements.maxOutputTokens } : {}), onObservation })), effect.id);
                 const measuredUsage = output.usage === undefined ? { latencyMs: Math.max(0, Date.now() - startedAt) } : { ...output.usage, latencyMs: output.usage.latencyMs ?? Math.max(0, Date.now() - startedAt), ...(output.usage.uncachedInputTokens === undefined && output.usage.inputTokens !== undefined && output.usage.cachedInputTokens !== undefined ? { uncachedInputTokens: Math.max(0, output.usage.inputTokens - output.usage.cachedInputTokens) } : {}) };
                 usage.set(attempt.attemptId, measuredUsage);
+                if (output.finishReason === 'length' && input.outputSchema !== undefined)
+                    throw Object.assign(new OutputValidationError('adapter', 'OUTPUT_TRUNCATED', 'Model output reached its token limit; increase maxOutputTokens before retrying.'), { retryable: false });
                 if (output.finishReason === 'refusal') {
                     recordFeedback('refused', 0);
                     throw new OutputValidationError('adapter', 'MODEL_REFUSAL', output.refusal ?? 'Provider refused the request.');
@@ -201,7 +203,7 @@ export function createModelEffectExecutor(config) {
             const waited = providerAttempt === undefined ? undefined : slotWaitMs.get(providerAttempt.attemptId);
             if (waited !== undefined)
                 slotWaitMs.set(effect.attemptId, waited);
-            return { ...value, attempts: value.attempts.map(() => ({ effectId: effect.id, attemptId: effect.attemptId, attemptNo, candidate })) };
+            return { ...value, attempts: value.attempts.map((attempt) => ({ ...attempt, effectId: effect.id })) };
         }).catch((cause) => {
             if (failedForSchema && lastSchemaViolation !== undefined)
                 return { result: { text: '', toolCalls: [], finishReason: 'error' }, candidate, attempts: [{ effectId: effect.id, attemptId: effect.attemptId, attemptNo, candidate }], schemaRejected: lastSchemaViolation };

package/dist/tools/filesystem.d.ts

@@ -15,6 +15,10 @@ export declare class FilesystemTool {
     private writable;
     read(path: string, signal?: AbortSignal): Promise<string>;
     readLimited(path: string, maxBytes: number, signal?: AbortSignal): Promise<FilesystemReadResult>;
+    readRange(path: string, maxBytes: number, offset?: number, signal?: AbortSignal): Promise<FilesystemReadResult & {
+        offset: number;
+        nextOffset: number | null;
+    }>;
     list(path?: string, signal?: AbortSignal): Promise<string[]>;
     write(path: string, content: string, signal?: AbortSignal): Promise<void>;
     move(source: string, destination: string, expectedHash?: string, signal?: AbortSignal): Promise<{

package/dist/tools/filesystem.js

@@ -56,13 +56,31 @@ export class FilesystemTool {
     async read(path, signal) { if (signal?.aborted)
         throw filesystemError('ABORTED'); return readFile(await this.existing(path), 'utf8'); }
     async readLimited(path, maxBytes, signal) {
+        const { content, truncated } = await this.readRange(path, maxBytes, 0, signal);
+        return { content, truncated };
+    }
+    async readRange(path, maxBytes, offset = 0, signal) {
         if (signal?.aborted)
             throw filesystemError('ABORTED');
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 1_000_000 || !Number.isSafeInteger(offset) || offset < 0)
+            throw filesystemError('INVALID_READ_RANGE');
         const handle = await open(await this.existing(path), 'r');
         try {
             const buffer = Buffer.alloc(maxBytes + 1);
-            const { bytesRead } = await handle.read(buffer, 0, maxBytes + 1, 0);
-            return { content: buffer.subarray(0, Math.min(bytesRead, maxBytes)).toString('utf8'), truncated: bytesRead > maxBytes };
+            const { bytesRead } = await handle.read(buffer, 0, maxBytes + 1, offset);
+            if (bytesRead && (buffer[0] & 0xc0) === 0x80)
+                throw filesystemError('INVALID_UTF8_OFFSET');
+            let end = Math.min(bytesRead, maxBytes);
+            if (bytesRead > maxBytes) {
+                // The byte after the window is a continuation: drop the partial codepoint.
+                while (end > 0 && (buffer[end] & 0xc0) === 0x80)
+                    end--;
+            }
+            if (end === 0 && bytesRead > 0)
+                throw filesystemError('READ_WINDOW_TOO_SMALL');
+            const content = buffer.subarray(0, end).toString('utf8');
+            const truncated = bytesRead > end;
+            return { content, truncated, offset, nextOffset: truncated ? offset + end : null };
         }
         finally {
             await handle.close();

package/dist/tools/shell.d.ts

@@ -6,6 +6,10 @@ export interface ShellResult {
     timedOut: boolean;
     aborted: boolean;
 }
+export declare function quoteWindowsArgument(value: string): string;
+/** Build the command text expected by srt without interpreting model argv as shell syntax. */
+export declare function encodeSandboxCommand(command: string, args: string[], platform?: NodeJS.Platform): string;
+export declare function decodeUtf8WithinByteLimit(value: Buffer, maxBytes: number): string;
 export declare function runShell(command: string, args?: string[], options?: {
     cwd?: string;
     signal?: AbortSignal;