@absolutejs/ai 0.0.43 → 0.0.45

package/README.md

@@ -12,3 +12,36 @@ chunks over SSE, while `createProviderProxyResponse()` hosts any
 callbacks and abort objects never cross the wire. The Anthropic provider also
 accepts an injectable `fetch`, allowing hosts to retain egress policy, tracing,
 and test transports.
+
+## SSE event stream (`streamAIToSSE`)
+
+`streamAIToSSE` yields `{ event, data }` SSE frames. By default `data` is
+pre-rendered HTML from the renderers, and the terminal `status` event is
+overloaded across completion, budget stops, and errors — a headless consumer has
+to sniff `ai-usage` vs `ai-error` out of the HTML to tell them apart.
+
+Pass `structuredEvents: true` to get typed, machine-readable frames instead: each
+`data` is JSON (parse it), and the overloaded terminal splits into three distinct
+event names:
+
+| event      | when                    | `JSON.parse(data)`                                          |
+| ---------- | ----------------------- | ----------------------------------------------------------- |
+| `content`  | text delta              | `{ delta, full }`                                           |
+| `thinking` | reasoning delta         | `{ text }` (accumulated)                                    |
+| `tools`    | one per tool transition | `{ name, status: "running" \| "complete", input, result? }` |
+| `images`   | generated image         | `{ data, format, revisedPrompt? }`                          |
+| `complete` | normal completion       | `{ usage, durationMs, model }`                              |
+| `stopped`  | ceiling / limit / abort | `{ reason, detail }`                                        |
+| `error`    | thrown / lookup error   | `{ message }`                                               |
+| `ping`     | heartbeat keepalive     | `""` (unchanged)                                            |
+
+`stopped.reason` is one of `"max_total_tokens" | "max_duration_ms" | "max_tokens"
+| "max_turns" | "aborted"`. Exactly one terminal (`complete` / `stopped` /
+`error`) fires on every path — including an externally aborted loop, which now
+emits `stopped` with `reason: "aborted"` rather than masquerading as a
+completion. Payload types are exported (`AISSECompletePayload`,
+`AISSEStoppedPayload`, `AISSEErrorPayload`, `AISSEContentPayload`, …).
+
+The default (HTML) path is unchanged for the built-in HTMX/default UI, except an
+abort now renders the (previously unused) `canceled` renderer instead of a
+misleading usage chip.

package/dist/ai/index.js

@@ -2779,6 +2779,26 @@ var executeTool2 = async (options, toolName, toolInput) => {
   }
 };
 var serializeToolCall2 = (name, input) => `${name}:${JSON.stringify(input)}`;
