tachibot-mcp 2.22.0 → 2.23.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to TachiBot MCP will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.23.1] - 2026-06-11
+
+### Changed
+- **MiniMax M2.7 → M3** (`minimax/minimax-m3`, released May 31 on OpenRouter, API-verified via grok_search): 1M-token context (up from 200K), MSA sparse attention (~1/20 compute at 1M ctx vs prior gen), native multimodal, tuned for long-horizon agentic work. Same promo pricing as M2.7 ($0.30/$1.20 per M). Powers `minimax_code`, `minimax_agent`, and the `minimax` juror. M2.7 kept as quota fallback via `MODEL_FALLBACKS`.
+
+## [2.23.0] - 2026-06-11
+
+### Changed
+- **Tool registration via central scan registry** — merged the tool-standardization refactor (PR #5): all provider tools register through `src/tools/registry.ts` + `defineModelTool` factory, with golden wire-contract tests (57 tool schemas snapshot-locked) and a plop `add-tool` generator. No behavior change; the registered tool surface is byte-identical.
+- **Jury: removed the `hermes` juror** — it was a persona variant of `local` calling the same `LOCAL_LLM_MODEL` weights while claiming "You are Hermes" (a false-role prompt). Council-reviewed rationale: jury independence comes from different model weights, not different system prompts on the same backend. `hermes` is kept as a **legacy alias** of `local`; panels are deduped after alias mapping, so `jurors: "hermes,local"` now yields one local vote instead of two correlated ones. 12 jurors total.
+- Docs now describe the Hermes connection honestly (verified via grok_search against Nous docs/GitHub): the local juror runs whatever `LOCAL_LLM_MODEL` points at, e.g. a Nous Hermes build via Ollama. The Hermes *agent* is model-agnostic — it consumes 300+ backends (GPT, Claude, Gemini, self-hosted Ollama/vLLM); it is not an OpenAI-compatible endpoint to point `LOCAL_LLM_BASE_URL` at.
+
 ## [2.22.0] - 2026-06-10
 
 ### Added

package/CONTRIBUTING.md

@@ -47,6 +47,10 @@ Use the issue templates and include:
 - Open a [Discussion](https://github.com/pavveu/tachibot-mcp/discussions)
 - Create an issue
 
+## Adding a tool
+
+Run `npm run add-tool` and answer the prompts (provider, wire name, description). It scaffolds a `defineModelTool(...)` in the provider file at the `// plop:tools`/`// plop:register` anchors and a test stub. Fill in the `parameters` and `execute` TODOs. The emitted-schema golden test (`npm run test:golden`) guards the tool-name/schema wire contract.
+
 ## License
 
 By submitting code to this project, you agree that your contributions will be licensed under the AGPL-3.0 license and you grant Pawel Pawlowski the right to relicense your contributions under alternative licenses (including commercial licenses).

package/README.md

@@ -12,7 +12,7 @@
 
 **57 AI tools. 12 providers. One protocol.**
 
-Orchestrate Perplexity, Grok, GPT-5, Gemini, Qwen, Kimi K2.5, and MiniMax M2.5
+Orchestrate Perplexity, Grok, GPT-5.5, Gemini, Qwen, Kimi K2.6, and MiniMax M3
 from Claude Code, Claude Desktop, Cursor, or any MCP client.
 
 [Get Started](#-quick-start) · [View Tools](#-tool-ecosystem-57-tools) · [Documentation](https://tachibot.com/docs)
@@ -202,7 +202,7 @@ See [Installation Guide](docs/INSTALLATION_BOTH.md) for detailed instructions.
 `list_prompt_techniques` · `preview_prompt_technique` · `execute_prompt_technique`
 
 ### Local Models (1)
-`local_query` — any OpenAI-compatible local server (Ollama / LM Studio / llama.cpp / vLLM). Zero-cost, offline, private; also available as `hermes`/`local` jury jurors.
+`local_query` — any OpenAI-compatible local server (Ollama / LM Studio / llama.cpp / vLLM). Zero-cost, offline, private; also available as the `local` jury juror (`hermes` is accepted as a legacy alias). Runs whatever `LOCAL_LLM_MODEL` points at — e.g. a Nous Hermes build (`ollama pull hermes3`). Note the [Hermes agent](https://hermes-agent.nousresearch.com) itself is model-agnostic — it runs on 300+ backends (GPT, Claude, Gemini, DeepSeek, or self-hosted Ollama/vLLM) — so "Hermes" was never a guarantee of distinct weights.
 
 ### Advanced Modes (bonus)
 - **Challenger** — Critical analysis with multi-model fact-checking

package/dist/src/config/model-constants.js

@@ -95,9 +95,10 @@ export const KIMI_MODELS = {
     K2_5: "moonshotai/kimi-k2.5", // Previous: multimodal + agent swarm (fallback)
 };
 // MiniMax Models (MiniMax via OpenRouter)
-// M2.7 released Mar 18, 2026 - Self-evolving, #1 AI Intelligence Index, SWE-Pro 56.22%
+// M3 released May 31, 2026 - 1M ctx, MSA sparse attention (~1/20 compute at 1M), native multimodal
 export const MINIMAX_MODELS = {
-    M2_7: "minimax/minimax-m2.7", // 2300B/100B MoE, 200K ctx, SWE-Pro 56.22%, Multi-SWE #1, $0.30/$1.20
+    M3: "minimax/minimax-m3", // 1M ctx, MSA sparse attention, multimodal, agentic/coding, $0.30/$1.20
+    M2_7: "minimax/minimax-m2.7", // 2300B/100B MoE, 200K ctx, SWE-Pro 56.22%, Multi-SWE #1 (fallback)
     M2_5: "minimax/minimax-m2.5", // SWE-Bench 80.2%, 37% faster than M2.1 (legacy)
     M2_1: "minimax/minimax-m2.1", // 230B/10B MoE - SWE-Bench 72.5% (legacy)
 };
@@ -188,7 +189,7 @@ export const CURRENT_MODELS = {
         kimi: KIMI_MODELS.K2_6, // K2.6 (Apr 2026): 1T MoE, SWE-bench Pro leader
         qwen: QWEN_MODELS.CODER_NEXT, // Qwen3-Coder-Next: 80B/3B MoE, 262K ctx, SWE >70% (no 3.6-coder yet)
         qwen_reason: QWEN_MODELS.MAX_THINKING, // 235B MoE thinking mode (HMMT 98%) — still best for reasoning
-        minimax: MINIMAX_MODELS.M2_7, // M2.7: SWE-Pro 56.22%, Multi-SWE #1, self-evolving
+        minimax: MINIMAX_MODELS.M3, // M3: 1M ctx, MSA sparse attention, agentic/coding
     }
 };
 // Tool-specific defaults - References CURRENT_MODELS for easy bumping
@@ -309,12 +310,12 @@ export const TOOL_DEFAULTS = {
     },
     // MiniMax tools - VERY CHEAP, open source
     minimax_code: {
-        model: MINIMAX_MODELS.M2_7, // SWE-Pro 56.22%, Multi-SWE #1
+        model: MINIMAX_MODELS.M3, // 1M ctx, MSA sparse attention, agentic/coding
         maxTokens: 4000,
         temperature: 0.3, // Lower for precise code
     },
     minimax_agent: {
-        model: MINIMAX_MODELS.M2_7, // SWE-Pro 56.22%, self-evolving, #1 AI Intelligence Index
+        model: MINIMAX_MODELS.M3, // 1M ctx, multimodal, long-horizon agentic work
         maxTokens: 4000,
         temperature: 0.5, // Balanced for agentic tasks
     },
@@ -381,6 +382,7 @@ export const MODEL_DISPLAY_NAMES = {
     "qwen/qwen3-max-thinking": "qwen-max",
     "qwen/qwen3-235b-a22b-thinking-2507": "qwen-235b-thinking",
     // MiniMax
+    "minimax/minimax-m3": "minimax-m3",
     "minimax/minimax-m2.7": "minimax-m2.7",
     "minimax/minimax-m2.5": "minimax-m2.5",
     "minimax/minimax-m2.1": "minimax-m2.1",
@@ -434,7 +436,8 @@ export const MODEL_PRICING = {
     "qwen/qwen3-max-thinking": 0.005,
     "qwen/qwen3-235b-a22b-thinking-2507": 0.000822, // ($0.15 + $1.50) / 2 / 1000
     // OpenRouter models - MiniMax (VERY CHEAP!)
-    "minimax/minimax-m2.7": 0.00075, // ($0.30 + $1.20) / 2 / 1000 - flagship
+    "minimax/minimax-m3": 0.00075, // ($0.30 + $1.20) / 2 / 1000 - flagship (promo pricing)
+    "minimax/minimax-m2.7": 0.00075, // ($0.30 + $1.20) / 2 / 1000 - fallback
     "minimax/minimax-m2.5": 0.000685, // legacy
     "minimax/minimax-m2.1": 0.000685, // legacy
 };

package/dist/src/config/model-defaults.js

@@ -29,7 +29,7 @@ const MODELS = {
     QWEN: QWEN_MODELS.CODER_NEXT, // qwen/qwen3-coder-next (80B/3B MoE, 262K ctx)
     QWEN_REASON: QWEN_MODELS.MAX_THINKING, // qwen/qwen3-235b-a22b-thinking (235B MoE)
     KIMI: KIMI_MODELS.K2_6, // moonshotai/kimi-k2.6 (Apr 2026 - SWE-bench Pro leader)
-    MINIMAX: MINIMAX_MODELS.M2_7, // minimax/minimax-m2.7 (SWE-Pro 56.22%, #1 AI Intelligence Index)
+    MINIMAX: MINIMAX_MODELS.M3, // minimax/minimax-m3 (May 2026 - 1M ctx, MSA sparse attention)
 };
 /**
  * Get Scout model configuration

package/dist/src/orchestrators/collaborative/registries/ModelProviderRegistry.js

@@ -101,7 +101,7 @@ modelProviderRegistry.registerMany([
     // Qwen reason (heavy math/reasoning)
     { modelName: "qwen-reason", toolName: "qwen_reason", provider: "openrouter", aliases: ["qwen_reason", "qwen-max", "qwen-thinking"] },
     // MiniMax models (cheap agentic)
-    { modelName: "minimax", toolName: "minimax_agent", provider: "openrouter", aliases: ["minimax-agent", "minimax-m2.7", "minimax-m2.5"] },
+    { modelName: "minimax", toolName: "minimax_agent", provider: "openrouter", aliases: ["minimax-agent", "minimax-m3", "minimax-m2.7", "minimax-m2.5"] },
     { modelName: "minimax-code", toolName: "minimax_code", provider: "openrouter", aliases: ["minimax_code"] },
     // Think tool
     { modelName: "think", toolName: "think", provider: "anthropic" },

package/dist/src/server.js

@@ -65,16 +65,14 @@ import { getProviderInfo } from "./tools/unified-ai-provider.js";
 import { getAllPerplexityTools, isPerplexityAvailable } from "./tools/perplexity-tools.js";
 import { getAllGrokTools, isGrokAvailable } from "./tools/grok-tools.js";
 import { registerWorkflowTools } from "./tools/workflow-runner.js";
-import { validateWorkflowTool, validateWorkflowFileTool } from "./tools/workflow-validator-tool.js";
+import { getAllTools } from "./tools/registry.js";
 import { canRunFocusDeep } from "./focus-deep.js";
 import { loadConfig } from "./config.js";
 // import { registerSessionTools } from "./session/session-tools.js"; // Removed - not needed for minimal tool set
 import { getAllAdvancedTools, areAdvancedModesAvailable } from "./tools/advanced-modes.js";
 import { isOpenAIAvailable, getAllOpenAITools } from "./tools/openai-tools.js";
-import { isGeminiAvailable, geminiBrainstormTool, geminiAnalyzeCodeTool } from "./tools/gemini-tools.js";
+import { isGeminiAvailable } from "./tools/gemini-tools.js";
 import { isOpenRouterAvailable } from "./tools/openrouter-tools.js";
-import { getTachiTools } from "./tools/tachi-tool.js";
-import { getPromptTechniqueTools } from "./tools/prompt-technique-tools.js";
 import { withParamAliases } from "./utils/param-aliases.js";
 // import { registerGPT5Tools, isGPT5Available } from "./tools/openai-gpt5-fixed.js"; // DISABLED - using regular openai-tools.ts
 import { initializeOptimizations } from "./optimization/index.js";
@@ -553,114 +551,27 @@ const availableProviders = Object.entries(providerInfo)
     .filter(([_, info]) => info.available)
     .map(([name]) => name);
 console.error(`✅ Available AI providers: ${availableProviders.join(', ')}`);
-// Register Perplexity tools separately (custom API, not OpenAI-compatible)
-if (isPerplexityAvailable()) {
-    const perplexityTools = getAllPerplexityTools();
-    perplexityTools.forEach(tool => {
-        safeAddTool(tool);
-    });
-    console.error(`✅ Registered ${perplexityTools.length} Perplexity tools (custom API)`);
-}
-// Register Grok tools separately (custom API, not OpenAI-compatible)
-if (isGrokAvailable()) {
-    const grokTools = getAllGrokTools();
-    grokTools.forEach(tool => {
-        safeAddTool(tool);
-    });
-    console.error(`✅ Registered ${grokTools.length} Grok tools (custom API)`);
-}
-// Register all OpenAI tools (includes openai_reason, openai_brainstorm, etc.)
-if (isOpenAIAvailable()) {
-    const openaiTools = getAllOpenAITools();
-    openaiTools.forEach(tool => {
-        safeAddTool(tool);
-    });
-    console.error(`✅ Registered ${openaiTools.length} OpenAI tools (GPT-5 suite)`);
-}
 // Async initialization function to handle dynamic imports and startup
 async function initializeServer() {
     try {
-        // Register select Gemini tools (brainstorm, analyze, search)
-        if (isGeminiAvailable()) {
-            const { geminiAnalyzeTextTool, geminiJudgeTool, geminiSearchTool } = await import("./tools/gemini-tools.js");
-            const geminiTools = [
-                geminiBrainstormTool, // Creative brainstorming
-                geminiAnalyzeCodeTool, // Code analysis
-                geminiAnalyzeTextTool, // Text analysis (sentiment, summary, etc.)
-                geminiJudgeTool, // Multi-perspective evaluation & synthesis
-                geminiSearchTool // Web search with Google Search grounding
-            ];
-            geminiTools.forEach(tool => {
-                safeAddTool(tool);
-            });
-            console.error(`✅ Registered ${geminiTools.length} Gemini tools (brainstorm, code, text, judge, search)`);
-            // Register Jury tool (multi-model panel with Gemini judge)
-            const { juryTool } = await import("./tools/jury-tool.js");
-            safeAddTool(juryTool);
-            console.error(`✅ Registered jury tool (multi-model panel)`);
-        }
-        // Register OpenRouter tools (Qwen, Kimi, MiniMax - filtered by profile via safeAddTool)
-        if (isOpenRouterAvailable()) {
-            const { qwenCoderTool, qwenAlgoTool, qwqReasoningTool, qwenCompetitiveTool, kimiThinkingTool, kimiCodeTool, kimiDecomposeTool, kimiLongContextTool, qwenReasonTool, minimaxCodeTool, minimaxAgentTool, deepseekReasonTool, deepseekAlgoTool, glmReasonTool, stepfunReasonTool, ernieReasonTool } = await import("./tools/openrouter-tools.js");
-            // safeAddTool checks isToolEnabled internally
-            safeAddTool(qwenCoderTool);
-            safeAddTool(qwenAlgoTool);
-            safeAddTool(qwqReasoningTool); // QwQ-32B - multi-perspective deliberation (free tier)
-            safeAddTool(qwenCompetitiveTool);
-            safeAddTool(kimiThinkingTool);
-            safeAddTool(kimiCodeTool); // SWE-focused code (Kimi K2.5 - 76.8% SWE-Bench)
-            safeAddTool(kimiDecomposeTool); // Task decomposition (Kimi K2.5 Agent Swarm)
-            safeAddTool(kimiLongContextTool); // Long-context analysis (Kimi K2.5 - 256K)
-            safeAddTool(qwenReasonTool); // Heavy reasoning (Qwen3-Max-Thinking >1T params)
-            safeAddTool(minimaxCodeTool); // MiniMax M2.7 - SWE-Pro 56.22%, #1 AI Intelligence Index
-            safeAddTool(minimaxAgentTool); // MiniMax M2.7 - agentic workflows, self-evolving
-            safeAddTool(deepseekReasonTool); // DeepSeek V4 Pro - frontier reasoning/math (open-weight)
-            safeAddTool(deepseekAlgoTool); // DeepSeek V4 Pro - algorithmic code review (top AIME/CodeElo)
-            safeAddTool(glmReasonTool); // Zhipu GLM-5.1 - agentic reasoning (SWE-Bench Pro leader)
-            safeAddTool(stepfunReasonTool); // StepFun Step 3.7 Flash - efficient reasoning
-            safeAddTool(ernieReasonTool); // Baidu ERNIE 4.5 VL - broad-knowledge reasoning
-            console.error(`✅ Registered OpenRouter tools (Qwen, QwQ, Kimi x4, MiniMax, DeepSeek x2, GLM, StepFun, ERNIE)`);
-            // Register planner tools (multi-model council for plan creation/execution)
-            const { plannerMakerTool, plannerRunnerTool, listPlansTool } = await import("./tools/planner-tools.js");
-            safeAddTool(plannerMakerTool); // Council-based plan creation
-            safeAddTool(plannerRunnerTool); // Plan execution with checkpoints
-            safeAddTool(listPlansTool); // List recent plans
-            console.error(`✅ Registered planner tools (planner_maker, planner_runner, list_plans)`);
+        // Register ALL provider tools via the central scan registry. getAllTools()
+        // evaluates the SAME is*Available() guards, in the SAME order, with the SAME
+        // async dynamic-import timing the per-provider blocks used to use inline here
+        // — so the registered set is byte-identical across every API-key scenario.
+        // This single loop replaces the former Perplexity/Grok/OpenAI sync blocks and
+        // the Gemini+jury / OpenRouter+planner / local / workflow-validator /
+        // advanced / tachi / prompt-technique async blocks. The 5 inline tools
+        // (think/focus/nextThought/usage_stats/continue_focus) are registered above
+        // and are intentionally NOT returned by the registry, so there is no overlap.
+        for (const t of await getAllTools()) {
+            safeAddTool(t);
         }
-        // Register local-model tools (Ollama / LM Studio / llama.cpp / vLLM - zero-cost,
-        // offline, no API key). Registered unconditionally; profile membership is
-        // enforced by safeAddTool/isToolEnabled.
-        const { localQueryTool } = await import("./tools/local-tools.js");
-        safeAddTool(localQueryTool);
-        console.error(`✅ Registered local-model tools (local_query)`);
-        // Register workflow tools
+        console.error(`✅ Registered provider tools via central registry`);
+        // Register workflow tools (registers directly onto FastMCP, not via
+        // safeAddTool — intentionally OUT of the registry, kept in its original spot).
         registerWorkflowTools(server);
         console.error(`✅ Registered workflow tools (execute, list, create, visualize)`);
-        // Register workflow validator tools
-        safeAddTool(validateWorkflowTool);
-        safeAddTool(validateWorkflowFileTool);
-        console.error(`✅ Registered workflow validator tools`);
         // Session management tools removed - not needed for minimal TachiBot
-        // Register advanced mode tools (Verifier, Challenger, Scout, etc.)
-        if (areAdvancedModesAvailable()) {
-            const advancedTools = getAllAdvancedTools();
-            advancedTools.forEach(tool => {
-                safeAddTool(tool);
-            });
-            console.error(`✅ Registered ${advancedTools.length} advanced mode tools`);
-        }
-        // Register tachi tools (smart auto-routing AI assistant)
-        const tachiTools = getTachiTools();
-        tachiTools.forEach(tool => {
-            safeAddTool(tool);
-        });
-        console.error(`✅ Registered tachi tools (tachi, focus alias)`);
-        // Register prompt technique tools (transparent prompt engineering)
-        const promptTechniqueTools = getPromptTechniqueTools();
-        promptTechniqueTools.forEach(tool => {
-            safeAddTool(tool);
-        });
-        console.error(`✅ Registered ${promptTechniqueTools.length} prompt technique tools`);
         // Log startup information
         const perplexityCount = isPerplexityAvailable() ? getAllPerplexityTools().length : 0;
         const grokCount = isGrokAvailable() ? getAllGrokTools().length : 0;

package/dist/src/tools/factory/base-schemas.js

@@ -0,0 +1,61 @@
+/**
+ * Shared Zod base schema partials — Task 0.3.
+ *
+ * Each export is a plain object meant to be SPREAD into a `z.object({...})`.
+ * Spreading creates a fresh `ZodObject` whose shape owns a copy of each
+ * field reference; two tools that spread the same partial do NOT alias a
+ * single mutable ZodObject — they each get an independent schema instance.
+ *
+ * SELECTION CRITERIA (grep-verified across all src/tools/*-tools.ts):
+ *   A field is factored HERE only if its FULL definition
+ *   (type + .describe() text + optionality) is **byte-identical** across
+ *   every use site (outliers with different describe text stay inline).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * filesField
+ *   30 of 31 occurrences across gemini/grok/openai/openrouter/perplexity/
+ *   planner tools share this exact definition. The one outlier
+ *   (openrouter-tools.ts line ~758) has a different describe text and stays
+ *   inline in its tool.
+ *
+ * reasoningContextField
+ *   7 occurrences across openai/openrouter/perplexity tools share this exact
+ *   definition. The remaining ~7 context fields have different describe text
+ *   (e.g. "Additional context for the problem", "Additional context about the
+ *   environment or conditions", "Additional context") and stay inline.
+ *
+ * REJECTED CANDIDATES (non-identical definitions — do NOT factor here):
+ *   temperature  — 3 defs, all differ (defaults 0.4 vs 0.7, z.coerce.number
+ *                  vs z.number, different describe text).
+ *   query        — many defs with varying describe text across tools.
+ *   problem      — varying describe text.
+ *   prompt       — varying describe text.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+import { z } from "zod";
+/**
+ * `files` — file-paths-as-code-context field.
+ *
+ * Identical across 30 tool definitions (verified by grep, Task 0.3 recon).
+ * Spread into z.object({...filesField, ...}) to include this field.
+ */
+export const filesField = {
+    files: z
+        .array(z.string())
+        .optional()
+        .describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+};
+/**
+ * `context` — additional reasoning context field.
+ *
+ * Identical across 7 tool definitions in openai/openrouter/perplexity tools
+ * (verified by grep, Task 0.3 recon). Context fields with different describe
+ * text stay inline in their respective tools.
+ * Spread into z.object({...reasoningContextField, ...}) to include this field.
+ */
+export const reasoningContextField = {
+    context: z
+        .string()
+        .optional()
+        .describe("Additional context for the reasoning task"),
+};

package/dist/src/tools/factory/define-model-tool.js

@@ -0,0 +1,37 @@
+/**
+ * PURE pass-through. Adds types + a single definition site — NO schema
+ * transformation, NO added .describe()/defaults. The emitted JSON schema MUST
+ * be unchanged. The body is exactly `return tool;` and must stay that way.
+ *
+ * IDENTITY-PRESERVING: the RETURN type is the concrete tool type `T`, not
+ * `ModelTool<S>`. Wrapping a tool is therefore type-transparent — the wrapped
+ * const keeps the *exact* concrete type it would have unwrapped (e.g.
+ * `execute`'s real `Promise<string>` return and its concrete input where
+ * `.default()` fields are still optional at the call site). Returning
+ * `ModelTool<S>` instead would widen `execute` to
+ * `(input: z.infer<S>, ctx) => Promise<unknown>` and break direct callers such
+ * as `src/tools/prompt-technique-tools.ts` that invoke `.execute(...)` outside
+ * FastMCP's parse step.
+ *
+ * Two type params are required for BOTH goals at once:
+ *   - `S` is inferred from `tool.parameters` so the shape constraint's
+ *     `execute` input is `z.infer<S>` — i.e. the tool's OWN output type, which
+ *     its concrete `execute` is assignable to (contravariantly). Constraining
+ *     to the generic `ModelTool<z.ZodObject<z.ZodRawShape>>` instead resolves
+ *     the input to `{ [x: string]: any }` (an index signature with no required
+ *     keys), to which a concrete `execute(input: { prompt: string })` is NOT
+ *     assignable — so a single `T extends ModelTool<…>` param wrongly rejects
+ *     every real tool.
+ *   - `T extends ModelTool<S>` captures and returns the concrete tool type.
+ * The `ModelTool<S>` bound still validates the shape (rejects a missing
+ * `name`/`description`/`execute` or a non-`ZodObject` `parameters`).
+ *
+ * C3: a future tool whose top-level `parameters` uses `.refine()` /
+ * `.superRefine()` / `.transform()` would produce a `ZodEffects` (not a
+ * `ZodObject`) and would require widening the `S` constraint here. No such
+ * tool exists today (grep-confirmed), so the `z.ZodObject` constraint is
+ * correct for now.
+ */
+export function defineModelTool(tool) {
+    return tool;
+}

package/dist/src/tools/gemini-tools.js

@@ -12,6 +12,8 @@ import { FORMAT_INSTRUCTION } from "../utils/format-constants.js";
 import { withHeartbeat } from "../utils/streaming-helper.js";
 import { getTimeoutConfig } from "../config/timeout-config.js";
 import { readFilesIntoContext } from "../utils/file-reader.js";
+import { defineModelTool } from "./factory/define-model-tool.js";
+import { filesField } from "./factory/base-schemas.js";
 // Note: renderOutput is applied centrally in server.ts safeAddTool() - no need to import here
 // NOTE: dotenv is loaded in server.ts before any imports
 // No need to reload here - just read from process.env
@@ -164,7 +166,7 @@ export async function callGemini(prompt, model = GEMINI_MODELS.GEMINI_3_PRO, sys
  * Gemini Query Tool
  * Direct querying of Gemini models for general information
  */
-export const geminiQueryTool = {
+export const geminiQueryTool = defineModelTool({
     name: "gemini_query",
     description: "Query Gemini. Put your PROMPT in the 'prompt' parameter.",
     parameters: z.object({
@@ -173,7 +175,7 @@ export const geminiQueryTool = {
             .optional()
             .default("gemini-3")
             .describe("Model variant - must be one of: gemini-3 (default), pro, flash"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         let model = GEMINI_MODELS.GEMINI_3_PRO; // Default to Gemini 3
@@ -189,7 +191,7 @@ export const geminiQueryTool = {
         const result = await withHeartbeat(() => callGemini(args.prompt + fileContext, model, undefined, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Brainstorm Tool
  * Collaborative problem-solving and ideation
@@ -197,14 +199,14 @@ export const geminiQueryTool = {
  * Note: skipValidation is used for internal LLM-to-LLM calls where input
  * has already been validated at the MCP entry point (server.ts).
  */
-export const geminiBrainstormTool = {
+export const geminiBrainstormTool = defineModelTool({
     name: "gemini_brainstorm",
     description: "Convergent synthesis: cluster, refine, and prioritize raw ideas into structured hierarchies. Use AFTER divergent ideation to organize and rank ideas by impact/feasibility. Put your PROMPT in the 'prompt' parameter.",
     parameters: z.object({
         prompt: z.string().describe("The ideas or topic to organize and refine (REQUIRED - put raw ideas or topic here)"),
         claudeThoughts: z.string().optional().describe("Claude's initial thoughts or raw ideas to cluster and refine"),
         maxClusters: z.number().optional().default(5).describe("Number of idea clusters to create (default: 5)"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         const systemPrompt = `Convergent synthesis engine. Output consumed by automated toolchain.
@@ -237,18 +239,18 @@ ${FORMAT_INSTRUCTION}`;
         const response = await withHeartbeat(() => callGemini(args.prompt + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(response);
     }
-};
+});
 /**
  * Gemini Analyze Code Tool
  * Code quality and performance analysis
  */
-export const geminiAnalyzeCodeTool = {
+export const geminiAnalyzeCodeTool = defineModelTool({
     name: "gemini_analyze_code",
     description: "Analyze code for bugs, quality, security, or performance issues. Put the CODE in the 'code' parameter, NOT in 'focus'.",
     parameters: z.object({
         code: z.string().describe("The actual source code to analyze (REQUIRED - put your code here)"),
         language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
         focus: z.string().optional().default("general").describe("Analysis focus (e.g., quality, security, performance, bugs, general)")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -271,17 +273,17 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(`Analyze this code:\n\n\`\`\`${args.language || ''}\n${args.code}\n\`\`\`${fileContext}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Analyze Text Tool
  * Text analysis and sentiment detection
  */
-export const geminiAnalyzeTextTool = {
+export const geminiAnalyzeTextTool = defineModelTool({
     name: "gemini_analyze_text",
     description: "Rhetorical analysis: dissect arguments for bias, logical fallacies, and persuasion tactics. Use for evaluating claims, detecting manipulation, or understanding argument structure. Put the TEXT in the 'text' parameter.",
     parameters: z.object({
         text: z.string().describe("The text to analyze (REQUIRED - put your text here)"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
         type: z.string()
             .optional()
             .default("rhetoric")
@@ -325,12 +327,12 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(`Analyze this text:\n\n${args.text}${fileContext}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Summarize Tool
  * Content summarization at different levels
  */
-export const geminiSummarizeTool = {
+export const geminiSummarizeTool = defineModelTool({
     name: "gemini_summarize",
     description: "Summarization. Put the CONTENT in the 'content' parameter.",
     parameters: z.object({
@@ -343,7 +345,7 @@ export const geminiSummarizeTool = {
             .optional()
             .default("paragraph")
             .describe("Output format - must be one of: paragraph, bullet-points, outline"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         const lengthGuides = {
@@ -370,12 +372,12 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(`Summarize this content:\n\n${args.content}` + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Image Prompt Tool
  * Create detailed prompts for image generation
  */
-export const geminiImagePromptTool = {
+export const geminiImagePromptTool = defineModelTool({
     name: "gemini_image_prompt",
     description: "Image prompt generation. Put the DESCRIPTION in the 'description' parameter.",
     parameters: z.object({
@@ -407,7 +409,7 @@ ${args.details ? `Additional details: ${args.details}` : ''}`;
         const result = await withHeartbeat(() => callGemini(userPrompt, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Judge Tool
  * Multi-perspective evaluation and synthesis (LLM-as-a-Judge)
@@ -417,7 +419,7 @@ ${args.details ? `Additional details: ${args.details}` : ''}`;
  * - Position bias mitigation (don't favor first/last)
  * - Extract-then-synthesize (not pick-a-winner)
  */
-export const geminiJudgeTool = {
+export const geminiJudgeTool = defineModelTool({
     name: "gemini_judge",
     description: "Evaluate and synthesize multiple AI perspectives into a unified verdict. Put CONTENT in the 'perspectives' parameter.",
     parameters: z.object({
@@ -429,7 +431,7 @@ export const geminiJudgeTool = {
             .optional()
             .default("synthesize")
             .describe("Judge mode: synthesize (merge best), evaluate (score each), rank (order by quality), resolve (settle conflicts)"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         // Resolve perspectives from fallback params (AI clients sometimes use wrong param name)
@@ -500,13 +502,13 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(userPrompt + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Search Tool
  * Web search using Google Search grounding
  * Uses google_search_retrieval with dynamic retrieval config
  */
-export const geminiSearchTool = {
+export const geminiSearchTool = defineModelTool({
     name: "gemini_search",
     description: "Web search via Gemini with Google Search grounding",
     parameters: z.object({
@@ -634,7 +636,7 @@ IMPORTANT:
             return `[Gemini Search error: ${error instanceof Error ? error.message : String(error)}]`;
         }
     }
-};
+});
 /**
  * Check if Gemini is available
  */