modelmix 5.2.0 → 5.2.2

package/README.md

@@ -193,6 +193,7 @@ ModelMix provides convenient shorthand methods for quickly accessing different A
 | `gemini35flash()` | Google | gemini-3.5-flash | [\$0.75][3] | [\$4.50][3] |
 | `gemini35flashLite()` | Google | gemini-3.5-flash-lite | [\$0.30][3] | [\$2.50][3] |
 | `gemini31flashLite()` | Google | gemini-3.1-flash-lite-preview | [\$0.25][3] | [\$1.50][3] |
+| `grok47()` | Grok | grok-4.7 | — | — |
 | `grok46()` | Grok | grok-4.6 | [\$2.00][6] | [\$6.00][6] |
 | `grok45()` | Grok | grok-4.5 | [\$2.00][6] | [\$6.00][6] |
 | `grok43()` | Grok | grok-4.3 | [\$1.25][6] | [\$2.50][6] |
@@ -1000,6 +1001,33 @@ Supported policies are `'inherit'`, `'none'`, `{ include: [...] }`, and `{ exclu
 
 Child `systemFile` templates use the same EJS engine, `assign()` data contract, and relative Markdown includes as ordinary ModelMix templates. Use either `system` or `systemFile`, not both.
 
+Plugins may append `{ tool, callback }` entries to `context.request.tools` using the same definitions as `addTools()`. These tools are available for that execution and its tool continuations, alongside registered local/MCP tools. They do not change the instance's tool registry. Duplicate names are rejected before calling a provider. Child invocations rebuild their tools through the selected plugins or explicit `tools` input.
+
+When plugins add tools, native `options.tools` entries are combined with registered and plugin tools; duplicate function names are rejected. OpenAI Responses converts function definitions and preserves tool calls, results, and accompanying reasoning across continuations.
+
+### Skills plugin
+
+The included plugin loads local [Agent Skills](https://agentskills.io/specification). Pass explicit skill directories or `SKILL.md` files:
+
+```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', './skills/research/SKILL.md'] }))
+    .addText('Use the writing skill to improve this paragraph: ...');
+
+console.log(await model.message());
+```
+
+`skills()` is asynchronous. Each file must have YAML frontmatter with non-empty string `name` and `description` fields; duplicate names and malformed files fail during loading. Relative paths resolve from `process.cwd()`.
+
+Only names and descriptions are appended to the system prompt. A model supporting tool calls can select a skill with `read_skill({ name })`, then load supporting UTF-8 text files with `read_skill({ name, path: 'references/style.md' })`. Full instructions are returned literally, including any EJS syntax. Existing system instructions and tools are preserved; `read_skill` is reserved while this plugin runs.
+
+Skill metadata and `SKILL.md` content are snapshots taken when creating the plugin; recreate it to reload edits. Supporting files are read on demand. Reads must stay inside the registered skill directory, including resolved symlinks. Files are returned in full, so callers should register appropriately sized, trusted skills. The plugin does not execute scripts, install tools, or grant permissions from `allowed-tools` metadata. Skills requiring additional capabilities need tools supplied by the application.
+
 ### Benchmark plugin
 
 The included benchmark plugin derives task-specific criteria, runs each configured model independently, and uses the other distinct models as anonymous judges. Model specifications use the same `shortcut@effort` syntax as `chain()`:

package/demo/benchmark.js

@@ -43,7 +43,7 @@ await mkdir(resultsDirectory, { recursive: true });
 for (const result of report.results) {
     if (result.response === null) continue;
     const filename = result.id.replace(/[^A-Za-z0-9_-]/g, '_');
-    const contents = `# ${result.id}\n\nScore: ${result.score === null ? 'N/A' : Number(result.score.toFixed(2))}\n\nEstimated generation cost (USD): ${result.responseMetrics?.cost ?? 'N/A'}\n\n---\n\n${result.response}\n`;
+    const contents = `# ${result.id}\n\nScore: ${result.score === null ? 'N/A' : Math.round(result.score * 10)}/100\n\nEstimated generation cost (USD): ${result.responseMetrics?.cost ?? 'N/A'}\n\n---\n\n${result.response}\n`;
     await writeFile(path.join(resultsDirectory, `${filename}.md`), contents, 'utf8');
 }
 
