modelmix 5.1.20 → 5.2.1

package/plugins/skills/test/skills.test.js

@@ -0,0 +1,182 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { ModelMix, MixCustom } = require('../../..');
+const { skills } = require('..');
+
+describe('Skills plugin', () => {
+    let temporary;
+    let directory;
+    const source = '---\nname: writing\ndescription: >-\n  Write clear prose\n  for readers.\nmetadata:\n  category: editorial\n---\nUse references/style.md. Preserve <%= literal %> and ${text}.\n';
+
+    beforeEach(async () => {
+        temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'modelmix-skills-'));
+        directory = path.join(temporary, 'writing');
+        await fs.mkdir(path.join(directory, 'references'), { recursive: true });
+        await fs.writeFile(path.join(directory, 'SKILL.md'), source);
+        await fs.writeFile(path.join(directory, 'references/style.md'), 'Use concrete verbs.');
+    });
+
+    afterEach(async () => {
+        await fs.rm(temporary, { recursive: true, force: true });
+    });
+
+    async function prepare(plugin) {
+        const request = { system: 'Existing system', tools: [] };
+        await plugin.execute({ request }, async () => ({ message: 'ok' }));
+        return request;
+    }
+
+    it('loads only metadata into the prompt and exposes literal skill content on demand', async () => {
+        const plugin = await skills({ paths: [directory] });
+        const request = await prepare(plugin);
+        assert.ok(request.system.startsWith('Existing system\n\n'));
+        assert.ok(request.system.includes('Write clear prose for readers.'));
+        assert.ok(!request.system.includes('Preserve <%= literal %>'));
+        const result = await request.tools[0].callback({ name: 'writing' });
+        assert.deepEqual(result, { name: 'writing', path: 'SKILL.md', content: source });
+    });
+
+    it('supports SKILL.md paths and reads references relative to the skill root', async () => {
+        const request = await prepare(await skills({ paths: [path.join(directory, 'SKILL.md')] }));
+        assert.deepEqual(await request.tools[0].callback({ name: 'writing', path: 'references/style.md' }), {
+            name: 'writing', path: 'references/style.md', content: 'Use concrete verbs.'
+        });
+    });
+
+    it('returns the loaded snapshot for every path that resolves to SKILL.md', async () => {
+        await fs.symlink(path.join(directory, 'SKILL.md'), path.join(directory, 'alias.md'));
+        const request = await prepare(await skills({ paths: [directory] }));
+        await fs.writeFile(path.join(directory, 'SKILL.md'), '---\nname: writing\ndescription: Changed\n---\nChanged body.\n');
+        for (const relative of ['./SKILL.md', 'references/../SKILL.md', 'alias.md']) {
+            assert.deepEqual(await request.tools[0].callback({ name: 'writing', path: relative }), {
+                name: 'writing', path: relative, content: source
+            });
+        }
+    });
+
+    it('reads supporting files from disk on every call', async () => {
+        const request = await prepare(await skills({ paths: [directory] }));
+        await fs.writeFile(path.join(directory, 'references/style.md'), 'Use strong verbs.');
+        assert.deepEqual(await request.tools[0].callback({ name: 'writing', path: 'references/style.md' }), {
+            name: 'writing', path: 'references/style.md', content: 'Use strong verbs.'
+        });
+    });
+
+    it('returns the snapshot for SKILL.md aliases without decoding the changed file', async () => {
+        await fs.symlink(path.join(directory, 'SKILL.md'), path.join(directory, 'alias.md'));
+        const request = await prepare(await skills({ paths: [directory] }));
+        await fs.writeFile(path.join(directory, 'SKILL.md'), Buffer.from([0, 255, 128]));
+        for (const relative of ['./SKILL.md', 'alias.md']) {
+            assert.deepEqual(await request.tools[0].callback({ name: 'writing', path: relative }), {
+                name: 'writing', path: relative, content: source
+            });
+        }
+    });
+
+    it('runs the complete tool loop without re-rendering skill text or changing instance configuration', async () => {
+        const requests = [];
+        const provider = new MixCustom();
+        provider.create = async request => {
+            requests.push(request);
+            if (requests.length === 1) return {
+                message: '', toolCalls: [{ id: 'skill', name: 'read_skill', input: { name: 'writing' } }]
+            };
+            if (requests.length === 2) return {
+                message: '', toolCalls: [{ id: 'reference', name: 'read_skill', input: { name: 'writing', path: 'references/style.md' } }]
+            };
+            return { message: '{"answer":"Concrete verbs"}', toolCalls: [] };
+        };
+        const model = ModelMix.new({ config: { system: 'Be concise.' } })
+            .attach('custom', provider).use(await skills({ paths: [directory] })).addText('Use writing.');
+        assert.deepEqual(await model.json(), { answer: 'Concrete verbs' });
+        assert.equal(requests.length, 3);
+        for (const request of requests) {
+            assert.equal(request.config.system.split('Available skills:').length, 2);
+            assert.equal(request.options.tools[0].function.name, 'read_skill');
+        }
+        const outputs = requests[2].options.messages.filter(message => message.role === 'tool').map(message => JSON.parse(message.content));
+        assert.equal(outputs[0].content, source);
+        assert.equal(outputs[1].content, 'Use concrete verbs.');
+        assert.equal(model.config.max_history, 0);
+        assert.equal(model.config.system, 'Be concise.');
+        assert.deepEqual(model.tools, {});
+        assert.deepEqual(model.messages, []);
+    });
+
+    it('supports inherited plugins without leaking tools into sibling or later requests', async () => {
+        const provider = new MixCustom();
+        const requests = [];
+        provider.create = async request => {
+            requests.push(request);
+            return { message: 'ok', toolCalls: [] };
+        };
+        const model = ModelMix.new().attach('custom', provider).use(await skills({ paths: [directory] }));
+        await model.new().addText('child').message();
+        await model.addText('first').message();
+        await model.addText('second').message();
+        await ModelMix.new().attach('custom', provider).addText('sibling').message();
+        for (const request of requests.slice(0, 3)) assert.equal(request.options.tools.length, 1);
+        assert.equal(requests[3].options.tools, undefined);
+    });
+
+    it('rejects missing files, missing metadata, malformed YAML, and duplicate names', async () => {
+        await assert.rejects(skills({ paths: [path.join(temporary, 'missing')] }), /ENOENT/);
+        for (const content of ['No frontmatter', '---\nname: writing\n---\nBody', '---\nname: [broken\n---\nBody', '---\nname: writing\nname: duplicate\ndescription: text\n---\nBody']) {
+            await fs.writeFile(path.join(directory, 'SKILL.md'), content);
+            await assert.rejects(skills({ paths: [directory] }));
+        }
+        await fs.writeFile(path.join(directory, 'SKILL.md'), source);
+        await assert.rejects(skills({ paths: [directory, directory] }), /Duplicate skill name/);
+    });
+
+    it('validates configuration and tool arguments', async () => {
+        for (const options of [undefined, {}, { paths: [] }, { paths: [''] }, { paths: 'directory' }]) {
+            await assert.rejects(skills(options), /paths must be/);
+        }
+        const request = await prepare(await skills({ paths: [directory] }));
+        const read = request.tools[0].callback;
+        await assert.rejects(read({ name: 'missing' }), /Unknown skill/);
+        await assert.rejects(read({ name: 'writing', extra: true }), /expects a name/);
+        for (const value of ['', null, 42, directory]) {
+            await assert.rejects(read({ name: 'writing', path: value }), /relative path/);
+        }
+    });
+
+    it('blocks traversal, prefix siblings, and symlinks outside the skill directory', async () => {
+        await fs.writeFile(path.join(temporary, 'outside.md'), 'outside');
+        const sibling = path.join(temporary, 'writing-other');
+        await fs.mkdir(sibling);
+        await fs.writeFile(path.join(sibling, 'file.md'), 'sibling');
+        await fs.symlink(path.join(temporary, 'outside.md'), path.join(directory, 'linked.md'));
+        const request = await prepare(await skills({ paths: [directory] }));
+        for (const relative of ['../outside.md', '../writing-other/file.md', 'linked.md']) {
+            await assert.rejects(request.tools[0].callback({ name: 'writing', path: relative }), /inside the skill directory/);
+        }
+    });
+
+    it('blocks SKILL.md symlinks outside the registered directory', async () => {
+        await fs.writeFile(path.join(temporary, 'outside.md'), source);
+        await fs.unlink(path.join(directory, 'SKILL.md'));
+        await fs.symlink(path.join(temporary, 'outside.md'), path.join(directory, 'SKILL.md'));
+        await assert.rejects(skills({ paths: [directory] }), /inside the skill directory/);
+    });
+
+    it('rejects directories and binary resources', async () => {
+        await fs.writeFile(path.join(directory, 'binary'), Buffer.from([0, 255, 128]));
+        const request = await prepare(await skills({ paths: [directory] }));
+        await assert.rejects(request.tools[0].callback({ name: 'writing', path: 'references' }), /regular file/);
+        await assert.rejects(request.tools[0].callback({ name: 'writing', path: 'binary' }));
+    });
+
+    it('propagates cancellation before middleware and resource reads', async () => {
+        const plugin = await skills({ paths: [directory] });
+        const request = await prepare(plugin);
+        const controller = new AbortController();
+        const reason = new Error('cancelled');
+        controller.abort(reason);
+        await assert.rejects(plugin.execute({ request, signal: controller.signal }, () => assert.fail('next called')), error => error === reason);
+        await assert.rejects(request.tools[0].callback({ name: 'writing', path: 'references/style.md' }, controller.signal), error => error === reason);
+    });
+});

