modelmix 4.7.4 → 5.0.1

package/index.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const ejs = require('ejs');
 const fileType = require('file-type');
 const detectFileTypeFromBuffer = fileType.fileTypeFromBuffer || fileType.fromBuffer;
 const { inspect } = require('util');
@@ -24,7 +25,9 @@ const {
     normalizeEffort,
     applyUnifiedEffort,
     resolveProviderFamily,
-    resolveGrok420ModelKey
+    resolveGrok420ModelKey,
+    GROK420_REASONING,
+    GROK420_NON_REASONING
 } = require('./effort');
 
 const DEFAULT_RETRYABLE_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504, 529];
@@ -37,102 +40,319 @@ function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-// Pricing per 1M tokens: [input, output] in USD
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
+function normalizeContentCache(cache) {
+    if (cache !== undefined) {
+        if (!isPlainObject(cache) || cache.breakpoint !== true) {
+            throw new TypeError('cache must be { breakpoint: true }.');
+        }
+        return { breakpoint: true };
+    }
+    return undefined;
+}
+
+function stripContentCacheMetadata(content) {
+    if (!content || typeof content !== 'object') return content;
+    const sanitized = { ...content };
+    delete sanitized.cache;
+    delete sanitized.cache_control;
+    delete sanitized.prompt_cache_breakpoint;
+    return sanitized;
+}
+
+function hasNeutralCacheBreakpoint(messages = []) {
+    return messages.some(message => Array.isArray(message?.content)
+        && message.content.some(block => block?.cache?.breakpoint === true));
+}
+
+function validateTemplateData(value) {
+    if (!isPlainObject(value)) {
+        throw new TypeError('Template data must be a plain non-null object.');
+    }
+    if (Object.prototype.hasOwnProperty.call(value, '$mix')) {
+        throw new TypeError('Template data key "$mix" is reserved.');
+    }
+}
+
+function validateTemplateDataKey(key) {
+    if (typeof key !== 'string' || key.length === 0) {
+        throw new TypeError('Template data key must be a non-empty string.');
+    }
+    if (key === '$mix') {
+        throw new TypeError('Template data key "$mix" is reserved.');
+    }
+}
+
+function templateLocation({ filename, label }, lineNumber) {
+    return `${filename || label} at line ${lineNumber}`;
+}
+
+function preprocessChoiceDirectives(source, { filename = null, label = 'template' } = {}) {
+    const parts = source.split(/(\r\n|\n|\r)/);
+    const blocks = [];
+
+    for (let index = 0; index < parts.length; index += 2) {
+        const line = parts[index];
+        const trimmed = line.trim();
+        const lineNumber = (index / 2) + 1;
+        const location = templateLocation({ filename, label }, lineNumber);
+        const newline = parts[index + 1] || '';
+
+        if (/^<%\s*choice\s*%>$/.test(trimmed)) {
+            const parent = blocks[blocks.length - 1];
+            if (parent && parent.optionCount === 0) {
+                throw new Error(`A nested choice must be inside an option (${location}).`);
+            }
+            blocks.push({ lineNumber, optionCount: 0, weighted: null });
+            parts[index] = '<% $mix.choice(option => { -%>';
+            continue;
+        }
+
+        const optionMatch = trimmed.match(/^<%\s*option(?:\s+(.+?))?\s*%>$/);
+        if (optionMatch) {
+            const block = blocks[blocks.length - 1];
+            if (!block) {
+                throw new Error(`Option directive must be inside a choice (${location}).`);
+            }
+
+            const weightText = optionMatch[1];
+            const weighted = weightText !== undefined;
+            if (block.weighted !== null && block.weighted !== weighted) {
+                throw new Error(`Choice options must either all have weights or all omit them (${location}).`);
+            }
+
+            let argument = '';
+            if (weighted) {
+                const weight = Number(weightText);
+                if (!Number.isFinite(weight) || weight <= 0) {
+                    throw new Error(`Choice weight must be a positive finite number (${location}).`);
+                }
+                argument = `${weight}, `;
+            }
+
+            block.weighted = weighted;
+            parts[index] = `<% ${block.optionCount > 0 ? '}); ' : ''}option(${argument}() => { -%>`;
+            block.optionCount += 1;
+            continue;
+        }
+
+        if (/^<%\s*\/choice\s*%>$/.test(trimmed)) {
+            const block = blocks.pop();
+            if (!block) {
+                throw new Error(`Closing choice directive has no matching opening directive (${location}).`);
+            }
+            if (block.optionCount === 0) {
+                throw new Error(`Choice must contain at least one option (${location}).`);
+            }
+            parts[index] = '<% }); }); -%>';
+            continue;
+        }
+
+        if (/^<%\s*(?:choice|option|\/choice)(?:\s|%>)/.test(trimmed)) {
+            throw new Error(`Invalid choice directive (${location}).`);
+        }
+
+        const block = blocks[blocks.length - 1];
+        if (block && block.optionCount === 0) {
+            if (trimmed) {
+                throw new Error(`Choice content must be inside an option (${location}).`);
+            }
+            parts[index] = '<%# -%>';
+        }
+
+        if (newline) parts[index + 1] = newline;
+    }
+
+    if (blocks.length > 0) {
+        const block = blocks[blocks.length - 1];
+        throw new Error(`Unclosed choice directive (${templateLocation({ filename, label }, block.lineNumber)}).`);
+    }
+
+    return parts.join('');
+}
+
+function createTemplateRenderContext(random = Math.random) {
+    const choice = defineOptions => {
+        if (typeof defineOptions !== 'function') {
+            throw new TypeError('$mix.choice expects an option definition callback.');
+        }
+
+        const options = [];
+        let weighted = null;
+        const option = (weightOrRender, renderOption) => {
+            const hasWeight = renderOption !== undefined;
+            const weight = hasWeight ? weightOrRender : 1;
+            const render = hasWeight ? renderOption : weightOrRender;
+
+            if (weighted !== null && weighted !== hasWeight) {
+                throw new TypeError('$mix.choice options cannot mix weighted and unweighted forms.');
+            }
+            if (!Number.isFinite(weight) || weight <= 0) {
+                throw new TypeError('$mix.choice weights must be positive finite numbers.');
+            }
+            if (typeof render !== 'function') {
+                throw new TypeError('$mix.choice options require a render callback.');
+            }
+
+            weighted = hasWeight;
+            options.push({ weight, render });
+        };
+
+        defineOptions(option);
+        if (options.length === 0) {
+            throw new Error('$mix.choice requires at least one option.');
+        }
+
+        const totalWeight = options.reduce((sum, current) => sum + current.weight, 0);
+        if (!Number.isFinite(totalWeight)) {
+            throw new TypeError('$mix.choice total weight must be finite.');
+        }
+
+        let target = random() * totalWeight;
+        for (const current of options) {
+            target -= current.weight;
+            if (target < 0) return current.render();
+        }
+        return options[options.length - 1].render();
+    };
+
+    return {
+        helpers: Object.freeze({ choice }),
+        renderedTemplateData: new Map(),
+        renderedMessages: new Map(),
+        renderedSystems: new Map()
+    };
+}
+
+function configForDebug(config) {
+    const safeConfig = { ...config };
+    delete safeConfig.apiKey;
+    delete safeConfig.debug;
+    return safeConfig;
+}
+
+function redactSecret(value, secret, seen = new WeakSet()) {
+    if (!secret) return value;
+    if (typeof value === 'string') return value.split(secret).join('[REDACTED]');
+    if (!value || typeof value !== 'object') return value;
+    if (seen.has(value)) return '[Circular]';
+
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map(item => redactSecret(item, secret, seen));
+    }
+    return Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [key, redactSecret(item, secret, seen)])
+    );
+}
+
+// Pricing per 1M tokens in USD
 // Based on provider pricing pages linked in README