+var contentEvent = (options, renderers, delta, full) => options.structuredEvents ? { data: JSON.stringify({ delta, full }), event: "content" } : { data: renderers.chunk(delta, full), event: "content" };
+var thinkingEvent = (options, renderers, text) => options.structuredEvents ? { data: JSON.stringify({ text }), event: "thinking" } : { data: renderers.thinking(text), event: "thinking" };
+var imageEvent = (options, renderers, data, format, revisedPrompt) => options.structuredEvents ? { data: JSON.stringify({ data, format, revisedPrompt }), event: "images" } : { data: renderers.image(data, format, revisedPrompt), event: "images" };
+var completeEvent = (options, renderers, fullResponse, usage, durationMs) => {
+  options.onComplete?.(fullResponse, usage);
+  return options.structuredEvents ? {
+    data: JSON.stringify({ durationMs, model: options.model, usage }),
+    event: "complete"
+  } : {
+    data: renderers.complete(usage, durationMs, options.model),
+    event: "status"
+  };
+};
+var stoppedEvent = (options, renderers, reason, detail) => {
+  if (options.structuredEvents) {
+    return { data: JSON.stringify({ detail, reason }), event: "stopped" };
+  }
+  return reason === "aborted" ? { data: renderers.canceled(), event: "status" } : { data: renderers.error(detail), event: "status" };
+};
+var errorEvent = (options, renderers, message) => options.structuredEvents ? { data: JSON.stringify({ message }), event: "error" } : { data: renderers.error(message), event: "status" };
 var streamAIToSSE = async function* (conversationId, messageId, options, renderers) {
   const signal = options.signal ?? new AbortController().signal;
   const startTime = Date.now();
@@ -2787,12 +2807,11 @@ var streamAIToSSE = async function* (conversationId, messageId, options, rendere
   try {
     yield* withHeartbeat(streamTurns(options, renderers, messages, signal, startTime, maxTurns), signal, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
   } catch (err) {
-    if (signal.aborted)
+    if (signal.aborted) {
+      yield stoppedEvent(options, renderers, "aborted", "Aborted by caller.");
       return;
-    yield {
-      data: renderers.error(err instanceof Error ? err.message : String(err)),
-      event: "status"
-    };
+    }
+    yield errorEvent(options, renderers, err instanceof Error ? err.message : String(err));
   }
 };
 var flushThinking2 = (thinking, contentBlocks) => {
@@ -2802,22 +2821,11 @@ var flushThinking2 = (thinking, contentBlocks) => {
     type: "thinking"
   });
 };
-var yieldCompletion = (renderers, options, fullResponse, usage, startTime) => {
-  const durationMs = Date.now() - startTime;
-  options.onComplete?.(fullResponse, usage);
-  return {
-    data: renderers.complete(usage, durationMs, options.model),
-    event: "status"
-  };
-};
-var processThinkingChunk = function* (content, signature, chunkState, renderers) {
+var processThinkingChunk = function* (content, signature, chunkState, renderers, options) {
   chunkState.currentThinking ??= { signature: "", text: "" };
   chunkState.currentThinking.text += content;
   chunkState.currentThinking.signature = signature ?? chunkState.currentThinking.signature;
-  yield {
-    data: renderers.thinking(chunkState.currentThinking.text),
-    event: "thinking"
-  };
+  yield thinkingEvent(options, renderers, chunkState.currentThinking.text);
 };
 var maybeFlushThinking = (chunkState) => {
   if (!chunkState.currentThinking)
@@ -2825,22 +2833,16 @@ var maybeFlushThinking = (chunkState) => {
   flushThinking2(chunkState.currentThinking, chunkState.contentBlocks);
   chunkState.currentThinking = null;
 };
-var processTextChunk = function* (content, chunkState, renderers, fullResponse) {
+var processTextChunk = function* (content, chunkState, renderers, fullResponse, options) {
   maybeFlushThinking(chunkState);
   chunkState.contentBlocks.push({
     content,
     type: "text"
   });
-  yield {
-    data: renderers.chunk(content, fullResponse + content),
-    event: "content"
-  };
+  yield contentEvent(options, renderers, content, fullResponse + content);
 };
 var processImageChunk = function* (chunk, renderers, options) {
-  yield {
-    data: renderers.image(chunk.data, chunk.format, chunk.revisedPrompt),
-    event: "images"
-  };
+  yield imageEvent(options, renderers, chunk.data, chunk.format, chunk.revisedPrompt);
   options.onImage?.({
     data: chunk.data,
     format: chunk.format,
@@ -2866,10 +2868,10 @@ var processToolUseChunk = (chunk, chunkState) => {
 var processChunk2 = function* (chunk, chunkState, renderers, options, fullResponse) {
   switch (chunk.type) {
     case "thinking":
-      yield* processThinkingChunk(chunk.content, chunk.signature, chunkState, renderers);
+      yield* processThinkingChunk(chunk.content, chunk.signature, chunkState, renderers, options);
       break;
     case "text":
-      yield* processTextChunk(chunk.content, chunkState, renderers, fullResponse);
+      yield* processTextChunk(chunk.content, chunkState, renderers, fullResponse, options);
       break;
     case "image":
       yield* processImageChunk(chunk, renderers, options);
@@ -2898,11 +2900,34 @@ var truncateToolResult = (result, max) => {
 var executeToolCalls = async function* (pendingToolCalls, options, renderers, turnState) {
   const toolResultBlocks = [];
   for (const toolCall of pendingToolCalls) {
-    turnState.allToolsHtml += renderers.toolRunning(toolCall.name, toolCall.input);
-    yield { data: turnState.allToolsHtml, event: "tools" };
+    if (options.structuredEvents) {
+      yield {
+        data: JSON.stringify({
+          input: toolCall.input,
+          name: toolCall.name,
+          status: "running"
+        }),
+        event: "tools"
+      };
+    } else {
+      turnState.allToolsHtml += renderers.toolRunning(toolCall.name, toolCall.input);
+      yield { data: turnState.allToolsHtml, event: "tools" };
+    }
     const result = await executeTool2(options, toolCall.name, toolCall.input);
-    turnState.allToolsHtml = turnState.allToolsHtml.replace(renderers.toolRunning(toolCall.name, toolCall.input), renderers.toolComplete(toolCall.name, result));
-    yield { data: turnState.allToolsHtml, event: "tools" };
+    if (options.structuredEvents) {
+      yield {
+        data: JSON.stringify({
+          input: toolCall.input,
+          name: toolCall.name,
+          result,
+          status: "complete"
+        }),
+        event: "tools"
+      };
+    } else {
+      turnState.allToolsHtml = turnState.allToolsHtml.replace(renderers.toolRunning(toolCall.name, toolCall.input), renderers.toolComplete(toolCall.name, result));
+      yield { data: turnState.allToolsHtml, event: "tools" };
+    }
     options.onToolUse?.(toolCall.name, toolCall.input, result);
     const resultContent = options.maxToolResultChars !== undefined ? truncateToolResult(result, options.maxToolResultChars) : result;
     toolResultBlocks.push({
@@ -2955,7 +2980,7 @@ var streamTurns = async function* (options, renderers, messages, signal, startTi
   let finishReason = "max_turns";
   let completedTurns = 0;
   try {
-    for (;turnState.turn < maxTurns && !signal.aborted; turnState.turn++) {
+    for (;turnState.turn <= maxTurns && !signal.aborted; turnState.turn++) {
       const chunkState = {
         contentBlocks: [],
         currentThinking: null,
@@ -2985,36 +3010,38 @@ var streamTurns = async function* (options, renderers, messages, signal, startTi
       const runningTotalTokens = aggregateUsage.inputTokens + aggregateUsage.outputTokens;
       if (chunkState.stopReason === "max_tokens") {
         finishReason = "max_tokens";
-        yield {
-          data: renderers.error(`Response truncated at max_tokens (output=${chunkState.usage?.outputTokens ?? "?"}). ` + `Raise maxTokens on the provider/options, split the request, or reduce upstream context.`),
-          event: "status"
-        };
+        yield stoppedEvent(options, renderers, "max_tokens", `Response truncated at max_tokens (output=${chunkState.usage?.outputTokens ?? "?"}). ` + `Raise maxTokens on the provider/options, split the request, or reduce upstream context.`);
         return;
       }
       if (options.maxTotalTokens && runningTotalTokens >= options.maxTotalTokens) {
         finishReason = "max_total_tokens";
-        yield {
-          data: renderers.error(`Stopped: token budget reached (${runningTotalTokens}/${options.maxTotalTokens} tokens over ` + `${turnState.turn} turns). Narrow the request or raise maxTotalTokens.`),
-          event: "status"
-        };
+        yield stoppedEvent(options, renderers, "max_total_tokens", `Stopped: token budget reached (${runningTotalTokens}/${options.maxTotalTokens} tokens over ` + `${turnState.turn} turns). Narrow the request or raise maxTotalTokens.`);
         return;
       }
       if (options.maxDurationMs && Date.now() - startTime >= options.maxDurationMs) {
         finishReason = "max_duration";
-        yield {
-          data: renderers.error(`Stopped: time budget reached (${Math.round((Date.now() - startTime) / 1000)}s over ` + `${turnState.turn} turns). Narrow the request or raise maxDurationMs.`),
-          event: "status"
-        };
+        yield stoppedEvent(options, renderers, "max_duration_ms", `Stopped: time budget reached (${Math.round((Date.now() - startTime) / 1000)}s over ` + `${turnState.turn} turns). Narrow the request or raise maxDurationMs.`);
         return;
       }
       if (shouldStopToolLoop(chunkState, turnState, signal)) {
-        finishReason = signal.aborted ? "aborted" : "complete";
-        return void (yield yieldCompletion(renderers, options, turnState.fullResponse, chunkState.usage, startTime));
+        if (signal.aborted) {
+          finishReason = "aborted";
+          yield stoppedEvent(options, renderers, "aborted", "Aborted by caller.");
+        } else {
+          finishReason = "complete";
+          yield completeEvent(options, renderers, turnState.fullResponse, chunkState.usage, Date.now() - startTime);
+        }
+        return;
       }
       yield* processTurn(chunkState, options, renderers, turnState);
     }
-    if (signal.aborted)
+    if (signal.aborted) {
       finishReason = "aborted";
+      yield stoppedEvent(options, renderers, "aborted", "Aborted by caller.");
+    } else {
+      finishReason = "max_turns";
+      yield stoppedEvent(options, renderers, "max_turns", `Stopped: reached maxTurns (${maxTurns}) without a final answer.`);
+    }
   } catch (error) {
     finishReason = signal.aborted ? "aborted" : "error";
     throw error;
@@ -3730,49 +3757,78 @@ var errorPayload = (error) => {
     type: providerError.type
   };
 };
-var streamResponseBody = (iterator, heartbeatMs, onError) => new ReadableStream({
-  async start(controller) {
+var streamResponseBody = (iterator, heartbeatMs, onError, onCancel) => {
+  let closed = false;
+  const send = (controller, value) => {
+    if (closed)
+      return false;
     try {
-      for (;; ) {
-        const pending = iterator.next();
-        let next;
+      controller.enqueue(value);
+      return true;
+    } catch {
+      closed = true;
+      return false;
+    }
+  };
+  return new ReadableStream({
+    cancel(reason) {
+      closed = true;
+      onCancel?.(reason);
+    },
+    async start(controller) {
+      try {
         for (;; ) {
-          let timer;
-          const heartbeat = new Promise((resolve) => {
-            timer = setTimeout(() => resolve("heartbeat"), heartbeatMs);
-          });
-          const winner = heartbeatMs > 0 ? await Promise.race([pending, heartbeat]) : await pending;
-          if (timer)
-            clearTimeout(timer);
-          if (winner === "heartbeat") {
-            controller.enqueue(encoder.encode(`: ping
+          const pending = iterator.next();
+          let next;
+          for (;; ) {
+            let timer;
+            const heartbeat = new Promise((resolve) => {
+              timer = setTimeout(() => resolve("heartbeat"), heartbeatMs);
+            });
+            const winner = heartbeatMs > 0 ? await Promise.race([pending, heartbeat]) : await pending;
+            if (timer)
+              clearTimeout(timer);
+            if (winner === "heartbeat") {
+              if (!send(controller, encoder.encode(`: ping
 
-`));
-            continue;
+`)))
+                return;
+              continue;
+            }
+            next = winner;
+            break;
           }
-          next = winner;
-          break;
+          if (closed || next.done)
+            break;
+          if (!send(controller, encodeEvent("chunk", next.value)))
+            break;
+        }
+      } catch (error) {
+        if (closed)
+          return;
+        await onError?.(error);
+        send(controller, encodeEvent("error", errorPayload(error)));
+      } finally {
+        await iterator.return?.();
+        if (!closed) {
+          closed = true;
+          try {
+            controller.close();
+          } catch {}
         }
-        if (next.done)
-          break;
-        controller.enqueue(encodeEvent("chunk", next.value));
       }
-    } catch (error) {
-      await onError?.(error);
-      controller.enqueue(encodeEvent("error", errorPayload(error)));
-    } finally {
-      await iterator.return?.();
-      controller.close();
     }
-  }
-});
+  });
+};
 var createProviderProxyResponse = async (provider, value, options = {}) => {
   const params = parseProviderProxyParams(value);
   if (!params) {
     return Response.json({ error: "invalid provider stream request" }, { status: 400 });
   }
-  const iterator = provider.stream({ ...params, signal: options.signal })[Symbol.asyncIterator]();
-  return new Response(streamResponseBody(iterator, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS2, options.onError), {
+  const disconnectController = new AbortController;
+  const signal = options.signal ? AbortSignal.any([options.signal, disconnectController.signal]) : disconnectController.signal;
+  const iterator = provider.stream({ ...params, signal })[Symbol.asyncIterator]();
+  return new Response(streamResponseBody(iterator, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS2, options.onError, (reason) => disconnectController.abort(reason)), {
     headers: {
       "cache-control": "no-cache",
       "content-type": "text/event-stream; charset=utf-8",
@@ -5943,5 +5999,5 @@ export {
   BUILTIN_UI_CARDS
 };
 
-//# debugId=DACDBFA8148E663564756E2164756E21
+//# debugId=4DB8BD5EBB62E6E464756E2164756E21
 //# sourceMappingURL=index.js.map