@aragon-agent/core 0.2.17 → 0.2.20

package/dist/llm/provider.d.ts

@@ -56,7 +56,8 @@ export interface LLMProvider {
      * Stream a completion from the model.
      *
      * The returned iterator yields {@link StreamEvent} items and MUST terminate
-     * with either a `done` or an `error` event.
+     * with either a `done` or an `error` event, unless the caller cancels. Caller
+     * cancellation ends silently without executable tool results or a terminal.
      */
     stream(request: LLMRequest): AsyncIterableIterator<StreamEvent>;
     /**

package/dist/llm/provider.js

@@ -13,6 +13,7 @@
  * Keep both usages inside functions.
  */
 import { parseRetryAfterMs } from './retry.js';
+import { SseFrameLimitError } from './sse-parser.js';
 export class LLMError extends Error {
     provider;
     errorType;
@@ -106,6 +107,9 @@ export function classifyHttpError(statusCode, body, provider, headers) {
 export function wrapFetchError(err, provider) {
     if (err instanceof LLMError)
         return err;
+    if (err instanceof SseFrameLimitError) {
+        return new LLMError('SSE_FRAME_TOO_LARGE', provider, 'unknown', false);
+    }
     const message = err instanceof Error ? err.message : String(err);
     if (err instanceof Error && err.name === 'AbortError') {
         return new LLMError(`${provider} request aborted: ${message}`, provider, 'timeout', true);

package/dist/llm/providers/anthropic.js

@@ -33,6 +33,8 @@ export class AnthropicProvider {
     // stream
     // -----------------------------------------------------------------------
     async *stream(request) {
+        if (request.signal?.aborted)
+            return;
         const baseUrl = (request.baseUrl || this.defaultBaseUrl).replace(/\/+$/, '');
         const url = `${baseUrl}/v1/messages`;
         const body = buildRequestBody(request);
@@ -59,9 +61,13 @@ export class AnthropicProvider {
             errorBody = attempt.bodyText;
         }
         catch (err) {
+            if (request.signal?.aborted)
+                return;
             yield { type: 'error', error: wrapFetchError(err, this.id) };
             return;
         }
+        if (request.signal?.aborted)
+            return;
         if (!response.ok) {
             // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
             // `response.headers` carries `Retry-After` / `anthropic-ratelimit-*-reset`
@@ -86,6 +92,8 @@ export class AnthropicProvider {
         let currentBlockIndex = -1;
         try {
             for await (const sse of parseSSEStream(response.body, request.signal)) {
+                if (request.signal?.aborted)
+                    return;
                 // Anthropic uses the `event` field to distinguish event types
                 const eventType = sse.event;
                 if (!eventType || !sse.data)
@@ -220,6 +228,8 @@ export class AnthropicProvider {
                         break;
                     }
                     case 'message_stop': {
+                        if (request.signal?.aborted)
+                            return;
                         const message = {
                             role: 'assistant',
                             content: contentBlocks,
@@ -249,44 +259,17 @@ export class AnthropicProvider {
                         break;
                 }
             }
-            // ---- The terminal-sentinel contract (llm-api-retry-backoff §4.5a) ----
-            //
-            // Reaching here means the SSE ended WITHOUT `message_stop`: that case
-            // `return`s from inside the loop above, and so does the in-stream `error`
-            // case. No `sawTerminal` flag is needed for this adapter precisely because
-            // of those two returns — the absence is the signal. (`openai.ts` and
-            // `google.ts` DO need a flag, because their terminal frames only `break`.)
-            //
-            // TWO VERY DIFFERENT SITUATIONS SHARE THIS LINE, and conflating them is how
-            // every user abort would become a fake network error (constraint 1 / R-17):
-            //
-            //  - the request was ABORTED. `parseSSEStream` `break`s on
-            //    `signal.aborted` rather than throwing, so Esc lands here. An abort is
-            //    not a provider failure, and `agent-loop` discards the `done` anyway.
-            //  - the stream was TRUNCATED — a proxy idle cut, a load-balancer timeout,
-            //    an HTTP/2 GOAWAY, `message_stop` never arriving. This USED to yield
-            //    `done` with partial content, which is indistinguishable from success
-            //    at every layer above and is the single failure the retry machinery
-            //    exists to recover. It is now a retryable `network_error`.
-            //
-            // An empty-but-complete turn is unaffected: Anthropic always sends
-            // `message_stop`, so a model that emits zero content still returns above.
-            if (request.signal?.aborted) {
-                const message = {
-                    role: 'assistant',
-                    content: contentBlocks,
-                    usage,
-                    stopReason,
-                };
-                yield { type: 'done', message, usage };
+            // A caller abort is silent; only an incomplete transport EOF is retried.
+            if (request.signal?.aborted)
                 return;
-            }
             yield {
                 type: 'error',
                 error: new LLMError(`${this.id} stream truncated before message_stop`, this.id, 'network_error', true),
             };
         }
         catch (err) {
+            if (request.signal?.aborted)
+                return;
             yield { type: 'error', error: wrapFetchError(err, this.id) };
         }
     }

package/dist/llm/providers/google.js

@@ -31,6 +31,8 @@ export class GoogleProvider {
     // stream
     // -----------------------------------------------------------------------
     async *stream(request) {
+        if (request.signal?.aborted)
+            return;
         const baseUrl = (request.baseUrl || this.defaultBaseUrl).replace(/\/+$/, '');
         const url = `${baseUrl}/v1beta/models/${request.model}:streamGenerateContent?alt=sse&key=${encodeURIComponent(request.apiKey)}`;
         const body = buildRequestBody(request);
@@ -53,9 +55,13 @@ export class GoogleProvider {
             errorBody = attempt.bodyText;
         }
         catch (err) {
+            if (request.signal?.aborted)
+                return;
             yield { type: 'error', error: wrapFetchError(err, this.id) };
             return;
         }
+        if (request.signal?.aborted)
+            return;
         if (!response.ok) {
             // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
             // `response.headers` carries `Retry-After` out on `LLMError.retryAfterMs`
@@ -86,6 +92,8 @@ export class GoogleProvider {
         let sawTerminal = false;
         try {
             for await (const sse of parseSSEStream(response.body, request.signal)) {
+                if (request.signal?.aborted)
+                    return;
                 const raw = sse.data.trim();
                 if (!raw)
                     continue;
@@ -120,19 +128,29 @@ export class GoogleProvider {
                 if (!parts)
                     continue;
                 for (const part of parts) {
+                    if (request.signal?.aborted)
+                        return;
                     // Text part
                     if (typeof part.text === 'string') {
                         textAccumulator += part.text;
                         yield { type: 'text_delta', delta: part.text };
                     }
+                    if (request.signal?.aborted)
+                        return;
                     // Function call — arrives complete in a single chunk
                     const functionCall = part.functionCall;
                     if (functionCall) {
                         const toolName = functionCall.name || '';
                         const args = functionCall.args || {};
                         const toolCallId = `call_${randomUUID().slice(0, 8)}`;
+                        if (request.signal?.aborted)
+                            return;
                         yield { type: 'tool_call_start', toolCallId, toolName };
+                        if (request.signal?.aborted)
+                            return;
                         yield { type: 'tool_call_end', toolCallId, toolName, args };
+                        if (request.signal?.aborted)
+                            return;
                         contentBlocks.push({
                             type: 'tool_call',
                             toolCallId,
@@ -142,13 +160,10 @@ export class GoogleProvider {
                     }
                 }
             }
-            // ---- The terminal-sentinel contract (§4.5a) -------------------------
-            //
-            // An abort is NOT a truncation: `parseSSEStream` `break`s on
-            // `signal.aborted` and lands here, and reporting that as a retryable
-            // `network_error` would re-create the trap `isRetryableError` check 1
-            // closes (constraint 1 / R-17). Signal first; that path yields `done`.
-            if (!sawTerminal && !request.signal?.aborted) {
+            // A caller abort is silent; only an incomplete transport EOF is retried.
+            if (request.signal?.aborted)
+                return;
+            if (!sawTerminal) {
                 yield {
                     type: 'error',
                     error: new LLMError(`${this.id} stream truncated before a terminal chunk`, this.id, 'network_error', true),
@@ -159,6 +174,8 @@ export class GoogleProvider {
             if (textAccumulator) {
                 contentBlocks.push({ type: 'text', text: textAccumulator });
             }
+            if (request.signal?.aborted)
+                return;
             const message = {
                 role: 'assistant',
                 content: contentBlocks,
@@ -168,6 +185,8 @@ export class GoogleProvider {
             yield { type: 'done', message, usage };
         }
         catch (err) {
+            if (request.signal?.aborted)
+                return;
             yield { type: 'error', error: wrapFetchError(err, this.id) };
         }
     }

package/dist/llm/providers/openai.d.ts

@@ -12,6 +12,7 @@
  */
 import type { AssistantMessage, ModelInfo, StreamEvent } from '../types.js';
 import type { LLMProvider, LLMRequest } from '../provider.js';
+export declare const OPENAI_TERMINAL_DRAIN_MS = 750;
 /**
  * Which parameter name carries the cap for this model.
  *

package/dist/llm/providers/openai.js

@@ -19,6 +19,7 @@ import { consumeStream } from '../stream-utils.js';
 // Constants
 // ---------------------------------------------------------------------------
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+export const OPENAI_TERMINAL_DRAIN_MS = 750;
 /** Reasoning-family models reject `max_tokens` in favour of `max_completion_tokens`. */
 const REASONING_MODEL_PATTERN = /^(o1|o3|o4|gpt-5)/;
 // Model ID patterns to filter out non-chat models
@@ -68,194 +69,38 @@ export class OpenAIProvider {
     // stream
     // -----------------------------------------------------------------------
     async *stream(request) {
-        const baseUrl = (request.baseUrl || this.defaultBaseUrl).replace(/\/+$/, '');
-        const url = `${baseUrl}/chat/completions`;
-        const body = buildRequestBody(request);
-        let response;
-        let errorBody = '';
-        try {
-            const attempt = await sendWithOutputLimitRecovery({
-                providerId: this.id,
-                modelId: request.model,
-                body,
-                tokenField: openAiTokenField(request.model),
-                send: (payload) => fetch(url, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'Authorization': `Bearer ${request.apiKey}`,
-                    },
-                    body: JSON.stringify(payload),
-                    signal: request.signal,
-                }),
-            });
-            response = attempt.response;
-            errorBody = attempt.bodyText;
-        }
-        catch (err) {
-            yield { type: 'error', error: wrapFetchError(err, this.id) };
-            return;
-        }
-        if (!response.ok) {
-            // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
-            // `response.headers` carries `Retry-After` / `x-ratelimit-reset-after` out
-            // on `LLMError.retryAfterMs` so a 429 waits as long as the server asked.
-            yield {
-                type: 'error',
-                error: classifyHttpError(response.status, errorBody, this.id, response.headers),
-            };
-            return;
-        }
-        if (!response.body) {
-            yield { type: 'error', error: new LLMError('Response body is null', this.id, 'network_error', true) };
+        if (request.signal?.aborted)
             return;
-        }
-        // -- Parse SSE events --
-        const usage = { inputTokens: 0, outputTokens: 0 };
-        const contentBlocks = [];
-        let textAccumulator = '';
-        let stopReason;
-        // Accumulate tool calls by index
-        const toolAccumulators = new Map();
-        /**
-         * Whether this stream reached a terminal frame (§4.5a). Unlike Anthropic's
-         * `message_stop`, neither of OpenAI's terminal signals `return`s, so the
-         * absence of a return cannot stand in for the flag.
-         *
-         * TWO SIGNALS, NOT ONE, and the second is not optional. The `[DONE]`
-         * sentinel is the documented terminator, but it is a convention of OpenAI's
-         * own server rather than a property of the wire format: several
-         * OpenAI-compatible endpoints (the ones `--base-url` exists for) close the
-         * connection after the last chunk without sending it. Keying truncation on
-         * `[DONE]` alone would make every request against such a server a retryable
-         * error, i.e. ten retries and then a failure, for a stream that completed
-         * perfectly. A `finish_reason` on any choice is the model's own statement
-         * that it stopped, and a stream cut mid-answer carries neither.
-         */
-        let sawTerminal = false;
+        const scope = new OpenAIRequestScope(request.signal);
         try {
-            for await (const sse of parseSSEStream(response.body, request.signal)) {
-                const raw = sse.data.trim();
-                // [DONE] sentinel
-                if (raw === '[DONE]') {
-                    sawTerminal = true;
-                    break;
-                }
-                let data;
-                try {
-                    data = JSON.parse(raw);
-                }
-                catch {
-                    continue;
-                }
-                // Extract usage if present (some providers include it in the final chunk)
-                const usageData = data.usage;
-                if (usageData) {
-                    usage.inputTokens = usageData.prompt_tokens ?? usage.inputTokens;
-                    usage.outputTokens = usageData.completion_tokens ?? usage.outputTokens;
-                }
-                const choices = data.choices;
-                if (!choices || choices.length === 0)
-                    continue;
-                const choice = choices[0];
-                const delta = choice.delta;
-                const finishReason = choice.finish_reason;
-                if (delta) {
-                    // Text content
-                    const content = delta.content;
-                    if (content) {
-                        textAccumulator += content;
-                        yield { type: 'text_delta', delta: content };
-                    }
-                    // Tool calls
-                    const toolCalls = delta.tool_calls;
-                    if (toolCalls) {
-                        for (const tc of toolCalls) {
-                            const idx = tc.index ?? 0;
-                            const fn = tc.function;
-                            let acc = toolAccumulators.get(idx);
-                            if (!acc) {
-                                acc = {
-                                    index: idx,
-                                    toolCallId: tc.id || `call_${idx}`,
-                                    toolName: fn?.name || '',
-                                    argsJson: '',
-                                    started: false,
-                                };
-                                toolAccumulators.set(idx, acc);
-                            }
-                            // Update name if present in this chunk
-                            if (fn?.name) {
-                                acc.toolName = fn.name;
-                            }
-                            // Emit tool_call_start on first encounter
-                            if (!acc.started && acc.toolName) {
-                                acc.started = true;
-                                yield { type: 'tool_call_start', toolCallId: acc.toolCallId, toolName: acc.toolName };
-                            }
-                            // Accumulate argument fragments
-                            if (fn?.arguments) {
-                                const argChunk = fn.arguments;
-                                acc.argsJson += argChunk;
-                                if (acc.started) {
-                                    yield { type: 'tool_call_delta', toolCallId: acc.toolCallId, argsDelta: argChunk };
-                                }
-                            }
-                        }
-                    }
-                }
-                // Finish reason handling
-                if (finishReason) {
-                    sawTerminal = true;
-                    stopReason = mapFinishReason(finishReason);
-                }
-            }
-            // ---- The terminal-sentinel contract (§4.5a) -------------------------
-            //
-            // An abort is NOT a truncation: `parseSSEStream` `break`s on
-            // `signal.aborted`, which lands on exactly this path, and turning that into
-            // a retryable `network_error` would re-create the trap `isRetryableError`
-            // check 1 exists to close (constraint 1 / R-17). The signal is therefore
-            // tested FIRST and that path keeps yielding `done`.
-            if (!sawTerminal && !request.signal?.aborted) {
-                yield {
-                    type: 'error',
-                    error: new LLMError(`${this.id} stream truncated before a terminal chunk`, this.id, 'network_error', true),
-                };
+            if (request.signal?.aborted)
                 return;
+            const attempt = await sendOpenAIRequest(request, this.defaultBaseUrl, scope.signal);
+            if (request.signal?.aborted)
+                return;
+            const response = attempt.response;
+            if (!response.ok) {
+                throw classifyHttpError(response.status, attempt.bodyText, this.id, response.headers);
             }
-            // Flush text block
-            if (textAccumulator) {
-                contentBlocks.push({ type: 'text', text: textAccumulator });
+            if (!response.body) {
+                throw new LLMError('Response body is null', this.id, 'network_error', true);
             }
-            // Flush tool calls — parse accumulated args JSON
-            for (const acc of toolAccumulators.values()) {
-                let args = {};
-                try {
-                    args = acc.argsJson ? JSON.parse(acc.argsJson) : {};
-                }
-                catch {
-                    args = { __raw: acc.argsJson };
-                }
-                contentBlocks.push({
-                    type: 'tool_call',
-                    toolCallId: acc.toolCallId,
-                    toolName: acc.toolName,
-                    args,
-                });
-                yield { type: 'tool_call_end', toolCallId: acc.toolCallId, toolName: acc.toolName, args };
+            for await (const event of readOpenAIResponse(response.body, scope)) {
+                if (request.signal?.aborted)
+                    return;
+                yield event;
+                if (request.signal?.aborted)
+                    return;
             }
-            const message = {
-                role: 'assistant',
-                content: contentBlocks,
-                usage,
-                stopReason,
-            };
-            yield { type: 'done', message, usage };
         }
         catch (err) {
+            if (request.signal?.aborted)
+                return;
             yield { type: 'error', error: wrapFetchError(err, this.id) };
         }
+        finally {
+            scope.dispose();
+        }
     }
     // -----------------------------------------------------------------------
     // complete
@@ -303,6 +148,208 @@ export class OpenAIProvider {
         }
     }
 }
+/** Owns the request signal and the absolute, non-renewable terminal deadline. */
+class OpenAIRequestScope {
+    caller;
+    controller = new AbortController();
+    timer;
+    cancelCause = null;
+    onCallerAbort = () => {
+        this.cancelCause = 'caller';
+        this.controller.abort();
+    };
+    constructor(caller) {
+        this.caller = caller;
+        caller?.addEventListener('abort', this.onCallerAbort, { once: true });
+        if (caller?.aborted)
+            this.onCallerAbort();
+    }
+    get signal() { return this.controller.signal; }
+    get callerAborted() { return this.caller?.aborted === true; }
+    get terminalDrainExpired() { return this.cancelCause === 'terminal-drain'; }
+    startDrain() {
+        if (this.timer !== undefined || this.cancelCause !== null)
+            return;
+        this.timer = setTimeout(() => {
+            if (this.callerAborted) {
+                this.onCallerAbort();
+                return;
+            }
+            this.cancelCause = 'terminal-drain';
+            this.controller.abort();
+        }, OPENAI_TERMINAL_DRAIN_MS);
+    }
+    dispose() {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.caller?.removeEventListener('abort', this.onCallerAbort);
+    }
+}
+function sendOpenAIRequest(request, defaultBaseUrl, signal) {
+    const baseUrl = (request.baseUrl || defaultBaseUrl).replace(/\/+$/, '');
+    return sendWithOutputLimitRecovery({
+        providerId: 'openai',
+        modelId: request.model,
+        body: buildRequestBody(request),
+        tokenField: openAiTokenField(request.model),
+        send: (payload) => fetch(`${baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${request.apiKey}`,
+            },
+            body: JSON.stringify(payload),
+            signal,
+        }),
+    });
+}
+async function* readOpenAIResponse(body, scope) {
+    const state = new OpenAIStreamState();
+    try {
+        for await (const sse of parseSSEStream(body, scope.signal)) {
+            if (scope.callerAborted)
+                return;
+            const raw = sse.data.trim();
+            if (raw === '[DONE]') {
+                state.sawTerminal = true;
+                break;
+            }
+            for (const event of state.consume(raw, scope)) {
+                if (scope.callerAborted)
+                    return;
+                yield event;
+                if (scope.callerAborted)
+                    return;
+            }
+        }
+    }
+    catch (err) {
+        if (scope.callerAborted)
+            return;
+        if (!scope.terminalDrainExpired || !state.sawTerminal)
+            throw err;
+    }
+    if (scope.callerAborted)
+        return;
+    if (!state.sawTerminal) {
+        throw new LLMError('openai stream truncated before a terminal chunk', 'openai', 'network_error', true);
+    }
+    for (const event of state.finish()) {
+        if (scope.callerAborted)
+            return;
+        yield event;
+        if (scope.callerAborted)
+            return;
+    }
+}
+class OpenAIStreamState {
+    usage = { inputTokens: 0, outputTokens: 0 };
+    sawTerminal = false;
+    text = '';
+    thinking = '';
+    stopReason;
+    tools = new Map();
+    *consume(raw, scope) {
+        let chunk;
+        try {
+            chunk = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!chunk || typeof chunk !== 'object')
+            return;
+        const usage = chunk.usage;
+        if (usage) {
+            this.usage.inputTokens = usage.prompt_tokens ?? this.usage.inputTokens;
+            this.usage.outputTokens = usage.completion_tokens ?? this.usage.outputTokens;
+        }
+        if (this.sawTerminal)
+            return;
+        const choices = chunk.choices;
+        if (!Array.isArray(choices) || choices.length === 0)
+            return;
+        const choice = choices.find((candidate) => candidate.index === 0)
+            ?? (choices[0].index === undefined ? choices[0] : undefined);
+        if (!choice)
+            return;
+        if (typeof choice.finish_reason === 'string' && choice.finish_reason.length > 0) {
+            this.sawTerminal = true;
+            this.stopReason = mapFinishReason(choice.finish_reason);
+            // Start at receipt, including when a consumer pauses on this frame's delta.
+            scope.startDrain();
+        }
+        const delta = choice.delta;
+        if (delta)
+            yield* this.consumeDelta(delta);
+    }
+    *consumeDelta(delta) {
+        const reasoning = delta.reasoning_content;
+        if (typeof reasoning === 'string' && reasoning.length > 0) {
+            if (this.thinking.length === 0)
+                yield { type: 'thinking_start' };
+            this.thinking += reasoning;
+            yield { type: 'thinking_delta', delta: reasoning };
+        }
+        if (typeof delta.content === 'string' && delta.content.length > 0) {
+            this.text += delta.content;
+            yield { type: 'text_delta', delta: delta.content };
+        }
+        const tools = delta.tool_calls;
+        if (Array.isArray(tools)) {
+            for (const tool of tools)
+                yield* this.consumeTool(tool);
+        }
+    }
+    *consumeTool(tool) {
+        const index = tool.index ?? 0;
+        const fn = tool.function;
+        let acc = this.tools.get(index);
+        if (!acc) {
+            acc = {
+                index, toolCallId: tool.id || `call_${index}`,
+                toolName: fn?.name || '', argsJson: '', started: false,
+            };
+            this.tools.set(index, acc);
+        }
+        if (fn?.name)
+            acc.toolName = fn.name;
+        if (!acc.started && acc.toolName) {
+            acc.started = true;
+            yield { type: 'tool_call_start', toolCallId: acc.toolCallId, toolName: acc.toolName };
+        }
+        if (typeof fn?.arguments === 'string' && fn.arguments.length > 0) {
+            acc.argsJson += fn.arguments;
+            if (acc.started) {
+                yield { type: 'tool_call_delta', toolCallId: acc.toolCallId, argsDelta: fn.arguments };
+            }
+        }
+    }
+    *finish() {
+        const content = [];
+        if (this.thinking)
+            content.push({ type: 'thinking', text: this.thinking });
+        if (this.text)
+            content.push({ type: 'text', text: this.text });
+        for (const acc of this.tools.values()) {
+            let args = {};
+            try {
+                args = acc.argsJson ? JSON.parse(acc.argsJson) : {};
+            }
+            catch {
+                args = { __raw: acc.argsJson };
+            }
+            content.push({
+                type: 'tool_call', toolCallId: acc.toolCallId, toolName: acc.toolName, args,
+            });
+            yield { type: 'tool_call_end', toolCallId: acc.toolCallId, toolName: acc.toolName, args };
+        }
+        const message = {
+            role: 'assistant', content, usage: this.usage, stopReason: this.stopReason,
+        };
+        yield { type: 'done', message, usage: this.usage };
+    }
+}
 // ---------------------------------------------------------------------------
 // Internal: request body builder
 // ---------------------------------------------------------------------------

package/dist/llm/retry.js

@@ -366,6 +366,8 @@ export async function* withRetry(makeStream, opts) {
     /** Retries COMPLETED so far. */
     let retryIndex = 0;
     for (;;) {
+        if (Boolean(signal?.aborted))
+            return;
         let committed = false;
         const toolCallIds = [];
         let sawDone = false;
@@ -388,6 +390,8 @@ export async function* withRetry(makeStream, opts) {
                 sawDone = true;
             yield event;
         }
+        if (Boolean(signal?.aborted))
+            return;
         if (sawDone)
             return; // success; the hot path ends here
         if (terminalError === undefined) {

package/dist/llm/sse-parser.d.ts

@@ -0,0 +1,25 @@
+import type { SSEEvent } from './stream-utils.js';
+export declare const SSE_FRAME_LIMIT = 1048576;
+/** A single SSE frame exceeded its UTF-16 capacity; retrying cannot repair it. */
+export declare class SseFrameLimitError extends Error {
+    constructor();
+}
+/** Incremental model-stream parser; IDs are local to each event, not reconnect state. */
+export declare class SseParser {
+    private line;
+    private dataLines;
+    private event;
+    private id;
+    private frameUnits;
+    private skipNextLf;
+    private atStart;
+    /** Consume decoded text lazily, throwing SseFrameLimitError on an oversized frame. */
+    push(text: string): IterableIterator<SSEEvent>;
+    /** Preserve the model adapters' complete-last-line compatibility at normal EOF. */
+    finish(): IterableIterator<SSEEvent>;
+    /** Discard uncommitted input without dispatching it, including on cancellation. */
+    clear(): void;
+    private countUnit;
+    private finishLine;
+    private dispatch;
+}

package/dist/llm/sse-parser.js

@@ -0,0 +1,103 @@
+export const SSE_FRAME_LIMIT = 1_048_576;
+/** A single SSE frame exceeded its UTF-16 capacity; retrying cannot repair it. */
+export class SseFrameLimitError extends Error {
+    constructor() {
+        super(`SSE frame exceeds ${SSE_FRAME_LIMIT} UTF-16 code units`);
+        this.name = 'SseFrameLimitError';
+    }
+}
+/** Incremental model-stream parser; IDs are local to each event, not reconnect state. */
+export class SseParser {
+    line = '';
+    dataLines = [];
+    event;
+    id;
+    frameUnits = 0;
+    skipNextLf = false;
+    atStart = true;
+    /** Consume decoded text lazily, throwing SseFrameLimitError on an oversized frame. */
+    *push(text) {
+        for (let index = 0; index < text.length; index++) {
+            const char = text[index];
+            if (this.atStart) {
+                this.atStart = false;
+                if (char === '\uFEFF')
+                    continue;
+            }
+            if (this.skipNextLf) {
+                this.skipNextLf = false;
+                if (char === '\n') {
+                    // A blank CR already dispatched/reset the frame. Its optional LF
+                    // belongs to that delimiter, never to the next frame's budget.
+                    if (this.frameUnits > 0)
+                        this.countUnit();
+                    continue;
+                }
+            }
+            this.countUnit();
+            if (char !== '\r' && char !== '\n') {
+                this.line += char;
+                continue;
+            }
+            this.skipNextLf = char === '\r';
+            const event = this.finishLine();
+            if (event)
+                yield event;
+        }
+    }
+    /** Preserve the model adapters' complete-last-line compatibility at normal EOF. */
+    *finish() {
+        if (this.line.length > 0)
+            this.finishLine();
+        const event = this.dispatch();
+        if (event)
+            yield event;
+    }
+    /** Discard uncommitted input without dispatching it, including on cancellation. */
+    clear() {
+        this.line = '';
+        this.dataLines = [];
+        this.event = undefined;
+        this.id = undefined;
+        this.frameUnits = 0;
+    }
+    countUnit() {
+        this.frameUnits++;
+        if (this.frameUnits <= SSE_FRAME_LIMIT)
+            return;
+        this.clear();
+        throw new SseFrameLimitError();
+    }
+    finishLine() {
+        const line = this.line;
+        this.line = '';
+        if (line.length === 0)
+            return this.dispatch();
+        if (line.startsWith(':'))
+            return;
+        const colon = line.indexOf(':');
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        switch (field) {
+            case 'data':
+                this.dataLines.push(value);
+                break;
+            case 'event':
+                this.event = value;
+                break;
+            case 'id':
+                if (!value.includes('\0'))
+                    this.id = value;
+                break;
+        }
+    }
+    dispatch() {
+        const event = this.dataLines.length > 0 || this.event !== undefined
+            ? { event: this.event, data: this.dataLines.join('\n'), id: this.id }
+            : undefined;
+        this.clear();
+        return event;
+    }
+}

package/dist/llm/stream-utils.d.ts

@@ -11,16 +11,9 @@ export interface SSEEvent {
     id?: string;
 }
 /**
- * Parse a `ReadableStream<Uint8Array>` (typically `Response.body`) into an
- * async iterator of {@link SSEEvent} objects.
- *
- * Handles:
- * - Multi-line `data:` fields (concatenated with `\n`)
- * - `event:` and `id:` fields
- * - Proper `\n\n` event boundary detection
- * - Graceful abort via `signal`
- *
- * The iterator ends when the stream closes or `signal` fires.
+ * Parse model SSE frames, retaining the normal EOF compatibility extension.
+ * Abort drops pending data; all early exits cancel once without awaiting cleanup.
+ * Throws SseFrameLimitError when an individual frame exceeds its capacity.
  */
 export declare function parseSSEStream(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterableIterator<SSEEvent>;
 /**

package/dist/llm/stream-utils.js

@@ -1,106 +1,92 @@
 /**
  * SSE stream parser and convenience helpers for LLM streaming.
  */
+import { SseParser } from './sse-parser.js';
 // ---------------------------------------------------------------------------
 // Generic SSE parser
 // ---------------------------------------------------------------------------
 /**
- * Parse a `ReadableStream<Uint8Array>` (typically `Response.body`) into an
- * async iterator of {@link SSEEvent} objects.
- *
- * Handles:
- * - Multi-line `data:` fields (concatenated with `\n`)
- * - `event:` and `id:` fields
- * - Proper `\n\n` event boundary detection
- * - Graceful abort via `signal`
- *
- * The iterator ends when the stream closes or `signal` fires.
+ * Parse model SSE frames, retaining the normal EOF compatibility extension.
+ * Abort drops pending data; all early exits cancel once without awaiting cleanup.
+ * Throws SseFrameLimitError when an individual frame exceeds its capacity.
  */
 export async function* parseSSEStream(body, signal) {
+    if (signal?.aborted)
+        return;
     const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = '';
-    // Set up abort listener to release the reader
-    const onAbort = () => {
-        reader.cancel().catch(() => { });
+    const decoder = new TextDecoder('utf-8', { ignoreBOM: true });
+    const parser = new SseParser();
+    let reachedEof = false;
+    let cancelled = false;
+    const cancelOnce = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        try {
+            // A transport can reject or never settle its cleanup promise.
+            void reader.cancel().catch(() => { });
+        }
+        catch {
+            // A synchronous transport cleanup failure must not mask the stream result.
+        }
     };
-    signal?.addEventListener('abort', onAbort, { once: true });
+    signal?.addEventListener('abort', cancelOnce, { once: true });
     try {
-        while (true) {
-            if (signal?.aborted)
-                break;
+        if (signal?.aborted) {
+            cancelOnce();
+            return;
+        }
+        while (!signal?.aborted) {
             const { done, value } = await reader.read();
-            if (done)
+            if (signal?.aborted)
+                return;
+            if (done) {
+                reachedEof = true;
                 break;
-            buffer += decoder.decode(value, { stream: true });
-            // Process complete events separated by \n\n
-            let boundary;
-            while ((boundary = buffer.indexOf('\n\n')) !== -1) {
-                const rawEvent = buffer.slice(0, boundary);
-                buffer = buffer.slice(boundary + 2);
-                const parsed = parseSSEBlock(rawEvent);
-                if (parsed) {
-                    yield parsed;
-                }
             }
-        }
-        // Flush any trailing data that wasn't terminated by \n\n
-        if (buffer.trim().length > 0) {
-            const parsed = parseSSEBlock(buffer);
-            if (parsed) {
-                yield parsed;
+            for (const event of decodeChunk(value, decoder, parser)) {
+                if (signal?.aborted)
+                    return;
+                yield event;
+                if (signal?.aborted)
+                    return;
             }
         }
+        if (signal?.aborted)
+            return;
+        for (const event of parser.push(decoder.decode())) {
+            if (signal?.aborted)
+                return;
+            yield event;
+        }
+        if (signal?.aborted)
+            return;
+        for (const event of parser.finish()) {
+            if (signal?.aborted)
+                return;
+            yield event;
+        }
+    }
+    catch (err) {
+        cancelOnce();
+        if (signal?.aborted)
+            return;
+        throw err;
     }
     finally {
-        signal?.removeEventListener('abort', onAbort);
+        signal?.removeEventListener('abort', cancelOnce);
+        parser.clear();
+        if (!reachedEof)
+            cancelOnce();
         reader.releaseLock();
     }
 }
-/**
- * Parse a single SSE block (the text between two `\n\n` boundaries) into an
- * {@link SSEEvent}.  Returns `undefined` for comment-only or empty blocks.
- */
-function parseSSEBlock(block) {
-    let event;
-    let id;
-    const dataLines = [];
-    for (const line of block.split('\n')) {
-        // Comment lines start with ':'
-        if (line.startsWith(':'))
-            continue;
-        const colonIdx = line.indexOf(':');
-        if (colonIdx === -1) {
-            // Field with no value — treat field name as the value (per SSE spec)
-            continue;
-        }
-        const field = line.slice(0, colonIdx);
-        // Value starts after ':' — strip a single leading space if present
-        let value = line.slice(colonIdx + 1);
-        if (value.startsWith(' ')) {
-            value = value.slice(1);
-        }
-        switch (field) {
-            case 'event':
-                event = value;
-                break;
-            case 'data':
-                dataLines.push(value);
-                break;
-            case 'id':
-                id = value;
-                break;
-            // 'retry' and unknown fields are ignored
-        }
-    }
-    if (dataLines.length === 0 && event === undefined) {
-        return undefined;
+function* decodeChunk(bytes, decoder, parser) {
+    const decodeSliceBytes = 16 * 1024;
+    for (let offset = 0; offset < bytes.length; offset += decodeSliceBytes) {
+        const slice = bytes.subarray(offset, offset + decodeSliceBytes);
+        yield* parser.push(decoder.decode(slice, { stream: true }));
     }
-    return {
-        event,
-        data: dataLines.join('\n'),
-        id,
-    };
 }
 // ---------------------------------------------------------------------------
 // Convenience: streamLLM / completeLLM

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/core",
-  "version": "0.2.17",
+  "version": "0.2.20",
   "description": "AragonAgent core engine — LLM provider adapters, streaming, tool registry/execution, steering, idle watchdog, and an optional isolated-vm sandbox.",
   "license": "MIT",
   "author": "AragonAgent contributors",