profclaw 2.3.0 → 2.4.0

package/dist/providers/ai-sdk.js

@@ -6,13 +6,14 @@
  *
  * @see https://sdk.vercel.ai/docs
  */
-import { generateText, streamText, tool as createTool, jsonSchema } from 'ai';
+import { generateText, streamText, stepCountIs, tool as createTool, jsonSchema } from 'ai';
 // Provider SDKs are lazily imported inside ensureProvider() to reduce startup memory
 // (each SDK is ~15MB; loading all 6 at startup costs ~100MB even if unused)
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { randomUUID } from 'node:crypto';
 import { logger } from '../utils/logger.js';
 import { normalizeToolSchema } from './schema-utils.js';
+import { aggregateStepUsage, applyAnthropicMessageCache, applyAnthropicToolCache, calculateCachedInputCost, getCacheConfigForModel, extractCacheUsage, } from './prompt-cache.js';
 // AI provider resilience settings (configurable via env)
 const AI_TIMEOUT_MS = parseInt(process.env['AI_PROVIDER_TIMEOUT_MS'] ?? '120000', 10);
 const AI_MAX_RETRIES = parseInt(process.env['AI_MAX_RETRIES'] ?? '2', 10);
@@ -866,7 +867,7 @@ class AIProviderManager {
         try {
             const result = await withRetry(() => generateText({
                 model,
-                messages,
+                messages: applyAnthropicMessageCache(messages, modelRef.provider),
                 temperature: request.temperature ?? 0.7,
                 maxOutputTokens: request.maxTokens ?? 4096,
                 abortSignal: AbortSignal.timeout(AI_TIMEOUT_MS),
@@ -874,12 +875,9 @@ class AIProviderManager {
             const duration = Date.now() - startTime;
             const modelInfo = this.getModelInfo(modelRef.model);
             // Calculate cost - AI SDK v6 uses usage.totalTokens and similar
-            const promptTokens = result.usage?.promptTokens ??
-                result.usage?.inputTokens ?? 0;
-            const completionTokens = result.usage?.completionTokens ??
-                result.usage?.outputTokens ?? 0;
+            const { promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens } = extractCacheUsage(result.usage);
             const cost = modelInfo
-                ? (promptTokens / 1_000_000) * modelInfo.costPer1MInput +
+                ? calculateCachedInputCost(promptTokens, cacheReadTokens, cacheWriteTokens, modelInfo.costPer1MInput, getCacheConfigForModel(modelInfo.id)) +
                     (completionTokens / 1_000_000) * modelInfo.costPer1MOutput
                 : 0;
             return {
@@ -893,6 +891,8 @@ class AIProviderManager {
                     completionTokens,
                     totalTokens: promptTokens + completionTokens,
                     cost,
+                    cacheReadTokens,
+                    cacheWriteTokens,
                 },
                 duration,
             };
@@ -923,7 +923,7 @@ class AIProviderManager {
         try {
             const result = streamText({
                 model,
-                messages,
+                messages: applyAnthropicMessageCache(messages, modelRef.provider),
                 temperature: request.temperature ?? 0.7,
                 maxOutputTokens: request.maxTokens ?? 4096,
                 abortSignal: AbortSignal.timeout(AI_TIMEOUT_MS),
@@ -953,12 +953,9 @@ class AIProviderManager {
             const usage = await result.usage;
             const duration = Date.now() - startTime;
             const modelInfo = this.getModelInfo(modelRef.model);
-            const promptTokens = usage?.promptTokens ??
-                usage?.inputTokens ?? 0;
-            const completionTokens = usage?.completionTokens ??
-                usage?.outputTokens ?? 0;
+            const { promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens } = extractCacheUsage(usage);
             const cost = modelInfo
-                ? (promptTokens / 1_000_000) * modelInfo.costPer1MInput +
+                ? calculateCachedInputCost(promptTokens, cacheReadTokens, cacheWriteTokens, modelInfo.costPer1MInput, getCacheConfigForModel(modelInfo.id)) +
                     (completionTokens / 1_000_000) * modelInfo.costPer1MOutput
                 : 0;
             return {
@@ -972,6 +969,8 @@ class AIProviderManager {
                     completionTokens,
                     totalTokens: promptTokens + completionTokens,
                     cost,
+                    cacheReadTokens,
+                    cacheWriteTokens,
                 },
                 duration,
             };
@@ -1039,10 +1038,10 @@ class AIProviderManager {
         try {
             const result = await withRetry(() => generateText({
                 model,
-                messages,
+                messages: applyAnthropicMessageCache(messages, modelRef.provider),
                 temperature: request.temperature ?? 0.7,
                 maxOutputTokens: request.maxTokens ?? 4096,
-                tools: useNativeTools ? aiSdkTools : undefined,
+                tools: useNativeTools ? applyAnthropicToolCache(aiSdkTools, modelRef.provider) : undefined,
                 abortSignal: AbortSignal.timeout(AI_TIMEOUT_MS),
             }));
             let finalContent = result.text;
@@ -1101,12 +1100,9 @@ class AIProviderManager {
             }
             const duration = Date.now() - startTime;
             const modelInfo = this.getModelInfo(modelRef.model);
-            const promptTokens = result.usage?.promptTokens ??
-                result.usage?.inputTokens ?? 0;
-            const completionTokens = result.usage?.completionTokens ??
-                result.usage?.outputTokens ?? 0;
+            const { promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens } = extractCacheUsage(result.usage);
             const cost = modelInfo
-                ? (promptTokens / 1_000_000) * modelInfo.costPer1MInput +
+                ? calculateCachedInputCost(promptTokens, cacheReadTokens, cacheWriteTokens, modelInfo.costPer1MInput, getCacheConfigForModel(modelInfo.id)) +
                     (completionTokens / 1_000_000) * modelInfo.costPer1MOutput
                 : 0;
             return {
@@ -1120,6 +1116,8 @@ class AIProviderManager {
                     completionTokens,
                     totalTokens: promptTokens + completionTokens,
                     cost,
+                    cacheReadTokens,
+                    cacheWriteTokens,
                 },
                 duration,
                 toolCalls: detectedToolCalls.length > 0 ? detectedToolCalls : undefined,
@@ -1293,22 +1291,19 @@ class AIProviderManager {
         try {
             const result = await withRetry(() => generateText({
                 model,
-                messages,
-                tools: Object.keys(tools).length > 0 ? tools : undefined,
+                messages: applyAnthropicMessageCache(messages, modelRef.provider),
+                tools: Object.keys(tools).length > 0 ? applyAnthropicToolCache(tools, modelRef.provider) : undefined,
                 temperature: request.temperature ?? 0.7,
                 maxOutputTokens: request.maxTokens ?? 4096,
-                maxSteps: request.maxToolRoundtrips ?? 5,
+                stopWhen: stepCountIs(request.maxToolRoundtrips ?? 5),
                 abortSignal: AbortSignal.timeout(AI_TIMEOUT_MS),
             }));
             const duration = Date.now() - startTime;
             const modelInfo = this.getModelInfo(modelRef.model);
-            // Calculate usage
-            const promptTokens = result.usage?.promptTokens ??
-                result.usage?.inputTokens ?? 0;
-            const completionTokens = result.usage?.completionTokens ??
-                result.usage?.outputTokens ?? 0;
+            // Calculate usage, summed across all steps (result.usage is last-step only)
+            const { promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens } = aggregateStepUsage(result.steps, result.usage);
             const cost = modelInfo
-                ? (promptTokens / 1_000_000) * modelInfo.costPer1MInput +
+                ? calculateCachedInputCost(promptTokens, cacheReadTokens, cacheWriteTokens, modelInfo.costPer1MInput, getCacheConfigForModel(modelInfo.id)) +
                     (completionTokens / 1_000_000) * modelInfo.costPer1MOutput
                 : 0;
             // Check if any tool calls require approval
@@ -1328,6 +1323,8 @@ class AIProviderManager {
                     completionTokens,
                     totalTokens: promptTokens + completionTokens,
                     cost,
+                    cacheReadTokens,
+                    cacheWriteTokens,
                 },
                 duration,
                 toolCalls: toolCallHistory.length > 0 ? toolCallHistory : undefined,
@@ -1438,11 +1435,11 @@ class AIProviderManager {
         try {
             const result = streamText({
                 model,
-                messages,
-                tools: Object.keys(tools).length > 0 ? tools : undefined,
+                messages: applyAnthropicMessageCache(messages, modelRef.provider),
+                tools: Object.keys(tools).length > 0 ? applyAnthropicToolCache(tools, modelRef.provider) : undefined,
                 temperature: request.temperature ?? 0.7,
                 maxOutputTokens: request.maxTokens ?? 4096,
-                maxSteps: request.maxToolRoundtrips ?? 5,
+                stopWhen: stepCountIs(request.maxToolRoundtrips ?? 5),
                 abortSignal: AbortSignal.timeout(AI_TIMEOUT_MS),
             });
             let fullText = '';
@@ -1453,12 +1450,9 @@ class AIProviderManager {
             const usage = await result.usage;
             const duration = Date.now() - startTime;
             const modelInfo = this.getModelInfo(modelRef.model);
-            const promptTokens = usage?.promptTokens ??
-                usage?.inputTokens ?? 0;
-            const completionTokens = usage?.completionTokens ??
-                usage?.outputTokens ?? 0;
+            const { promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens } = extractCacheUsage(usage);
             const cost = modelInfo
-                ? (promptTokens / 1_000_000) * modelInfo.costPer1MInput +
+                ? calculateCachedInputCost(promptTokens, cacheReadTokens, cacheWriteTokens, modelInfo.costPer1MInput, getCacheConfigForModel(modelInfo.id)) +
                     (completionTokens / 1_000_000) * modelInfo.costPer1MOutput
                 : 0;
             const pendingApprovals = toolResultHistory.filter(r => r.approvalRequired);
@@ -1477,6 +1471,8 @@ class AIProviderManager {
                     completionTokens,
                     totalTokens: promptTokens + completionTokens,
                     cost,
+                    cacheReadTokens,
+                    cacheWriteTokens,
                 },
                 duration,
                 toolCalls: toolCallHistory.length > 0 ? toolCallHistory : undefined,

package/dist/providers/core/models.js

@@ -7,8 +7,11 @@ import { ProviderType } from './types.js';
 // Model Aliases
 export const MODEL_ALIASES = {
     // Anthropic
-    opus: { provider: 'anthropic', model: 'claude-opus-4-6' },
-    sonnet: { provider: 'anthropic', model: 'claude-sonnet-4-5-20250929' },
+    opus: { provider: 'anthropic', model: 'claude-opus-5-5' },
+    sonnet: { provider: 'anthropic', model: 'claude-sonnet-5' },
+    fable: { provider: 'anthropic', model: 'claude-fable-5-1' },
+    'opus-legacy': { provider: 'anthropic', model: 'claude-opus-4-6' },
+    'sonnet-legacy': { provider: 'anthropic', model: 'claude-sonnet-4-5-20250929' },
     haiku: { provider: 'anthropic', model: 'claude-haiku-4-5-20251001' },
     // OpenAI
     gpt: { provider: 'openai', model: 'gpt-4o' },
@@ -113,6 +116,45 @@ export const MODEL_ALIASES = {
 // Model Catalog
 export const MODEL_CATALOG = [
     // Anthropic - All support native function calling
+    // Current Anthropic models. ids, context, max output and prices verified against
+    // https://platform.claude.com/docs/en/about-claude/models/overview (2026-09-26).
+    {
+        id: 'claude-fable-5-1',
+        name: 'Claude Fable 5.1',
+        provider: 'anthropic',
+        contextWindow: 1000000,
+        maxOutput: 128000,
+        supportsVision: true,
+        supportsStreaming: true,
+        supportsTools: true,
+        costPer1MInput: 10,
+        costPer1MOutput: 50,
+    },
+    {
+        id: 'claude-opus-5-5',
+        name: 'Claude Opus 5.5',
+        provider: 'anthropic',
+        contextWindow: 1000000,
+        maxOutput: 128000,
+        supportsVision: true,
+        supportsStreaming: true,
+        supportsTools: true,
+        costPer1MInput: 4,
+        costPer1MOutput: 20,
+    },
+    {
+        id: 'claude-sonnet-5',
+        name: 'Claude Sonnet 5',
+        provider: 'anthropic',
+        contextWindow: 1000000,
+        maxOutput: 128000,
+        supportsVision: true,
+        supportsStreaming: true,
+        supportsTools: true,
+        costPer1MInput: 2,
+        costPer1MOutput: 10,
+    },
+    // Legacy entries kept because other code and tests reference them.
     {
         id: 'claude-opus-4-6',
         name: 'Claude Opus 4.6',
@@ -142,12 +184,12 @@ export const MODEL_CATALOG = [
         name: 'Claude Haiku 4.5',
         provider: 'anthropic',
         contextWindow: 200000,
-        maxOutput: 8192,
+        maxOutput: 64000,
         supportsVision: true,
         supportsStreaming: true,
         supportsTools: true,
-        costPer1MInput: 0.25,
-        costPer1MOutput: 1.25,
+        costPer1MInput: 1,
+        costPer1MOutput: 5,
     },
     // OpenAI - GPT-4+ supports function calling
     {
@@ -381,23 +423,22 @@ export const MODEL_CATALOG = [
         costPer1MInput: 30.0,
         costPer1MOutput: 60.0,
     },
-    // Qwen 3 (local) — best small model for tool calling
+    // Gemma 4 (local): supports native tool calling + multimodal
     {
-        id: 'qwen3:4b',
-        name: 'Qwen 3 4B (Local)',
+        id: 'gemma4:e4b',
+        name: 'Gemma 4 E4B (Local)',
         provider: 'ollama',
-        contextWindow: 32768,
+        contextWindow: 128000,
         maxOutput: 8192,
-        supportsVision: false,
+        supportsVision: true,
         supportsStreaming: true,
         supportsTools: true,
         costPer1MInput: 0,
         costPer1MOutput: 0,
     },
-    // Gemma 4 (local) — supports native tool calling + multimodal
     {
-        id: 'gemma4:e4b',
-        name: 'Gemma 4 E4B (Local)',
+        id: 'gemma4:26b',
+        name: 'Gemma 4 26B (Local)',
         provider: 'ollama',
         contextWindow: 128000,
         maxOutput: 8192,
@@ -407,13 +448,14 @@ export const MODEL_CATALOG = [
         costPer1MInput: 0,
         costPer1MOutput: 0,
     },
+    // Qwen 3 (local): best small model for tool calling
     {
-        id: 'gemma4:26b',
-        name: 'Gemma 4 26B (Local)',
+        id: 'qwen3:4b',
+        name: 'Qwen 3 4B (Local)',
         provider: 'ollama',
-        contextWindow: 128000,
+        contextWindow: 32768,
         maxOutput: 8192,
-        supportsVision: true,
+        supportsVision: false,
         supportsStreaming: true,
         supportsTools: true,
         costPer1MInput: 0,

package/dist/providers/core/types.d.ts

@@ -55,6 +55,10 @@ export interface ChatResponse {
         completionTokens: number;
         totalTokens: number;
         cost: number;
+        /** Prompt tokens served from the provider cache (subset of promptTokens) */
+        cacheReadTokens?: number;
+        /** Prompt tokens written to the provider cache (subset of promptTokens) */
+        cacheWriteTokens?: number;
     };
     duration: number;
 }

package/dist/providers/prompt-cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Prompt caching helpers
+ *
+ * Anthropic requires explicit cache breakpoints (providerOptions.anthropic.cacheControl).
+ * The cached prefix order is: tools, then system, then messages. A breakpoint on the
+ * last system message therefore caches tool schemas and the system prompt together;
+ * an extra breakpoint on the last tool lets the tool block hit even if the system
+ * prompt changes. OpenAI caches automatically and only reports cached token counts.
+ *
+ * Cache multipliers are relative to the base input price and are env-configurable.
+ */
+import type { ModelMessage, ToolSet } from 'ai';
+export interface PromptCacheConfig {
+    enabled: boolean;
+    ttl: '5m' | '1h';
+    /** Cost of a cache read relative to base input price */
+    readMultiplier: number;
+    /** Cost of a cache write relative to base input price */
+    writeMultiplier: number;
+}
+export interface CacheUsage {
+    /** Total prompt tokens, including cached reads and writes */
+    promptTokens: number;
+    completionTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/** Read cache settings from env on each call so tests and runtime changes apply. */
+export declare function getPromptCacheConfig(env?: NodeJS.ProcessEnv): PromptCacheConfig;
+/**
+ * Cache config for one model. An explicit PROFCLAW_CACHE_READ_MULTIPLIER always wins,
+ * otherwise the model's documented read multiplier applies.
+ */
+export declare function getCacheConfigForModel(model: string, env?: NodeJS.ProcessEnv): PromptCacheConfig;
+/**
+ * Add cache breakpoints to the leading system block: one on the first system message
+ * (the stable prompt) and one on the last leading system message. Callers put volatile
+ * per-request context in a later system message so the first breakpoint still hits
+ * across requests. History after the system block stays outside the cached prefix.
+ * Returns a new array; inputs are not mutated.
+ */
+export declare function applyAnthropicMessageCache<T extends ModelMessage>(messages: T[], provider: string, config?: PromptCacheConfig): T[];
+/**
+ * Return tools in a deterministic (name-sorted) order with a cache breakpoint on the
+ * last one. Object key order in the request body affects the prefix bytes, so sorting
+ * keeps the tool block byte-stable across steps and sessions.
+ */
+export declare function applyAnthropicToolCache<T extends ToolSet>(tools: T, provider: string, config?: PromptCacheConfig): T;
+/**
+ * Normalize AI SDK usage (v6 shape, legacy promptTokens shape, or raw provider
+ * counters) into total prompt tokens plus cache read/write counts.
+ * In AI SDK v6, inputTokens already includes cached reads and writes.
+ */
+export declare function extractCacheUsage(usage: unknown): CacheUsage;
+/**
+ * Sum usage across multi-step runs (tokens plus cache read/write). Falls back to
+ * `fallback` (the run-level usage) when there are no per-step usages, because
+ * result.usage only reflects the last step in AI SDK v6.
+ */
+export declare function aggregateStepUsage(steps: unknown, fallback: unknown): CacheUsage;
+/**
+ * Input cost in USD for a prompt that may include cached tokens.
+ * Uncached tokens bill at the base rate, reads and writes at the multiplied rate.
+ */
+export declare function calculateCachedInputCost(promptTokens: number, cacheReadTokens: number, cacheWriteTokens: number, inputRatePer1M: number, config?: PromptCacheConfig): number;
+/** Fraction of prompt tokens served from cache (0 when there were no prompt tokens). */
+export declare function cacheHitRate(cacheReadTokens: number, promptTokens: number): number;
+//# sourceMappingURL=prompt-cache.d.ts.map

package/dist/providers/prompt-cache.js

@@ -0,0 +1,165 @@
+/**
+ * Prompt caching helpers
+ *
+ * Anthropic requires explicit cache breakpoints (providerOptions.anthropic.cacheControl).
+ * The cached prefix order is: tools, then system, then messages. A breakpoint on the
+ * last system message therefore caches tool schemas and the system prompt together;
+ * an extra breakpoint on the last tool lets the tool block hit even if the system
+ * prompt changes. OpenAI caches automatically and only reports cached token counts.
+ *
+ * Cache multipliers are relative to the base input price and are env-configurable.
+ */
+const DEFAULT_READ_MULTIPLIER = 0.1;
+const DEFAULT_WRITE_MULTIPLIER = 1.25;
+function parseMultiplier(raw, fallback) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+/** Read cache settings from env on each call so tests and runtime changes apply. */
+export function getPromptCacheConfig(env = process.env) {
+    const disabled = (env['PROFCLAW_PROMPT_CACHE'] ?? '').toLowerCase();
+    return {
+        enabled: !['0', 'false', 'off', 'no'].includes(disabled),
+        ttl: env['PROFCLAW_PROMPT_CACHE_TTL'] === '1h' ? '1h' : '5m',
+        readMultiplier: parseMultiplier(env['PROFCLAW_CACHE_READ_MULTIPLIER'], DEFAULT_READ_MULTIPLIER),
+        writeMultiplier: parseMultiplier(env['PROFCLAW_CACHE_WRITE_MULTIPLIER'], DEFAULT_WRITE_MULTIPLIER),
+    };
+}
+/**
+ * Cache reads bill at 5% of the base input price on Opus 5.5 and 2.5% on Fable 5.1,
+ * versus the 10% default elsewhere (Anthropic models overview, pricing notes).
+ */
+const MODEL_READ_MULTIPLIERS = [
+    [/fable-5-1/, 0.025],
+    [/opus-5-5/, 0.05],
+];
+/**
+ * Cache config for one model. An explicit PROFCLAW_CACHE_READ_MULTIPLIER always wins,
+ * otherwise the model's documented read multiplier applies.
+ */
+export function getCacheConfigForModel(model, env = process.env) {
+    const base = getPromptCacheConfig(env);
+    if ((env['PROFCLAW_CACHE_READ_MULTIPLIER'] ?? '').trim() !== '')
+        return base;
+    const match = MODEL_READ_MULTIPLIERS.find(([pattern]) => pattern.test(model));
+    return match ? { ...base, readMultiplier: match[1] } : base;
+}
+function cacheProviderOptions(config) {
+    return {
+        anthropic: {
+            cacheControl: config.ttl === '1h' ? { type: 'ephemeral', ttl: '1h' } : { type: 'ephemeral' },
+        },
+    };
+}
+/**
+ * Add cache breakpoints to the leading system block: one on the first system message
+ * (the stable prompt) and one on the last leading system message. Callers put volatile
+ * per-request context in a later system message so the first breakpoint still hits
+ * across requests. History after the system block stays outside the cached prefix.
+ * Returns a new array; inputs are not mutated.
+ */
+export function applyAnthropicMessageCache(messages, provider, config = getPromptCacheConfig()) {
+    if (provider !== 'anthropic' || !config.enabled)
+        return messages;
+    let lastSystem = -1;
+    for (let i = 0; i < messages.length && messages[i].role === 'system'; i++) {
+        lastSystem = i;
+    }
+    if (lastSystem < 0)
+        return messages;
+    return messages.map((msg, i) => i === 0 || i === lastSystem
+        ? { ...msg, providerOptions: { ...msg.providerOptions, ...cacheProviderOptions(config) } }
+        : msg);
+}
+/**
+ * Return tools in a deterministic (name-sorted) order with a cache breakpoint on the
+ * last one. Object key order in the request body affects the prefix bytes, so sorting
+ * keeps the tool block byte-stable across steps and sessions.
+ */
+export function applyAnthropicToolCache(tools, provider, config = getPromptCacheConfig()) {
+    if (provider !== 'anthropic' || !config.enabled)
+        return tools;
+    const names = Object.keys(tools).sort();
+    if (names.length === 0)
+        return tools;
+    const sorted = {};
+    names.forEach((name, i) => {
+        const def = tools[name];
+        sorted[name] = i === names.length - 1
+            ? { ...def, providerOptions: { ...def.providerOptions, ...cacheProviderOptions(config) } }
+            : def;
+    });
+    return sorted;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function rec(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+/**
+ * Normalize AI SDK usage (v6 shape, legacy promptTokens shape, or raw provider
+ * counters) into total prompt tokens plus cache read/write counts.
+ * In AI SDK v6, inputTokens already includes cached reads and writes.
+ */
+export function extractCacheUsage(usage) {
+    const u = rec(usage);
+    if (!u)
+        return { promptTokens: 0, completionTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+    const details = rec(u['inputTokenDetails']);
+    const raw = rec(u['raw']);
+    const cacheReadTokens = num(details?.['cacheReadTokens']) ??
+        num(u['cachedInputTokens']) ??
+        num(raw?.['cache_read_input_tokens']) ??
+        num(rec(raw?.['prompt_tokens_details'])?.['cached_tokens']) ??
+        0;
+    const cacheWriteTokens = num(details?.['cacheWriteTokens']) ??
+        num(raw?.['cache_creation_input_tokens']) ??
+        0;
+    return {
+        promptTokens: num(u['inputTokens']) ?? num(u['promptTokens']) ?? 0,
+        completionTokens: num(u['outputTokens']) ?? num(u['completionTokens']) ?? 0,
+        cacheReadTokens,
+        cacheWriteTokens,
+    };
+}
+/**
+ * Sum usage across multi-step runs (tokens plus cache read/write). Falls back to
+ * `fallback` (the run-level usage) when there are no per-step usages, because
+ * result.usage only reflects the last step in AI SDK v6.
+ */
+export function aggregateStepUsage(steps, fallback) {
+    const usages = Array.isArray(steps)
+        ? steps.map((s) => rec(s)?.['usage']).filter((u) => u !== undefined && u !== null)
+        : [];
+    if (usages.length === 0)
+        return extractCacheUsage(fallback);
+    const total = { promptTokens: 0, completionTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+    for (const usage of usages) {
+        const u = extractCacheUsage(usage);
+        total.promptTokens += u.promptTokens;
+        total.completionTokens += u.completionTokens;
+        total.cacheReadTokens += u.cacheReadTokens;
+        total.cacheWriteTokens += u.cacheWriteTokens;
+    }
+    return total;
+}
+/**
+ * Input cost in USD for a prompt that may include cached tokens.
+ * Uncached tokens bill at the base rate, reads and writes at the multiplied rate.
+ */
+export function calculateCachedInputCost(promptTokens, cacheReadTokens, cacheWriteTokens, inputRatePer1M, config = getPromptCacheConfig()) {
+    const cached = cacheReadTokens + cacheWriteTokens;
+    const uncached = Math.max(0, promptTokens - cached);
+    const effective = uncached +
+        cacheReadTokens * config.readMultiplier +
+        cacheWriteTokens * config.writeMultiplier;
+    return (effective / 1_000_000) * inputRatePer1M;
+}
+/** Fraction of prompt tokens served from cache (0 when there were no prompt tokens). */
+export function cacheHitRate(cacheReadTokens, promptTokens) {
+    return promptTokens > 0 ? Math.min(1, cacheReadTokens / promptTokens) : 0;
+}
+//# sourceMappingURL=prompt-cache.js.map

package/dist/providers/smart-router.js

@@ -328,9 +328,17 @@ function getCandidatesForTier(tier, availableProviders, signals) {
     });
     // Sort by tier strategy
     switch (tier) {
-        case 'trivial':
-            // Cheapest first (total cost = input + output rate)
-            return eligible.sort((a, b) => (a.costPer1MInput + a.costPer1MOutput) - (b.costPer1MInput + b.costPer1MOutput));
+        case 'trivial': {
+            // Cheapest first (total cost = input + output rate). Ties (e.g. several free local
+            // models) prefer the configured free trivial model (default Gemma 4 via Ollama).
+            const preferred = process.env['SMART_ROUTER_TRIVIAL_PREFERRED_MODEL'] ?? 'gemma4:e4b';
+            return eligible.sort((a, b) => {
+                const diff = (a.costPer1MInput + a.costPer1MOutput) - (b.costPer1MInput + b.costPer1MOutput);
+                if (diff !== 0)
+                    return diff;
+                return Number(b.id === preferred) - Number(a.id === preferred);
+            });
+        }
         case 'standard':
             // Best value: capability (context * tool support) per dollar
             return eligible.sort((a, b) => {

package/dist/routes/chat.js

@@ -53,6 +53,17 @@ let getSessionModel;
 let streamAgenticChat;
 let getGroupChatManager;
 let trackChatUsage;
+/** Best-effort removal of spilled tool-result temp files at request end. */
+async function disposeToolHandler(handler) {
+    try {
+        await handler.dispose?.();
+    }
+    catch (error) {
+        logger.warn("[Chat] Tool handler dispose failed", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 async function ensureChatRuntime() {
     if (!chatRuntimePromise) {
         chatRuntimePromise = Promise.all([
@@ -220,7 +231,10 @@ chatRoutes.post("/send", chatRateLimiter, contentFilter(), zValidator("json", z.
         // Track token usage for cost dashboard
         if (response.usage?.totalTokens && response.model) {
             await ensureChatRuntime();
-            trackChatUsage(response.model, response.usage.totalTokens, response.usage.promptTokens, response.usage.completionTokens);
+            trackChatUsage(response.model, response.usage.totalTokens, response.usage.promptTokens, response.usage.completionTokens, {
+                cacheReadTokens: response.usage.cacheReadTokens,
+                cacheWriteTokens: response.usage.cacheWriteTokens,
+            });
         }
         return c.json({
             id: response.id,
@@ -1297,6 +1311,7 @@ chatRoutes.post("/conversations/:id/messages/with-tools", chatRateLimiter, conte
         });
         // Get any pending approvals
         const pendingApprovals = toolHandler.getPendingApprovals();
+        await disposeToolHandler(toolHandler);
         const inferToolCallStatus = (result) => {
             if (!result || typeof result !== "object") {
                 return "success";
@@ -1519,6 +1534,7 @@ chatRoutes.post("/with-tools", zValidator("json", z.object({
         });
         // Check for pending approvals
         const pendingApprovals = toolHandler.getPendingApprovals();
+        await disposeToolHandler(toolHandler);
         return c.json({
             id: response.id,
             conversationId,
@@ -1787,10 +1803,8 @@ chatRoutes.post("/conversations/:id/messages/agentic", chatRateLimiter, contentF
                             : undefined,
                         toolCalls: collectedToolCalls.length > 0 ? collectedToolCalls : undefined,
                     });
-                    // Track in-memory usage for cost dashboard
-                    if (totalTokens > 0 && finalModel) {
-                        trackChatUsage(finalModel, totalTokens, inputTokensTotal, outputTokensTotal);
-                    }
+                    // Cost tracking for agentic runs happens per step inside AgentExecutor;
+                    // tracking totals here as well would double count.
                     // Send final saved message event
                     await stream.write(`data: ${JSON.stringify({
                         type: "message_saved",
@@ -1812,6 +1826,9 @@ chatRoutes.post("/conversations/:id/messages/agentic", chatRateLimiter, contentF
                     timestamp: Date.now(),
                 })}\n\n`);
             }
+            finally {
+                await disposeToolHandler(toolHandler);
+            }
         });
     }
     catch (error) {

package/dist/server.js

@@ -805,6 +805,9 @@ async function main() {
     const { initTokenTracker } = await import('./costs/token-tracker.js');
     initTokenTracker();
     appLog.info('Token tracker initialized');
+    // Sweep stale tool-result temp dirs left by crashed runs (fire-and-forget)
+    const { ResultStore } = await import('./agents/result-store.js');
+    void ResultStore.sweepStale();
     // Initialize agents from config
     const { getAgentRegistry } = await import('./adapters/registry.js');
     const registry = getAgentRegistry();