@absolutejs/ai 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,12 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.4.1 — 2026-10-17
+
+### Fixed
+
+- **Preserve provider usage snapshots through stream interruptions, distinguish partial from final usage, and retain tool-input start events without application patches** (`AIUsageUpdateChunk`, `anthropic`, `openai`, `openaiResponses`, `AIChunk`, `StreamAIWithToolsEvent`, `AIToolInputStartChunk`)
+
 ## 0.4.0 — 2026-10-16
 
 ### Added

package/README.md

@@ -560,3 +560,18 @@ are documented provider limits, not a substitute for runtime token budgeting.
 Regional features are omitted when they are not consistently supported.
 
 `@absolutejs/ai/research` separates an injected `SearchProvider` from evidence-only synthesis. It returns sources, findings, searches, limitations and explicit availability, and excludes invented source references/quotes. Quotation checks establish provenance; they are not a substitute for claim entailment or entity review. Hosts can set `maxRetries: 0` on one-shot or stream requests when they own attempt accounting, and independently bound `maxRepairAttempts` and disable context recovery.
+
+### Interrupted streams and usage
+
+Provider streams can emit `usage_update` chunks before `done`. Each carries a
+provider-reported cumulative snapshot: replace the previous snapshot for that
+attempt; never sum snapshots. `final: true` means the provider reported complete
+usage. An absent or false `final` means partial evidence, not a final bill.
+Anthropic exposes message-start and message-delta usage; OpenAI Chat exposes its
+usage chunk, and Responses preserves usage even on incomplete responses.
+
+Persist snapshots while consuming the stream. Cancellation or transport failure
+can prevent `done`, and no adapter can reconstruct usage the provider never sent.
+`onUsage` still reports only complete usage, once per instrumented stream. Keep
+credit reservations separate from charges and reconcile unknown outcomes in the
+host application. The package does not invent token counts or decide billing policy.

package/changelog.json

@@ -2,6 +2,25 @@
 	"contract": 1,
 	"name": "@absolutejs/ai",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "fixed",
