@absolutejs/ai 0.0.42 → 0.0.44

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({
@@ -2951,57 +2976,88 @@ var streamTurns = async function* (options, renderers, messages, signal, startTi
     turn: 0
   };
   const toolDefs = options.tools ? buildToolDefinitions2(options.tools) : undefined;
-  let runningTotalTokens = 0;
-  for (;turnState.turn <= maxTurns && !signal.aborted; turnState.turn++) {
-    const chunkState = {
-      contentBlocks: [],
-      currentThinking: null,
-      pendingToolCalls: [],
-      stopReason: undefined,
-      usage: undefined
-    };
-    const responseBeforeTurn = turnState.fullResponse;
-    const stream = options.provider.stream({
-      cacheSystemPrompt: options.cacheSystemPrompt,
-      maxTokens: options.maxTokens,
-      messages: turnState.currentMessages,
-      model: options.model,
-      promptCaching: options.promptCaching,
-      reasoning: options.reasoning,
-      signal,
-      systemPrompt: options.systemPrompt,
-      tools: toolDefs
-    });
-    yield* consumeStream2(stream, chunkState, renderers, options, turnState, signal);
-    options.onTurn?.(turnState.turn, chunkState.usage, turnState.fullResponse.slice(responseBeforeTurn.length));
-    runningTotalTokens += (chunkState.usage?.inputTokens ?? 0) + (chunkState.usage?.outputTokens ?? 0);
-    if (chunkState.stopReason === "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"
-      };
-      return;
-    }
-    if (options.maxTotalTokens && runningTotalTokens >= options.maxTotalTokens) {
-      yield {
-        data: renderers.error(`Stopped: token budget reached (${runningTotalTokens}/${options.maxTotalTokens} tokens over ` + `${turnState.turn} turns). Narrow the request or raise maxTotalTokens.`),
-        event: "status"
+  const aggregateUsage = { inputTokens: 0, outputTokens: 0 };
+  let finishReason = "max_turns";
+  let completedTurns = 0;
+  try {
+    for (;turnState.turn <= maxTurns && !signal.aborted; turnState.turn++) {
+      const chunkState = {
+        contentBlocks: [],
+        currentThinking: null,
+        pendingToolCalls: [],
+        stopReason: undefined,
+        usage: undefined
       };
-      return;
+      const responseBeforeTurn = turnState.fullResponse;
+      const stream = options.provider.stream({
+        cacheSystemPrompt: options.cacheSystemPrompt,
+        maxTokens: options.maxTokens,
+        messages: turnState.currentMessages,
+        model: options.model,
+        promptCaching: options.promptCaching,
+        reasoning: options.reasoning,
+        signal,
+        systemPrompt: options.systemPrompt,
+        tools: toolDefs
+      });
+      yield* consumeStream2(stream, chunkState, renderers, options, turnState, signal);
+      options.onTurn?.(turnState.turn, chunkState.usage, turnState.fullResponse.slice(responseBeforeTurn.length));
+      completedTurns += 1;
+      aggregateUsage.inputTokens += chunkState.usage?.inputTokens ?? 0;
+      aggregateUsage.outputTokens += chunkState.usage?.outputTokens ?? 0;
+      aggregateUsage.cacheReadInputTokens = (aggregateUsage.cacheReadInputTokens ?? 0) + (chunkState.usage?.cacheReadInputTokens ?? 0);
+      aggregateUsage.cacheWriteInputTokens = (aggregateUsage.cacheWriteInputTokens ?? 0) + (chunkState.usage?.cacheWriteInputTokens ?? 0);
+      const runningTotalTokens = aggregateUsage.inputTokens + aggregateUsage.outputTokens;
+      if (chunkState.stopReason === "max_tokens") {
+        finishReason = "max_tokens";
+        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 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 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)) {
+        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 (options.maxDurationMs && Date.now() - startTime >= options.maxDurationMs) {
-      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"
-      };
-      return;
+    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.`);
     }
-    if (shouldStopToolLoop(chunkState, turnState, signal)) {
-      return void (yield yieldCompletion(renderers, options, turnState.fullResponse, chunkState.usage, startTime));
+  } catch (error) {
+    finishReason = signal.aborted ? "aborted" : "error";
+    throw error;
+  } finally {
+    try {
+      await options.onFinish?.({
+        durationMs: Date.now() - startTime,
+        fullResponse: turnState.fullResponse,
+        reason: finishReason,
+        turns: completedTurns,
+        usage: aggregateUsage
+      });
+    } catch (error) {
+      console.error("[absolute-ai] onFinish rejected:", error);
     }
-    yield* processTurn(chunkState, options, renderers, turnState);
   }
-  return;
 };
 
 // src/constants.ts
@@ -5914,5 +5970,5 @@ export {
   BUILTIN_UI_CARDS
 };
 
-//# debugId=31B8793E47976E7B64756E2164756E21
+//# debugId=1FA497882C909B0464756E2164756E21
 //# sourceMappingURL=index.js.map