package/pnpm-workspace.yaml

@@ -16,8 +16,8 @@ overrides:
   brace-expansion: 5.0.9
   diff: 8.0.4
   fast-uri: 3.1.6
-  hono: 4.12.34
+  hono: 4.13.5
   ip-address: 10.3.1
-  js-yaml: 4.3.1
+  js-yaml: 4.3.2
   qs: 6.16.0
   serialize-javascript: 7.0.5

package/skills/modelmix/SKILL.md

@@ -121,6 +121,27 @@ model.use({
 
 The optional `@modelmix/rlm` package is a separate workspace/npm package for recursive processing of large structured inputs. Pass Markdown through `documents: { name: { format: 'markdown', content } }`, register named ModelMix worker chains, and provide every runtime limit explicitly. A worker uses either `model: anotherModelMixInstance` or `useParent: true`. Its planner sees content-free variable size/shape metadata, while document values and generated orchestration code stay inside an `isolated-vm` sandbox. RLM planner prompts are Markdown files rendered with the normal child `assign` plus `systemFile` path.
 
+### Loading local skills
+
+Use the included skills plugin to expose local `SKILL.md` instructions to a model with tool-call support:
+
+```javascript
+import { ModelMix } from 'modelmix';
+import { skills } from 'modelmix/plugins/skills/index.js';
+const model = ModelMix.new()
+    .gpt6astra()
+    .opus5()
+    .use(await skills({ paths: ['./skills/writing'] }))
+    .addText('Use the writing skill to revise this paragraph: ...');
+const answer = await model.message();
+```
+
+Paths identify explicit skill directories or `SKILL.md` files relative to the working directory. YAML `name` and `description` must be non-empty strings. The system prompt receives only the catalog; `read_skill({ name })` loads instructions and `read_skill({ name, path })` reads a supporting UTF-8 file inside that skill directory. Instructions are literal, never EJS-rendered. Skill metadata and instructions are snapshots; recreate the plugin to reload them. References are read on demand. The plugin supplies no script execution or automatic permissions from skill metadata.
+
+Plugin tools use `context.request.tools.push({ tool, callback })`. They coexist with local/MCP tools, are scoped to the current execution, and survive tool continuations. Duplicate names fail before a provider call; the skills plugin reserves `read_skill`. Child executions receive the tools only when the plugin is inherited or the tools are explicitly passed to `context.invoke()`.
+
+With plugin tools, native `options.tools` entries are combined with registered and plugin tools. OpenAI Responses supports this tool loop, including reasoning returned with function calls.
+
 ### Unified effort
 
 Provider-agnostic reasoning intensity. **Not** an `options` field — use `config.effort` or `.effort(n)`.
@@ -183,14 +204,23 @@ Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.ef
 ### MiniMax
 `minimaxM27()` `minimaxM3()`
 
+### DeepSeek
+`deepseekV41Flash({ mix: { deepseek: true, openrouter: false } })` uses the native API at `https://api.deepseek.com/chat/completions` with model `deepseek-flash` (currently V4.1 Flash). Requires `DEEPSEEK_API_KEY`; `MixDeepSeek` supports explicit `.attach()` calls. Unified effort and native cache usage are supported, and assistant reasoning is preserved for tool continuations. Cost estimates use peak rates per 1M tokens: $0.30 input, $0.006 cached input, $1.20 output; off-peak charges are half. Enabling all three providers orders them DeepSeek → Fireworks → OpenRouter.
+
 ### Fireworks
 `museGlimmer30b()` `gptOss()` `qwen36plus()` (private/on-demand only) `qwen37plus()` `qwen38max()` `deepseekV4Flash()` `deepseekV4Pro()` `kimiK26()` `kimiK27Code()` `kimiK3()` `minimaxM27()` `minimaxM3()` `GLM52()`
 
+`deepseekV41Flash({ mix: { fireworks: true, openrouter: false } })` selects `accounts/fireworks/models/deepseek-v4p1-flash` and requires `FIREWORKS_API_KEY`. Per 1M tokens: $0.22 input, $0.007 cached input, $0.66 output. Set both providers to `true` for Fireworks followed by OpenRouter fallback; no arguments selects OpenRouter.
+
 ### Cerebras
 `GLM46()`
 
 ### OpenRouter
-`museGlimmer30b()` `museSpark12()` `museSpark12c()` `museSpark13()` `museSpark13c()` `gptOss()` `qwen35397b()` `qwen36plus()` `qwen37plus()` `qwen3827b()` `qwen38flash()` `hermes470b()` `hermes4405b()` `qwen38max()` `kimiK27Code()` `kimiK3()` `minimaxM27()` `minimaxM3()` `GLM45()` `GLM52()` `GLM53()` `GLM53Flash()`
+`deepseekPro()` uses `deepseek/deepseek-v4-pro-0813` through OpenRouter. Requires `OPENROUTER_API_KEY`; supports the DeepSeek effort mapping and `chain('deepseekPro@100')`. Base cost estimates per 1M tokens: $0.5808 input, $0.05808 cached input, $1.7424 output. Actual rates may change, including provider and time-based pricing.
+
+`museGlimmer30b()` `museSpark12()` `museSpark12c()` `museSpark13()` `museSpark13c()` `gptOss()` `qwen35397b()` `qwen36plus()` `qwen37plus()` `qwen3827b()` `qwen38flash()` `hermes470b()` `hermes4405b()` `qwen38max()` `kimiK27Code()` `kimiK3()` `minimaxM27()` `minimaxM3()` `GLM45()` `GLM52()` `GLM53()` `GLM53Flash()` `deepseekV41Flash()`
+
+`deepseekV41Flash()` selects `deepseek/deepseek-v4.1-flash` (text and image input) and requires `OPENROUTER_API_KEY`. It supports the DeepSeek effort mapping above, including `chain('deepseekV41Flash@100')`. Base cost estimates per 1M tokens: $0.15 input, $0.015 cached input, $0.60 output; actual OpenRouter pricing varies by provider and time.
 
 Muse Spark: the `c` suffix selects Contributor, where prompts and outputs may be used to improve Meta products. Without `c`, the standard tier is selected. Use `museSpark12c()` for the former `museSpark12()` Contributor behavior.
 
@@ -651,7 +681,7 @@ const model = ModelMix.new({
 
 ## Available Provider Classes
 
-`ModerationMix` `MixModeration` `MixOpenAI` `MixOpenAIResponses` `MixOpenAIModeration` `MixAnthropic` `MixGoogle` `MixPerplexity` `MixGroq` `MixTogether` `MixGrok` `MixOpenRouter` `MixOllama` `MixLMStudio` `MixCustom` `MixCerebras` `MixFireworks` `MixKimi` `MixMiniMax` `MixLambda`
+`ModerationMix` `MixModeration` `MixOpenAI` `MixOpenAIResponses` `MixOpenAIModeration` `MixAnthropic` `MixGoogle` `MixPerplexity` `MixGroq` `MixTogether` `MixGrok` `MixOpenRouter` `MixOllama` `MixLMStudio` `MixCustom` `MixCerebras` `MixFireworks` `MixKimi` `MixMiniMax` `MixDeepSeek` `MixLambda`
 
 ## Troubleshooting
 

package/test/deepseek.test.js

@@ -1,7 +1,279 @@
 const { expect } = require('chai');
-const { ModelMix } = require('../index.js');
+const nock = require('nock');
+const { ModelMix, MixDeepSeek, MixFireworks, MixOpenRouter } = require('../index.js');
 
 describe('DeepSeek Model Registration Tests', () => {
+    it('registers V4 Pro 0813 through OpenRouter and preserves caller settings', () => {
+        const model = ModelMix.new();
+        expect(model.deepseekPro({
+            options: { temperature: 0.5 },
+            config: { apiKey: 'test-key', effort: 100 }
+        })).to.equal(model);
+
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('deepseek/deepseek-v4-pro-0813');
+        expect(model.models[0].provider).to.be.instanceOf(MixOpenRouter);
+        expect(model.models[0].provider.options.temperature).to.equal(0.5);
+        expect(model.models[0].provider.config.effort).to.equal(100);
+    });
+
+    describe('DeepSeek V4 Pro 0813 requests', () => {
+        afterEach(() => nock.cleanAll());
+
+        for (const [effort, level] of [[0, undefined], [20, 'low'], [60, 'high'], [100, 'max'], [-1, undefined]]) {
+            it(`sends the exact model ID through chain() at effort ${effort} and accounts for cached input`, async () => {
+                const scope = nock('https://openrouter.ai')
+                    .post('/api/v1/chat/completions', body => {
+                        expect(body.model).to.equal('deepseek/deepseek-v4-pro-0813');
+                        expect(body.reasoning_effort).to.equal(level);
+                        expect(body.thinking).to.deep.equal(effort === -1
+                            ? undefined
+                            : { type: effort === 0 ? 'disabled' : 'enabled' });
+                        return true;
+                    })
+                    .reply(200, {
+                        model: 'deepseek/deepseek-v4-pro-0813',
+                        choices: [{ message: { role: 'assistant', content: 'ok' } }],
+                        usage: {
+                            prompt_tokens: 1000,
+                            completion_tokens: 100,
+                            prompt_tokens_details: { cached_tokens: 400 }
+                        }
+                    });
+                const model = ModelMix.new().chain(`deepseekPro@${effort}`).addText('Hello');
+
+                expect(await model.message()).to.equal('ok');
+                expect(scope.isDone()).to.equal(true);
+                expect(model.lastRaw.tokens).to.include({ input: 1000, cached: 400, output: 100 });
+                expect(model.lastRaw.tokens.cost).to.be.closeTo(0.000545952, 1e-12);
+            });
+        }
+    });
+
+    it('requires native credentials and accepts DEEPSEEK_API_KEY', () => {
+        const originalApiKey = process.env.DEEPSEEK_API_KEY;
+        try {
+            delete process.env.DEEPSEEK_API_KEY;
+            expect(() => new MixDeepSeek()).to.throw(/DEEPSEEK_API_KEY/);
+            process.env.DEEPSEEK_API_KEY = 'native-test-key';
+            const model = ModelMix.new().deepseekV41Flash({ mix: { deepseek: true, openrouter: false } });
+            expect(model.models).to.have.length(1);
+            expect(model.models[0].key).to.equal('deepseek-flash');
+            expect(model.models[0].provider.config.apiKey).to.equal('native-test-key');
+        } finally {
+            if (originalApiKey === undefined) delete process.env.DEEPSEEK_API_KEY;
+            else process.env.DEEPSEEK_API_KEY = originalApiKey;
+        }
+    });
+
+    it('registers DeepSeek V4.1 Flash through OpenRouter and preserves caller settings', () => {
+        const model = ModelMix.new();
+        expect(model.deepseekV41Flash({
+            options: { temperature: 0.5 },
+            config: { effort: 100 }
+        })).to.equal(model);
+
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('deepseek/deepseek-v4.1-flash');
+        expect(model.models[0].provider).to.be.instanceOf(MixOpenRouter);
+        expect(model.models[0].provider.options.temperature).to.equal(0.5);
+        expect(model.models[0].provider.config.effort).to.equal(100);
+    });
+
+    describe('DeepSeek V4.1 Flash requests', () => {
+        afterEach(() => nock.cleanAll());
+
+        it('falls back from native DeepSeek through Fireworks to OpenRouter', async () => {
+            const native = nock('https://api.deepseek.com')
+                .post('/chat/completions', body => body.model === 'deepseek-flash')
+                .reply(503, { error: { message: 'Unavailable' } });
+            const fireworks = nock('https://api.fireworks.ai')
+                .post('/inference/v1/chat/completions')
+                .reply(503, { error: { message: 'Unavailable' } });
+            const openrouter = nock('https://openrouter.ai')
+                .post('/api/v1/chat/completions')
+                .reply(200, { choices: [{ message: { content: 'fallback' } }] });
+            const model = ModelMix.new({ config: { retry: { retries: 0 } } })
+                .deepseekV41Flash({
+                    mix: { deepseek: true, fireworks: true, openrouter: true },
+                    config: { apiKey: 'test-key' }
+                }).addText('Hello');
+
+            expect(await model.message()).to.equal('fallback');
+            expect(native.isDone()).to.equal(true);
+            expect(fireworks.isDone()).to.equal(true);
+            expect(openrouter.isDone()).to.equal(true);
+        });
+
+        for (const [effort, level] of [[0, undefined], [20, 'low'], [60, 'high'], [100, 'max'], [-1, undefined]]) {
+            it(`sends native DeepSeek effort ${effort} and reads native cache usage`, async () => {
+                const scope = nock('https://api.deepseek.com', {
+                    reqheaders: { authorization: 'Bearer native-test-key' }
+                })
+                    .post('/chat/completions', body => {
+                        expect(body.model).to.equal('deepseek-flash');
+                        expect(body.reasoning_effort).to.equal(level);
+                        expect(body.thinking).to.deep.equal(effort === -1
+                            ? undefined
+                            : { type: effort === 0 ? 'disabled' : 'enabled' });
+                        return true;
+                    })
+                    .reply(200, {
+                        choices: [{ message: { role: 'assistant', content: 'ok', reasoning_content: 'Reasoning' } }],
+                        usage: { prompt_tokens: 1000, completion_tokens: 100, prompt_cache_hit_tokens: 400 }
+                    });
+                const model = ModelMix.new().deepseekV41Flash({
+                    mix: { deepseek: true, openrouter: false },
+                    config: { apiKey: 'native-test-key', effort }
+                }).addText('Hello');
+
+                expect(model.models).to.have.length(1);
+                expect(model.models[0].provider).to.be.instanceOf(MixDeepSeek);
+                expect(await model.message()).to.equal('ok');
+                expect(scope.isDone()).to.equal(true);
+                expect(model.lastRaw.tokens).to.include({ input: 1000, cached: 400, output: 100 });
+                expect(model.lastRaw.tokens.cost).to.be.closeTo(0.0003024, 1e-12);
+            });
+        }
+
+        it('preserves native reasoning across tool continuation and later turns', async () => {
+            const assistantMessage = {
+                role: 'assistant', content: null, reasoning_content: 'Use the lookup tool.',
+                tool_calls: [{ id: 'call_lookup', type: 'function', function: { name: 'lookup', arguments: '{}' } }]
+            };
+            const scope = nock('https://api.deepseek.com')
+                .post('/chat/completions')
+                .reply(200, { choices: [{ message: assistantMessage }] })
+                .post('/chat/completions', body => {
+                    expect(body.messages.find(message => message.role === 'assistant')).to.deep.equal(assistantMessage);
+                    expect(body.messages.find(message => message.role === 'tool')).to.include({ tool_call_id: 'call_lookup' });
+                    return true;
+                })
+                .reply(200, { choices: [{ message: { role: 'assistant', content: 'Found', reasoning_content: 'Lookup complete.' } }] })
+                .post('/chat/completions', body => {
+                    expect(body.messages.filter(message => message.role === 'assistant').map(message => message.reasoning_content))
+                        .to.deep.equal(['Use the lookup tool.', 'Lookup complete.']);
+                    return true;
+                })
+                .reply(200, { choices: [{ message: { role: 'assistant', content: 'Done' } }] });
+            const model = ModelMix.new().deepseekV41Flash({
+                mix: { deepseek: true, openrouter: false },
+                config: { apiKey: 'native-test-key' }
+            }).addTool({
+                name: 'lookup', description: 'Look up a value.',
+                inputSchema: { type: 'object', properties: {} }
+            }, () => 'value').addText('Look it up');
+
+            expect(await model.message()).to.equal('Found');
+            model.addText('Continue');
+            expect(await model.message()).to.equal('Done');
+            expect(scope.isDone()).to.equal(true);
+        });
+
+        it('streams native text without including empty reasoning or usage deltas', async () => {
+            const chunks = [
+                { choices: [{ delta: { reasoning_content: 'Reasoning' } }] },
+                { choices: [{ delta: { content: 'Hello' } }] },
+                { choices: [], usage: { prompt_tokens: 1000, completion_tokens: 100, prompt_cache_hit_tokens: 400 } }
+            ];
+            const scope = nock('https://api.deepseek.com')
+                .post('/chat/completions', body => body.stream === true)
+                .reply(200, chunks.map(chunk => `data: ${JSON.stringify(chunk)}\n\n`).join('') + 'data: [DONE]\n\n', {
+                    'content-type': 'text/event-stream'
+                });
+            const model = ModelMix.new().deepseekV41Flash({
+                mix: { deepseek: true, openrouter: false },
+                config: { apiKey: 'native-test-key' }
+            }).addText('Hello');
+            const deltas = [];
+            const result = await model.stream(({ delta }) => deltas.push(delta));
+
+            expect(result.message).to.equal('Hello');
+            expect(deltas.join('')).to.equal('Hello');
+            expect(result.tokens.cached).to.equal(400);
+            expect(scope.isDone()).to.equal(true);
+        });
+
+        it('uses only Fireworks when selected and accounts for its cached input pricing', async () => {
+            const scope = nock('https://api.fireworks.ai')
+                .post('/inference/v1/chat/completions', body => {
+                    expect(body.model).to.equal('accounts/fireworks/models/deepseek-v4p1-flash');
+                    expect(body.reasoning_effort).to.equal('max');
+                    expect(body.thinking).to.deep.equal({ type: 'enabled' });
+                    expect(body.temperature).to.equal(0.5);
+                    return true;
+                })
+                .reply(200, {
+                    choices: [{ message: { content: 'ok' } }],
+                    usage: {
+                        prompt_tokens: 1000,
+                        completion_tokens: 100,
+                        prompt_tokens_details: { cached_tokens: 400 }
+                    }
+                });
+            const model = ModelMix.new().deepseekV41Flash({
+                mix: { fireworks: true, openrouter: false },
+                config: { effort: 100 },
+                options: { temperature: 0.5 }
+            }).addText('Hello');
+
+            expect(model.models).to.have.length(1);
+            expect(model.models[0].provider).to.be.instanceOf(MixFireworks);
+            expect(await model.message()).to.equal('ok');
+            expect(scope.isDone()).to.equal(true);
+            expect(model.lastRaw.tokens).to.include({ input: 1000, cached: 400, output: 100 });
+            expect(model.lastRaw.tokens.cost).to.be.closeTo(0.0002008, 1e-12);
+        });
+
+        it('falls back from Fireworks to OpenRouter when both are enabled', async () => {
+            const fireworks = nock('https://api.fireworks.ai')
+                .post('/inference/v1/chat/completions')
+                .reply(503, { error: { message: 'Unavailable' } });
+            const openrouter = nock('https://openrouter.ai')
+                .post('/api/v1/chat/completions', body => body.model === 'deepseek/deepseek-v4.1-flash')
+                .reply(200, { choices: [{ message: { content: 'fallback' } }] });
+            const model = ModelMix.new({ config: { retry: { retries: 0 } } })
+                .deepseekV41Flash({ mix: { fireworks: true, openrouter: true } })
+                .addText('Hello');
+
+            expect(model.models.map(({ key }) => key)).to.deep.equal([
+                'accounts/fireworks/models/deepseek-v4p1-flash',
+                'deepseek/deepseek-v4.1-flash'
+            ]);
+            expect(await model.message()).to.equal('fallback');
+            expect(fireworks.isDone()).to.equal(true);
+            expect(openrouter.isDone()).to.equal(true);
+        });
+
+        for (const [effort, level] of [[0, null], [20, 'low'], [60, 'high'], [100, 'max'], [-1, undefined]]) {
+            it(`sends chain effort ${effort} and accounts for cached input`, async () => {
+                const scope = nock('https://openrouter.ai')
+                    .post('/api/v1/chat/completions', body => {
+                        expect(body.model).to.equal('deepseek/deepseek-v4.1-flash');
+                        expect(body.reasoning_effort).to.equal(level || undefined);
+                        expect(body.thinking).to.deep.equal(level === undefined
+                            ? undefined
+                            : { type: level === null ? 'disabled' : 'enabled' });
+                        return true;
+                    })
+                    .reply(200, {
+                        choices: [{ message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+                        usage: {
+                            prompt_tokens: 1000,
+                            completion_tokens: 100,
+                            prompt_tokens_details: { cached_tokens: 400 }
+                        }
+                    });
+
+                const model = ModelMix.new().chain(`deepseekV41Flash@${effort}`).addText('Hello');
+                expect(await model.message()).to.equal('ok');
+                expect(scope.isDone()).to.equal(true);
+                expect(model.lastRaw.tokens).to.include({ input: 1000, cached: 400, output: 100 });
+                expect(model.lastRaw.tokens.cost).to.be.closeTo(0.000156, 1e-12);
+            });
+        }
+    });
+
     it('should register Fireworks DeepSeek V4 Pro by default', () => {
         const model = ModelMix.new();
         model.deepseekV4Pro({ mix: { fireworks: true, openrouter: false } });

package/test/fallback.test.js

@@ -13,6 +13,63 @@ const {
 } = require('../index.js');
 
 describe('Provider Fallback Chain Tests', () => {
+
+    describe('Interrupted provider responses', () => {
+        const timeout = {
+            id: 'generation-timeout',
+            provider: 'Novita',
+            error: { code: 504, message: 'Upstream idle timeout exceeded', metadata: { error_type: 'timeout' } },
+            choices: [{ finish_reason: 'error', message: { content: '' } }]
+        };
+
+        it('rejects HTTP 200 error bodies with their status and generation details', async () => {
+            sinon.stub(global, 'fetch').resolves(new Response(JSON.stringify(timeout), { status: 200 }));
+            const model = ModelMix.new().deepseekV41Flash().addText('test');
+            let failure;
+            try { await model.raw(); } catch (error) { failure = error; }
+            expect(failure).to.include({ statusCode: 504, message: timeout.error.message });
+            expect(failure.details).to.include({ id: timeout.id, provider: 'Novita' });
+            expect(failure.details.error.metadata.error_type).to.equal('timeout');
+        });
+
+        it('retries HTTP 200 provider errors only under the configured policy', async () => {
+            const fetch = sinon.stub(global, 'fetch');
+            fetch.onFirstCall().resolves(new Response(JSON.stringify(timeout)));
+            fetch.onSecondCall().resolves(new Response(JSON.stringify({ choices: [{ finish_reason: 'stop', message: { content: 'recovered' } }] })));
+            const model = ModelMix.new({ config: { retry: { enabled: true, retries: 1, baseDelayMs: 0, maxDelayMs: 0 } } }).deepseekV41Flash().addText('test');
+            expect((await model.raw()).message).to.equal('recovered');
+            expect(fetch.callCount).to.equal(2);
+        });
+
+        it('falls back when a provider returns only reasoning without completing', async () => {
+            const fetch = sinon.stub(global, 'fetch');
+            fetch.onFirstCall().resolves(new Response(JSON.stringify({ choices: [{ finish_reason: null, message: { content: '', reasoning: 'partial' } }] })));
+            fetch.onSecondCall().resolves(new Response(JSON.stringify({ choices: [{ finish_reason: 'stop', message: { content: 'fallback' } }] })));
+            const model = ModelMix.new().deepseekV41Flash().gpt5mini().addText('test');
+            expect((await model.raw()).message).to.equal('fallback');
+            expect(fetch.callCount).to.equal(2);
+        });
+
+        it('rejects a streaming timeout instead of returning partial output', async () => {
+            const chunks = [
+                { choices: [{ delta: { content: 'partial' } }] },
+                timeout
+            ];
+            sinon.stub(global, 'fetch').resolves(new Response(chunks.map(chunk => `data: ${JSON.stringify(chunk)}\n\n`).join(''), { headers: { 'content-type': 'text/event-stream' } }));
+            const model = ModelMix.new().deepseekV41Flash().addText('test');
+            let failure;
+            try { await model.stream(() => {}); } catch (error) { failure = error; }
+            expect(failure).to.include({ statusCode: 504, message: timeout.error.message });
+        });
+
+        it('rejects an abruptly ended stream even after some text arrived', async () => {
+            sinon.stub(global, 'fetch').resolves(new Response('data: {"choices":[{"delta":{"content":"partial"},"finish_reason":null}]}\n\n'));
+            let failure;
+            try { await ModelMix.new().deepseekV41Flash().addText('test').stream(() => {}); } catch (error) { failure = error; }
+            expect(failure).to.include({ statusCode: 502 });
+            expect(failure.message).to.include('without completing');
+        });
+    });
     
     // Setup test hooks
     if (global.setupTestHooks) {