+					"summary": "Preserve provider usage snapshots through stream interruptions, distinguish partial from final usage, and retain tool-input start events without application patches",
+					"symbols": [
+						"AIUsageUpdateChunk",
+						"anthropic",
+						"openai",
+						"openaiResponses",
+						"AIChunk",
+						"StreamAIWithToolsEvent",
+						"AIToolInputStartChunk"
+					]
+				}
+			],
+			"date": "2026-10-17",
+			"version": "0.4.1"
+		},
 		{
 			"changes": [
 				{

package/dist/ai/index.js

@@ -2074,6 +2074,8 @@ var streamAIWithTools = async function* (options) {
           transcript: chunk.transcript,
           type: "audio"
         };
+      } else if (chunk.type === "tool_input_start") {
+        yield chunk;
       } else if (chunk.type === "tool_use") {
         thinking = flushThinking3(blocks, thinking);
         pending.push({ id: chunk.id, input: chunk.input, name: chunk.name });
@@ -4874,7 +4876,7 @@ async function* tapStream(source, params, providerName) {
   let lastUsage;
   try {
     for await (const chunk of source) {
-      if (chunk.type === "done" && chunk.usage) {
+      if ((chunk.type === "done" || chunk.type === "usage_update" && chunk.final) && chunk.usage) {
         lastUsage = chunk.usage;
       }
       yield chunk;
@@ -5487,6 +5489,8 @@ var processCompleted = function* (parsed) {
   const { response } = parsed;
   const usage = extractUsage(response);
   const metadata = extractResponseMetadata(response);
+  if (usage)
+    yield { type: "usage_update", usage, metadata, final: true };
   if (isRecordArray(response.output)) {
     yield* extractCitationsFromOutput(response.output);
     yield* extractImageFromOutput(response.output);
@@ -5525,6 +5529,15 @@ var processSSEEvent = function* (eventType, parsed, pendingCalls, providerName)
       break;
     case "response.output_item.added":
       processOutputItemAdded(parsed, pendingCalls);
+      if (isRecord2(parsed.item) && parsed.item.type === "function_call" && typeof parsed.item.name === "string") {
+        const id = typeof parsed.item.call_id === "string" ? parsed.item.call_id : parsed.item.id;
+        if (typeof id === "string")
+          yield {
+            type: "tool_input_start",
+            id,
+            name: parsed.item.name
+          };
+      }
       break;
     case "response.output_item.done":
       yield* processOutputItemDone(parsed);
@@ -5541,8 +5554,19 @@ var processSSEEvent = function* (eventType, parsed, pendingCalls, providerName)
     case "response.failed":
     case "response.incomplete":
     case "response.error":
-    case "error":
+    case "error": {
+      if (isRecord2(parsed.response)) {
+        const usage = extractUsage(parsed.response);
+        if (usage)
+          yield {
+            type: "usage_update",
+            usage,
+            metadata: extractResponseMetadata(parsed.response),
+            final: false
+          };
+      }
       throw responseFailure(eventType, parsed, providerName);
+    }
   }
 };
 var flushSSEBuffer = function* (state) {
@@ -5964,6 +5988,14 @@ var processDelta = function* (delta, pendingToolCalls) {
   }
   if (isRecordArray2(delta.tool_calls)) {
     processToolCallDeltas(delta.tool_calls, pendingToolCalls);
+    for (const call of delta.tool_calls) {
+      if (isRecord3(call.function) && typeof call.function.name === "string" && call.function.name)
+        yield {
+          type: "tool_input_start",
+          id: typeof call.id === "string" ? call.id : String(call.index),
+          name: call.function.name
+        };
+    }
   }
   if (Array.isArray(delta.annotations)) {
     for (const annotation of delta.annotations) {
@@ -6062,7 +6094,12 @@ var processSSELine2 = function* (line, pendingToolCalls, providerName) {
   }
   const usageUpdate = narrowUsageRecord(parsed);
   if (usageUpdate) {
-    yield { type: "usage_update", usage: usageUpdate };
+    yield {
+      type: "usage_update",
+      usage: usageUpdate,
+      final: Array.isArray(parsed.choices) && parsed.choices.length === 0,
+      metadata: narrowResponseMetadata(parsed)
+    };
   }
   const metadata = narrowResponseMetadata(parsed);
   if (metadata) {
@@ -6091,10 +6128,9 @@ var processSSELine2 = function* (line, pendingToolCalls, providerName) {
   }
   yield* processChoice(firstChoice, pendingToolCalls);
 };
-var isUsageUpdate = (chunk) => chunk.type === "usage_update";
 var collectYieldableChunks = (line, pendingToolCalls, usageRef, metadataRef, providerName) => {
   const allChunks = Array.from(processSSELine2(line, pendingToolCalls, providerName));
-  const usageChunks = allChunks.filter(isUsageUpdate);
+  const usageChunks = allChunks.filter((chunk) => chunk.type === "usage_update");
   const lastUsage = usageChunks.at(NOT_FOUND4);
   if (lastUsage) {
     usageRef.current = lastUsage.usage;
@@ -6111,7 +6147,7 @@ var collectYieldableChunks = (line, pendingToolCalls, usageRef, metadataRef, pro
       }
     };
   }
-  return allChunks.filter((chunk) => !isUsageUpdate(chunk) && chunk.type !== "response_metadata");
+  return allChunks.filter((chunk) => chunk.type !== "response_metadata").map((chunk) => chunk.type === "usage_update" ? { ...chunk, metadata: metadataRef.current } : chunk);
 };
 var processSSELines2 = function* (lines, pendingToolCalls, usageRef, metadataRef, providerName) {
   for (const line of lines) {
@@ -6613,7 +6649,6 @@ var API_VERSION = "2023-06-01";
 var DEFAULT_MAX_TOKENS = 32000;
 var EVENT_PREFIX_LENGTH2 = 7;
 var DATA_PREFIX_LENGTH2 = 6;
-var EMPTY_CHUNKS = [];
 var isRecord5 = (val) => typeof val === "object" && val !== null;
 var mapContentBlock2 = (block) => {
   if (block.type === "thinking") {
@@ -7141,11 +7176,21 @@ var processEvent = (eventType, parsed, state) => {
     case "message_delta": {
       handleMessageDelta(parsed, state);
       mergeMetadata(parsed, state);
-      return;
+      return state.usage ? {
+        type: "usage_update",
+        usage: state.usage,
+        metadata: state.metadata,
+        final: false
+      } : undefined;
     }
     case "message_start": {
       handleMessageStart(parsed, state);
-      return;
+      return state.usage ? {
+        type: "usage_update",
+        usage: state.usage,
+        metadata: state.metadata,
+        final: false
+      } : undefined;
     }
     case "message_stop": {
       mergeMetadata(parsed, state);
@@ -7179,49 +7224,6 @@ var processSingleEvent = (event, state) => {
   }
   return processEvent(eventType, parsed, state);
 };
-var collectChunk = (event, state) => {
-  const chunk = processSingleEvent(event, state);
-  return chunk ? [chunk] : [];
-};
-var processBufferedEvents = (eventsText, state) => {
-  const events = eventsText.split(`
-
-`);
-  state.buffer = events.pop() ?? "";
-  return events.flatMap((event) => collectChunk(event, state));
-};
-var readNextChunks = async (reader, decoder, state, signal) => {
-  if (signal?.aborted) {
-    return { chunks: EMPTY_CHUNKS, done: true };
-  }
-  const { done, value } = await reader.read();
-  if (done) {
-    return { chunks: EMPTY_CHUNKS, done: true };
-  }
-  const rawText = state.buffer + decoder.decode(value, { stream: true });
-  const chunks = processBufferedEvents(rawText, state);
-  return { chunks, done: false };
-};
-var findDoneChunk = (chunks) => chunks.findIndex((c) => c.type === "done");
-var sseStreamLoop = async (reader, decoder, state, signal) => {
-  const result = await readNextChunks(reader, decoder, state, signal);
-  if (result.done) {
-    return { chunks: result.chunks, finished: true };
-  }
-  const doneIdx = findDoneChunk(result.chunks);
-  if (doneIdx >= 0) {
-    return { chunks: result.chunks.slice(0, doneIdx + 1), finished: true };
-  }
-  return { chunks: result.chunks, finished: false };
-};
-async function* streamChunks(reader, decoder, state, signal) {
-  let finished = false;
-  while (!finished) {
-    const result = await sseStreamLoop(reader, decoder, state, signal);
-    ({ finished } = result);
-    yield* result.chunks;
-  }
-}
 async function* parseSSEStream4(body, providerName, signal) {
   const reader = body.getReader();
   const decoder = new TextDecoder;
@@ -7239,8 +7241,34 @@ async function* parseSSEStream4(body, providerName, signal) {
     providerBlockInputJson: ""
   };
   try {
-    yield* streamChunks(reader, decoder, state, signal);
+    while (true) {
+      signal?.throwIfAborted();
+      const { done, value } = await reader.read();
+      if (done)
+        return;
+      const events = (state.buffer + decoder.decode(value, { stream: true })).split(`
+
+`);
+      state.buffer = events.pop() ?? "";
+      for (const event of events) {
+        const chunk = processSingleEvent(event, state);
+        if (!chunk)
+          continue;
+        if (chunk.type === "tool_input" && chunk.receivedChars === 0)
+          yield {
+            type: "tool_input_start",
+            id: chunk.id,
+            name: chunk.name
+          };
+        yield chunk;
+        if (chunk.type === "done")
+          return;
+      }
+    }
   } finally {
+    await reader.cancel().catch(() => {
+      return;
+    });
     reader.releaseLock();
   }
 }
@@ -9144,5 +9172,5 @@ export {
   xai
 };
 
-//# debugId=4ED2ED351363579D64756E2164756E21
+//# debugId=A58174807DA8A73664756E2164756E21
 //# sourceMappingURL=index.js.map