@quilltap/plugin-utils 2.6.2 → 2.7.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to @quilltap/plugin-utils will be documented in this file.
 
+## [2.7.0] - 2026-10-13
+
+### Fixed
+
+- `OpenAICompatibleProvider` now reports `usage.promptTokens` / `usage.totalTokens` with prompt-cache hits excluded, matching every other Quilltap provider. Endpoints fold cached input into `prompt_tokens` and report it as `prompt_tokens_details.cached_tokens`; that count is now subtracted (floored at 0) and surfaced as `cacheUsage` (`cacheReadInputTokens`, `cachedTokens`). The final stream chunk also carries the endpoint's own `usage` block as `rawProviderUsage`. Endpoints that report no cached tokens are unchanged. Previously, cache hits on any plugin built on the base class counted against Quilltap's autonomous-room token budgets.
+
+### Added
+
+- `protected normalizeUsage(usage)` — the one place both `sendMessage` and `streamMessage` map a Chat Completions `usage` block. Subclasses that keep the base send/stream loops can override it for an endpoint that reports cache hits in a different field.
+
 ## [2.6.0] - 2026-08-27
 
 ### Removed

package/dist/index.d.mts

@@ -124,6 +124,6 @@ declare function getQuilltapUserAgent(): string;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "2.6.2";
+declare const PLUGIN_UTILS_VERSION = "2.7.0";
 
 export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.d.ts

@@ -124,6 +124,6 @@ declare function getQuilltapUserAgent(): string;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "2.6.2";
+declare const PLUGIN_UTILS_VERSION = "2.7.0";
 
 export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.js

@@ -701,6 +701,34 @@ var OpenAICompatibleProvider = class {
     this.applyProfileParams(body, params);
     return body;
   }
+  /**
+   * Normalizes a Chat Completions `usage` block into Quilltap's shape.
+   *
+   * OpenAI-compatible endpoints fold prompt-cache hits into `prompt_tokens`
+   * (reported separately as `prompt_tokens_details.cached_tokens`). Quilltap's
+   * convention is that `promptTokens` / `totalTokens` EXCLUDE cache reads, so
+   * cached input never counts against token budgets; `cacheUsage` still
+   * carries the cache reads for display. Endpoints that report no
+   * `cached_tokens` are unaffected.
+   */
+  normalizeUsage(usage) {
+    const cachedTokens = usage?.prompt_tokens_details?.cached_tokens ?? 0;
+    if (cachedTokens > 0) {
+      this.logger.debug(`${this.providerName} usage: excluding prompt-cache hits from prompt/total`, {
+        context: `${this.providerName}Provider.normalizeUsage`,
+        promptTokens: usage?.prompt_tokens ?? 0,
+        cachedTokens
+      });
+    }
+    return {
+      usage: {
+        promptTokens: Math.max(0, (usage?.prompt_tokens ?? 0) - cachedTokens),
+        completionTokens: usage?.completion_tokens ?? 0,
+        totalTokens: Math.max(0, (usage?.total_tokens ?? 0) - cachedTokens)
+      },
+      ...cachedTokens > 0 ? { cacheUsage: { cacheReadInputTokens: cachedTokens, cachedTokens } } : {}
+    };
+  }
   /**
    * Sends a message and returns the complete response.
    *
@@ -723,11 +751,7 @@ var OpenAICompatibleProvider = class {
       return {
         content: choice.message.content ?? "",
         finishReason: choice.finish_reason,
-        usage: {
-          promptTokens: response.usage?.prompt_tokens ?? 0,
-          completionTokens: response.usage?.completion_tokens ?? 0,
-          totalTokens: response.usage?.total_tokens ?? 0
-        },
+        ...this.normalizeUsage(response.usage),
         raw: response,
         attachmentResults,
         ...toolCalls.length > 0 ? { toolCalls } : {}
@@ -768,11 +792,7 @@ var OpenAICompatibleProvider = class {
         const content = choice?.delta?.content;
         const hasUsage = chunk.usage;
         if (hasUsage) {
-          accumulatedUsage = {
-            prompt_tokens: chunk.usage?.prompt_tokens,
-            completion_tokens: chunk.usage?.completion_tokens,
-            total_tokens: chunk.usage?.total_tokens
-          };
+          accumulatedUsage = chunk.usage ?? null;
         }
         if (choice?.delta?.tool_calls) {
           for (const tcDelta of choice.delta.tool_calls) {
@@ -800,11 +820,10 @@ var OpenAICompatibleProvider = class {
       yield {
         content: "",
         done: true,
-        usage: accumulatedUsage ? {
-          promptTokens: accumulatedUsage.prompt_tokens ?? 0,
-          completionTokens: accumulatedUsage.completion_tokens ?? 0,
-          totalTokens: accumulatedUsage.total_tokens ?? 0
-        } : void 0,
+        ...accumulatedUsage ? {
+          ...this.normalizeUsage(accumulatedUsage),
+          rawProviderUsage: accumulatedUsage
+        } : {},
         attachmentResults,
         // Only synthesized when the stream actually carried tool calls: the
         // host's tool detection reads `rawResponse`, and an empty one on every
@@ -1064,7 +1083,7 @@ function rewriteLocalhostUrl(url) {
 }
 
 // src/version.generated.ts
-var PLUGIN_UTILS_VERSION = "2.6.2";
+var PLUGIN_UTILS_VERSION = "2.7.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUILTIN_TOOL_NAMES,