+const GPT56_LONG_CONTEXT_PRICING = Object.freeze({
+    inputThreshold: 272_000,
+    inputMultiplier: 2,
+    outputMultiplier: 1.5
+});
+
 const MODEL_PRICING = {
     // OpenAI
-    'gpt-realtime-mini': [0.60, 2.40],
-    'gpt-realtime': [4.00, 16.00],
-    'gpt-5.6-sol': [5.00, 30.00],
-    'gpt-5.6-terra': [2.00, 12.00],
-    'gpt-5.6-luna': [0.20, 1.20],
-    'gpt-5.5-pro': [30.00, 180.00],
-    'gpt-5.5': [5.00, 30.00],
-    'gpt-5.4': [2.50, 15.00],
-    'gpt-5.4-pro': [30, 180.00],
-    'gpt-5.4-mini': [0.75, 4.50],
-    'gpt-5.4-nano': [0.20, 1.25],
-    'gpt-5.3-codex': [1.75, 14.00],
-    'gpt-5.2': [1.75, 14.00],
-    'gpt-5.2-chat-latest': [1.75, 14.00],
-    'gpt-5.1': [1.25, 10.00],
-    'gpt-5': [1.25, 10.00],
-    'gpt-5-mini': [0.25, 2.00],
-    'gpt-5-nano': [0.05, 0.40],
-    'gpt-4.1': [2.00, 8.00],
-    'gpt-4.1-mini': [0.40, 1.60],
-    'gpt-4.1-nano': [0.10, 0.40],
+    'gpt-realtime-mini': { input: 0.60, cachedInput: 0.06, output: 2.40 },
+    'gpt-realtime': { input: 4.00, cachedInput: 0.40, output: 16.00 },
+    'gpt-5.6-sol': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, output: 30.00, longContext: GPT56_LONG_CONTEXT_PRICING },
+    'gpt-5.6-terra': { input: 2.00, cachedInput: 0.20, cacheWrite: 2.50, output: 12.00, longContext: GPT56_LONG_CONTEXT_PRICING },
+    'gpt-5.6-luna': { input: 0.20, cachedInput: 0.02, cacheWrite: 0.25, output: 1.20, longContext: GPT56_LONG_CONTEXT_PRICING },
+    'gpt-5.5-pro': { input: 30.00, output: 180.00 },
+    'gpt-5.5': { input: 5.00, cachedInput: 0.50, output: 30.00 },
+    'gpt-5.4': { input: 2.50, cachedInput: 0.25, output: 15.00 },
+    'gpt-5.4-pro': { input: 30.00, output: 180.00 },
+    'gpt-5.4-mini': { input: 0.75, cachedInput: 0.075, output: 4.50 },
+    'gpt-5.4-nano': { input: 0.20, cachedInput: 0.02, output: 1.25 },
+    'gpt-5.3-codex': { input: 1.75, cachedInput: 0.175, output: 14.00 },
+    'gpt-5.2': { input: 1.75, cachedInput: 0.175, output: 14.00 },
+    'gpt-5.2-chat-latest': { input: 1.75, cachedInput: 0.175, output: 14.00 },
+    'gpt-5.1': { input: 1.25, cachedInput: 0.125, output: 10.00 },
+    'gpt-5': { input: 1.25, cachedInput: 0.125, output: 10.00 },
+    'gpt-5-mini': { input: 0.25, cachedInput: 0.025, output: 2.00 },
+    'gpt-5-nano': { input: 0.05, cachedInput: 0.005, output: 0.40 },
+    'gpt-4.1': { input: 2.00, cachedInput: 0.50, output: 8.00 },
+    'gpt-4.1-mini': { input: 0.40, cachedInput: 0.10, output: 1.60 },
+    'gpt-4.1-nano': { input: 0.10, cachedInput: 0.025, output: 0.40 },
     // gptOss (Together/Groq/Cerebras/OpenRouter)
-    'openai/gpt-oss-120b': [0.15, 0.60],
-    'gpt-oss-120b': [0.15, 0.60],
-    'openai/gpt-oss-120b:free': [0, 0],
+    'openai/gpt-oss-120b': { input: 0.15, output: 0.60 },
+    'gpt-oss-120b': { input: 0.15, output: 0.60 },
+    'openai/gpt-oss-120b:free': { input: 0, output: 0 },
     // Anthropic
-    'claude-fable-5': [10.00, 50.00],
-    'claude-opus-5': [5.00, 25.00],
-    'claude-sonnet-5': [3.00, 15.00],
-    'claude-opus-4-8': [5.00, 25.00],
-    'claude-opus-4-7': [5.00, 25.00],
-    'claude-opus-4-6': [5.00, 25.00],
-    'claude-sonnet-4-6': [3.00, 15.00],
-    'claude-sonnet-4-5-20250929': [3.00, 15.00],
-    'claude-haiku-4-5-20251001': [1.00, 5.00],
+    'claude-fable-5': { input: 10.00, cachedInput: 1.00, cacheWrite: 12.50, cacheWrite1h: 20.00, output: 50.00 },
+    'claude-opus-5': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-sonnet-5': { input: 3.00, cachedInput: 0.30, cacheWrite: 3.75, cacheWrite1h: 6.00, output: 15.00 },
+    'claude-opus-4-8': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-opus-4-7': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-opus-4-6': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-sonnet-4-6': { input: 3.00, cachedInput: 0.30, cacheWrite: 3.75, cacheWrite1h: 6.00, output: 15.00 },
+    'claude-sonnet-4-5-20250929': { input: 3.00, cachedInput: 0.30, cacheWrite: 3.75, cacheWrite1h: 6.00, output: 15.00 },
+    'claude-haiku-4-5-20251001': { input: 1.00, cachedInput: 0.10, cacheWrite: 1.25, cacheWrite1h: 2.00, output: 5.00 },
     // Google
-    'gemini-3.1-pro-preview':[2.00, 12.00],
-    'gemini-3-pro-preview': [2.00, 12.00],
-    'gemini-3-flash-preview': [0.50, 3.00],
-    'gemini-3.6-flash': [1.50, 7.50],
-    'gemini-3.5-flash': [0.75, 4.50],
-    'gemini-3.5-flash-lite': [0.30, 2.50],
-    'gemini-2.5-pro': [1.25, 10.00],
-    'gemini-2.5-flash': [0.30, 2.50],
-    'gemini-3.1-flash-lite-preview': [0.25, 1.50],
+    'gemini-3.1-pro-preview': { input: 2.00, output: 12.00 },
+    'gemini-3-pro-preview': { input: 2.00, output: 12.00 },
+    'gemini-3-flash-preview': { input: 0.50, output: 3.00 },
+    'gemini-3.6-flash': { input: 1.50, output: 7.50 },
+    'gemini-3.5-flash': { input: 0.75, output: 4.50 },
+    'gemini-3.5-flash-lite': { input: 0.30, output: 2.50 },
+    'gemini-2.5-pro': { input: 1.25, output: 10.00 },
+    'gemini-2.5-flash': { input: 0.30, output: 2.50 },
+    'gemini-3.1-flash-lite-preview': { input: 0.25, output: 1.50 },
     // Grok
-    'grok-4.5': [2.00, 6.00],
-    'grok-4.3': [1.25, 2.50],
-    'grok-4.20-multi-agent-0309': [1.25, 2.50],
-    'grok-4.20-0309': [1.25, 2.50],
-    'grok-4.20-0309-reasoning': [1.25, 2.50],
-    'grok-4.20-0309-non-reasoning': [1.25, 2.50],
+    'grok-4.5': { input: 2.00, output: 6.00 },
+    'grok-4.3': { input: 1.25, output: 2.50 },
+    'grok-4.20-multi-agent-0309': { input: 1.25, output: 2.50 },
+    'grok-4.20-0309': { input: 1.25, output: 2.50 },
+    'grok-4.20-0309-reasoning': { input: 1.25, output: 2.50 },
+    'grok-4.20-0309-non-reasoning': { input: 1.25, output: 2.50 },
     // Fireworks
-    'accounts/fireworks/models/deepseek-v4-flash': [0.14, 0.28],
-    'accounts/fireworks/models/deepseek-v4-pro': [1.74, 3.48],
-    'deepseek-ai/DeepSeek-V4-Flash': [0.14, 0.28],
-    'deepseek-ai/DeepSeek-V4-Pro': [2.10, 4.40],
-    'deepseek/deepseek-v4-flash': [0.09, 0.18],
-    'accounts/fireworks/models/glm-4p7': [0.55, 2.19],
-    'accounts/fireworks/models/glm-5p1': [1.05, 3.50],
-    'zai-org/GLM-5.2': [1.40, 4.40],
-    'accounts/fireworks/models/kimi-k2p5': [0.50, 2.80],
-    'accounts/fireworks/models/qwen3p6-plus': [0.50, 3.00],
-    'Qwen/Qwen3.6-Plus': [0.50, 3.00],
-    'accounts/fireworks/models/qwen3p7-plus': [0.40, 1.60],
-    'qwen/qwen3.7-plus': [0.32, 1.28],
-    'qwen/qwen3.8-max': [2.00, 6.00],
+    'accounts/fireworks/models/deepseek-v4-flash': { input: 0.14, output: 0.28 },
+    'accounts/fireworks/models/deepseek-v4-pro': { input: 1.74, output: 3.48 },
+    'deepseek-ai/DeepSeek-V4-Flash': { input: 0.14, output: 0.28 },
+    'deepseek-ai/DeepSeek-V4-Pro': { input: 2.10, output: 4.40 },
+    'deepseek/deepseek-v4-flash': { input: 0.09, output: 0.18 },
+    'accounts/fireworks/models/glm-4p7': { input: 0.55, output: 2.19 },
+    'accounts/fireworks/models/glm-5p1': { input: 1.05, output: 3.50 },
+    'zai-org/GLM-5.2': { input: 1.40, output: 4.40 },
+    'accounts/fireworks/models/kimi-k2p5': { input: 0.50, output: 2.80 },
+    'accounts/fireworks/models/qwen3p6-plus': { input: 0.50, output: 3.00 },
+    'Qwen/Qwen3.6-Plus': { input: 0.50, output: 3.00 },
+    'accounts/fireworks/models/qwen3p7-plus': { input: 0.40, output: 1.60 },
+    'qwen/qwen3.7-plus': { input: 0.32, output: 1.28 },
+    'qwen/qwen3.8-max': { input: 2.00, output: 6.00 },
     // MiniMax
