modelmix 5.0.2 → 5.0.3

package/index.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const { randomUUID } = require('crypto');
 const ejs = require('ejs');
 const fileType = require('file-type');
 const detectFileTypeFromBuffer = fileType.fileTypeFromBuffer || fileType.fromBuffer;
@@ -46,6 +47,34 @@ function isPlainObject(value) {
     return prototype === Object.prototype || prototype === null;
 }
 
+function clonePluginValue(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== 'object') return value;
+    if (Buffer.isBuffer(value)) return Buffer.from(value);
+    if (seen.has(value)) return seen.get(value);
+
+    if (Array.isArray(value)) {
+        const clone = [];
+        seen.set(value, clone);
+        for (const item of value) clone.push(clonePluginValue(item, seen));
+        return clone;
+    }
+
+    if (!isPlainObject(value)) return value;
+    const clone = {};
+    seen.set(value, clone);
+    for (const [key, item] of Object.entries(value)) {
+        clone[key] = clonePluginValue(item, seen);
+    }
+    return clone;
+}
+
+function validatePluginResult(result, pluginName) {
+    if (!isPlainObject(result)) {
+        throw new TypeError(`Plugin "${pluginName}" must return a ModelMixResult object.`);
+    }
+    return result;
+}
+
 function normalizeContentCache(cache) {
     if (cache !== undefined) {
         if (!isPlainObject(cache) || cache.breakpoint !== true) {
@@ -315,7 +344,8 @@ const MODEL_PRICING = {
     'gemini-3.1-pro-preview': { input: 2.00, output: 12.00 },
     'gemini-3-pro-preview': { input: 2.00, output: 12.00 },
     'gemini-3-flash-preview': { input: 0.50, output: 3.00 },
-    'gemini-3.6-flash': { input: 1.50, output: 7.50 },
+    'gemini-3.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 },
@@ -380,6 +410,7 @@ class ModelMix {
         this.toolClient = {};
         this.mcp = {};
         this.mcpToolsManager = new MCPToolsManager();
+        this.plugins = [];
         this.templateFileAssignments = new Map();
         this.messageTemplates = new WeakMap();
         this.lastRaw = null;
@@ -452,6 +483,23 @@ class ModelMix {
         return this;
     }
 
+    use(plugin) {
+        if (!isPlainObject(plugin)) {
+            throw new TypeError('plugin must be a plain object.');
+        }
+        if (typeof plugin.name !== 'string' || plugin.name.trim().length === 0) {
+            throw new TypeError('plugin.name must be a non-empty string.');
+        }
+        if (typeof plugin.execute !== 'function') {
+            throw new TypeError(`Plugin "${plugin.name}" must define execute(context, next).`);
+        }
+        if (this.plugins.some(current => current.name === plugin.name)) {
+            throw new Error(`Plugin "${plugin.name}" is already registered on this instance.`);
+        }
+        this.plugins.push(plugin);
+        return this;
+    }
+
     static new({ options = {}, config = {}, mix = {} } = {}) {
         return new ModelMix({ options, config, mix });
     }
@@ -467,6 +515,7 @@ class ModelMix {
             instance.systemTemplate = { ...this.systemTemplate };
         }
         instance.templateFileAssignments = new Map(this.templateFileAssignments);
+        instance.plugins = [...this.plugins];
         for (const key of Object.keys(config.templateData || {})) {
             instance.templateFileAssignments.delete(key);
         }
@@ -474,6 +523,102 @@ class ModelMix {
         return instance;
     }
 
+    _pluginsForPolicy(policy = 'inherit') {
+        if (policy === 'inherit') return [...this.plugins];
+        if (policy === 'none') return [];
+        if (!isPlainObject(policy)) {
+            throw new TypeError('plugins must be "inherit", "none", { include }, or { exclude }.');
+        }
+
+        const hasInclude = Object.prototype.hasOwnProperty.call(policy, 'include');
+        const hasExclude = Object.prototype.hasOwnProperty.call(policy, 'exclude');
+        if (hasInclude === hasExclude) {
+            throw new TypeError('plugins policy must define exactly one of include or exclude.');
+        }
+        const names = hasInclude ? policy.include : policy.exclude;
+        if (!Array.isArray(names) || names.some(name => typeof name !== 'string' || name.length === 0)) {
+            throw new TypeError('plugin include/exclude names must be non-empty strings.');
+        }
+        const uniqueNames = new Set(names);
+        const knownNames = new Set(this.plugins.map(plugin => plugin.name));
+        for (const name of uniqueNames) {
+            if (!knownNames.has(name)) {
+                throw new Error(`Plugin "${name}" is not registered on this instance.`);
+            }
+        }
+        return hasInclude
+            ? this.plugins.filter(plugin => uniqueNames.has(plugin.name))
+            : this.plugins.filter(plugin => !uniqueNames.has(plugin.name));
+    }
+
+    async _invokeChild(input, parentExecution) {
+        if (!isPlainObject(input)) {
+            throw new TypeError('Child invocation must be a plain object.');
+        }
+        if (input.history !== undefined && input.history !== false) {
+            throw new TypeError('Child invocations currently require history: false.');
+        }
+
+        const {
+            system,
+            systemFile,
+            assign,
+            messages = [],
+            tools = [],
+            options = {},
+            config = {},
+            mix = {},
+            model = this,
+            plugins = 'inherit',
+            outputMode = 'raw'
+        } = input;
+        if (!Array.isArray(messages)) {
+            throw new TypeError('Child invocation messages must be an array.');
+        }
+        if (system !== undefined && systemFile !== undefined) {
+            throw new TypeError('Child invocation must define only one of system or systemFile.');
+        }
+        if (systemFile !== undefined && (typeof systemFile !== 'string' || systemFile.length === 0)) {
+            throw new TypeError('Child invocation systemFile must be a non-empty string.');
+        }
+        if (assign !== undefined && !isPlainObject(assign)) {
+            throw new TypeError('Child invocation assign must be a plain object.');
+        }
+        if (!Array.isArray(tools)) {
+            throw new TypeError('Child invocation tools must be an array.');
+        }
+        if (!(model instanceof ModelMix)) {
+            throw new TypeError('Child invocation model must be a ModelMix instance.');
+        }
+
+        const child = model === this
+            ? ModelMix.new({ options, config, mix })
+            : model.new({ options, config, mix });
+        child.models = model.models;
+        child.plugins = this._pluginsForPolicy(plugins);
+        if (assign !== undefined) child.assign(assign);
+        if (system !== undefined) child.setSystem(system);
+        if (systemFile !== undefined) child.setSystemFromFile(systemFile);
+        child.messages = clonePluginValue(messages);
+        for (const tool of tools) {
+            if (!isPlainObject(tool) || !isPlainObject(tool.tool) || typeof tool.callback !== 'function') {
+                throw new TypeError('Child invocation tools must contain { tool, callback }.');
+            }
+            child.addTool(tool.tool, tool.callback);
+        }
+
+        const execution = {
+            executionId: randomUUID(),
+            parentExecutionId: parentExecution.executionId,
+            depth: parentExecution.depth + 1
+        };
+        const result = await child.execute({
+            outputMode,
+            _executionMetadata: execution
+        });
+        return { ...result, execution };
+    }
+
     static formatJSON(obj) {
         return inspect(obj, {
             depth: null,
@@ -500,10 +645,11 @@ class ModelMix {
         return str.length > maxLen ? str.substring(0, maxLen) + '...' : str;
     }
 
-    static normalizeTokenUsage({ input = 0, output = 0, total, cached = 0, cacheWrite = 0, cacheWrite5m = 0, cacheWrite1h = 0 } = {}) {
+    static 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);
@@ -513,7 +659,7 @@ class ModelMix {
         );
         const normalizedTotal = Number.isFinite(total)
             ? Math.max(0, total)
-            : normalizedInput + normalizedOutput;
+            : normalizedInput + normalizedOutput + normalizedThinking;
         const uncachedInput = Math.max(0, normalizedInput - normalizedCached - normalizedCacheWrite);
         const cacheHitRate = normalizedInput > 0
             ? Number((normalizedCached / normalizedInput).toFixed(4))
@@ -522,6 +668,7 @@ class ModelMix {
         return {
             input: normalizedInput,
             output: normalizedOutput,
+            thinking: normalizedThinking,
             total: normalizedTotal,
             cached: normalizedCached,
             cacheWrite: normalizedCacheWrite,
@@ -581,7 +728,9 @@ class ModelMix {
             cacheWrite: roundCost(genericCacheWriteCost + cacheWrite5mCost + cacheWrite1hCost),
             cacheWrite5m: cacheWrite5mCost,
             cacheWrite1h: cacheWrite1hCost,
-            output: roundCost(normalized.output * outputPerMillion * outputMultiplier / 1_000_000)
+            output: roundCost(
+                (normalized.output + normalized.thinking) * outputPerMillion * outputMultiplier / 1_000_000
+            )
         };
         breakdown.total = roundCost(
             breakdown.uncachedInput
@@ -837,6 +986,9 @@ class ModelMix {
     gemini3flash({ options = {}, config = {} } = {}) {
         return this.attach('gemini-3-flash-preview', new MixGoogle({ options, config }));
     }
+    gemini37flash({ options = {}, config = {} } = {}) {
+        return this.attach('gemini-3.7-flash', new MixGoogle({ options, config }));
+    }
     gemini36flash({ options = {}, config = {} } = {}) {
         return this.attach('gemini-3.6-flash', new MixGoogle({ options, config }));
     }
@@ -1192,7 +1344,7 @@ class ModelMix {
     }
 
     async message() {
-        let raw = await this.execute({ options: { stream: false } });
+        let raw = await this.execute({ options: { stream: false }, outputMode: 'message' });
         return raw.message;
     }
 
@@ -1228,7 +1380,7 @@ class ModelMix {
                 systemSuffix += "\n\nOutput JSON Escape: double quotes, backslashes, and control characters inside JSON strings.\nEnsure the output contains no comments.";
             }
         }
-        const { message } = await this.execute({ options, config, systemSuffix });
+        const { message } = await this.execute({ options, config, systemSuffix, outputMode: 'json' });
         const parsed = JSON.parse(this._extractBlock(message));
         return isArrayWrap ? parsed.out : parsed;
     }
@@ -1244,18 +1396,19 @@ class ModelMix {
             : '';
         const { message } = await this.execute({
             options: { stream: false },
-            systemSuffix
+            systemSuffix,
+            outputMode: 'block'
         });
         return this._extractBlock(message);
     }
 
     async raw() {
-        return this.execute({ options: { stream: false } });
+        return this.execute({ options: { stream: false }, outputMode: 'raw' });
     }
 
     async stream(callback) {
         this.streamCallback = callback;
-        return this.execute({ options: { stream: true } });
+        return this.execute({ options: { stream: true }, outputMode: 'stream' });
     }
 
     assignKeyFromFile(key, filePath) {
@@ -1474,22 +1627,25 @@ class ModelMix {
         return this.systemTemplate;
     }
 
-    async execute({ config = {}, options = {}, systemSuffix = '', _templateContext = null } = {}) {
-        if (!this.models || this.models.length === 0) {
-            throw new Error("No models specified. Use methods like .gpt5(), .sonnet46() first.");
-        }
-
+    async execute({
+        config = {},
+        options = {},
+        systemSuffix = '',
+        outputMode = 'raw',
+        _templateContext = null,
+        _pluginRequest = null,
+        _executionMetadata = null,
+        _pluginsApplied = false
+    } = {}) {
         const isRootExecution = _templateContext === null;
         const templateContext = _templateContext || createTemplateRenderContext(() => this._choiceRandom());
-        const execution = this.limiter.schedule(async () => {
-            const preparedMessages = await this.prepareMessages(templateContext);
 
+        if (!_pluginsApplied && this.plugins.length > 0) {
+            const preparedMessages = await this.prepareMessages(templateContext);
             if (preparedMessages.length === 0) {
                 throw new Error("No user messages have been added. Use addText(prompt), addTextFromFile(filePath), addImage(filePath), or addImageFromUrl(url) to add a prompt.");
             }
-
-            // Merge config to get final roundRobin value and retry settings
-            const finalConfig = {
+            const requestConfig = {
                 ...this.config,
                 ...config,
                 retry: {
@@ -1497,6 +1653,101 @@ class ModelMix {
                     ...(config.retry || {})
                 }
             };
+            const systemTemplate = this._resolveSystemTemplate(config, {});
+            const systemCacheKey = JSON.stringify([systemTemplate.filename, systemTemplate.source]);
+            if (!templateContext.renderedSystems.has(systemCacheKey)) {
+                templateContext.renderedSystems.set(
+                    systemCacheKey,
+                    this._renderTemplate(systemTemplate.source, {
+                        filename: systemTemplate.filename,
+                        label: 'system template'
+                    }, templateContext)
+                );
+            }
+            const request = {
+                system: templateContext.renderedSystems.get(systemCacheKey) + systemSuffix,
+                messages: clonePluginValue(preparedMessages),
+                options: clonePluginValue({ ...this.options, ...options }),
+                config: clonePluginValue(requestConfig),
+                outputMode
+            };
+            const executionMetadata = _executionMetadata || {
+                executionId: randomUUID(),
+                parentExecutionId: null,
+                depth: 0
+            };
+            let providerInvoked = false;
+
+            const dispatch = async index => {
+                if (index === this.plugins.length) {
+                    providerInvoked = true;
+                    return this.execute({
+                        config,
+                        options,
+                        systemSuffix,
+                        outputMode,
+                        _templateContext: templateContext,
+                        _pluginRequest: request,
+                        _executionMetadata: executionMetadata,
+                        _pluginsApplied: true
+                    });
+                }
+
+                const plugin = this.plugins[index];
+                let nextCalled = false;
+                const next = () => {
+                    if (nextCalled) {
+                        throw new Error(`Plugin "${plugin.name}" called next() multiple times.`);
+                    }
+                    nextCalled = true;
+                    return dispatch(index + 1);
+                };
+                const context = {
+                    request,
+                    execution: Object.freeze({ ...executionMetadata }),
+                    invoke: input => this._invokeChild(input, executionMetadata)
+                };
+                const result = await plugin.execute(context, next);
+                return validatePluginResult(result, plugin.name);
+            };
+
+            const result = await dispatch(0);
+            this.lastRaw = result;
+            if (!providerInvoked) {
+                if (this.config.max_history === 0) {
+                    this.messages = [];
+                } else if (result.message) {
+                    this._addText(result.message, { role: 'assistant' });
+                }
+            }
+            if (isRootExecution) this._commitTemplateRenderContext(templateContext);
+            return result;
+        }
+
+        if (!this.models || this.models.length === 0) {
+            throw new Error("No models specified. Use methods like .gpt5(), .sonnet46() first.");
+        }
+
+        const execution = this.limiter.schedule(async () => {
+            const preparedMessages = _pluginRequest
+                ? _pluginRequest.messages
+                : await this.prepareMessages(templateContext);
+
+            if (preparedMessages.length === 0) {
+                throw new Error("No user messages have been added. Use addText(prompt), addTextFromFile(filePath), addImage(filePath), or addImageFromUrl(url) to add a prompt.");
+            }
+
+            // Merge config to get final roundRobin value and retry settings
+            const finalConfig = _pluginRequest
+                ? _pluginRequest.config
+                : {
+                    ...this.config,
+                    ...config,
+                    retry: {
+                        ...(this.config.retry || {}),
+                        ...(config.retry || {})
+                    }
+                };
 
             // Try all models in order (first is primary, rest are fallbacks)
             const modelsToTry = this.models.map((model, index) => ({ model, index }));
@@ -1523,31 +1774,45 @@ class ModelMix {
                     ...providerInstance.options,
                     ...optionsTools,
                     ...options,
+                    ...(_pluginRequest?.options || {}),
                     model: currentModelKey
                 };
 
-                const currentConfig = {
-                    ...finalConfig,
-                    ...providerInstance.config,
-                    ...config,
-                    retry: {
-                        ...(finalConfig.retry || {}),
-                        ...(providerInstance.config?.retry || {}),
-                        ...(config.retry || {})
+                const currentConfig = _pluginRequest
+                    ? {
+                        ...providerInstance.config,
+                        ..._pluginRequest.config,
+                        retry: {
+                            ...(providerInstance.config?.retry || {}),
+                            ...(_pluginRequest.config.retry || {})
+                        }
                     }
-                };
-                const systemTemplate = this._resolveSystemTemplate(config, providerInstance.config);
-                const systemCacheKey = JSON.stringify([systemTemplate.filename, systemTemplate.source]);
-                if (!templateContext.renderedSystems.has(systemCacheKey)) {
-                    templateContext.renderedSystems.set(
-                        systemCacheKey,
-                        this._renderTemplate(systemTemplate.source, {
-                            filename: systemTemplate.filename,
-                            label: 'system template'
-                        }, templateContext)
-                    );
+                    : {
+                        ...finalConfig,
+                        ...providerInstance.config,
+                        ...config,
+                        retry: {
+                            ...(finalConfig.retry || {}),
+                            ...(providerInstance.config?.retry || {}),
+                            ...(config.retry || {})
+                        }
+                    };
+                if (_pluginRequest) {
+                    currentConfig.system = _pluginRequest.system;
+                } else {
+                    const systemTemplate = this._resolveSystemTemplate(config, providerInstance.config);
+                    const systemCacheKey = JSON.stringify([systemTemplate.filename, systemTemplate.source]);
+                    if (!templateContext.renderedSystems.has(systemCacheKey)) {
+                        templateContext.renderedSystems.set(
+                            systemCacheKey,
+                            this._renderTemplate(systemTemplate.source, {
+                                filename: systemTemplate.filename,
+                                label: 'system template'
+                            }, templateContext)
+                        );
+                    }
+                    currentConfig.system = templateContext.renderedSystems.get(systemCacheKey) + systemSuffix;
                 }
-                currentConfig.system = templateContext.renderedSystems.get(systemCacheKey) + systemSuffix;
 
                 // Grok 4.20 alias → reasoning / non-reasoning from unified effort
                 const resolvedModelKey = resolveGrok420ModelKey(
@@ -1641,11 +1906,14 @@ class ModelMix {
                     }
 
                     if (result.toolCalls && result.toolCalls.length > 0) {
+                        const toolMessages = _pluginRequest
+                            ? clonePluginValue(_pluginRequest.messages)
+                            : this.messages;
                         if (result.assistantMessage) {
-                            this.messages.push(result.assistantMessage);
+                            toolMessages.push(result.assistantMessage);
                         } else if (result.message) {
                             if (result.signature) {
-                                this.messages.push({
+                                toolMessages.push({
                                     role: "assistant", content: [{
                                         type: "thinking",
                                         // Empty string is valid (Anthropic display: "omitted").
@@ -1654,25 +1922,44 @@ class ModelMix {
                                     }]
                                 });
                             } else {
-                                this._addText(result.message, { role: "assistant" });
+                                toolMessages.push({
+                                    role: 'assistant',
+                                    content: [{ type: 'text', text: result.message }]
+                                });
                             }
                         }
 
                         if (!result.assistantMessage) {
-                            this.messages.push({ role: "assistant", content: null, tool_calls: result.toolCalls });
+                            toolMessages.push({ role: "assistant", content: null, tool_calls: result.toolCalls });
                         }
 
                         const toolResults = await this.processToolCalls(result.toolCalls);
                         for (const toolResult of toolResults) {
-                            this.messages.push({
+                            toolMessages.push({
                                 role: 'tool',
                                 tool_call_id: toolResult.tool_call_id,
                                 name: toolResult.name,
                                 content: toolResult.content
                             });
                         }
+                        this.messages = toolMessages;
 
-                        return this.execute({ options, config, systemSuffix, _templateContext: templateContext });
+                        const nextPluginRequest = _pluginRequest
+                            ? {
+                                ..._pluginRequest,
+                                messages: toolMessages
+                            }
+                            : null;
+                        return this.execute({
+                            options,
+                            config,
+                            systemSuffix,
+                            outputMode,
+                            _templateContext: templateContext,
+                            _pluginRequest: nextPluginRequest,
+                            _executionMetadata,
+                            _pluginsApplied
+                        });
                     }
 
                     // debug level 1: Just success indicator
@@ -3680,6 +3967,7 @@ class MixGoogle extends MixCustom {
             return ModelMix.normalizeTokenUsage({
                 input: data.usageMetadata.promptTokenCount || 0,
                 output: data.usageMetadata.candidatesTokenCount || 0,
+                thinking: data.usageMetadata.thoughtsTokenCount || 0,
                 total: data.usageMetadata.totalTokenCount,
                 cached: ModelMix.extractCacheTokens(data.usageMetadata),
                 cacheWrite: ModelMix.extractCacheWriteTokens(data.usageMetadata)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -75,6 +75,9 @@
     "test:live": "mocha test/live.test.js --timeout 10000 --require test/setup.js",
     "test:live.mcp": "mocha test/live.mcp.js --timeout 60000 --require test/setup.js",
     "test:tokens": "mocha test/tokens.test.js --timeout 10000 --require test/setup.js",
-    "test:offline": "mocha test/json.test.js test/fallback.test.js test/templates.test.js test/images.test.js test/bottleneck.test.js test/tokens.test.js test/history.test.js test/anthropic.test.js test/effort.test.js test/grok.test.js --timeout 10000 --require test/setup.js"
-  }
-}
+    "test:plugins": "mocha test/plugins.test.js --timeout 10000 --require test/setup.js",
+    "test:rlm": "mocha plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js",
+    "test:offline": "mocha test/json.test.js test/fallback.test.js test/templates.test.js test/images.test.js test/bottleneck.test.js test/tokens.test.js test/history.test.js test/anthropic.test.js test/effort.test.js test/grok.test.js test/plugins.test.js plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js"
+  },
+  "packageManager": "pnpm@11.18.0+sha512.33d83c77da82f49fba836925c6f1b841181ec3132b670639bd012f7075f5c7cf634c5f870147c19aae7478fac01df09d8892e880454896edd23ee9b33757563c"
+}