modelmix 5.1.1 → 5.1.2

package/lib/template-engine.js

@@ -0,0 +1,168 @@
+const { isPlainObject } = require('./object-utils');
+
+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()
+    };
+}
+
+module.exports = {
+    validateTemplateData,
+    validateTemplateDataKey,
+    preprocessChoiceDirectives,
+    createTemplateRenderContext
+};
+

package/lib/token-usage.js

@@ -0,0 +1,299 @@
+const GPT56_LONG_CONTEXT_PRICING = Object.freeze({
+    inputThreshold: 272_000,
+    inputMultiplier: 2,
+    outputMultiplier: 1.5
+});
+
+const GROK46_LONG_CONTEXT_PRICING = Object.freeze({
+    inputThreshold: 200_000,
+    inputMultiplier: 2,
+    outputMultiplier: 2,
+    inclusive: true
+});
+
+function usesLongContextRates(pricing, inputTokens) {
+    const longContext = pricing.longContext;
+    if (!longContext) return false;
+    return longContext.inclusive
+        ? inputTokens >= longContext.inputThreshold
+        : inputTokens > longContext.inputThreshold;
+}
+
+const MODEL_PRICING = {
+    // OpenAI
+    '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': { input: 0.15, output: 0.60 },
+    'gpt-oss-120b': { input: 0.15, output: 0.60 },
+    // Anthropic
+    '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': { 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.7-flash': { input: 0.75, cachedInput: 0.075, output: 3.75 },
+    'gemini-3.6-flash': { input: 0.75, cachedInput: 0.075, output: 3.75 },
+    '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.6': { input: 2.00, cachedInput: 0.50, output: 6.00, longContext: GROK46_LONG_CONTEXT_PRICING },
+    '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': { input: 0.14, output: 0.28 },
+    'accounts/fireworks/models/deepseek-v4-pro': { input: 1.74, output: 3.48 },
+    'accounts/fireworks/models/deepseek-v4-pro-0813': { input: 1.32, cachedInput: 0.044, output: 3.96 },
+    '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 },
+    'qwen/qwen3.5-397b-a17b': { input: 0.385, output: 2.45 },
+    '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 },
+    'accounts/fireworks/models/qwen3p8-2p4t-a95b': { input: 2.00, cachedInput: 0.25, output: 6.00 },
+    'qwen/qwen3.8-max': { input: 2.00, output: 6.00 },
+    // MiniMax
+    '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': { input: 1.00, output: 1.00 },
+    'sonar-pro': { input: 3.00, output: 15.00 },
+    // Hermes 4 (OpenRouter)
+    'nousresearch/hermes-4-70b': { input: 0.13, output: 0.40 },
+    'nousresearch/hermes-4-405b': { input: 1.00, output: 3.00 },
+    // Hermes 3 (Lambda/OpenRouter)
+    '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': { 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': { input: 0.50, output: 2.80 },
+    'moonshotai/kimi-k2.5': { input: 0.50, output: 2.80 },
+    // Kimi K3
+    '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': { input: 0.55, output: 2.19 },
+    'zai-glm-4.7': { input: 0.55, output: 2.19 },
+};
+
+function normalizeTokenUsage({ input = 0, output = 0, thinking = 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 normalizedThinking = tokenCount(thinking);
+    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 + normalizedThinking;
+    const uncachedInput = Math.max(0, normalizedInput - normalizedCached - normalizedCacheWrite);
+    const cacheHitRate = normalizedInput > 0
+        ? Number((normalizedCached / normalizedInput).toFixed(4))
+        : 0;
+
+    return {
+        input: normalizedInput,
+        output: normalizedOutput,
+        thinking: normalizedThinking,
+        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
+        }
+    };
+}
+
+function calculateCostBreakdown(modelKey, tokens) {
+    const pricing = MODEL_PRICING[modelKey];
+    if (!pricing) return normalizeTokenUsage().costBreakdown;
+
+    const normalized = normalizeTokenUsage(tokens);
+    const longContext = pricing.longContext;
+    const useLongContextRates = usesLongContextRates(pricing, normalized.input);
+    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 + normalized.thinking) * outputPerMillion * outputMultiplier / 1_000_000
+        )
+    };
+    breakdown.total = roundCost(
+        breakdown.uncachedInput
+        + breakdown.cachedInput
+        + breakdown.cacheWrite
+        + breakdown.output
+    );
+    return breakdown;
+}
+
+function calculateCacheMetrics(modelKey, tokens) {
+    const pricing = MODEL_PRICING[modelKey];
+    const emptyMetrics = {
+        cacheSavings: 0,
+        cacheWritePremium: 0,
+        breakEvenHits: 0
+    };
+    if (!pricing) return emptyMetrics;
+
+    const normalized = normalizeTokenUsage(tokens);
+    const longContext = pricing.longContext;
+    const useLongContextRates = usesLongContextRates(pricing, normalized.input);
+    const inputMultiplier = useLongContextRates ? 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
+    };
+}
+
+function calculateCost(modelKey, tokens) {
+    if (!hasModelPricing(modelKey)) return null;
+    return calculateCostBreakdown(modelKey, tokens).total;
+}
+
+function hasModelPricing(modelKey) {
+    return Object.prototype.hasOwnProperty.call(MODEL_PRICING, modelKey);
+}
+
+function 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;
+}
+
+function 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;
+}
+
+module.exports = {
+    normalizeTokenUsage,
+    calculateCostBreakdown,
+    calculateCacheMetrics,
+    calculateCost,
+    hasModelPricing,
+    extractCacheTokens,
+    extractCacheWriteTokens
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "5.1.1",
+  "version": "5.1.2",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/modelmix/SKILL.md

@@ -548,7 +548,7 @@ For full debug output, also set: `DEBUG=ModelMix* node script.js`
 ### Free-tier models
 
 ```javascript
-const model = ModelMix.new()
+const model = ModelMix.new({ mix: { openrouter: false } })
     .gptOss()
     .kimiK25()
     .hermes3()
@@ -556,7 +556,7 @@ const model = ModelMix.new()
 console.log(await model.message());
 ```
 
-These use providers with free quotas (OpenRouter, Groq, Cerebras). If one runs out of quota, ModelMix falls back to the next.
+These use providers with free quotas (Groq, Cerebras, and Together). OpenRouter is disabled because its GPT-OSS 120B route is no longer free. If one runs out of quota, ModelMix falls back to the next.
 
 ### Multi-provider routing
 

package/test/effort.test.js

@@ -1,4 +1,5 @@
 const { expect } = require('chai');
+const sinon = require('sinon');
 const {
     normalizeEffort,
     mapEffort,
@@ -359,6 +360,25 @@ describe('Unified effort scale', () => {
         });
     });
 
