modelmix 4.7.2 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.7.2",
+  "version": "5.0.0",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -25,7 +25,9 @@
     "kimi",
     "mythos",
     "gpt5",
+    "opus50",
     "opus5",
+    "fable50",
     "fable",
     "sonnet",
     "openrouter",
@@ -51,6 +53,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "bottleneck": "^2.19.5",
+    "ejs": "6.0.1",
     "file-type": "^21.3.4",
     "lemonlog": "^1.2.2",
     "ws": "^8.21.1"

package/skills/modelmix/SKILL.md

@@ -37,7 +37,7 @@ Do NOT use for:
 - [Get raw response (tokens, thinking, tool calls)](#get-raw-response)
 - [Access full response with lastRaw](#access-full-response-with-lastraw)
 - [Add images](#add-images)
-- [Templates with placeholders](#templates-with-placeholders)
+- [EJS templates](#ejs-templates)
 - [Round-robin load balancing](#round-robin-load-balancing)
 - [MCP integration](#mcp-integration)
 - [Custom local tools](#custom-local-tools)
@@ -122,12 +122,12 @@ ModelMix.new({ config: { effort: 80 } })
 `gpt52()` `gpt52chat()` `gpt51()` `gpt5()` `gpt5mini()` `gpt5nano()` `gpt45()` `gpt41()` `gpt41mini()` `gpt41nano()` `o3()` `o4mini()`
 
 ### Anthropic
-`fable5()` `opus5()` `opus48()` `opus47()` `opus46()` `sonnet5()` `sonnet46()` `sonnet45()` `haiku45()`
+`fable50()` `opus50()` `opus48()` `opus47()` `opus46()` `sonnet5()` `sonnet46()` `sonnet45()` `haiku45()`
 
-Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.effort(100).opus5()`.
+Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.effort(100).opus50()`. `fable5()` and `opus5()` remain available as compatibility aliases.
 
 ### Google
-`gemini3pro()` `gemini3flash()` `gemini36flash()` `gemini35flash()` `gemini25pro()` `gemini25flash()`
+`gemini3pro()` `gemini3flash()` `gemini36flash()` `gemini35flash()` `gemini35flashLite()` `gemini31flashLite()` `gemini25pro()` `gemini25flash()`
 
 ### Grok
 `grok45()` `grok43()` `grok420multiAgent()` `grok420()`
@@ -301,11 +301,51 @@ After calling `message()`, `json()`, `block()`, or `stream()`, use `lastRaw` to
 const model = ModelMix.new().gpt5mini().addText("Hello!");
 const text = await model.message();
 console.log(model.lastRaw.tokens);
-// { input: 122, output: 86, total: 541, cost: 0.000319, speed: 38 }
+// {
+//   input: 1200, output: 50, total: 1250,
+//   cached: 1024, cacheWrite: 0, uncachedInput: 176,
+//   cacheWrite5m: 0, cacheWrite1h: 0,
+//   cacheHitRate: 0.8533, cacheSavings: 0.00018432,
+//   cacheWritePremium: 0, breakEvenHits: 0,
+//   cost: 0.00011568,
+//   costBreakdown: {
+//     uncachedInput: 0.0000352, cachedInput: 0.00002048,
+//     cacheWrite: 0, cacheWrite5m: 0, cacheWrite1h: 0,
+//     output: 0.00006, total: 0.00011568
+//   },
+//   speed: 38
+// }
 console.log(model.lastRaw.think);    // reasoning content (if available)
 console.log(model.lastRaw.response); // raw API response
 ```
 
+### GPT-5.6 explicit prompt caching
+
+```javascript
+const model = ModelMix.new()
+  .gpt56luna({
+    options: {
+      prompt_cache_key: 'stable-prefix-v1',
+      prompt_cache_options: { mode: 'explicit', ttl: '30m' }
+    }
+  })
+  .haiku45({
+    options: {
+      cache_control: { type: 'ephemeral', ttl: '1h' }
+    }
+  })
+  .addText(longStableInstructions, {
+    cache: { breakpoint: true }
+  })
+  .addText('Handle this variable request.');
+
+const result = await model.raw();
+```
+
+`cache: { breakpoint: true }` is provider-neutral: GPT-5.6 receives `prompt_cache_breakpoint`, Anthropic receives `cache_control`, and unsupported providers omit it. Keep native request policies inside each model shorthand so they do not leak across fallbacks. Anthropic usage separates `cacheWrite5m` and `cacheWrite1h`; `cacheWrite` stays as their compatible aggregate.
+
+GPT-5.6 replaces `prompt_cache_retention` with `prompt_cache_options.ttl`. Explicit breakpoints also work on image methods and Responses-native `input_text`, `input_image`, and `input_file` blocks. Prompts need at least 1,024 tokens to be cached. Requests over 272K input tokens use 2× input and 1.5× output prices for the complete request; ModelMix applies these multipliers to `cost`, `costBreakdown`, and cache economics.
+
 ### Add images
 
 ```javascript
@@ -319,20 +359,37 @@ const description = await model.message();
 
 All image methods accept an optional second argument `{ role }` (default `"user"`).
 
-### Templates with placeholders
+### EJS templates
 
 ```javascript
 const model = ModelMix.new().gpt5mini();
 model.setSystemFromFile('./prompts/system.md');
 model.addTextFromFile('./prompts/task.md');
 model.replace({
-    '{role}': 'data analyst',
-    '{language}': 'Spanish'
+    role: 'data analyst',
+    language: 'Spanish'
 });
-model.replaceKeyFromFile('{code}', './src/utils.js');
+model.replaceKeyFromFile('code', './src/utils.js');
 console.log(await model.message());
 ```
 
+Templates use standard EJS syntax. Use `<%- value %>` for raw prompt content and `<%= value %>` only when XML escaping is intentional. Missing variables and files throw. Templates may contain JavaScript, so the template source must be developer-controlled; untrusted content belongs only in `replace()` data. Relative includes work in templates loaded from files.
+
+Use ModelMix choice directives for random prompt variants:
+
+```ejs
+<% choice %>
+<% option 20 %>
+Use emojis.
+<% option 40 %>
+Use few emojis.
+<% option 40 %>
+Do not use emojis.
+<% /choice %>
+```
+
+Omit all weights for equal probabilities. Otherwise every option needs a positive relative weight; weights do not need to total 100. Keep directives on their own lines. Nested choices and choices inside includes are supported. A request keeps its selections through retries, provider fallbacks, and tool continuations.
+
 ### Round-robin load balancing
 
 ```javascript
@@ -464,27 +521,27 @@ const model = ModelMix.new({
 - When using MCP tools or `addTool()`, set `max_history` to at least 3 — tool call/response pairs consume history slots.
 - Use `.json()` for structured output instead of parsing text manually. Use descriptor objects `{ description, required, enum, default, nullable }` for richer schema control.
 - Use `.message()` for simple text, `.raw()` when you need tokens/thinking/toolCalls.
-- For Anthropic thinking, use unified `effort` (`-1` or `0`–`100`) via `config.effort` or `.effort(n)` — e.g. `.effort(100).opus5()`. Never put `effort` in `options`. Native fields win if already set.
-- Template placeholders use `{key}` syntax in both system prompts and user messages.
+- For Anthropic thinking, use unified `effort` (`-1` or `0`–`100`) via `config.effort` or `.effort(n)` — e.g. `.effort(100).opus50()`. Never put `effort` in `options`. Native fields win if already set.
+- Templates use EJS syntax in both system prompts and user messages; prefer `<%- key %>` for raw prompt data.
 - The library uses CommonJS internally but supports ESM import via `{ ModelMix }`.
 - GPT-5+ models automatically use `max_completion_tokens` instead of `max_tokens`.
 - o-series models (o3, o4mini) automatically strip `max_tokens` and `temperature` since those APIs don't support them.
 - Anthropic Opus 4.7+ / Claude 5 family automatically strip `temperature`, `top_p`, and `top_k` (API rejects them).
-- `addText()`, `addImage()`, `addImageFromUrl()`, and `addImageFromBuffer()` all accept `{ role }` as second argument (default `"user"`).
+- `addText()`, `addImage()`, `addImageFromUrl()`, and `addImageFromBuffer()` accept `{ role, cache?: { breakpoint: true } }` as the second argument (default role: `"user"`). Adapters translate or omit the neutral marker by provider.
 
 ## API Quick Reference
 
 | Method | Returns | Description |
 | --- | --- | --- |
-| `.addText(text, {role?})` | `this` | Add user message |
-| `.addTextFromFile(path, {role?})` | `this` | Add user message from file |
+| `.addText(text, {role?, cache?})` | `this` | Add user message |
+| `.addTextFromFile(path, {role?, cache?})` | `this` | Add user message from file |
 | `.setSystem(text)` | `this` | Set system prompt |
 | `.setSystemFromFile(path)` | `this` | Set system prompt from file |
-| `.addImage(path, {role?})` | `this` | Add image from file |
-| `.addImageFromUrl(url, {role?})` | `this` | Add image from URL or data URI |
-| `.addImageFromBuffer(buffer, {role?})` | `this` | Add image from Buffer |
-| `.replace({})` | `this` | Set placeholder replacements |
-| `.replaceKeyFromFile(key, path)` | `this` | Replace placeholder with file content |
+| `.addImage(path, {role?, cache?})` | `this` | Add image from file |
+| `.addImageFromUrl(url, {role?, cache?})` | `this` | Add image from URL or data URI |
+| `.addImageFromBuffer(buffer, {role?, cache?})` | `this` | Add image from Buffer |
+| `.replace({})` | `this` | Add EJS template data |
+| `.replaceKeyFromFile(key, path)` | `this` | Add raw file content as EJS template data |
 | `.message()` | `Promise<string>` | Get text response |
 | `.json(example, desc?, opts?)` | `Promise<object\|array>` | Get structured JSON |
 | `.raw()` | `Promise<{message, think, toolCalls, tokens, response}>` | Full response |

package/test/README.md

@@ -9,7 +9,7 @@ This comprehensive test suite provides complete coverage for the ModelMix librar
 These tests require actual API keys and test the complete integration:
 - Real image processing with multiple providers
 - Actual JSON structured output  
-- Template replacement with real models
+- EJS template rendering with real models
 - Multi-modal combinations
 - Performance testing with real APIs
 
@@ -45,13 +45,14 @@ npm test -- --grep "Live Integration"
 - ✅ Context preservation through fallbacks
 - ✅ Provider-specific configurations
 
-### 3. File Operations and Templates (`templates.test.js`)
-- ✅ Template variable replacement
-- ✅ Template file loading
-- ✅ JSON file processing
-- ✅ Absolute and relative paths
-- ✅ File error handling
-- ✅ Complex template + file integration
+### 3. File Operations and EJS Templates (`templates.test.js`)
+- ✅ Raw and XML-escaped EJS output
+- ✅ Nested data, conditionals, and loops
+- ✅ Uniform, weighted, nested, and included choice blocks
+- ✅ File templates and relative includes
+- ✅ Raw file and JSON data injection
+- ✅ Missing-variable and missing-file errors
+- ✅ JSON, block, system, and multi-turn integration
 
 ### 4. Image Processing and Multimodal (`images.test.js`)
 - ✅ Base64 data handling
@@ -155,4 +156,4 @@ DEBUG_TESTS=true npm test
 - All tests use API mocking to avoid real calls
 - Test environment variables are configured in `setup.js`
 - Tests are independent and can run in any order
-- Automatic cleanup prevents interference between tests
+- Automatic cleanup prevents interference between tests

package/test/anthropic.test.js

@@ -5,15 +5,29 @@ const { ModelMix, MixAnthropic } = require('../index.js');
 describe('Anthropic Model Registration Tests', () => {
     it('should register Claude Fable 5', () => {
         const model = ModelMix.new();
-        model.fable5();
+        model.fable50();
 
         expect(model.models).to.have.length(1);
         expect(model.models[0].key).to.equal('claude-fable-5');
         expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
     });
 
-    it('should apply max effort thinking via .effort(100).fable5()', () => {
-        const model = ModelMix.new().effort(100).fable5();
+    it('should keep fable5() as an alias for fable50()', () => {
+        const model = ModelMix.new();
+
+        expect(model.fable5({
+            options: { max_tokens: 123 },
+            config: { url: 'https://anthropic.example.test' }
+        })).to.equal(model);
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('claude-fable-5');
+        expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+        expect(model.models[0].provider.options.max_tokens).to.equal(123);
+        expect(model.models[0].provider.config.url).to.equal('https://anthropic.example.test');
+    });
+
+    it('should apply max effort thinking via .effort(100).fable50()', () => {
+        const model = ModelMix.new().effort(100).fable50();
         const { applyUnifiedEffort } = require('../effort.js');
 
         expect(model.config.effort).to.equal(100);
@@ -25,15 +39,29 @@ describe('Anthropic Model Registration Tests', () => {
 
     it('should register Claude Opus 5', () => {
         const model = ModelMix.new();
-        model.opus5();
+        model.opus50();
 
         expect(model.models).to.have.length(1);
         expect(model.models[0].key).to.equal('claude-opus-5');
         expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
     });
 
-    it('should apply max effort thinking via .effort(100).opus5()', () => {
-        const model = ModelMix.new().effort(100).opus5();
+    it('should keep opus5() as an alias for opus50()', () => {
+        const model = ModelMix.new();
+
+        expect(model.opus5({
+            options: { max_tokens: 123 },
+            config: { url: 'https://anthropic.example.test' }
+        })).to.equal(model);
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('claude-opus-5');
+        expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+        expect(model.models[0].provider.options.max_tokens).to.equal(123);
+        expect(model.models[0].provider.config.url).to.equal('https://anthropic.example.test');
+    });
+
+    it('should apply max effort thinking via .effort(100).opus50()', () => {
+        const model = ModelMix.new().effort(100).opus50();
         const { applyUnifiedEffort } = require('../effort.js');
 
         expect(model.config.effort).to.equal(100);
@@ -133,6 +161,101 @@ describe('Anthropic Model Registration Tests', () => {
         });
     });
 
+    describe('Provider-neutral prompt caching', () => {
+        it('should translate neutral breakpoints and remove foreign OpenAI controls', async () => {
+            const originalApiKey = process.env.ANTHROPIC_API_KEY;
+            process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+
+            try {
+                const provider = new MixAnthropic();
+                let requestBody;
+                nock('https://api.anthropic.com')
+                    .post('/v1/messages', body => {
+                        requestBody = body;
+                        return true;
+                    })
+                    .reply(200, {
+                        content: [{ type: 'text', text: 'Done' }],
+                        usage: { input_tokens: 1, output_tokens: 1 }
+                    });
+
+                await provider.create({
+                    config: { system: 'You are an assistant.' },
+                    options: {
+                        model: 'claude-haiku-4-5-20251001',
+                        max_tokens: 16,
+                        cache_control: { type: 'ephemeral', ttl: '1h' },
+                        prompt_cache_key: 'openai-only',
+                        prompt_cache_options: { mode: 'explicit', ttl: '30m' },
+                        messages: [{
+                            role: 'user',
+                            content: [
+                                { type: 'text', text: 'Stable', cache: { breakpoint: true } },
+                                {
+                                    type: 'text',
+                                    text: 'Variable',
+                                    prompt_cache_breakpoint: { mode: 'explicit' }
+                                }
+                            ]
+                        }]
+                    }
+                });
+
+                expect(requestBody).to.not.have.property('prompt_cache_key');
+                expect(requestBody).to.not.have.property('prompt_cache_options');
+                expect(requestBody).to.not.have.property('cache_control');
+                expect(requestBody.messages[0].content[0]).to.deep.equal({
+                    type: 'text',
+                    text: 'Stable',
+                    cache_control: { type: 'ephemeral', ttl: '1h' }
+                });
+                expect(requestBody.messages[0].content[1]).to.deep.equal({
+                    type: 'text',
+                    text: 'Variable'
+                });
+            } finally {
+                if (originalApiKey === undefined) delete process.env.ANTHROPIC_API_KEY;
+                else process.env.ANTHROPIC_API_KEY = originalApiKey;
+                nock.cleanAll();
+            }
+        });
+
+        it('should preserve top-level automatic caching when there is no explicit breakpoint', async () => {
+            const originalApiKey = process.env.ANTHROPIC_API_KEY;
+            process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+
+            try {
+                const provider = new MixAnthropic();
+                let requestBody;
+                nock('https://api.anthropic.com')
+                    .post('/v1/messages', body => {
+                        requestBody = body;
+                        return true;
+                    })
+                    .reply(200, {
+                        content: [{ type: 'text', text: 'Done' }],
+                        usage: { input_tokens: 1, output_tokens: 1 }
+                    });
+
+                await provider.create({
+                    config: { system: 'You are an assistant.' },
+                    options: {
+                        model: 'claude-haiku-4-5-20251001',
+                        max_tokens: 16,
+                        cache_control: { type: 'ephemeral' },
+                        messages: [{ role: 'user', content: 'Hello' }]
+                    }
+                });
+
+                expect(requestBody.cache_control).to.deep.equal({ type: 'ephemeral' });
+            } finally {
+                if (originalApiKey === undefined) delete process.env.ANTHROPIC_API_KEY;
+                else process.env.ANTHROPIC_API_KEY = originalApiKey;
+                nock.cleanAll();
+            }
+        });
+    });
+
     it('should register Claude Opus 4.8', () => {
         const model = ModelMix.new();
         model.opus48();
@@ -154,15 +277,29 @@ describe('Anthropic Model Registration Tests', () => {
 
     it('should register Claude Sonnet 5', () => {
         const model = ModelMix.new();
-        model.sonnet5();
+        model.sonnet50();
+
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('claude-sonnet-5');
+        expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+    });
+
+    it('should keep sonnet5() as an alias for sonnet50()', () => {
+        const model = ModelMix.new();
 
+        expect(model.sonnet5({
+            options: { max_tokens: 123 },
+            config: { url: 'https://anthropic.example.test' }
+        })).to.equal(model);
         expect(model.models).to.have.length(1);
         expect(model.models[0].key).to.equal('claude-sonnet-5');
         expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+        expect(model.models[0].provider.options.max_tokens).to.equal(123);
+        expect(model.models[0].provider.config.url).to.equal('https://anthropic.example.test');
     });
 
-    it('should apply adaptive thinking via .effort(100).sonnet5()', () => {
-        const model = ModelMix.new().effort(100).sonnet5();
+    it('should apply adaptive thinking via .effort(100).sonnet50()', () => {
+        const model = ModelMix.new().effort(100).sonnet50();
         const { applyUnifiedEffort } = require('../effort.js');
 
         const options = { model: 'claude-sonnet-5' };

package/test/effort.test.js

@@ -336,8 +336,8 @@ describe('Unified effort scale', () => {
             expect(request.reasoning).to.deep.equal({ effort: 'none' });
         });
 
-        it('Anthropic config.effort maps through .effort().opus5()', () => {
-            const model = ModelMix.new().effort(100).opus5();
+        it('Anthropic config.effort maps through .effort().opus50()', () => {
+            const model = ModelMix.new().effort(100).opus50();
             expect(model.config.effort).to.equal(100);
 
             const options = {

package/test/fallback.test.js

@@ -1,7 +1,9 @@
 const { expect } = require('chai');
 const sinon = require('sinon');
 const nock = require('nock');
-const { ModelMix } = require('../index.js');
+const { EventEmitter } = require('events');
+const Module = require('module');
+const { MixCustom, MixGoogle, ModelMix } = require('../index.js');
 
 describe('Provider Fallback Chain Tests', () => {
     
@@ -67,6 +69,97 @@ describe('Provider Fallback Chain Tests', () => {
             expect(response).to.include('Hello from Claude Sonnet 4!');
         });
 
+        it('should translate neutral cache breakpoints independently across providers', async () => {
+            let openAIRequest;
+            let anthropicRequest;
+            model
+                .gpt56luna({
+                    options: {
+                        prompt_cache_key: 'shared-prefix',
+                        prompt_cache_options: { mode: 'explicit', ttl: '30m' }
+                    }
+                })
+                .haiku45({
+                    options: {
+                        cache_control: { type: 'ephemeral', ttl: '1h' }
+                    }
+                })
+                .addText('Stable prefix', { cache: { breakpoint: true } })
+                .addText('Variable request');
+
+            nock('https://api.openai.com')
+                .post('/v1/responses', body => {
+                    openAIRequest = body;
+                    return true;
+                })
+                .reply(500, { error: 'Server error' });
+
+            nock('https://api.anthropic.com')
+                .post('/v1/messages', body => {
+                    anthropicRequest = body;
+                    return true;
+                })
+                .reply(200, {
+                    content: [{ type: 'text', text: 'Cached fallback response' }],
+                    usage: { input_tokens: 2, output_tokens: 3 }
+                });
+
+            const response = await model.message();
+
+            expect(response).to.equal('Cached fallback response');
+            expect(openAIRequest.prompt_cache_options).to.deep.equal({ mode: 'explicit', ttl: '30m' });
+            expect(openAIRequest.input[1].content[0].prompt_cache_breakpoint).to.deep.equal({ mode: 'explicit' });
+            expect(openAIRequest.input[1].content[0]).to.not.have.property('cache');
+            expect(anthropicRequest).to.not.have.property('prompt_cache_options');
+            expect(anthropicRequest).to.not.have.property('prompt_cache_key');
+            expect(anthropicRequest).to.not.have.property('cache_control');
+            expect(anthropicRequest.messages[0].content[0]).to.deep.equal({
+                type: 'text',
+                text: 'Stable prefix',
+                cache_control: { type: 'ephemeral', ttl: '1h' }
+            });
+            expect(anthropicRequest.messages[0].content[1]).to.deep.equal({
+                type: 'text',
+                text: 'Variable request'
+            });
+        });
+
+        it('should preserve neutral cache metadata after an older OpenAI fallback attempt', async () => {
+            let openAIRequest;
+            let anthropicRequest;
+            model
+                .gpt5mini()
+                .haiku45({ options: { cache_control: { type: 'ephemeral' } } })
+                .addText('Stable prefix', { cache: { breakpoint: true } })
+                .addText('Variable request');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions', body => {
+                    openAIRequest = body;
+                    return true;
+                })
+                .reply(500, { error: 'Server error' });
+
+            nock('https://api.anthropic.com')
+                .post('/v1/messages', body => {
+                    anthropicRequest = body;
+                    return true;
+                })
+                .reply(200, {
+                    content: [{ type: 'text', text: 'Fallback preserved cache' }],
+                    usage: { input_tokens: 2, output_tokens: 3 }
+                });
+
+            const response = await model.message();
+
+            expect(response).to.equal('Fallback preserved cache');
+            expect(openAIRequest.messages[1].content[0]).to.not.have.property('cache');
+            expect(openAIRequest.messages[1].content[0]).to.not.have.property('cache_control');
+            expect(anthropicRequest.messages[0].content[0].cache_control).to.deep.equal({
+                type: 'ephemeral'
+            });
+        });
+
         it('should cascade through multiple fallbacks', async () => {
             model.gpt5mini().sonnet46().gemini3flash().addText('Hello');
 
@@ -440,6 +533,103 @@ describe('Provider Fallback Chain Tests', () => {
             });
         });
 
+        it('should not expose provider configuration or options in errors', () => {
+            const provider = new MixCustom({
+                config: { apiKey: 'secret-test-key' },
+                options: { user: 'private-user-id' }
+            });
+
+            const error = provider.handleError(new Error('Request failed'));
+
+            expect(error).to.not.have.property('config');
+            expect(error).to.not.have.property('options');
+            expect(JSON.stringify(error)).to.not.include('secret-test-key');
+            expect(JSON.stringify(error)).to.not.include('private-user-id');
+        });
+
+        it('should redact Gemini API keys from HTTP errors', async () => {
+            const apiKey = 'secret-test-key';
+            const provider = new MixGoogle({ config: { apiKey } });
+
+            nock('https://generativelanguage.googleapis.com')
+                .post('/v1beta/models/gemini-test:generateContent')
+                .query({ key: apiKey })
+                .reply(401, {
+                    error: 'Unauthorized',
+                    requestUrl: `https://example.test?key=${apiKey}`
+                });
+
+            let error;
+            try {
+                await provider.create({
+                    config: { system: 'Test system' },
+                    options: { model: 'gemini-test', messages: [] }
+                });
+            } catch (caught) {
+                error = caught;
+            }
+
+            expect(error).to.exist;
+            expect(error.message).to.not.include(apiKey);
+            expect(error.details.requestUrl).to.include('[REDACTED]');
+            expect(error.stack).to.not.include(apiKey);
+            expect(JSON.stringify(error)).to.not.include(apiKey);
+        });
+
+        it('should not expose config or options when realtime closes early', async () => {
+            class ClosingWebSocket extends EventEmitter {
+                constructor() {
+                    super();
+                    queueMicrotask(() => this.emit('close'));
+                }
+
+                close() {}
+                send() {}
+            }
+
+            const indexPath = require.resolve('../index.js');
+            const cachedIndex = require.cache[indexPath];
+            const originalLoad = Module._load;
+            let RealtimeProvider;
+            try {
+                delete require.cache[indexPath];
+                Module._load = function (request, parent, isMain) {
+                    if (request === 'ws') return ClosingWebSocket;
+                    return originalLoad.call(this, request, parent, isMain);
+                };
+                ({ MixOpenAIWebSocket: RealtimeProvider } = require('../index.js'));
+            } finally {
+                Module._load = originalLoad;
+                delete require.cache[indexPath];
+                if (cachedIndex) require.cache[indexPath] = cachedIndex;
+            }
+
+            const apiKey = 'secret-realtime-key';
+            const provider = new RealtimeProvider({ config: { apiKey } });
+            let error;
+            try {
+                await provider.create({
+                    config: { system: 'private system prompt' },
+                    options: {
+                        model: 'gpt-realtime-mini',
+                        messages: [{ role: 'user', content: 'private prompt' }]
+                    }
+                });
+            } catch (caught) {
+                error = caught;
+            }
+
+            expect(error).to.deep.equal({
+                message: 'Realtime WebSocket closed before response.done',
+                statusCode: null,
+                details: null
+            });
+            const serialized = JSON.stringify(error);
+            expect(serialized).to.not.include(apiKey);
+            expect(serialized).to.not.include('private system prompt');
+            expect(serialized).to.not.include('private prompt');
+        });
+
         it('should provide detailed error information when all fallbacks fail', async () => {
             model.gpt5mini().sonnet46().gemini3flash().addText('Test');
 
@@ -488,4 +678,4 @@ describe('Provider Fallback Chain Tests', () => {
             expect(response).to.include('Valid fallback response from Claude');
         });
     });
-});
+});

package/test/fixtures/account-details.txt

@@ -0,0 +1,4 @@
+Your account details:
+- Username: <%- username %>
+- Role: <%- role %>
+- Created: <%- createdDate %>

package/test/fixtures/choice-options.txt

@@ -0,0 +1,6 @@
+<% choice %>
+<% option %>
+Be detailed.
+<% option %>
+Be concise.
+<% /choice %>

package/test/fixtures/choice-template.txt

@@ -0,0 +1,2 @@
+Style:
+<%- include('choice-options.txt') %>

package/test/fixtures/system-rules.txt

@@ -0,0 +1 @@
+Always respond in <%- language %>.