@absolutejs/ai 0.3.4 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,24 @@ 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
+
+- **Report a tool call's input while it streams: a `tool_input` chunk, and a `preparing` tools event from streamAIToSSE** (`AIChunk`, `AIToolInputChunk`, `streamAIToSSE`)
+  A tool call with a long input, such as a whole file, takes the model a minute or more to write, and until now nothing arrived meanwhile. The Anthropic provider now yields a `tool_input` chunk when a tool call starts and every 2 KB of its input, with the tool name, the characters received and the top-level string fields already complete (a path, a name; at most 200 characters each, never read from inside other values). With structured events, streamAIToSSE turns it into a `tools` event with status `preparing`. Consumers that do not know the chunk can ignore it.
+
+### Fixed
+
+- **streamAIToSSE sends a turn's text back as one block, not one per streamed delta, so agent loops stop re-writing their prompt cache** (`streamAIToSSE`)
+  streamAIToSSE stored every streamed text delta as its own content block, so an agent loop sent each turn's text back as dozens of blocks. Anthropic looks back only 20 blocks for an earlier cache entry, and a turn with a few sentences of text pushed the previous request's entry out of reach: the next request re-wrote the whole history at the cache-write price. A run of text is now one block, as generateAI and streamAIWithTools already kept it.
+
 ## 0.3.4 — 2026-10-15
 
 ### Fixed

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,49 @@
 	"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": [
+				{
+					"detail": "streamAIToSSE stored every streamed text delta as its own content block, so an agent loop sent each turn's text back as dozens of blocks. Anthropic looks back only 20 blocks for an earlier cache entry, and a turn with a few sentences of text pushed the previous request's entry out of reach: the next request re-wrote the whole history at the cache-write price. A run of text is now one block, as generateAI and streamAIWithTools already kept it.",
+					"kind": "fixed",
+					"summary": "streamAIToSSE sends a turn's text back as one block, not one per streamed delta, so agent loops stop re-writing their prompt cache",
+					"symbols": [
+						"streamAIToSSE"
+					]
+				},
+				{
+					"detail": "A tool call with a long input, such as a whole file, takes the model a minute or more to write, and until now nothing arrived meanwhile. The Anthropic provider now yields a `tool_input` chunk when a tool call starts and every 2 KB of its input, with the tool name, the characters received and the top-level string fields already complete (a path, a name; at most 200 characters each, never read from inside other values). With structured events, streamAIToSSE turns it into a `tools` event with status `preparing`. Consumers that do not know the chunk can ignore it.",
+					"kind": "added",
+					"summary": "Report a tool call's input while it streams: a `tool_input` chunk, and a `preparing` tools event from streamAIToSSE",
+					"symbols": [
+						"AIChunk",
+						"AIToolInputChunk",
+						"streamAIToSSE"
+					]
+				}
+			],
+			"date": "2026-10-16",
+			"version": "0.4.0"
+		},
 		{
 			"changes": [
 				{

package/dist/ai/index.js

@@ -999,10 +999,11 @@ var maybeFlushThinking = (chunkState) => {
 };
 var processTextChunk = function* (content, chunkState, renderers, fullResponse, options) {
   maybeFlushThinking(chunkState);
-  chunkState.contentBlocks.push({
-    content,
-    type: "text"
-  });
+  const last = chunkState.contentBlocks.at(-1);
+  if (last?.type === "text")
+    last.content += content;
+  else
+    chunkState.contentBlocks.push({ content, type: "text" });
   yield contentEvent(options, renderers, content, fullResponse + content);
 };
 var processImageChunk = function* (chunk, renderers, options) {
@@ -1056,6 +1057,19 @@ var processChunk = function* (chunk, chunkState, renderers, options, fullRespons
     case "tool_use":
       processToolUseChunk(chunk, chunkState);
       break;
+    case "tool_input":
+      if (options.structuredEvents)
+        yield {
+          data: JSON.stringify({
+            fields: chunk.fields,
+            id: chunk.id,
+            name: chunk.name,
+            receivedChars: chunk.receivedChars,
+            status: "preparing"
+          }),
+          event: "tools"
+        };
+      break;
     case "provider_event":
       maybeFlushThinking(chunkState);
       chunkState.contentBlocks.push({
@@ -2060,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 });
@@ -4860,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;
@@ -5473,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);
@@ -5511,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);
@@ -5527,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) {
@@ -5950,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) {
@@ -6048,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) {
@@ -6077,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;
@@ -6097,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) {
@@ -6599,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") {
@@ -6878,14 +6927,79 @@ var getNumber = (obj, key) => {
   }
   return 0;
 };
+var TOOL_INPUT_PROGRESS_CHARS = 2048;
+var TOOL_INPUT_FIELD_MAX_CHARS = 200;
+var readJsonString = (json, start) => {
+  for (let index = start + 1;index < json.length; index += 1) {
+    if (json[index] === "\\")
+      index += 1;
+    else if (json[index] === '"')
+      return { end: index + 1, raw: json.slice(start + 1, index) };
+  }
+  return;
+};
+var decodeJsonString = (raw) => {
+  try {
+    const value = JSON.parse(`"${raw}"`);
+    return typeof value === "string" ? value : undefined;
+  } catch {
+    return;
+  }
+};
+var completeStringFields = (partialJson) => {
+  const fields = {};
+  let depth = 0;
+  let key;
+  let index = 0;
+  while (index < partialJson.length) {
+    const character = partialJson[index];
+    if (character === '"') {
+      const text = readJsonString(partialJson, index);
+      if (!text)
+        break;
+      if (depth === 1 && key === undefined) {
+        const after = partialJson.slice(text.end).trimStart();
+        if (after.startsWith(":"))
+          key = text.raw;
+      } else if (depth === 1 && key !== undefined) {
+        const value = decodeJsonString(text.raw);
+        if (value !== undefined && value.length <= TOOL_INPUT_FIELD_MAX_CHARS)
+          fields[key] = value;
+        key = undefined;
+      }
+      index = text.end;
+      continue;
+    }
+    if (character === "{" || character === "[")
+      depth += 1;
+    else if (character === "}" || character === "]")
+      depth -= 1;
+    else if (character === "," && depth === 1)
+      key = undefined;
+    index += 1;
+  }
+  return fields;
+};
+var toolInputProgress = (state) => {
+  state.toolInputReported = state.toolInputJson.length;
+  return {
+    fields: completeStringFields(state.toolInputJson),
+    id: state.currentToolId,
+    name: state.currentToolName,
+    receivedChars: state.toolInputJson.length,
+    type: "tool_input"
+  };
+};
 var handleContentBlockStart = (parsed, state) => {
   const block = getRecord(parsed, "content_block");
   if (block && block.type === "tool_use") {
     state.currentToolId = getString(block, "id");
     state.currentToolName = getString(block, "name");
     state.toolInputJson = "";
+    state.toolInputReported = 0;
     state.isThinkingBlock = false;
     state.currentProviderBlock = undefined;
+    return toolInputProgress(state);
   } else if (block && block.type === "thinking") {
     state.isThinkingBlock = true;
     state.thinkingSignature = "";
@@ -6895,6 +7009,7 @@ var handleContentBlockStart = (parsed, state) => {
     state.currentProviderBlock = block && block.type !== "text" ? { ...block } : undefined;
     state.providerBlockInputJson = "";
   }
+  return;
 };
 var handleContentBlockDelta = (parsed, state) => {
   const delta = getRecord(parsed, "delta");
@@ -6929,6 +7044,8 @@ var handleContentBlockDelta = (parsed, state) => {
       state.providerBlockInputJson += getString(delta, "partial_json");
     } else {
       state.toolInputJson += getString(delta, "partial_json");
+      if (state.toolInputJson.length - state.toolInputReported >= TOOL_INPUT_PROGRESS_CHARS)
+        return toolInputProgress(state);
     }
   }
   if (delta.type === "signature_delta") {
@@ -7048,8 +7165,7 @@ var handleError = (parsed, state) => {
 var processEvent = (eventType, parsed, state) => {
   switch (eventType) {
     case "content_block_start": {
-      handleContentBlockStart(parsed, state);
-      return;
+      return handleContentBlockStart(parsed, state);
     }
     case "content_block_delta": {
       return handleContentBlockDelta(parsed, state);
@@ -7060,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);
@@ -7098,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;
@@ -7152,13 +7235,40 @@ async function* parseSSEStream4(body, providerName, signal) {
     stopReason: "",
     thinkingSignature: "",
     toolInputJson: "",
+    toolInputReported: 0,
     usage: undefined,
     providerName,
     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();
   }
 }
@@ -9062,5 +9172,5 @@ export {
   xai
 };
 
-//# debugId=16913D2F7231C56164756E2164756E21
+//# debugId=A58174807DA8A73664756E2164756E21
 //# sourceMappingURL=index.js.map