@absolutejs/ai 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ 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.2.0 — 2026-09-16
+
+### Added
+
+- **Expose each tool-loop turn response metadata so consumers can price the actual served processing tier** (`streamAIWithTools`, `StreamAIWithToolsEvent`)
+- **Route exact model IDs to the same provider for token counting, capacity checks, preparation and generation** (`createAIProviderRouter`)
+
+## 0.1.3 — 2026-09-16
+
+### Fixed
+
+- **Exclude OpenAI cache-write tokens from ordinary input so cache-aware billing never charges the same tokens twice** (`openai`, `openaiResponses`)
+
 ## 0.1.2 — 2026-09-16
 
 ### Fixed

package/README.md

@@ -496,3 +496,21 @@ its explicit `false` remains an opt-out unless `contextPolicy` is supplied.
 Applications should surface typed failures with saved-input retry UI. These
 changes do not guarantee detection of every provider-side accounting discrepancy
 or provide exactly-once external execution after a process crash.
+
+### Models from different providers
+
+`createAIProviderRouter` routes exact model IDs for generation, token counting and
+capacity checks. It snapshots the route map and fails explicitly for unknown
+models or a route without counting support. It does not choose a model or add a
+fallback. For example, preparation and final answering can use different vendors:
+
+```ts
+const provider = createAIProviderRouter({
+  "claude-haiku-4-5-20251001": anthropicProvider,
+  "gpt-5.6-luna": openaiResponsesProvider,
+});
+```
+
+`streamAIWithTools` includes each completed turn's provider response `metadata`
+on its `turn` event. Price that turn using the returned `serviceTier`, when
+available, rather than assuming that the requested processing tier was served.

package/changelog.json

@@ -2,6 +2,41 @@
 	"contract": 1,
 	"name": "@absolutejs/ai",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Expose each tool-loop turn response metadata so consumers can price the actual served processing tier",