+    describe('debug logging', () => {
+        afterEach(() => {
+            sinon.restore();
+        });
+
+        it('includes the unified effort in the model header', async () => {
+            const provider = new MixOpenAIResponses();
+            sinon.stub(provider, 'create').resolves({ message: 'ok', toolCalls: [] });
+            const log = sinon.spy(console, 'log');
+            const model = ModelMix.new({ config: { debug: 1, effort: 60 } })
+                .attach('gpt-5.6-luna', provider)
+                .addText('Hello');
+
+            await model.message();
+
+            expect(log.calledWithMatch(/→ \[openairesponses:gpt-5\.6-luna@60\] #1/)).to.equal(true);
+        });
+    });
+
     describe('provider request wiring', () => {
         it('OpenAI Responses request uses mapped reasoning_effort', () => {
             const options = { model: 'gpt-5.2', messages: [] };

package/test/model-chain.test.js

@@ -0,0 +1,12 @@
+const { expect } = require('chai');
+
+const { ModelMix } = require('../index.js');
+const { listChainModelShortcuts } = require('../lib/model-chain');
+
+describe('model chain catalog', () => {
+    it('contains only implemented ModelMix shortcuts', () => {
+        for (const shortcut of listChainModelShortcuts()) {
+            expect(ModelMix.prototype[shortcut], shortcut).to.be.a('function');
+        }
+    });
+});

package/test/public-api.test.js

@@ -0,0 +1,54 @@
+const { expect } = require('chai');
+
+const api = require('../index.js');
+
+describe('public module boundary', () => {
+    it('preserves the CommonJS export surface', () => {
+        expect(Object.keys(api).sort()).to.deep.equal([
+            'MixAnthropic',
+            'MixCerebras',
+            'MixCustom',
+            'MixFireworks',
+            'MixGoogle',
+            'MixGrok',
+            'MixGroq',
+            'MixKimi',
+            'MixLMStudio',
+            'MixMiMo',
+            'MixMiniMax',
+            'MixModeration',
+            'MixNVIDIA',
+            'MixOllama',
+            'MixOpenAI',
+            'MixOpenAIModeration',
+            'MixOpenAIResponses',
+            'MixOpenAIWebSocket',
+            'MixOpenRouter',
+            'MixPerplexity',
+            'MixTogether',
+            'ModelMix',
+            'ModerationMix',
+            'applyUnifiedEffort',
+            'normalizeEffort',
+            'resolveProviderFamily'
+        ]);
+    });
+
+    it('preserves provider inheritance and class identity', () => {
+        expect(Object.getPrototypeOf(api.MixOpenAIResponses.prototype)).to.equal(api.MixOpenAI.prototype);
+        expect(Object.getPrototypeOf(api.MixOpenAIModeration.prototype)).to.equal(api.MixModeration.prototype);
+        expect(Object.getPrototypeOf(api.ModerationMix.prototype)).to.equal(api.ModelMix.prototype);
+        expect(require('../index.js').MixCustom).to.equal(api.MixCustom);
+    });
+
+    it('keeps root exports usable by model shortcuts', () => {
+        const model = api.ModelMix.new().qwen35397b({ config: { apiKey: 'test-key' } });
+
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].provider.constructor).to.equal(api.MixOpenRouter);
+    });
+
+    it('keeps the mutable pricing catalog private', () => {
+        expect(require('../lib/token-usage')).to.not.have.property('MODEL_PRICING');
+    });
+});

package/test/tokens.test.js

@@ -576,6 +576,26 @@ describe('Token Usage Tracking', () => {
         }
     });
 
+    it('should register GPT-OSS 120B through the current OpenRouter model ID', function () {
+        const originalOpenRouterApiKey = process.env.OPENROUTER_API_KEY;
+        process.env.OPENROUTER_API_KEY = 'test-openrouter-key';
+
+        try {
+            const model = ModelMix.new().gptOss({
+                mix: { cerebras: false, groq: true, openrouter: true, together: false }
+            });
+
+            expect(model.models.map(({ key }) => key)).to.deep.equal([
+                'openai/gpt-oss-120b',
+                'openai/gpt-oss-120b'
+            ]);
+            expect(model.models[1].provider).to.be.instanceOf(MixOpenRouter);
+        } finally {
+            if (originalOpenRouterApiKey === undefined) delete process.env.OPENROUTER_API_KEY;
+            else process.env.OPENROUTER_API_KEY = originalOpenRouterApiKey;
+        }
+    });
+
     it('should use api-key header for MiMo provider', function () {
         const originalMimoApiKey = process.env.MIMO_API_KEY;
         process.env.MIMO_API_KEY = 'test-mimo-key';