-    'MiniMax-M2.5': [0.30, 1.20],
-    'MiniMax-M2.7': [0.30, 1.20],
-    'MiniMax-M3': [0.30, 1.20],
-    'minimax/minimax-m2.7': [0.30, 1.20],
-    'minimax/minimax-m3': [0.30, 1.20],
-    'MiniMaxAI/MiniMax-M3': [0.30, 1.20],
+    'MiniMax-M2.5': { input: 0.30, output: 1.20 },
+    'MiniMax-M2.7': { input: 0.30, output: 1.20 },
+    'MiniMax-M3': { input: 0.30, output: 1.20 },
+    'minimax/minimax-m2.7': { input: 0.30, output: 1.20 },
+    'minimax/minimax-m3': { input: 0.30, output: 1.20 },
+    'MiniMaxAI/MiniMax-M3': { input: 0.30, output: 1.20 },
     // Perplexity
-    'sonar': [1.00, 1.00],
-    'sonar-pro': [3.00, 15.00],
+    'sonar': { input: 1.00, output: 1.00 },
+    'sonar-pro': { input: 3.00, output: 15.00 },
     // Hermes3 (Lambda/OpenRouter)
-    'Hermes-3-Llama-3.1-405B-FP8': [0.80, 0.80],
-    'nousresearch/hermes-3-llama-3.1-405b:free': [0, 0],
+    'Hermes-3-Llama-3.1-405B-FP8': { input: 0.80, output: 0.80 },
+    'nousresearch/hermes-3-llama-3.1-405b:free': { input: 0, output: 0 },
     // Qwen3 (Together/Cerebras)
-    'Qwen/Qwen3-235B-A22B-fp8-tput': [0.20, 0.60],
-    'qwen-3-32b': [0.20, 0.60],
+    'Qwen/Qwen3-235B-A22B-fp8-tput': { input: 0.20, output: 0.60 },
+    'qwen-3-32b': { input: 0.20, output: 0.60 },
     // Kimi K2.5 (Together/Fireworks/OpenRouter)
-    'moonshotai/Kimi-K2.5': [0.50, 2.80],
-    'moonshotai/kimi-k2.5': [0.50, 2.80],
+    'moonshotai/Kimi-K2.5': { input: 0.50, output: 2.80 },
+    'moonshotai/kimi-k2.5': { input: 0.50, output: 2.80 },
     // Kimi K3
-    'kimi-k3': [3.00, 15.00],
-    'moonshotai/kimi-k3': [3.00, 15.00],
+    'kimi-k3': { input: 3.00, output: 15.00 },
+    'moonshotai/kimi-k3': { input: 3.00, output: 15.00 },
     // GLM 4.7 (OpenRouter/Cerebras)