@@ -69,7 +69,7 @@ const ranking = report.results
         if (right.score === null) return -1;
         return right.score - left.score;
     })
-    .map(row => ({ ...row, score: row.score === null ? null : Number(row.score.toFixed(2)) }));
+    .map(row => ({ ...row, score: row.score === null ? null : Math.round(row.score * 10) }));
 
 console.table(ranking);
 if (report.errors.length > 0) {

package/demo/grok.js

@@ -13,7 +13,7 @@ const mmix = new ModelMix({
 });
 
 
-const r = await mmix.grok46()
+const r = await mmix.grok47()
     .addText('hi there!')
     .addText('do you like cats?')
     .raw();

package/index.d.ts

@@ -1,8 +1,3 @@
-/**
- * Type definitions for modelmix
- * @see https://github.com/clasen/ModelMix
- */
-
 export type MessageRole = 'user' | 'assistant' | 'system' | 'tool' | string;
 
 export type DebugLevel = 0 | 1 | 2 | 3 | 4;
@@ -258,6 +253,7 @@ export interface PluginExecutionContext {
   request: {
     system: string;
     messages: ChatMessage[];
+    tools: ToolWithCallback[];
     options: ModelMixOptions;
     config: ModelMixConfig;
     outputMode: ModelMixOutputMode;
@@ -499,6 +495,7 @@ export declare class ModelMix {
   sonar(args?: ModelAttachArgs): this;
 
   // Grok
+  grok47(args?: ModelAttachArgs): this;
   grok46(args?: ModelAttachArgs): this;
   grok45(args?: ModelAttachArgs): this;
   grok43(args?: ModelAttachArgs): this;

package/index.js

@@ -603,6 +603,9 @@ class ModelMix {
         return this.attach('sonar', new MixPerplexity({ options, config }));
     }
 
+    grok47({ options = {}, config = {} } = {}) {
+        return this.attach('grok-4.7', new MixGrok({ options, config }));
+    }
     grok46({ options = {}, config = {} } = {}) {
         return this.attach('grok-4.6', new MixGrok({ options, config }));
     }
@@ -1312,6 +1315,7 @@ class ModelMix {
         const request = {
             system: this._renderSystem(config, {}, systemSuffix, templateContext),
             messages: clonePluginValue(preparedMessages),
+            tools: [],
             options: clonePluginValue({ ...this.options, ...options }),
             config: clonePluginValue(this._mergeRequestConfig(config)),
             outputMode
@@ -1383,15 +1387,34 @@ class ModelMix {
         templateContext
     }) {
         const provider = currentModel.provider;
+        const tools = pluginRequest?.tools.length ? {
+            ...this.tools,
+            local: [...(this.tools.local || []), ...pluginRequest.tools.map(entry => entry.tool)]
+        } : this.tools;
+        const toolOptions = provider.getOptionsTools(tools);
         const currentOptions = {
             ...this.options,
             messages: preparedMessages,
             ...provider.options,
-            ...provider.getOptionsTools(this.tools),
+            ...toolOptions,
             ...options,
             ...(pluginRequest?.options || {}),
             model: currentModel.key
         };
+        if (pluginRequest?.tools.length && currentOptions.tools !== toolOptions.tools) {
+            if (!Array.isArray(currentOptions.tools)) {
+                throw new TypeError('Request options.tools must be an array when using plugin tools.');
+            }
+            currentOptions.tools = [...(toolOptions.tools || []), ...currentOptions.tools];
+            const names = new Set();
+            for (const tool of currentOptions.tools) {
+                for (const definition of tool.functionDeclarations || [tool.function || tool]) {
+                    if (!definition.name) continue;
+                    if (names.has(definition.name)) throw new Error(`Duplicate tool name: ${definition.name}`);
+                    names.add(definition.name);
+                }
+            }
+        }
         const currentConfig = pluginRequest
             ? {
                 ...provider.config,
@@ -1512,7 +1535,7 @@ class ModelMix {
         result.tokens.speed = elapsedSec > 0 ? Math.round(result.tokens.output / elapsedSec) : 0;
     }
 
-    async _continueToolCalls(result, pluginRequest, execution) {
+    async _continueToolCalls(result, pluginRequest, execution, pluginTools) {
         const originalMessages = this.messages;
         const toolMessages = pluginRequest
             ? clonePluginValue(pluginRequest.messages)
@@ -1540,7 +1563,7 @@ class ModelMix {
         if (!result.assistantMessage) {
             toolMessages.push({ role: 'assistant', content: null, tool_calls: result.toolCalls });
         }
-        const toolResults = await this.processToolCalls(result.toolCalls, execution.signal);
+        const toolResults = await this.processToolCalls(result.toolCalls, execution.signal, pluginTools);
         for (const toolResult of toolResults) {
             toolMessages.push({
                 role: 'tool',
@@ -1650,6 +1673,23 @@ class ModelMix {
         this._requirePreparedMessages(preparedMessages);
 
         const finalConfig = pluginRequest ? pluginRequest.config : this._mergeRequestConfig(config);
+        const pluginTools = pluginRequest ? new MCPToolsManager() : null;
+        if (pluginRequest) {
+            if (!Array.isArray(pluginRequest.tools)) {
+                throw new TypeError('Plugin request tools must be an array.');
+            }
+            const names = new Set(Object.values(this.tools).flat().map(tool => tool.name));
+            for (const entry of pluginRequest.tools) {
+                if (!isPlainObject(entry) || !isPlainObject(entry.tool)) {
+                    throw new TypeError('Plugin request tools must contain { tool, callback }.');
+                }
+                if (names.has(entry.tool.name)) {
+                    throw new Error(`Duplicate tool name: ${entry.tool.name}`);
+                }
+                pluginTools.registerTool(entry.tool, entry.callback);
+                names.add(entry.tool.name);
+            }
+        }
         const modelsToTry = this.models.map((model, index) => ({ model, index }));
         if (finalConfig.roundRobin && this.models.length > 1) {
             this.models.push(this.models.shift());
@@ -1695,7 +1735,7 @@ class ModelMix {
                         _templateContext: templateContext,
                         _executionMetadata: executionMetadata,
                         _pluginsApplied: pluginsApplied
-                    });
+                    }, pluginTools);
                 }
 
                 this._logProviderSuccess(result, providerAttempt.currentConfig);
@@ -1771,7 +1811,7 @@ class ModelMix {
         if (isRootExecution) this._commitTemplateRenderContext(templateContext);
         return result;
     }
-    async processToolCalls(toolCalls, signal) {
+    async processToolCalls(toolCalls, signal, pluginTools) {
         assertAbortSignal(signal);
         const result = []
 
@@ -1804,8 +1844,9 @@ class ModelMix {
                 }
 
                 // Verificar si es una herramienta local registrada
-                if (this.mcpToolsManager.hasTool(toolName)) {
-                    const response = await this.mcpToolsManager.executeTool(toolName, toolArgs, signal);
+                if (pluginTools?.hasTool(toolName) || this.mcpToolsManager.hasTool(toolName)) {
+                    const manager = pluginTools?.hasTool(toolName) ? pluginTools : this.mcpToolsManager;
+                    const response = await manager.executeTool(toolName, toolArgs, signal);
                     throwIfAborted(signal);
                     result.push({
                         name: toolName,

package/lib/model-chain.js

@@ -9,7 +9,7 @@ const CHAIN_MODEL_SHORTCUTS = new Set([
     'sonnet50', 'sonnet5', 'sonnet46', 'sonnet45', 'haiku45',
     'gemini31pro', 'gemini38flash', 'gemini37flash', 'gemini36flash', 'gemini35flash',
     'gemini35flashLite', 'gemini31flashLite', 'sonarPro', 'sonar',
-    'grok46', 'grok45', 'grok43', 'grok420multiAgent', 'grok420',
+    'grok47', 'grok46', 'grok45', 'grok43', 'grok420multiAgent', 'grok420',
     'museGlimmer30b', 'museSpark12', 'museSpark12c', 'museSpark13', 'museSpark13c',
     'qwen35397b', 'qwen36plus', 'qwen37plus', 'qwen38max', 'qwen3827b', 'qwen38flash',
     'hermes470b', 'hermes4405b', 'hermes3',

package/lib/providers/openai.js

@@ -54,6 +54,17 @@ function createOpenAIProviders({
     
             if (options.reasoning_effort) request.reasoning = { effort: options.reasoning_effort };
             if (options.verbosity) request.text = { verbosity: options.verbosity };
+            if (options.tools !== undefined) {
+                request.tools = options.tools.map(tool => tool.type === 'function' && tool.function
+                    ? { type: 'function', strict: false, ...tool.function }
+                    : tool);
+            }
+            if (options.tool_choice !== undefined) {
+                request.tool_choice = options.tool_choice?.function
+                    ? { type: 'function', name: options.tool_choice.function.name }
+                    : options.tool_choice;
+            }
+            if (options.parallel_tool_calls !== undefined) request.parallel_tool_calls = options.parallel_tool_calls;
     
             if (options.response_format) {
                 const rf = options.response_format;
@@ -138,10 +149,25 @@ function createOpenAIProviders({
         static processResponsesResponse(response) {
             MixCustom.assertResponse(response.data);
             const message = MixOpenAIResponses.extractResponsesMessage(response.data);
+            const toolCalls = (response.data.output || [])
+                .filter(item => item.type === 'function_call')
+                .map(item => ({
+                    id: item.call_id,
+                    type: 'function',
+                    function: { name: item.name, arguments: item.arguments }
+                }));
             return {
                 message,
                 think: null,
-                toolCalls: [],
+                toolCalls,
+                ...(toolCalls.length > 0 && {
+                    assistantMessage: {
+                        role: 'assistant',
+                        content: message || null,
+                        tool_calls: toolCalls,
+                        _responsesOutput: response.data.output
+                    }
+                }),
                 tokens: MixOpenAIResponses.extractResponsesTokens(response.data),
                 response: response.data
             };
@@ -179,7 +205,14 @@ function createOpenAIProviders({
     
             for (const message of messages) {
                 if (!message || !message.role) continue;
-                if (message.tool_calls || message.role === 'tool') continue;
+                if (message.role === 'assistant' && Array.isArray(message._responsesOutput)) {
+                    mapped.push(...message._responsesOutput);
+                    continue;
+                }
+                if (message.role === 'tool') {
+                    mapped.push({ type: 'function_call_output', call_id: message.tool_call_id, output: message.content });
+                    continue;
+                }
     
                 const content = [];
                 const isAssistant = message.role === 'assistant';
@@ -234,11 +267,18 @@ function createOpenAIProviders({
                     }
                 }
     
-                if (content.length === 0) continue;
-                mapped.push({
-                    role: message.role,
-                    content
-                });
+                if (content.length > 0) {
+                    mapped.push({ role: message.role, content });
+                }
+                for (const call of message.tool_calls || []) {
+                    const args = call.function ? call.function.arguments : call.input ?? call.arguments ?? {};
+                    mapped.push({
+                        type: 'function_call',
+                        call_id: call.id,
+                        name: call.function ? call.function.name : call.name,
+                        arguments: typeof args === 'string' ? args : JSON.stringify(args)
+                    });
+                }
             }
     
             return mapped;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "5.2.0",
+  "version": "5.2.2",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -56,6 +56,7 @@
     "bottleneck": "^2.19.5",
     "ejs": "6.0.1",
     "file-type": "^21.3.4",
+    "js-yaml": "4.3.2",
     "lemonlog": "^1.2.2",
     "ws": "^8.21.1"
   },
@@ -77,8 +78,9 @@
     "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:plugins": "mocha test/plugins.test.js --timeout 10000 --require test/setup.js",
+    "test:skills": "mocha plugins/skills/test/**/*.test.js --timeout 10000 --require test/setup.js",
     "test:benchmark": "mocha plugins/benchmark/test/**/*.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/abort.test.js 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/google.test.js test/moderation.test.js test/plugins.test.js plugins/benchmark/test/**/*.test.js plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js"
+    "test:offline": "mocha test/abort.test.js 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/google.test.js test/moderation.test.js test/plugins.test.js plugins/skills/test/**/*.test.js plugins/benchmark/test/**/*.test.js plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js"
   }
 }

package/plugins/skills/index.d.ts

@@ -0,0 +1,9 @@
+import type { ModelMixPlugin } from '../..';
+
+export interface SkillsOptions {
+  /** Explicit skill directories or SKILL.md files, resolved relative to process.cwd(). */
+  paths: string[];
+}
+
+/** Load local skill metadata and expose instructions and references through read_skill. */
+export declare function skills(options: SkillsOptions): Promise<ModelMixPlugin>;

package/plugins/skills/index.js

@@ -0,0 +1,107 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const yaml = require('js-yaml');
+
+async function resolveFile(root, relativePath, signal) {
+    signal?.throwIfAborted();
+    if (typeof relativePath !== 'string' || !relativePath || path.isAbsolute(relativePath)) {
+        throw new TypeError('Skill file path must be a non-empty relative path.');
+    }
+    const filename = await fs.realpath(path.resolve(root, relativePath));
+    const relative = path.relative(root, filename);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error('Skill file path must stay inside the skill directory.');
+    }
+    if (!(await fs.stat(filename)).isFile()) {
+        throw new Error('Skill file path must point to a regular file.');
+    }
+    return filename;
+}
+
+async function readText(filename, signal) {
+    const buffer = await fs.readFile(filename, { signal });
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+    if (text.includes('\0')) throw new Error('Skill files must contain UTF-8 text.');
+    return text;
+}
+
+function parseSkill(source, filename) {
+    const match = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (!match) throw new Error(`Missing YAML frontmatter in ${filename}.`);
+    const metadata = yaml.load(match[1], { schema: yaml.JSON_SCHEMA, filename });
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+        throw new Error(`Skill frontmatter must be a mapping in ${filename}.`);
+    }
+    for (const field of ['name', 'description']) {
+        if (typeof metadata[field] !== 'string' || !metadata[field].trim()) {
+            throw new Error(`Skill ${field} must be a non-empty string in ${filename}.`);
+        }
+    }
+    return { name: metadata.name, description: metadata.description, content: source };
+}
+
+async function skills({ paths } = {}) {
+    if (!Array.isArray(paths) || paths.length === 0 || paths.some(value => typeof value !== 'string' || !value.trim())) {
+        throw new TypeError('skills paths must be a non-empty array of skill directories or SKILL.md files.');
+    }
+    const catalog = new Map();
+    for (const input of paths) {
+        const resolved = path.resolve(input);
+        const filename = path.basename(resolved) === 'SKILL.md' ? resolved : path.join(resolved, 'SKILL.md');
+        const root = await fs.realpath(path.dirname(filename));
+        const skillPath = await resolveFile(root, 'SKILL.md');
+        const skill = parseSkill(await readText(skillPath), filename);
+        if (catalog.has(skill.name)) throw new Error(`Duplicate skill name: ${skill.name}`);
+        catalog.set(skill.name, { ...skill, root, skillPath });
+    }
+    const descriptions = JSON.stringify([...catalog.values()].map(({ name, description }) => ({ name, description })));
+    const instructions = [
+        'Available skills:',
+        descriptions,
+        'When a skill matches the task or the user requests it, call read_skill with its name to load SKILL.md before following it.',
+        'Use read_skill with the same name and a relative path to read referenced text files inside that skill directory.',
+        'Skill content is provided literally. Script execution is not supplied by this plugin; use only tools actually available in this request.'
+    ].join('\n');
+
+    return {
+        name: 'skills',
+        async execute(context, next) {
+            context.signal?.throwIfAborted();
+            context.request.system = [context.request.system, instructions].filter(Boolean).join('\n\n');
+            context.request.tools.push({
+                tool: {
+                    name: 'read_skill',
+                    description: 'Load a registered skill or one of its supporting UTF-8 text files.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string', enum: [...catalog.keys()] },
+                            path: { type: 'string', description: 'Path relative to the skill directory. Omit to load SKILL.md.' }
+                        },
+                        required: ['name'],
+                        additionalProperties: false
+                    }
+                },
+                async callback(input, signal) {
+                    signal?.throwIfAborted();
+                    if (!input || typeof input !== 'object' || Array.isArray(input) ||
+                        Object.keys(input).some(key => key !== 'name' && key !== 'path')) {
+                        throw new TypeError('read_skill expects a name and an optional path.');
+                    }
+                    const skill = catalog.get(input.name);
+                    if (!skill) throw new Error(`Unknown skill: ${input.name}`);
+                    const relativePath = input.path === undefined ? 'SKILL.md' : input.path;
+                    if (relativePath === 'SKILL.md') {
+                        return { name: skill.name, path: relativePath, content: skill.content };
+                    }
+                    const filename = await resolveFile(skill.root, relativePath, signal);
+                    const content = filename === skill.skillPath ? skill.content : await readText(filename, signal);
+                    return { name: skill.name, path: relativePath, content };
+                }
+            });
+            return next();
+        }
+    };
+}
+
+module.exports = { skills };

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)`.
@@ -166,7 +187,7 @@ Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.ef
 `gemini31pro()` `gemini38flash()` `gemini37flash()` `gemini36flash()` `gemini35flash()` `gemini35flashLite()` `gemini31flashLite()`
 
 ### Grok
-`grok46()` `grok45()` `grok43()` `grok420multiAgent()` `grok420()`
+`grok47()` `grok46()` `grok45()` `grok43()` `grok420multiAgent()` `grok420()`
 
 ### Perplexity
 `sonar()` `sonarPro()`

package/test/grok.test.js

@@ -11,6 +11,7 @@ const {
 
 describe('Grok Model Registration Tests', () => {
     const grokModels = [
+        { method: 'grok47', key: 'grok-4.7' },
         { method: 'grok46', key: 'grok-4.6' },
         { method: 'grok45', key: 'grok-4.5' },
         { method: 'grok43', key: 'grok-4.3' },
@@ -38,6 +39,38 @@ describe('Grok Model Registration Tests', () => {
         expect(model.models[0].provider.config).to.include(config);
     });
 
+    it('supports Grok 4.7 in chain() and preserves attachment options', () => {
+        const options = { temperature: 0.5 };
+        const config = { max_history: 3 };
+        const model = ModelMix.new().grok47({ options, config });
+
+        expect(model.models[0].provider).to.be.instanceOf(MixGrok);
+        expect(model.models[0].provider.options).to.deep.equal(options);
+        expect(model.models[0].provider.config).to.include(config);
+        expect(ModelMix.new().chain('grok47').models[0].key).to.equal('grok-4.7');
+    });
+
+    it('sends Grok 4.7 requests to xAI', async () => {
+        const api = nock('https://api.x.ai')
+            .post('/v1/chat/completions', body => {
+                expect(body.model).to.equal('grok-4.7');
+                expect(body.temperature).to.equal(0.5);
+                return true;
+            })
+            .reply(200, {
+                choices: [{ message: { content: 'ok' } }],
+                usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 }
+            });
+
+        const response = await ModelMix.new()
+            .grok47({ options: { temperature: 0.5 }, config: { apiKey: 'test-key' } })
+            .addText('Hi')
+            .message();
+
+        expect(response).to.equal('ok');
+        api.done();
+    });
+
     it('maps unified effort to Grok 4.6 supported levels', () => {
         expect(mapEffort('openai', 0, 'grok-4.6')).to.deep.equal({ reasoning_effort: 'low' });
         expect(mapEffort('openai', 39, 'grok-4.6')).to.deep.equal({ reasoning_effort: 'low' });

package/test/plugins.test.js

@@ -1,6 +1,8 @@
 const { expect } = require('chai');
 const path = require('path');
-const { MixCustom, ModelMix } = require('../index.js');
+const nock = require('nock');
+const { MixCustom, MixOpenAIResponses, MixAnthropic, MixGoogle, ModelMix } = require('../index.js');
+const { skills } = require('../plugins/skills');
 
 function createProvider(handler = async () => ({ message: 'provider', toolCalls: [] })) {
     const provider = new MixCustom();
@@ -9,6 +11,153 @@ function createProvider(handler = async () => ({ message: 'provider', toolCalls:
 }
 
 describe('ModelMix plugins', () => {
+    it('runs a native Responses skill loop including reasoning and parallel tool outputs', async () => {
+        const requests = [];
+        const output = [
+            { type: 'reasoning', id: 'rs_skill', summary: [], encrypted_content: 'opaque-reasoning' },
+            { type: 'message', id: 'msg_skill', role: 'assistant', content: [{ type: 'output_text', text: 'Reading the skill.' }] },
+            { type: 'function_call', id: 'fc_skill', call_id: 'call_skill', name: 'read_skill', arguments: JSON.stringify({ name: 'modelmix' }) },
+            { type: 'function_call', id: 'fc_local', call_id: 'call_local', name: 'local_tool', arguments: '{"value":7}' }
+        ];
+        const scope = nock('https://api.openai.com')
+            .post('/v1/responses', body => { requests.push(body); return true; })
+            .reply(200, { output })
+            .post('/v1/responses', body => { requests.push(body); return true; })
+            .reply(200, { output: [{ type: 'message', content: [{ type: 'output_text', text: 'Done.' }] }] });
+        try {
+            const model = ModelMix.new({ config: { bottleneck: { minTime: 0 } } }).gpt6astra()
+                .addTool({ name: 'local_tool', description: 'Local tool', inputSchema: { type: 'object' } }, input => `value=${input.value}`)
+                .use(await skills({ paths: [path.join(__dirname, '../skills/modelmix')] }))
+                .addText('Use the modelmix skill.');
+            expect(await model.message()).to.equal('Done.');
+            expect(scope.isDone()).to.equal(true);
+            for (const request of requests) {
+                expect(request.tools.map(tool => tool.name)).to.have.members(['local_tool', 'read_skill']);
+                const skillTool = request.tools.find(tool => tool.name === 'read_skill');
+                expect(skillTool.strict).to.equal(false);
+                expect(skillTool.parameters.required).to.deep.equal(['name']);
+            }
+            expect(requests[1].input.slice(2, 6)).to.deep.equal(output);
+            const results = requests[1].input.filter(item => item.type === 'function_call_output');
+            expect(results.map(item => item.call_id)).to.deep.equal(['call_skill', 'call_local']);
+            expect(JSON.parse(results[0].output).content).to.include('name: modelmix');
+            expect(results[1].output).to.equal('value=7');
+        } finally {
+            nock.cleanAll();
+        }
+    });
+
+    it('converts neutral tool history and native Responses tool options', () => {
+        const request = MixOpenAIResponses.buildResponsesRequest({
+            tools: [{ type: 'web_search' }, { type: 'function', function: { name: 'lookup', parameters: { type: 'object' }, strict: true } }],
+            tool_choice: { type: 'function', function: { name: 'lookup' } },
+            parallel_tool_calls: false,
+            messages: [
+                { role: 'assistant', content: 'Checking.', tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'lookup', arguments: '{"query":"test"}' } }] },
+                { role: 'tool', tool_call_id: 'call_1', content: 'Found.' }
+            ]
+        });
+        expect(request.tools).to.deep.equal([{ type: 'web_search' }, { type: 'function', name: 'lookup', parameters: { type: 'object' }, strict: true }]);
+        expect(request.tool_choice).to.deep.equal({ type: 'function', name: 'lookup' });
+        expect(request.parallel_tool_calls).to.equal(false);
+        expect(request.input).to.deep.equal([
+            { role: 'assistant', content: [{ type: 'output_text', text: 'Checking.' }] },
+            { type: 'function_call', call_id: 'call_1', name: 'lookup', arguments: '{"query":"test"}' },
+            { type: 'function_call_output', call_id: 'call_1', output: 'Found.' }
+        ]);
+    });
+
+    for (const Provider of [MixCustom, MixAnthropic, MixGoogle]) {
+        for (const hasExplicitTool of [false, true]) {
+            it(`preserves plugin and registered tools with ${Provider.name} options.tools (${hasExplicitTool ? 'populated' : 'empty'})`, async () => {
+                const registered = { name: 'registered', description: 'Registered tool', inputSchema: { type: 'object' } };
+                const extra = { ...registered, name: 'explicit' };
+                const provider = new Provider();
+                const explicitTools = hasExplicitTool ? provider.getOptionsTools({ local: [extra] }).tools : [];
+                let received;
+                provider.create = async ({ options }) => { received = options.tools; return { message: 'done', toolCalls: [] }; };
+                const model = ModelMix.new({ options: { tools: explicitTools } }).attach('custom', provider)
+                    .addTool(registered, () => 'registered')
+                    .use(await skills({ paths: [path.join(__dirname, '../skills/modelmix')] })).addText('Use skills');
+                await model.message();
+                const names = received.flatMap(tool => tool.functionDeclarations || [tool.function || tool]).map(tool => tool.name);
+                expect(names).to.have.members(['registered', 'read_skill', ...(hasExplicitTool ? ['explicit'] : [])]);
+                expect(model.options.tools).to.deep.equal(explicitTools);
+            });
+        }
+    }
+
+    it('rejects collisions between explicit options and plugin tools before calling the provider', async () => {
+        let calls = 0;
+        const model = ModelMix.new({ options: { tools: [{ type: 'function', function: { name: 'read_skill' } }] } })
+            .attach('custom', createProvider(async () => { calls++; return { message: 'unexpected' }; }))
+            .use(await skills({ paths: [path.join(__dirname, '../skills/modelmix')] })).addText('test');
+        let failure;
+        try { await model.message(); } catch (error) { failure = error; }
+        expect(failure?.message).to.include('Duplicate tool name: read_skill');
+        expect(calls).to.equal(0);
+    });
+
+    it('keeps plugin tools request-scoped across tool continuations and alongside local tools', async () => {
+        const requests = [];
+        const signal = new AbortController().signal;
+        const provider = createProvider(async request => {
+            requests.push(request);
+            if (requests.length === 1) return {
+                message: '',
+                toolCalls: [
+                    { id: 'skill', name: 'read_skill', input: {} },
+                    { id: 'local', name: 'local_tool', input: {} }
+                ]
+            };
+            return { message: 'done', toolCalls: [] };
+        });
+        const model = ModelMix.new().attach('custom', provider)
+            .addTool({ name: 'local_tool', description: 'Local tool', inputSchema: { type: 'object' } }, () => 'local')
+            .use({
+                name: 'skills-test',
+                async execute(context, next) {
+                    context.request.tools.push({
+                        tool: { name: 'read_skill', description: 'Read skill', inputSchema: { type: 'object' } },
+                        callback: (_args, callbackSignal) => {
+                            expect(callbackSignal).to.equal(signal);
+                            return 'skill instructions';
+                        }
+                    });
+                    return next();
+                }
+            }).addText('Use both tools');
+
+        expect(await model.message(signal)).to.equal('done');
+        expect(requests).to.have.length(2);
+        for (const request of requests) {
+            expect(request.options.tools.map(tool => tool.function.name)).to.have.members(['local_tool', 'read_skill']);
+        }
+        const results = requests[1].options.messages.filter(message => message.role === 'tool');
+        expect(results.map(result => result.content)).to.deep.equal(['skill instructions', 'local']);
+        expect(model.mcpToolsManager.hasTool('read_skill')).to.equal(false);
+        expect(model.tools.local.map(tool => tool.name)).to.deep.equal(['local_tool']);
+    });
+
+    it('rejects collisions between plugin tools and existing tools before calling a provider', async () => {
+        let calls = 0;
+        const tool = { name: 'same', description: 'Same tool', inputSchema: { type: 'object' } };
+        const model = ModelMix.new().attach('custom', createProvider(async () => {
+            calls += 1;
+            return { message: 'unexpected' };
+        })).addTool(tool, () => 'local').use({
+            name: 'collision',
+            async execute(context, next) {
+                context.request.tools.push({ tool, callback: () => 'plugin' });
+                return next();
+            }
+        }).addText('test');
+        let failure;
+        try { await model.message(); } catch (error) { failure = error; }
+        expect(failure?.message).to.include('Duplicate tool name: same');
+        expect(calls).to.equal(0);
+    });
+
     it('keeps registration instance-scoped and lets new instances inherit plugins without history', () => {
         const plugin = { name: 'metrics', execute: (_context, next) => next() };
         const parent = ModelMix.new().use(plugin).addText('parent history');