@steve31415/baselib 3.58.1 → 3.59.0

package/dist/llm/complete.js

@@ -155,6 +155,7 @@ export async function llmComplete(request) {
                 model: modelEntry.apiModelId,
                 tokensUsed: result.tokensUsed,
                 outputTokens: result.outputTokens,
+                reasoningTokens: result.reasoningTokens,
                 cacheReadTokens: result.cacheReadTokens,
                 cacheCreationTokens: result.cacheCreationTokens,
                 finishReason: result.finishReason,

package/dist/llm/providers/gemini.js

@@ -151,8 +151,19 @@ export const geminiProvider = {
         const data = JSON.parse(responseText);
         const latencyMs = Date.now() - startTime;
         const text = data.candidates?.[0]?.content?.parts?.[0]?.text || '';
-        const tokensUsed = data.usageMetadata?.totalTokenCount || 0;
-        const outputTokens = data.usageMetadata?.candidatesTokenCount ?? undefined;
+        // totalTokenCount = promptTokenCount (cached part included) + candidates
+        // + thoughts (verified live on 3.6 Flash, 2026-11-07). Google bills
+        // thoughts at the output rate and implicit-cache hits at a tenth of the
+        // input rate, so thoughts count as output and the cached part is reported
+        // apart and kept out of tokensUsed — the contract Anthropic's usage sets
+        // (types.ts LLMResponse.tokensUsed).
+        const usage = data.usageMetadata;
+        const reasoningTokens = usage?.thoughtsTokenCount || undefined;
+        const cacheReadTokens = usage?.cachedContentTokenCount || undefined;
+        const outputTokens = usage?.candidatesTokenCount === undefined && reasoningTokens === undefined
+            ? undefined
+            : (usage?.candidatesTokenCount ?? 0) + (reasoningTokens ?? 0);
+        const tokensUsed = Math.max(0, (usage?.totalTokenCount || 0) - (cacheReadTokens ?? 0));
         const finishReason = data.candidates?.[0]?.finishReason?.toLowerCase() ?? undefined;
         let json;
         if (request.jsonSchema) {
@@ -164,8 +175,13 @@ export const geminiProvider = {
         request.logger?.info('llm.response', {
             provider: 'gemini', model: request.apiModelId,
             status: response.status, latencyMs, tokensUsed, outputTokens, finishReason,
+            ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+            ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
             ...(request.callSite ? { callSite: request.callSite } : {}),
         });
-        return { text, json, tokensUsed, outputTokens, finishReason, finishCategory: classifyFinish(finishReason), latencyMs };
+        return {
+            text, json, tokensUsed, outputTokens, reasoningTokens, cacheReadTokens,
+            finishReason, finishCategory: classifyFinish(finishReason), latencyMs,
+        };
     },
 };

package/dist/llm/providers/openai.js

@@ -181,8 +181,18 @@ export const openaiProvider = {
         const data = JSON.parse(responseText);
         const latencyMs = Date.now() - startTime;
         const text = data.choices?.[0]?.message?.content || '';
-        const outputTokens = data.usage?.completion_tokens ?? undefined;
-        const tokensUsed = (data.usage?.prompt_tokens || 0) + (data.usage?.completion_tokens || 0);
+        // prompt_tokens includes cache reads and writes; completion_tokens
+        // includes reasoning (verified live on gpt-5.6-luna, 2026-11-07). OpenAI
+        // bills cache reads at a tenth and 30-minute cache writes at 1.25x the
+        // input rate, so both are reported apart and kept out of tokensUsed —
+        // the contract Anthropic's usage sets (types.ts LLMResponse.tokensUsed).
+        const usage = data.usage;
+        const outputTokens = usage?.completion_tokens ?? undefined;
+        const reasoningTokens = usage?.completion_tokens_details?.reasoning_tokens || undefined;
+        const cacheReadTokens = usage?.prompt_tokens_details?.cached_tokens || undefined;
+        const cacheCreationTokens = usage?.prompt_tokens_details?.cache_write_tokens || undefined;
+        const uncachedInput = Math.max(0, (usage?.prompt_tokens || 0) - (cacheReadTokens ?? 0) - (cacheCreationTokens ?? 0));
+        const tokensUsed = uncachedInput + (usage?.completion_tokens || 0);
         const finishReason = data.choices?.[0]?.finish_reason ?? undefined;
         let json;
         if (request.jsonSchema) {
@@ -194,8 +204,14 @@ export const openaiProvider = {
         request.logger?.info('llm.response', {
             provider: 'openai', model: request.apiModelId,
             status: response.status, latencyMs, tokensUsed, outputTokens, finishReason,
+            ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+            ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+            ...(cacheCreationTokens !== undefined ? { cacheCreationTokens } : {}),
             ...(request.callSite ? { callSite: request.callSite } : {}),
         });
-        return { text, json, tokensUsed, outputTokens, finishReason, finishCategory: classifyFinish(finishReason), latencyMs };
+        return {
+            text, json, tokensUsed, outputTokens, reasoningTokens, cacheReadTokens, cacheCreationTokens,
+            finishReason, finishCategory: classifyFinish(finishReason), latencyMs,
+        };
     },
 };

package/dist/llm/types.d.ts

@@ -116,18 +116,39 @@ export interface LLMResponse {
     provider: ProviderName;
     /** The API model ID that produced this response. */
     model: string;
-    /** Total tokens used (input + output). */
+    /**
+     * Tokens billed at the regular rates: uncached input + output (hidden
+     * reasoning included). Prompt-cache reads and writes are NOT in it — they
+     * are reported apart, as every provider bills them at their own rate — so
+     * total input = tokensUsed − outputTokens + cacheReadTokens +
+     * cacheCreationTokens, and uncached input = tokensUsed − outputTokens.
+     * The same on all three providers (since 3.59.0; before it, Gemini and
+     * OpenAI counted cached input in here and Gemini left thinking out of
+     * outputTokens).
+     */
     tokensUsed: number;
-    /** Output tokens only, when the provider reports them separately. */
+    /**
+     * Output tokens, hidden reasoning included (Gemini's thoughts, OpenAI's
+     * reasoning tokens, Anthropic's thinking) — all billed at the output rate.
+     * Undefined when the provider reports no split.
+     */
     outputTokens?: number;
     /**
-     * Prompt-cache tokens read from the cache (Anthropic only, when caching is
-     * used). These are billed at a reduced rate vs. regular input tokens.
+     * The hidden-reasoning share of {@link outputTokens}, already included in
+     * it — informational, never added to output (Gemini `thoughtsTokenCount`,
+     * OpenAI `reasoning_tokens`; Anthropic does not report it). Absent when 0.
+     */
+    reasoningTokens?: number;
+    /**
+     * Prompt-cache tokens read from the cache: Anthropic when `cacheSystemPrompt`
+     * is used, Gemini implicit-cache hits, OpenAI automatic caching. Billed at
+     * about a tenth of the input rate (gpt-4o: half). Not in tokensUsed.
      */
     cacheReadTokens?: number;
     /**
-     * Prompt-cache tokens written to the cache (Anthropic only, when caching is
-     * used). These are billed at a premium over regular input tokens.
+     * Prompt-cache tokens written to the cache (Anthropic with
+     * `cacheSystemPrompt`; OpenAI's 30-minute writes on the gpt-5.6 family).
+     * Billed at 1.25x the input rate. Not in tokensUsed.
      */
     cacheCreationTokens?: number;
     /**
@@ -230,12 +251,15 @@ export interface ProviderCallRequest {
 export interface ProviderCallResponse {
     text: string;
     json?: unknown;
+    /** Uncached input + output; see {@link LLMResponse.tokensUsed}. */
     tokensUsed: number;
-    /** Output tokens only, when the provider reports them separately. */
+    /** Output tokens, reasoning included; see {@link LLMResponse.outputTokens}. */
     outputTokens?: number;
-    /** Prompt-cache read tokens (Anthropic, when caching is used). */
+    /** The reasoning share of outputTokens; see {@link LLMResponse.reasoningTokens}. */
+    reasoningTokens?: number;
+    /** Prompt-cache read tokens; see {@link LLMResponse.cacheReadTokens}. */
     cacheReadTokens?: number;
-    /** Prompt-cache creation tokens (Anthropic, when caching is used). */
+    /** Prompt-cache creation tokens; see {@link LLMResponse.cacheCreationTokens}. */
     cacheCreationTokens?: number;
     /** Normalized finish reason (lowercased common values where known). */
     finishReason?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.58.1",
+  "version": "3.59.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",