-    'z-ai/glm-4.7': [0.55, 2.19],
-    'zai-glm-4.7': [0.55, 2.19],
+    'z-ai/glm-4.7': { input: 0.55, output: 2.19 },
+    'zai-glm-4.7': { input: 0.55, output: 2.19 },
 };
 
 class ModelMix {
@@ -144,6 +364,8 @@ class ModelMix {
         this.toolClient = {};
         this.mcp = {};
         this.mcpToolsManager = new MCPToolsManager();
+        this.templateFileAssignments = new Map();
+        this.messageTemplates = new WeakMap();
         this.lastRaw = null;
         this.options = {
             max_tokens: 8192,
@@ -172,6 +394,13 @@ class ModelMix {
             roundRobin: false, // false=fallback mode, true=round robin rotation
             ...config
         };
+        this.systemTemplate = {
+            source: this.config.system,
+            filename: null
+        };
+        if (this.config.templateData !== undefined) {
+            validateTemplateData(this.config.templateData);
+        }
         // Unified effort is ModelMix policy (config.effort / .effort()), not a native option.
         if (this.config.effort !== undefined && this.config.effort !== null) {
             this.config.effort = normalizeEffort(this.config.effort);
@@ -183,11 +412,20 @@ class ModelMix {
 
     }
 
-    replace(keyValues) {
-        this.config.replace = { ...this.config.replace, ...keyValues };
+    assign(keyValues) {
+        validateTemplateData(keyValues);
+        for (const key of Object.keys(keyValues)) {
+            this.templateFileAssignments.delete(key);
+        }
+        this.config.templateData = { ...this.config.templateData, ...keyValues };
         return this;
     }
 
+    assignKey(key, value) {
+        validateTemplateDataKey(key);
+        return this.assign({ [key]: value });
+    }
+
     /**
      * Set unified reasoning effort: -1 (adaptive) or 0..100.
      * Stored in config.effort; mapped to provider-native fields at request time
@@ -203,11 +441,19 @@ class ModelMix {
     }
 
     new({ options = {}, config = {}, mix = {} } = {}) {
+        const hasSystemOverride = Object.prototype.hasOwnProperty.call(config, 'system');
         const instance = new ModelMix({
             options: { ...this.options, ...options },
             config: { ...this.config, ...config },
             mix: { ...this.mix, ...mix }
         });
+        if (!hasSystemOverride) {
+            instance.systemTemplate = { ...this.systemTemplate };
+        }
+        instance.templateFileAssignments = new Map(this.templateFileAssignments);
+        for (const key of Object.keys(config.templateData || {})) {
+            instance.templateFileAssignments.delete(key);
+        }
         instance.models = this.models; // Share models array for round-robin rotation
         return instance;
     }
@@ -238,20 +484,163 @@ class ModelMix {
         return str.length > maxLen ? str.substring(0, maxLen) + '...' : str;
     }
 
-    static calculateCost(modelKey, tokens) {
+    static normalizeTokenUsage({ input = 0, output = 0, total, cached = 0, cacheWrite = 0, cacheWrite5m = 0, cacheWrite1h = 0 } = {}) {
+        const tokenCount = value => Number.isFinite(value) ? Math.max(0, value) : 0;
+        const normalizedInput = tokenCount(input);
+        const normalizedOutput = tokenCount(output);
+        const normalizedCached = tokenCount(cached);
+        const normalizedCacheWrite5m = tokenCount(cacheWrite5m);
+        const normalizedCacheWrite1h = tokenCount(cacheWrite1h);
+        const normalizedCacheWrite = Math.max(
+            tokenCount(cacheWrite),
+            normalizedCacheWrite5m + normalizedCacheWrite1h
+        );
+        const normalizedTotal = Number.isFinite(total)
+            ? Math.max(0, total)
+            : normalizedInput + normalizedOutput;
+        const uncachedInput = Math.max(0, normalizedInput - normalizedCached - normalizedCacheWrite);
+        const cacheHitRate = normalizedInput > 0
+            ? Number((normalizedCached / normalizedInput).toFixed(4))
+            : 0;
+
+        return {
+            input: normalizedInput,
+            output: normalizedOutput,
+            total: normalizedTotal,
+            cached: normalizedCached,
+            cacheWrite: normalizedCacheWrite,
+            cacheWrite5m: normalizedCacheWrite5m,
+            cacheWrite1h: normalizedCacheWrite1h,
+            uncachedInput,
+            cacheHitRate,
+            cacheSavings: 0,
+            cacheWritePremium: 0,
+            breakEvenHits: 0,
+            cost: 0,
+            costBreakdown: {
+                uncachedInput: 0,
+                cachedInput: 0,
+                cacheWrite: 0,
+                cacheWrite5m: 0,
+                cacheWrite1h: 0,
+                output: 0,
+                total: 0
+            }
+        };
+    }
+
+    static calculateCostBreakdown(modelKey, tokens) {
+        const pricing = MODEL_PRICING[modelKey];
+        if (!pricing) return ModelMix.normalizeTokenUsage().costBreakdown;
+
+        const normalized = ModelMix.normalizeTokenUsage(tokens);
+        const longContext = pricing.longContext;
+        const useLongContextRates = longContext && normalized.input > longContext.inputThreshold;
+        const inputMultiplier = useLongContextRates ? longContext.inputMultiplier : 1;
+        const outputMultiplier = useLongContextRates ? longContext.outputMultiplier : 1;
+        const {
+            input: inputPerMillion,
+            cachedInput: cachedInputPerMillion = inputPerMillion,
+            cacheWrite: cacheWritePerMillion = inputPerMillion,
+            cacheWrite1h: cacheWrite1hPerMillion = cacheWritePerMillion,
+            output: outputPerMillion
+        } = pricing;
+        const roundCost = value => Number(value.toFixed(12));
+        const genericCacheWrite = Math.max(
+            0,
+            normalized.cacheWrite - normalized.cacheWrite5m - normalized.cacheWrite1h
+        );
+        const cacheWrite5mCost = roundCost(
+            normalized.cacheWrite5m * cacheWritePerMillion * inputMultiplier / 1_000_000
+        );
+        const cacheWrite1hCost = roundCost(
+            normalized.cacheWrite1h * cacheWrite1hPerMillion * inputMultiplier / 1_000_000
+        );
+        const genericCacheWriteCost = roundCost(
+            genericCacheWrite * cacheWritePerMillion * inputMultiplier / 1_000_000
+        );
+        const breakdown = {
+            uncachedInput: roundCost(normalized.uncachedInput * inputPerMillion * inputMultiplier / 1_000_000),
+            cachedInput: roundCost(normalized.cached * cachedInputPerMillion * inputMultiplier / 1_000_000),
+            cacheWrite: roundCost(genericCacheWriteCost + cacheWrite5mCost + cacheWrite1hCost),
+            cacheWrite5m: cacheWrite5mCost,
+            cacheWrite1h: cacheWrite1hCost,
+            output: roundCost(normalized.output * outputPerMillion * outputMultiplier / 1_000_000)
+        };
+        breakdown.total = roundCost(
+            breakdown.uncachedInput
+            + breakdown.cachedInput
+            + breakdown.cacheWrite
+            + breakdown.output
+        );
+        return breakdown;
+    }
+
+    static calculateCacheMetrics(modelKey, tokens) {
         const pricing = MODEL_PRICING[modelKey];
-        if (!pricing) return null;
-        const [inputPerMillion, outputPerMillion] = pricing;
-        return (tokens.input * inputPerMillion / 1_000_000) + (tokens.output * outputPerMillion / 1_000_000);
+        const emptyMetrics = {
+            cacheSavings: 0,
+            cacheWritePremium: 0,
+            breakEvenHits: 0
+        };
+        if (!pricing) return emptyMetrics;
+
+        const normalized = ModelMix.normalizeTokenUsage(tokens);
+        const longContext = pricing.longContext;
+        const inputMultiplier = longContext && normalized.input > longContext.inputThreshold
+            ? longContext.inputMultiplier
+            : 1;
+        const cachedInputPerMillion = pricing.cachedInput ?? pricing.input;
+        const cacheWritePerMillion = pricing.cacheWrite ?? pricing.input;
+        const cacheWrite1hPerMillion = pricing.cacheWrite1h ?? cacheWritePerMillion;
+        const readSavingsPerMillion = Math.max(0, pricing.input - cachedInputPerMillion) * inputMultiplier;
+        const writePremiumPerMillion = Math.max(0, cacheWritePerMillion - pricing.input) * inputMultiplier;
+        const write1hPremiumPerMillion = Math.max(0, cacheWrite1hPerMillion - pricing.input) * inputMultiplier;
+        const roundCost = value => Number(value.toFixed(12));
+        const cacheSavings = roundCost(normalized.cached * readSavingsPerMillion / 1_000_000);
+        const genericCacheWrite = Math.max(
+            0,
+            normalized.cacheWrite - normalized.cacheWrite5m - normalized.cacheWrite1h
+        );
+        const cacheWritePremium = roundCost(
+            (
+                (genericCacheWrite + normalized.cacheWrite5m) * writePremiumPerMillion
+                + normalized.cacheWrite1h * write1hPremiumPerMillion
+            ) / 1_000_000
+        );
+        const fullHitSavings = normalized.cacheWrite * readSavingsPerMillion / 1_000_000;
+
+        return {
+            cacheSavings,
+            cacheWritePremium,
+            breakEvenHits: fullHitSavings > 0
+                ? Number((cacheWritePremium / fullHitSavings).toFixed(4))
+                : 0
+        };
+    }
+
+    static calculateCost(modelKey, tokens) {
+        if (!MODEL_PRICING[modelKey]) return null;
+        return ModelMix.calculateCostBreakdown(modelKey, tokens).total;
     }
 
     static extractCacheTokens(usage = {}) {
         return usage.input_tokens_details?.cached_tokens
-            || usage.prompt_tokens_details?.cached_tokens
-            || usage.cache_read_input_tokens
-            || usage.cachedContentTokenCount
-            || usage.cached_content_token_count
-            || 0;
+            ?? usage.prompt_tokens_details?.cached_tokens
+            ?? usage.cache_read_input_tokens
+            ?? usage.cachedContentTokenCount
+            ?? usage.cached_content_token_count
+            ?? 0;
+    }
+
+    static extractCacheWriteTokens(usage = {}) {
+        return usage.input_tokens_details?.cache_write_tokens
+            ?? usage.prompt_tokens_details?.cache_write_tokens
+            ?? usage.cache_creation_input_tokens
+            ?? usage.cache_write_input_tokens
+            ?? usage.cacheWriteTokenCount
+            ?? usage.cache_write_token_count
+            ?? 0;
     }
 
     static formatInputSummary(messages, system, debug = 2) {
@@ -385,12 +774,18 @@ class ModelMix {
         if (mix.openrouter) this.attach('openai/gpt-oss-120b:free', new MixOpenRouter({ options, config }));
         return this;
     }
-    fable5({ options = {}, config = {} } = {}) {
+    fable50({ options = {}, config = {} } = {}) {
         return this.attach('claude-fable-5', new MixAnthropic({ options, config }));
     }
-    opus5({ options = {}, config = {} } = {}) {
+    fable5(args = {}) {
+        return this.fable50(args);
+    }
+    opus50({ options = {}, config = {} } = {}) {
         return this.attach('claude-opus-5', new MixAnthropic({ options, config }));
     }
+    opus5(args = {}) {
+        return this.opus50(args);
+    }
     opus48({ options = {}, config = {} } = {}) {
         return this.attach('claude-opus-4-8', new MixAnthropic({ options, config }));
     }
@@ -400,9 +795,12 @@ class ModelMix {
     opus46({ options = {}, config = {} } = {}) {
         return this.attach('claude-opus-4-6', new MixAnthropic({ options, config }));
     }
-    sonnet5({ options = {}, config = {} } = {}) {
+    sonnet50({ options = {}, config = {} } = {}) {
         return this.attach('claude-sonnet-5', new MixAnthropic({ options, config }));
     }
+    sonnet5(args = {}) {
+        return this.sonnet50(args);
+    }
     sonnet46({ options = {}, config = {} } = {}) {
         return this.attach('claude-sonnet-4-6', new MixAnthropic({ options, config }));
     }
@@ -597,34 +995,54 @@ class ModelMix {
         return this;
     }
 
-    addText(text, { role = "user" } = {}) {
+    addText(text, { role = "user", cache } = {}) {
+        return this._addText(text, {
+            role,
+            cache: normalizeContentCache(cache),
+            template: { source: text, filename: null }
+        });
+    }
+
+    _addText(text, { role = "user", cache, template = null } = {}) {
         const content = [{
             type: "text",
-            text
+            text,
+            ...(cache !== undefined && { cache })
         }];
 
+        if (template) {
+            this.messageTemplates.set(content[0], template);
+        }
         this.messages.push({ role, content });
         return this;
     }
 
-    addTextFromFile(filePath, { role = "user" } = {}) {
-        const content = this.readFile(filePath);
-        this.addText(content, { role });
-        return this;
+    addTextFromFile(filePath, { role = "user", cache } = {}) {
+        const filename = path.resolve(filePath);
+        const content = this.readFile(filename);
+        return this._addText(content, {
+            role,
+            cache: normalizeContentCache(cache),
+            template: { source: content, filename }
+        });
     }
 
     setSystem(text) {
         this.config.system = text;
+        this.systemTemplate = { source: text, filename: null };
         return this;
     }
 
     setSystemFromFile(filePath) {
-        const content = this.readFile(filePath);
-        this.setSystem(content);
+        const filename = path.resolve(filePath);
+        const content = this.readFile(filename);
+        this.config.system = content;
+        this.systemTemplate = { source: content, filename };
         return this;
     }
 
-    addImageFromBuffer(buffer, { role = "user" } = {}) {
+    addImageFromBuffer(buffer, { role = "user", cache } = {}) {
+        const contentCache = normalizeContentCache(cache);
         this.messages.push({
             role,
             content: [{
@@ -632,19 +1050,21 @@ class ModelMix {
                 source: {
                     type: "buffer",
                     data: buffer
-                }
+                },
+                ...(contentCache !== undefined && { cache: contentCache })
             }]
         });
         return this;
     }
 
-    addImage(filePath, { role = "user" } = {}) {
+    addImage(filePath, { role = "user", cache } = {}) {
         const absolutePath = path.resolve(filePath);
 
         if (!fs.existsSync(absolutePath)) {
             throw new Error(`Image file not found: ${filePath}`);
         }
 
+        const contentCache = normalizeContentCache(cache);
         this.messages.push({
             role,
             content: [{
@@ -652,13 +1072,14 @@ class ModelMix {
                 source: {
                     type: "file",
                     data: filePath
-                }
+                },
+                ...(contentCache !== undefined && { cache: contentCache })
             }]
         });
         return this;
     }
 
-    addImageFromUrl(url, { role = "user" } = {}) {
+    addImageFromUrl(url, { role = "user", cache } = {}) {
         let source;
         if (url.startsWith('data:')) {
             // Parse data URL: data:image/jpeg;base64,/9j/4AAQ...
@@ -679,11 +1100,13 @@ class ModelMix {
             };
         }
 
+        const contentCache = normalizeContentCache(cache);
         this.messages.push({
             role,
             content: [{
                 type: "image",
-                source
+                source,
+                ...(contentCache !== undefined && { cache: contentCache })
             }]
         });
 
@@ -732,7 +1155,7 @@ class ModelMix {
 
                     // Update the content with processed image
                     message.content[j] = {
-                        type: "image",
+                        ...content,
                         source: {
                             type: "base64",
                             media_type: mimeType,
@@ -771,27 +1194,23 @@ class ModelMix {
             stream: false,
         }
 
-        // Apply template replacements to system before adding extra instructions
-        let systemWithReplacements = this._template(this.config.system, this.config.replace);
-
-        let config = {
-            system: systemWithReplacements,
-        }
+        let config = {};
+        let systemSuffix = '';
 
         if (schemaExample) {
             config.schema = generateJsonSchema(schemaExample, schemaDescription);
 
             if (addSchema) {
-                config.system += "\n\nOutput JSON Schema: \n```\n" + JSON.stringify(config.schema) + "\n```";
+                systemSuffix += "\n\nOutput JSON Schema: \n```\n" + JSON.stringify(config.schema) + "\n```";
             }
             if (addExample) {
-                config.system += "\n\nOutput JSON Example: \n```\n" + JSON.stringify(schemaExample) + "\n```";
+                systemSuffix += "\n\nOutput JSON Example: \n```\n" + JSON.stringify(schemaExample) + "\n```";
             }
             if (addNote) {
-                config.system += "\n\nOutput JSON Escape: double quotes, backslashes, and control characters inside JSON strings.\nEnsure the output contains no comments.";
+                systemSuffix += "\n\nOutput JSON Escape: double quotes, backslashes, and control characters inside JSON strings.\nEnsure the output contains no comments.";
             }
         }
-        const { message } = await this.execute({ options, config });
+        const { message } = await this.execute({ options, config, systemSuffix });
         const parsed = JSON.parse(this._extractBlock(message));
         return isArrayWrap ? parsed.out : parsed;
     }
@@ -802,17 +1221,13 @@ class ModelMix {
     }
 
     async block({ addSystemExtra = true } = {}) {
-        // Apply template replacements to system before adding extra instructions
-        let systemWithReplacements = this._template(this.config.system, this.config.replace);
-
-        let config = {
-            system: systemWithReplacements,
-        }
-
-        if (addSystemExtra) {
-            config.system += "\nReturn the result of the task between triple backtick block code tags ```";
-        }
-        const { message } = await this.execute({ options: { stream: false }, config });
+        const systemSuffix = addSystemExtra
+            ? "\nReturn the result of the task between triple backtick block code tags ```"
+            : '';
+        const { message } = await this.execute({
+            options: { stream: false },
+            systemSuffix
+        });
         return this._extractBlock(message);
     }
 
@@ -825,23 +1240,97 @@ class ModelMix {
         return this.execute({ options: { stream: true } });
     }
 
-    replaceKeyFromFile(key, filePath) {
-        try {
-            const content = this.readFile(filePath);
-            this.replace({ [key]: this._template(content, this.config.replace) });
-        } catch (error) {
-            // Gracefully handle file read errors without throwing
-            log.warn(`replaceKeyFromFile: ${error.message}`);
-        }
+    assignKeyFromFile(key, filePath) {
+        validateTemplateDataKey(key);
+        this.readFile(filePath);
+
+        const templateData = { ...this.config.templateData };
+        delete templateData[key];
+        this.config.templateData = templateData;
+        this.templateFileAssignments.set(key, Object.freeze({
+            key,
+            filename: path.resolve(filePath)
+        }));
         return this;
     }
 
-    _template(input, replace) {
-        if (!replace) return input;
-        for (const k in replace) {
-            input = input.split(/([¿?¡!,"';:\(\)\.\s])/).map(x => x === k ? replace[k] : x).join("");
+    _choiceRandom() {
+        return Math.random();
+    }
+
+    _templateData(renderContext) {
+        const assigned = { ...(this.config.templateData || {}), $mix: renderContext.helpers };
+        const data = { ...assigned };
+
+        for (const [key, assignment] of this.templateFileAssignments) {
+            data[key] = this._renderAssignedTemplate(assignment, assigned, renderContext);
+        }
+
+        return data;
+    }
+
+    _renderAssignedTemplate(assignment, data, renderContext) {
+        if (renderContext.renderedTemplateData.has(assignment)) {
+            return renderContext.renderedTemplateData.get(assignment);
+        }
+
+        const rendered = this._renderTemplateWithData(
+            `<%- include(${JSON.stringify(assignment.filename)}) %>`,
+            {
+                filename: assignment.filename,
+                label: `template data "${assignment.key}"`
+            },
+            data
+        );
+        renderContext.renderedTemplateData.set(assignment, rendered);
+        return rendered;
+    }
+
+    _renderTemplate(
+        source,
+        { filename = null, label = 'template' } = {},
+        renderContext = createTemplateRenderContext(() => this._choiceRandom())
+    ) {
+        return this._renderTemplateWithData(
+            source,
+            { filename, label },
+            this._templateData(renderContext)
+        );
+    }
+
+    _renderTemplateWithData(source, { filename = null, label = 'template' }, data) {
+        if (typeof source !== 'string') {
+            throw new TypeError(`${label} source must be a string.`);
+        }
+
+        try {
+            const template = preprocessChoiceDirectives(source, { filename, label });
+            return ejs.render(template, data, {
+                ...(filename && { filename }),
+                async: false,
+                cache: false,
+                compileDebug: true,
+                unsafePrototypeLocals: false,
+                includer: (originalPath, resolvedFilename) => {
+                    if (!resolvedFilename) {
+                        throw new Error(`Could not find the include file "${originalPath}"`);
+                    }
+                    const includedSource = fs.readFileSync(resolvedFilename, 'utf8').replace(/^\uFEFF/, '');
+                    return {
+                        filename: resolvedFilename,
+                        template: preprocessChoiceDirectives(includedSource, {
+                            filename: resolvedFilename,
+                            label: 'included template'
+                        })
+                    };
+                }
+            });
+        } catch (error) {
+            const location = filename ? ` ${filename}` : '';
+            const renderError = new Error(`Failed to render ${label}${location}: ${error.message}`);
+            renderError.cause = error;
+            throw renderError;
         }
-        return input;
     }
 
     static hasToolInteraction(message) {
@@ -873,37 +1362,56 @@ class ModelMix {
         }, []);
     }
 
-    applyTemplate() {
-        if (!this.config.replace) return;
-
-        this.config.system = this._template(this.config.system, this.config.replace);
-
-        this.messages = this.messages.map(message => {
-            if (message.content instanceof Array) {
-                message.content = message.content.map(content => {
-                    if (content.type === 'text') {
-                        content.text = this._template(content.text, this.config.replace);
+    _renderMessageSnapshot(messages, renderContext) {
+        return messages.map(message => ({
+            ...message,
+            content: Array.isArray(message.content)
+                ? message.content.map(content => {
+                    if (!content || typeof content !== 'object') return content;
+
+                    const snapshotContent = { ...content };
+                    const template = content.type === 'text'
+                        ? this.messageTemplates.get(content)
+                        : null;
+                    if (!template) return snapshotContent;
+
+                    let rendered = renderContext.renderedMessages.get(content)?.rendered;
+                    if (rendered === undefined) {
+                        rendered = this._renderTemplate(template.source, {
+                            filename: template.filename,
+                            label: 'message template'
+                        }, renderContext);
+                        renderContext.renderedMessages.set(content, { rendered, template });
                     }
-                    return content;
-                });
-            }
-            return message;
-        });
+                    snapshotContent.text = rendered;
+                    return snapshotContent;
+                })
+                : message.content
+        }));
+    }
+
+    _commitTemplateRenderContext(renderContext) {
+        for (const [content, { rendered, template }] of renderContext.renderedMessages) {
+            if (this.messageTemplates.get(content) !== template) continue;
+            content.text = rendered;
+            this.messageTemplates.delete(content);
+        }
     }
 
-    async prepareMessages() {
+    async prepareMessages(renderContext = createTemplateRenderContext(() => this._choiceRandom())) {
         await this.processImages();
-        this.applyTemplate();
+
+        let messages = this.messages;
 
         // Smart message slicing based on max_history:
         // 0 = no history (stateless), N = keep last N messages, -1 = unlimited
         if (this.config.max_history > 0) {
-            let sliceStart = Math.max(0, this.messages.length - this.config.max_history);
+            let sliceStart = Math.max(0, messages.length - this.config.max_history);
 
             // If we're slicing into the middle of a tool interaction,
             // backtrack to include the full sequence (user → assistant/tool_calls → tool results)
-            while (sliceStart > 0 && sliceStart < this.messages.length) {
-                const msg = this.messages[sliceStart];
+            while (sliceStart > 0 && sliceStart < messages.length) {
+                const msg = messages[sliceStart];
                 if (ModelMix.hasToolInteraction(msg)) {
                     sliceStart--;
                 } else {
@@ -911,13 +1419,13 @@ class ModelMix {
                 }
             }
 
-            this.messages = this.messages.slice(sliceStart);
+            this.messages = messages.slice(sliceStart);
+            messages = this.messages;
         }
         // max_history = -1: unlimited, no slicing
         // max_history = 0: no history, messages only contain what was added since last call
 
-        this.messages = this.groupByRoles(this.messages);
-        this.options.messages = this.messages;
+        return this.groupByRoles(this._renderMessageSnapshot(messages, renderContext));
     }
 
     readFile(filePath, { encoding = 'utf8' } = {}) {
@@ -935,15 +1443,30 @@ class ModelMix {
         }
     }
 
-    async execute({ config = {}, options = {} } = {}) {
+    _resolveSystemTemplate(config, providerConfig) {
+        if (Object.prototype.hasOwnProperty.call(config, 'system')) {
+            return { source: config.system, filename: null };
+        }
+        if (Object.prototype.hasOwnProperty.call(providerConfig, 'system')) {
+            return { source: providerConfig.system, filename: null };
+        }
+        if (this.config.system !== this.systemTemplate.source) {
+            return { source: this.config.system, filename: null };
+        }
+        return this.systemTemplate;
+    }
+
+    async execute({ config = {}, options = {}, systemSuffix = '', _templateContext = null } = {}) {
         if (!this.models || this.models.length === 0) {
             throw new Error("No models specified. Use methods like .gpt5(), .sonnet46() first.");
         }
 
-        return this.limiter.schedule(async () => {
-            await this.prepareMessages();
+        const isRootExecution = _templateContext === null;
+        const templateContext = _templateContext || createTemplateRenderContext(() => this._choiceRandom());
+        const execution = this.limiter.schedule(async () => {
+            const preparedMessages = await this.prepareMessages(templateContext);
 
-            if (this.messages.length === 0) {
+            if (preparedMessages.length === 0) {
                 throw new Error("No user messages have been added. Use addText(prompt), addTextFromFile(filePath), addImage(filePath), or addImageFromUrl(url) to add a prompt.");
             }
 
@@ -978,6 +1501,7 @@ class ModelMix {
                 // Create clean copies for each provider to avoid contamination
                 const currentOptions = {
                     ...this.options,
+                    messages: preparedMessages,
                     ...providerInstance.options,
                     ...optionsTools,
                     ...options,
@@ -994,6 +1518,18 @@ class ModelMix {
                         ...(config.retry || {})
                     }
                 };
+                const systemTemplate = this._resolveSystemTemplate(config, providerInstance.config);
+                const systemCacheKey = JSON.stringify([systemTemplate.filename, systemTemplate.source]);
+                if (!templateContext.renderedSystems.has(systemCacheKey)) {
+                    templateContext.renderedSystems.set(
+                        systemCacheKey,
+                        this._renderTemplate(systemTemplate.source, {
+                            filename: systemTemplate.filename,
+                            label: 'system template'
+                        }, templateContext)
+                    );
+                }
+                currentConfig.system = templateContext.renderedSystems.get(systemCacheKey) + systemSuffix;
 
                 // Grok 4.20 alias → reasoning / non-reasoning from unified effort
                 const resolvedModelKey = resolveGrok420ModelKey(
@@ -1018,7 +1554,7 @@ class ModelMix {
                     const header = `\n${prefix} [${providerName}:${resolvedModelKey}] #${originalIndex + 1}${suffix}`;
 
                     if (currentConfig.debug >= 2) {
-                        console.log(`${header}\n${ModelMix.formatInputSummary(this.messages, currentConfig.system, currentConfig.debug)}`);
+                        console.log(`${header}\n${ModelMix.formatInputSummary(preparedMessages, currentConfig.system, currentConfig.debug)}`);
                     } else {
                         console.log(header);
                     }
@@ -1072,7 +1608,16 @@ class ModelMix {
                     const elapsedMs = Date.now() - startTime;
 
                     if (result.tokens) {
-                        result.tokens.cost = ModelMix.calculateCost(resolvedModelKey, result.tokens);
+                        const normalizedTokens = ModelMix.normalizeTokenUsage(result.tokens);
+                        const costBreakdown = ModelMix.calculateCostBreakdown(resolvedModelKey, normalizedTokens);
+                        const cacheMetrics = ModelMix.calculateCacheMetrics(resolvedModelKey, normalizedTokens);
+                        result.tokens = {
+                            ...result.tokens,
+                            ...normalizedTokens,
+                            ...cacheMetrics,
+                            cost: MODEL_PRICING[resolvedModelKey] ? costBreakdown.total : 0,
+                            costBreakdown
+                        };
                         const elapsedSec = elapsedMs / 1000;
                         result.tokens.speed = elapsedSec > 0 ? Math.round(result.tokens.output / elapsedSec) : 0;
                     }
@@ -1091,7 +1636,7 @@ class ModelMix {
                                     }]
                                 });
                             } else {
-                                this.addText(result.message, { role: "assistant" });
+                                this._addText(result.message, { role: "assistant" });
                             }
                         }
 
@@ -1109,7 +1654,7 @@ class ModelMix {
                             });
                         }
 
-                        return this.execute({ options, config });
+                        return this.execute({ options, config, systemSuffix, _templateContext: templateContext });
                     }
 
                     // debug level 1: Just success indicator
@@ -1171,7 +1716,7 @@ class ModelMix {
                                 }]
                             });
                         } else {
-                            this.addText(result.message, { role: "assistant" });
+                            this._addText(result.message, { role: "assistant" });
                         }
                     }
 
@@ -1197,6 +1742,12 @@ class ModelMix {
             log.error("Fallback logic completed without success or throwing the final error.");
             throw lastError || new Error("Failed to get response from any model, and no specific error was caught.");
         });
+
+        if (!isRootExecution) return execution;
+
+        const result = await execution;
+        this._commitTemplateRenderContext(templateContext);
+        return result;
     }
 
     async processToolCalls(toolCalls) {
@@ -1397,6 +1948,13 @@ class MixCustom {
         return MixOpenAI.convertMessages(messages, config);
     }
 
+    sanitizeCacheOptions(options) {
+        delete options.cache_control;
+        delete options.prompt_cache_key;
+        delete options.prompt_cache_options;
+        delete options.prompt_cache_retention;
+    }
+
     static stripContentTypeHeader(headers = {}) {
         return stripContentTypeHeader(headers);
     }
@@ -1411,6 +1969,7 @@ class MixCustom {
 
     async create({ config = {}, options = {} } = {}) {
         try {
+            this.sanitizeCacheOptions(options);
             if (Array.isArray(options.messages)) {
                 options.messages = this.convertMessages(options.messages, config);
             }
@@ -1422,9 +1981,7 @@ class MixCustom {
                 console.log('\n[REQUEST DETAILS]');
 
                 console.log('\n[CONFIG]');
-                const configToLog = { ...config };
-                delete configToLog.debug;
-                console.log(ModelMix.formatJSON(configToLog));
+                console.log(ModelMix.formatJSON(configForDebug(config)));
 
                 console.log('\n[OPTIONS]');
                 console.log(ModelMix.formatJSON(request.options));
@@ -1444,11 +2001,11 @@ class MixCustom {
                 }));
             }
         } catch (error) {
-            throw this.handleError(error, { config, options });
+            throw this.handleError(error);
         }
     }
 
-    handleError(error, { config, options }) {
+    handleError(error) {
         let errorMessage = 'An error occurred in MixCustom';
         let statusCode = null;
         let errorDetails = null;
@@ -1462,12 +2019,10 @@ class MixCustom {
         }
 
         const formattedError = {
-            message: errorMessage,
+            message: redactSecret(errorMessage, this.config.apiKey),
             statusCode,
-            details: errorDetails,
-            stack: error.stack,
-            config: config,
-            options: options
+            details: redactSecret(errorDetails, this.config.apiKey),
+            stack: redactSecret(error.stack, this.config.apiKey)
         };
 
         return formattedError;
@@ -1586,19 +2141,15 @@ class MixCustom {
     static extractTokens(data) {
         // OpenAI/Groq/Together/Lambda/Cerebras/Fireworks format
         if (data.usage) {
-            return {
+            return ModelMix.normalizeTokenUsage({
                 input: data.usage.prompt_tokens || 0,
                 output: data.usage.completion_tokens || 0,
-                total: data.usage.total_tokens || 0,
-                cached: ModelMix.extractCacheTokens(data.usage)
-            };
+                total: data.usage.total_tokens,
+                cached: ModelMix.extractCacheTokens(data.usage),
+                cacheWrite: ModelMix.extractCacheWriteTokens(data.usage)
+            });
         }
-        return {
-            input: 0,
-            output: 0,
-            total: 0,
-            cached: 0
-        };
+        return ModelMix.normalizeTokenUsage();
     }
 
     processResponse(response) {
@@ -1617,6 +2168,11 @@ class MixCustom {
 }
 
 class MixOpenAI extends MixCustom {
+    sanitizeCacheOptions(options) {
+        delete options.cache_control;
+        delete options.prompt_cache_options;
+    }
+
     getDefaultConfig(customConfig) {
 
         if (!process.env.OPENAI_API_KEY) {
@@ -1690,22 +2246,26 @@ class MixOpenAI extends MixCustom {
                 continue;
             }
 
+            let convertedMessage = { ...message };
             if (Array.isArray(message.content)) {
-                message.content = message.content.filter(content => content !== null && content !== undefined).map(content => {
-                    if (content && content.type === 'image') {
-                        const { media_type, data } = content.source;
-                        return {
-                            type: 'image_url',
-                            image_url: {
-                                url: `data:${media_type};base64,${data}`
-                            }
-                        };
-                    }
-                    return content;
-                });
+                convertedMessage = {
+                    ...message,
+                    content: message.content.filter(content => content !== null && content !== undefined).map(content => {
+                        if (content && content.type === 'image') {
+                            const { media_type, data } = content.source;
+                            return {
+                                type: 'image_url',
+                                image_url: {
+                                    url: `data:${media_type};base64,${data}`
+                                }
+                            };
+                        }
+                        return stripContentCacheMetadata(content);
+                    })
+                };
             }
 
-            results.push(message);
+            results.push(convertedMessage);
         }
 
         return results;
@@ -1765,10 +2325,14 @@ class MixOpenAIResponses extends MixOpenAI {
     }
 
     static buildResponsesRequest(options = {}, config = {}) {
-        const input = MixOpenAIResponses.messagesToResponsesInput(options.messages);
+        const isGPT56 = typeof options.model === 'string' && options.model.startsWith('gpt-5.6');
+        const input = MixOpenAIResponses.messagesToResponsesInput(options.messages, {
+            translateNeutralCache: isGPT56
+        });
         if (config.system) {
             input.unshift({ role: 'developer', content: [{ type: 'input_text', text: config.system }] });
         }
+        MixOpenAIResponses.validatePromptCaching(options, input);
         const request = {
             model: options.model,
             input,
@@ -1812,10 +2376,52 @@ class MixOpenAIResponses extends MixOpenAI {
         if (options.user !== undefined) request.user = options.user;
         if (options.prompt_cache_key !== undefined) request.prompt_cache_key = options.prompt_cache_key;
         if (options.prompt_cache_retention !== undefined) request.prompt_cache_retention = options.prompt_cache_retention;
+        if (options.prompt_cache_options !== undefined) request.prompt_cache_options = options.prompt_cache_options;
 
         return request;
     }
 
+    static validatePromptCaching(options, input) {
+        const isGPT56 = typeof options.model === 'string' && options.model.startsWith('gpt-5.6');
+        const cacheOptions = options.prompt_cache_options;
+        const breakpoints = input.flatMap(message => Array.isArray(message.content)
+            ? message.content
+                .filter(block => block?.prompt_cache_breakpoint !== undefined)
+                .map(block => block.prompt_cache_breakpoint)
+            : []);
+
+        if (isGPT56 && options.prompt_cache_retention !== undefined) {
+            throw new Error('GPT-5.6 does not support prompt_cache_retention; use prompt_cache_options.ttl instead.');
+        }
+        if (!isGPT56 && cacheOptions !== undefined) {
+            throw new Error('prompt_cache_options is only supported by GPT-5.6 models.');
+        }
+        if (!isGPT56 && breakpoints.length > 0) {
+            throw new Error('prompt_cache_breakpoint is only supported by GPT-5.6 models.');
+        }
+        if (cacheOptions !== undefined) {
+            if (!isPlainObject(cacheOptions)) {
+                throw new TypeError('prompt_cache_options must be a plain non-null object.');
+            }
+            if (cacheOptions.mode !== undefined
+                && cacheOptions.mode !== 'implicit'
+                && cacheOptions.mode !== 'explicit') {
+                throw new TypeError('prompt_cache_options.mode must be "implicit" or "explicit".');
+            }
+            if (cacheOptions.ttl !== undefined && cacheOptions.ttl !== '30m') {
+                throw new TypeError('prompt_cache_options.ttl must be "30m".');
+            }
+        }
+        for (const breakpoint of breakpoints) {
+            if (!isPlainObject(breakpoint)) {
+                throw new TypeError('prompt_cache_breakpoint must be a plain non-null object.');
+            }
+            if (breakpoint.mode !== 'explicit') {
+                throw new TypeError('prompt_cache_breakpoint mode must be "explicit".');
+            }
+        }
+    }
+
     static processResponsesResponse(response) {
         const message = MixOpenAIResponses.extractResponsesMessage(response.data);
         return {
@@ -1829,19 +2435,15 @@ class MixOpenAIResponses extends MixOpenAI {
 
     static extractResponsesTokens(data) {
         if (data.usage) {
-            return {
+            return ModelMix.normalizeTokenUsage({
                 input: data.usage.input_tokens || 0,
                 output: data.usage.output_tokens || 0,
-                total: data.usage.total_tokens || ((data.usage.input_tokens || 0) + (data.usage.output_tokens || 0)),
-                cached: ModelMix.extractCacheTokens(data.usage)
-            };
+                total: data.usage.total_tokens,
+                cached: ModelMix.extractCacheTokens(data.usage),
+                cacheWrite: ModelMix.extractCacheWriteTokens(data.usage)
+            });
         }
-        return {
-            input: 0,
-            output: 0,
-            total: 0,
-            cached: 0
-        };
+        return ModelMix.normalizeTokenUsage();
     }
 
     static extractResponsesMessage(data) {
@@ -1855,27 +2457,70 @@ class MixOpenAIResponses extends MixOpenAI {
             .trim();
     }
 
-    static messagesToResponsesInput(messages = []) {
+    static messagesToResponsesInput(messages = [], { translateNeutralCache = false } = {}) {
         const mapped = [];
 
         for (const message of messages) {
             if (!message || !message.role) continue;
             if (message.tool_calls || message.role === 'tool') continue;
 
-            let text = '';
+            const content = [];
+            const isAssistant = message.role === 'assistant';
+            const textType = isAssistant ? 'output_text' : 'input_text';
             if (typeof message.content === 'string') {
-                text = message.content;
+                if (message.content) content.push({ type: textType, text: message.content });
             } else if (Array.isArray(message.content)) {
-                text = message.content
-                    .filter(item => item && item.type === 'text' && typeof item.text === 'string')
-                    .map(item => item.text)
-                    .join('\n');
+                for (const item of message.content) {
+                    if (!item || typeof item !== 'object') continue;
+                    const neutralCache = item.cache !== undefined
+                        ? normalizeContentCache(item.cache)
+                        : undefined;
+                    const promptCacheBreakpoint = item.prompt_cache_breakpoint !== undefined
+                        ? item.prompt_cache_breakpoint
+                        : (translateNeutralCache && neutralCache?.breakpoint
+                            ? { mode: 'explicit' }
+                            : undefined);
+                    const breakpoint = !isAssistant && promptCacheBreakpoint !== undefined
+                        ? { prompt_cache_breakpoint: promptCacheBreakpoint }
+                        : {};
+
+                    if ((item.type === 'text' || item.type === 'input_text' || item.type === 'output_text')
+                        && typeof item.text === 'string') {
+                        content.push({ type: textType, text: item.text, ...breakpoint });
+                        continue;
+                    }
+                    if (item.type === 'image' && item.source) {
+                        let imageUrl;
+                        if (item.source.type === 'base64') {
+                            if (!item.source.media_type || typeof item.source.data !== 'string') {
+                                throw new TypeError('Responses base64 images require source.media_type and string source.data.');
+                            }
+                            imageUrl = `data:${item.source.media_type};base64,${item.source.data}`;
+                        } else if (item.source.type === 'url' && typeof item.source.data === 'string') {
+                            imageUrl = item.source.data;
+                        } else {
+                            throw new TypeError('Responses images must be processed to base64 or use a URL source.');
+                        }
+                        content.push({ type: 'input_image', image_url: imageUrl, ...breakpoint });
+                        continue;
+                    }
+                    if (item.type === 'image_url' && typeof item.image_url?.url === 'string') {
+                        content.push({ type: 'input_image', image_url: item.image_url.url, ...breakpoint });
+                        continue;
+                    }
+                    if (item.type === 'input_image' || item.type === 'input_file') {
+                        content.push({
+                            ...stripContentCacheMetadata(item),
+                            ...breakpoint
+                        });
+                    }
+                }
             }
 
-            if (!text) continue;
+            if (content.length === 0) continue;
             mapped.push({
                 role: message.role,
-                content: [{ type: 'input_text', text }]
+                content
             });
         }
 
@@ -1928,9 +2573,7 @@ class MixOpenAIWebSocket extends MixOpenAIResponses {
                 reject({
                     message: `Realtime WebSocket timed out after ${timeoutMs}ms`,
                     statusCode: null,
-                    details: null,
-                    config: mergedConfig,
-                    options
+                    details: null
                 });
             }, timeoutMs);
 
@@ -2024,9 +2667,7 @@ class MixOpenAIWebSocket extends MixOpenAIResponses {
                     reject({
                         message: event.error?.message || 'Realtime WebSocket error',
                         statusCode: null,
-                        details: event.error || event,
-                        config: mergedConfig,
-                        options
+                        details: event.error || event
                     });
                 }
             });
@@ -2039,9 +2680,7 @@ class MixOpenAIWebSocket extends MixOpenAIResponses {
                     message: error.message || 'Realtime WebSocket connection error',
                     statusCode: null,
                     details: null,
-                    stack: error.stack,
-                    config: mergedConfig,
-                    options
+                    stack: error.stack
                 });
             });
 
@@ -2052,9 +2691,7 @@ class MixOpenAIWebSocket extends MixOpenAIResponses {
                 reject({
                     message: 'Realtime WebSocket closed before response.done',
                     statusCode: null,
-                    details: null,
-                    config: mergedConfig,
-                    options
+                    details: null
                 });
             });
         });
@@ -2155,6 +2792,23 @@ class MixKimi extends MixOpenAI {
 
 class MixAnthropic extends MixCustom {
 
+    sanitizeCacheOptions(options) {
+        delete options.prompt_cache_key;
+        delete options.prompt_cache_options;
+        delete options.prompt_cache_retention;
+    }
+
+    static validateCacheControl(cacheControl) {
+        if (!isPlainObject(cacheControl) || cacheControl.type !== 'ephemeral') {
+            throw new TypeError('Anthropic cache_control must have type "ephemeral".');
+        }
+        if (cacheControl.ttl !== undefined
+            && cacheControl.ttl !== '5m'
+            && cacheControl.ttl !== '1h') {
+            throw new TypeError('Anthropic cache_control.ttl must be "5m" or "1h".');
+        }
+    }
+
     /**
      * Opus 4.7+ and Claude 5 family reject sampling params (temperature/top_p/top_k).
      * See: https://platform.claude.com/docs/en/about-claude/models/migration-guide
@@ -2200,10 +2854,20 @@ class MixAnthropic extends MixCustom {
             delete options.top_k;
         }
 
+        const requestConfig = { ...config };
+        if (hasNeutralCacheBreakpoint(options.messages)) {
+            const contentCacheControl = options.cache_control ?? { type: 'ephemeral' };
+            MixAnthropic.validateCacheControl(contentCacheControl);
+            requestConfig._contentCacheControl = { ...contentCacheControl };
+            delete options.cache_control;
+        } else if (options.cache_control !== undefined) {
+            MixAnthropic.validateCacheControl(options.cache_control);
+        }
+
         options.system = config.system;
 
         try {
-            return await super.create({ config, options });
+            return await super.create({ config: requestConfig, options });
         } catch (error) {
             // Log the error details for debugging
             if (error.response && error.response.data) {
@@ -2275,20 +2939,37 @@ class MixAnthropic extends MixCustom {
 
             // Handle content conversion for other messages
             if (message.content && Array.isArray(message.content)) {
-                message.content = message.content.filter(content => content !== null && content !== undefined).map(content => {
+                const content = message.content.filter(content => content !== null && content !== undefined).map(content => {
+                    const neutralCache = content?.cache !== undefined
+                        ? normalizeContentCache(content.cache)
+                        : undefined;
+                    if (neutralCache && content.cache_control !== undefined) {
+                        throw new TypeError('Use either cache or cache_control on an Anthropic content block, not both.');
+                    }
+                    let converted = content;
                     if (content && content.type === 'function') {
-                        return {
+                        converted = {
                             type: 'tool_use',
                             id: content.id,
                             name: content.function.name,
                             input: JSON.parse(content.function.arguments)
-                        }
+                        };
                     }
-                    return content;
+                    const sanitized = stripContentCacheMetadata(converted);
+                    if (content.cache_control !== undefined) {
+                        MixAnthropic.validateCacheControl(content.cache_control);
+                        sanitized.cache_control = { ...content.cache_control };
+                    } else if (neutralCache?.breakpoint) {
+                        sanitized.cache_control = {
+                            ...(config?._contentCacheControl || { type: 'ephemeral' })
+                        };
+                    }
+                    return sanitized;
                 });
+                return { ...message, content };
             }
 
-            return message;
+            return { ...message };
         });
     }
 
@@ -2370,19 +3051,26 @@ class MixAnthropic extends MixCustom {
     static extractTokens(data) {
         // Anthropic format
         if (data.usage) {
-            return {
-                input: data.usage.input_tokens || 0,
-                output: data.usage.output_tokens || 0,
-                total: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
-                cached: ModelMix.extractCacheTokens(data.usage)
-            };
+            const cached = ModelMix.extractCacheTokens(data.usage);
+            const cacheWrite5m = data.usage.cache_creation?.ephemeral_5m_input_tokens ?? 0;
+            const cacheWrite1h = data.usage.cache_creation?.ephemeral_1h_input_tokens ?? 0;
+            const cacheWrite = Math.max(
+                ModelMix.extractCacheWriteTokens(data.usage),
+                cacheWrite5m + cacheWrite1h
+            );
+            const input = (data.usage.input_tokens || 0) + cached + cacheWrite;
+            const output = data.usage.output_tokens || 0;
+            return ModelMix.normalizeTokenUsage({
+                input,
+                output,
+                total: input + output,
+                cached,
+                cacheWrite,
+                cacheWrite5m,
+                cacheWrite1h
+            });
         }
-        return {
-            input: 0,
-            output: 0,
-            total: 0,
-            cached: 0
-        };
+        return ModelMix.normalizeTokenUsage();
     }
 
     processResponse(response) {
@@ -2566,6 +3254,13 @@ class MixGrok extends MixOpenAI {
             ...customConfig
         });
     }
+
+    async create({ config = {}, options = {} } = {}) {
+        if (options.model === GROK420_REASONING || options.model === GROK420_NON_REASONING) {
+            delete options.reasoning_effort;
+        }
+        return super.create({ config, options });
+    }
 }
 
 class MixLambda extends MixCustom {
@@ -2740,6 +3435,7 @@ class MixGoogle extends MixCustom {
         return super.getDefaultConfig({
             url: 'https://generativelanguage.googleapis.com/v1beta/models',
             apiKey: process.env.GEMINI_API_KEY,
+            ...customConfig
         });
     }
 
@@ -2909,9 +3605,7 @@ class MixGoogle extends MixCustom {
                 console.log('\n[REQUEST DETAILS - GOOGLE]');
 
                 console.log('\n[CONFIG]');
-                const configToLog = { ...config };
-                delete configToLog.debug;
-                console.log(ModelMix.formatJSON(configToLog));
+                console.log(ModelMix.formatJSON(configForDebug(config)));
 
                 console.log('\n[PAYLOAD]');
                 console.log(ModelMix.formatJSON(payload));
@@ -2927,7 +3621,7 @@ class MixGoogle extends MixCustom {
                 }));
             }
         } catch (error) {
-            throw this.handleError(error, { config, options });
+            throw this.handleError(error);
         }
     }
 
@@ -2965,19 +3659,15 @@ class MixGoogle extends MixCustom {
     static extractTokens(data) {
         // Google Gemini format
         if (data.usageMetadata) {
-            return {
+            return ModelMix.normalizeTokenUsage({
                 input: data.usageMetadata.promptTokenCount || 0,
                 output: data.usageMetadata.candidatesTokenCount || 0,
-                total: data.usageMetadata.totalTokenCount || 0,
-                cached: ModelMix.extractCacheTokens(data.usageMetadata)
-            };
+                total: data.usageMetadata.totalTokenCount,
+                cached: ModelMix.extractCacheTokens(data.usageMetadata),
+                cacheWrite: ModelMix.extractCacheWriteTokens(data.usageMetadata)
+            });
         }
-        return {
-            input: 0,
-            output: 0,
-            total: 0,
-            cached: 0
-        };
+        return ModelMix.normalizeTokenUsage();
     }
 
     static stripUnsupportedSchemaProps(schema) {
@@ -3024,4 +3714,4 @@ class MixGoogle extends MixCustom {
     }
 }
 
-module.exports = { MixCustom, ModelMix, MixAnthropic, MixKimi, MixMiniMax, MixMiMo, MixOpenAI, MixOpenAIResponses, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA, normalizeEffort, applyUnifiedEffort, resolveProviderFamily };
+module.exports = { MixCustom, ModelMix, MixAnthropic, MixKimi, MixMiniMax, MixMiMo, MixOpenAI, MixOpenAIResponses, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA, normalizeEffort, applyUnifiedEffort, resolveProviderFamily };