+					"symbols": [
+						"streamAIWithTools",
+						"StreamAIWithToolsEvent"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Route exact model IDs to the same provider for token counting, capacity checks, preparation and generation",
+					"symbols": [
+						"createAIProviderRouter"
+					]
+				}
+			],
+			"date": "2026-09-16",
+			"version": "0.2.0"
+		},
+		{
+			"changes": [
+				{
+					"kind": "fixed",
+					"summary": "Exclude OpenAI cache-write tokens from ordinary input so cache-aware billing never charges the same tokens twice",
+					"symbols": [
+						"openai",
+						"openaiResponses"
+					]
+				}
+			],
+			"date": "2026-09-16",
+			"version": "0.1.3"
+		},
 		{
 			"changes": [
 				{

package/dist/ai/index.js

@@ -877,11 +877,12 @@ var extractUsage = (response) => {
   const outputDetails = isRecord(usage.output_tokens_details) ? usage.output_tokens_details : undefined;
   const inputDetails = isRecord(usage.input_tokens_details) ? usage.input_tokens_details : undefined;
   const costDetails = isRecord(usage.cost_details) ? usage.cost_details : undefined;
+  const written = inputDetails && typeof inputDetails.cache_write_tokens === "number" ? inputDetails.cache_write_tokens : 0;
   const normalized = {
     cacheReadInputTokens: cached,
-    cacheWriteInputTokens: inputDetails && typeof inputDetails.cache_write_tokens === "number" ? inputDetails.cache_write_tokens : undefined,
+    cacheWriteInputTokens: written || undefined,
     costCredits: typeof usage.cost === "number" ? usage.cost : undefined,
-    inputTokens: Math.max(0, input - cached),
+    inputTokens: Math.max(0, input - cached - written),
     outputTokens: typeof usage.output_tokens === "number" ? usage.output_tokens : 0,
     reasoningTokens: outputDetails && typeof outputDetails.reasoning_tokens === "number" ? outputDetails.reasoning_tokens : undefined,
     upstreamInferenceCostCredits: costDetails && typeof costDetails.upstream_inference_cost === "number" ? costDetails.upstream_inference_cost : undefined
@@ -1410,11 +1411,12 @@ var flushPendingToolCalls = function* (pendingToolCalls) {
 var extractUsage2 = (parsedUsage) => {
   const prompt = parsedUsage.prompt_tokens ?? 0;
   const cached = parsedUsage.cached_tokens ?? 0;
+  const written = parsedUsage.cache_write_tokens ?? 0;
   return {
     cacheReadInputTokens: cached,
-    cacheWriteInputTokens: parsedUsage.cache_write_tokens || undefined,
+    cacheWriteInputTokens: written || undefined,
     costCredits: parsedUsage.cost,
-    inputTokens: Math.max(0, prompt - cached),
+    inputTokens: Math.max(0, prompt - cached - written),
     outputTokens: parsedUsage.completion_tokens ?? 0,
     reasoningTokens: parsedUsage.reasoning_tokens || undefined,
     upstreamInferenceCostCredits: parsedUsage.upstream_inference_cost || undefined
@@ -5830,6 +5832,7 @@ var streamAIWithTools = async function* (options) {
     let thinking = null;
     let stopReason;
     let turnUsage;
+    let turnMetadata;
     let completed = false;
     for await (const chunk of stream) {
       if (base.signal?.aborted)
@@ -5875,19 +5878,30 @@ var streamAIWithTools = async function* (options) {
         thinking = flushThinking3(blocks, thinking);
         stopReason = chunk.stopReason;
         turnUsage = chunk.usage;
+        turnMetadata = chunk.metadata;
         completed = true;
       }
     }
     thinking = flushThinking3(blocks, thinking);
     if (policy !== false && !completed)
       throw new AIInputError("capacity_unavailable", "The model response was interrupted before completion. Preserve the original input for retry.");
-    return { blocks, pending, stopReason, usage: turnUsage };
+    return {
+      blocks,
+      pending,
+      stopReason,
+      usage: turnUsage,
+      metadata: turnMetadata
+    };
   };
   while (turn < maxTurns) {
     turn += 1;
     const outcome = yield* streamOneTurn();
     usage = mergeUsage(usage, outcome.usage);
-    yield { type: "turn", usage: outcome.usage };
+    yield {
+      type: "turn",
+      usage: outcome.usage,
+      ...outcome.metadata ? { metadata: outcome.metadata } : {}
+    };
     const { blocks, pending } = outcome;
     allToolCalls.push(...pending);
     if (outcome.stopReason === "pause_turn" && turn < maxTurns && base.signal?.aborted !== true) {
@@ -5937,7 +5951,11 @@ var streamAIWithTools = async function* (options) {
       turn += 1;
       const final = yield* streamOneTurn("none");
       usage = mergeUsage(usage, final.usage);
-      yield { type: "turn", usage: final.usage };
+      yield {
+        type: "turn",
+        usage: final.usage,
+        ...final.metadata ? { metadata: final.metadata } : {}
+      };
       allToolCalls.push(...final.pending);
       break;
     }
@@ -8595,6 +8613,30 @@ var createAIStoredToolResultRecovery = (toolNames) => async ({ params }) => {
     })
   }));
 };
+// src/ai/providerRouter.ts
+var createAIProviderRouter = (routes) => {
+  const providers = new Map(Object.entries(routes));
+  const resolve = (params) => {
+    params.signal?.throwIfAborted();
+    const provider = providers.get(params.model);
+    if (!provider)
+      throw new AIInputError("capacity_unavailable", `No provider route for model ${params.model}.`);
+    return provider;
+  };
+  const capacity = (params) => {
+    const result = resolve(params).inputCapacity;
+    if (!result)
+      throw new AIInputError("capacity_unavailable", `The provider for ${params.model} does not expose model capacity and token counting.`);
+    return result;
+  };
+  return {
+    inputCapacity: {
+      getLimits: async (params) => capacity(params).getLimits(params),
+      countTokens: async (params) => capacity(params).countTokens(params)
+    },
+    stream: (params) => resolve(params).stream(params)
+  };
+};
 export {
   AIInputError,
   BUILTIN_UI_CARDS,
@@ -8628,6 +8670,7 @@ export {
   configureProviderResilience,
   confirmCard,
   createAIConnection,
+  createAIProviderRouter,
   createAIStoredToolResultRecovery,
   createAIStream,
   createAITextSource,
@@ -8704,5 +8747,5 @@ export {
   xai
 };
 
-//# debugId=5DA989DD67F99C1B64756E2164756E21
+//# debugId=0CA4631EC8525EB564756E2164756E21
 //# sourceMappingURL=index.js.map