converse-mcp-server 3.7.1 → 4.1.0

package/docs/PROVIDERS.md

@@ -31,7 +31,7 @@ This guide documents all supported AI providers in the Converse MCP Server and t
   - `gemini-2.5-pro` (alias: `pro 2.5`) - Deep reasoning with thinking budget (1M context, 65K output)
   - `gemini-2.5-flash` (alias: `flash`) - Ultra-fast model with thinking budget (1M context, 65K output)
   - `gemini-2.5-flash-lite` (alias: `flash-lite`) - Lightweight fast model (1M context, 65K output)
-- **Note**: The short model name `gemini` (and `gemini:flash` / `gemini:pro`) routes to the **Antigravity CLI** (`agy`, OAuth-based access). For Google API access, use specific model names like `gemini-3.1-pro-preview` or `gemini-2.5-flash` (bare `gemini-pro`/`gemini-flash` also route to the Google API).
+- **Note**: The **Antigravity CLI** provider (`agy`, OAuth-based access) serves `gemini-3.8-flash` and `gemini-3.1-pro-preview` under the same IDs and aliases, and it comes before the Google API in bare-name order. When `agy` is installed, bare `pro`, `gemini-pro`, `flash`, `gemini-3.1-pro-preview` and `gemini-3.8-flash` go to Antigravity first; the bare name `gemini` is the Antigravity namespace. Use `google:<model>` (e.g. `google:pro`, `google:gemini-2.5-flash`) to always use the Google API. Names only the Google API serves (e.g. `gemini-2.5-pro`, `gemini-3.5-flash`) route there directly.
 
 ### X.AI (Grok)
 - **API Key Format**: `xai-...` (starts with `xai-`)
@@ -41,7 +41,7 @@ This guide documents all supported AI providers in the Converse MCP Server and t
   - `grok-4.5` (default; aliases: `grok`, `grok-4.5-latest`, `grok-build-latest`) - Flagship model with image input, reasoning content, and native web/X search (500K context)
 - **Reasoning**: `reasoning_effort` maps to Grok's `low`/`medium`/`high`. Grok 4.5 always reasons and cannot be turned off, so `none`/`minimal`/`low` clamp to `low`, `medium` stays `medium`, and `high`/`max` clamp to `high`.
 - **Web search**: Automatic — native web/X search (Agent Tools) is attached on every Grok 4.5 request; the model decides per-request whether to search, and any citations are returned in metadata.
-- **Retired IDs**: Older Grok identifiers (e.g. `grok-4-0709`, `grok-code-fast-1`) still pass through as explicit model strings, but xAI does not surface a retirement error for them — it silently remaps them upstream to a current model (HTTP 200). Use `grok-4.5` for predictable results.
+- **Retired IDs**: Older Grok identifiers (e.g. `grok-4-0709`, `grok-code-fast-1`) are not in the catalog and are rejected as unknown models. Use `grok-4.5`.
 
 ### Anthropic (Claude)
 - **API Key Format**: `sk-ant-...` (starts with `sk-ant-`)
@@ -100,15 +100,20 @@ This guide documents all supported AI providers in the Converse MCP Server and t
 ### Codex
 - **API Key Format**: Optional (uses ChatGPT login by default)
 - **Authentication**: ChatGPT login (system-wide) OR `CODEX_API_KEY`
+- **Availability**: The Codex SDK is installed and either `~/.codex/auth.json` exists (from `codex login`; `$CODEX_HOME/auth.json` when `CODEX_HOME` is set) or `CODEX_API_KEY` is set
 - **Environment Variables**:
   - `CODEX_API_KEY` - Optional API key for headless deployments
   - `CODEX_SANDBOX_MODE` - Filesystem access control (default: read-only)
   - `CODEX_SKIP_GIT_CHECK` - Skip Git repository validation (default: true)
   - `CODEX_APPROVAL_POLICY` - Command approval behavior (default: never)
-  - `CODEX_MODEL` - Underlying model for Codex sessions (default: gpt-6-sol; e.g. gpt-6-luna, gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5)
+  - `CODEX_DEFAULT_MODEL` - Model used for bare `codex` and `auto` (default: `gpt-6-sol`; any Codex model ID or alias below). The legacy name `CODEX_MODEL` is honored when `CODEX_DEFAULT_MODEL` is unset.
 - **Supported Models**:
   - `codex` - OpenAI Codex agentic coding assistant (GPT-6 Sol by default)
-  - `codex:<model>` - Same, with an explicit backend: `codex:sol`, `codex:luna`, `codex:astra` (GPT-6), `codex:gpt-5.6-sol`, `codex:terra`, `codex:gpt-5.6-luna`, `codex:gpt-5.5`, `codex:spark`, or any slug the Codex CLI knows
+  - `codex:<model>` - Same, with an explicit backend from the Codex catalog:
+    - `gpt-6-sol` (aliases: `sol`, `gpt-6`), `gpt-6-luna` (`luna`), `gpt-6-astra` (`astra`)
+    - `gpt-5.6-sol` (`gpt-5.6`), `gpt-5.6-terra` (`terra`), `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.3-codex-spark` (`spark`)
+  - Names outside this catalog are rejected with suggestions
+  - These IDs are also bare names: `gpt-6-astra`, `luna` or `terra` alone go to Codex first and fail over to the OpenAI API (see [Model Routing Logic](#model-routing-logic))
   - `reasoning_effort` is clamped onto what the backend accepts (Sol/Luna: `none`–`max`; GPT-6 Astra: `low`–`max`, no `none`)
   - Thread-based sessions with persistent context
   - Direct filesystem access from working directory
@@ -134,10 +139,13 @@ This guide documents all supported AI providers in the Converse MCP Server and t
      - Windows (PowerShell): `irm https://antigravity.google/cli/install.ps1 | iex`
      - macOS/Linux: `curl -fsSL https://antigravity.google/cli/install.sh | bash`
   2. Authenticate: run `agy` once interactively and complete the Google OAuth login. This also establishes workspace trust for your home directory (the provider spawns each call in a per-call subdirectory under `~/.converse/agy-runs`).
-- **Environment Variables**: None (the provider detects the `agy` binary on PATH or at the platform install location)
+- **Availability**: The `agy` binary is found on PATH or at the platform install location
+- **Environment Variables**:
+  - `AGY_DEFAULT_MODEL` - Model used for bare `gemini` and `auto` (default: `gemini-3.8-flash`)
+- **Namespaces**: `gemini`, `agy`, `antigravity`, `gemini-cli` (all equivalent, e.g. `agy:pro`)
 - **Supported Models** (text-only — print mode has no image input channel):
-  - `gemini` (= `gemini:flash`) - Gemini 3.8 Flash (default)
-  - `gemini:pro` - Gemini 3.1 Pro
+  - `gemini-3.8-flash` (aliases: `flash`, `gemini-3.8`, `flash-3.8`, ...) - Gemini 3.8 Flash (default; `gemini` alone = `gemini:flash`)
+  - `gemini-3.1-pro-preview` (aliases: `pro`, `gemini-pro`, `gemini-3.1-pro`, `gemini-3`, ...) - Gemini 3.1 Pro (`gemini:pro`)
   - `reasoning_effort` selects the variant: `low` → (Low), `medium` → (Medium) for Flash / (High) for Pro, `high`/`max` → (High); unset defaults to (High)
 
 **Key Features:**
@@ -184,27 +192,30 @@ agy
 
 **Best Practices:**
 - Authenticate before first use (run `agy` once interactively to log in)
-- Use specific model names for Google API access (e.g., `gemini-2.5-pro`)
-- Model names `gemini`, `gemini:pro`, and `gemini:flash` are reserved for Antigravity CLI access
+- Use the `google:` namespace for Google API access (e.g., `google:pro`, `google:gemini-2.5-pro`)
+- The `gemini:` / `agy:` namespaces always use the Antigravity CLI; bare `pro`, `gemini-pro` and `flash` also use it first when `agy` is installed
 - If a call returns an empty response, the CLI is likely not authenticated — run `agy` interactively once
 
 **Differences from Google API Provider:**
 - **Authentication**: Google OAuth via `agy` vs API Key (Google API)
 - **Billing**: Antigravity subscription/compute allowance vs pay-per-use API
-- **Model Routing**: `gemini` / `gemini:flash` / `gemini:pro` → Antigravity CLI provider, specific names (e.g., `gemini-2.5-pro`, bare `gemini-pro`) → Google API provider
+- **Model Routing**: `gemini` / `gemini:<model>` / `agy:<model>` → Antigravity CLI provider; `google:<model>` → Google API provider; bare names both serve (`pro`, `gemini-pro`, `gemini-3.1-pro-preview`, `gemini-3.8-flash`) → Antigravity first, then the Google API on authentication/availability failure; bare names only the Google API serves (e.g., `gemini-2.5-pro`) → Google API provider. Bare `flash` is Gemini 3.8 Flash on Antigravity but Gemini 2.5 Flash on the Google API, so it does not fail over between them.
 - **Images**: Not supported (text-only) vs full multimodal on the Google API provider
+- **Permissions**: `agy` runs with `--dangerously-skip-permissions` (headless calls cannot prompt), so every tool request, including shell commands and file writes, is auto-approved. Bare names and `auto` reach it whenever `agy` is installed; use `google:<model>` to keep a request on the plain API.
 
 ### Claude Agent SDK
 - **Authentication**: Claude Code CLI login (no API key needed)
 - **Setup Required**: Authenticate once with `claude login` (Claude Code CLI)
-- **Environment Variables**: None (uses Claude Code credentials)
-- **Supported Models**:
-  - `claude` (aliases: `claude-sdk`, `claude-code`) - Defaults to Claude Opus 5.5 (`claude-opus-5-5`)
-  - `claude:opus` or `claude:opus-5.5` - Claude Opus 5.5 explicitly
-  - `claude:opus-5` - Claude Opus 5 (`claude-opus-5`)
-  - `claude:fable` or `claude:fable-5.1` - Claude Fable 5.1 (`claude-fable-5-1`)
-  - `claude:fable-5` - Claude Fable 5.0 (`claude-fable-5`)
-  - Other `claude:`-prefixed names pass through to the SDK (e.g. `claude:claude-sonnet-4-6`)
+- **Availability**: The Claude Agent SDK is installed and a credential is present: `~/.claude/.credentials.json` (`$CLAUDE_CONFIG_DIR/.credentials.json` when set), or `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` in the environment. On macOS the login lives in the Keychain and is assumed present. An expired login is caught at call time, and bare-name/`auto` routing fails over to the next provider.
+- **Environment Variables**:
+  - `CLAUDE_DEFAULT_MODEL` - Model used for bare `claude` and `auto` (default: `claude-opus-5-5`)
+- **Supported Models** (namespaces: `claude`, `claude-code`, `claude-sdk`):
+  - `claude` - Defaults to Claude Opus 5.5 (`claude-opus-5-5`)
+  - `claude-opus-5-5` (aliases: `opus`, `claude-opus`, `opus-5.5`) - Claude Opus 5.5 (`claude:opus`)
+  - `claude-opus-5` (alias: `opus-5`) - Claude Opus 5
+  - `claude-fable-5-1` (aliases: `fable`, `claude-fable`, `fable-5.1`) - Claude Fable 5.1 (`claude:fable`)
+  - `claude-fable-5` (alias: `fable-5`) - Claude Fable 5.0
+  - Names outside this catalog are rejected with suggestions (e.g. `claude:sonnet` suggests `copilot:sonnet` and `anthropic:sonnet`)
 
 **Key Features:**
 - **Subscription Access**: Uses your Claude subscription instead of API credits
@@ -217,19 +228,22 @@ agy
 **Differences from Anthropic API Provider:**
 - **Authentication**: Claude Code login vs `ANTHROPIC_API_KEY`
 - **Billing**: Claude subscription vs pay-per-use API
-- **Model Routing**: `claude` and `claude:*` → SDK provider; specific names (e.g., `claude-fable-5`, `opus`, `sonnet`) → API provider
+- **Model Routing**: `claude` and `claude:<model>` → SDK provider; `anthropic:<model>` → API provider; bare names both serve as the same model (`opus`, `claude-opus-5-5`, `claude-opus-5`, `claude-fable-5`) → SDK first, then the API on authentication/availability failure; bare names only the API serves (e.g., `sonnet`, `haiku`) → API provider. Bare `fable` is Fable 5.1 on the SDK but Fable 5 on the API, so it does not fail over between them.
+- **Permissions**: The SDK runs with `bypassPermissions`, and bare names and `auto` reach it whenever it is available. Use `anthropic:<model>` to keep a request on the plain API.
 
 ### GitHub Copilot SDK
 - **Authentication**: GitHub Copilot subscription via the Copilot CLI (`gh auth login` with an active Copilot subscription) — no API key needed
 - **Setup Required**: Authenticate the GitHub CLI and ensure your account has an active Copilot subscription
-- **Environment Variables**: None
-- **Supported Models** (reach them with the `copilot:` namespace, e.g. `copilot:gpt-6-sol`):
-  - `copilot` - Uses Copilot's default or env-configured model
-  - OpenAI: `gpt-6-sol` (aliases: bare `gpt-6`, `gpt-5`, `sol`), `gpt-6-luna` (alias: `luna`), `gpt-5.6-sol` (alias: `gpt-5.6`), `gpt-5.6-terra`, `gpt-5.6-luna`
+- **Availability**: The Copilot SDK (`@github/copilot-sdk`) is installed
+- **Environment Variables**:
+  - `COPILOT_DEFAULT_MODEL` - Model used for bare `copilot` and `auto` (default: `gpt-6-sol`). The legacy name `COPILOT_MODEL` is honored when `COPILOT_DEFAULT_MODEL` is unset.
+- **Supported Models** (namespace-only: reach them with `copilot:`, `github-copilot:` or `copilot-sdk:`, e.g. `copilot:gpt-6-sol`; Copilot never serves bare model names):
+  - `copilot` - GPT-6 Sol, or `COPILOT_DEFAULT_MODEL`
+  - OpenAI: `gpt-6-sol` (aliases: `gpt-6`, `gpt-5`, `sol`), `gpt-6-luna` (alias: `luna`), `gpt-5.6-sol` (alias: `gpt-5.6`), `gpt-5.6-terra`, `gpt-5.6-luna`
   - Anthropic: `claude-opus-5.5` (aliases: `opus`, `claude`; Copilot Pro+/Max/Business/Enterprise), `claude-fable-5` (alias: `fable`), `claude-sonnet-5` (alias: `sonnet`), `claude-opus-5`, `claude-opus-4.8`
   - Google: `gemini-3.1-pro-preview` (aliases: `gemini`, `gemini-3.1-pro`), `gemini-3.8-flash` (aliases: `gemini-3.8`, `flash-3.8`), `gemini-3.5-flash` (alias: `gemini-flash`)
 - **Reasoning**: The GPT-6 and GPT-5.6 tiers accept `reasoning_effort` (clamped onto Copilot's `low`–`xhigh`).
-- **Explicit pass-through**: Any other `copilot:<id>` model string is forwarded to the Copilot backend verbatim, so IDs outside the curated list still work while the backend accepts them.
+- **Unknown IDs**: Any other `copilot:<id>` is rejected with suggestions; only the IDs and aliases above are accepted.
 
 **Key Features:**
 - **Subscription Access**: Uses your GitHub Copilot subscription instead of API credits
@@ -259,6 +273,24 @@ CODEX_SKIP_GIT_CHECK=true                    # true (default), false
 CODEX_APPROVAL_POLICY=never                  # never (default), untrusted, on-failure, on-request
 ```
 
+### Default Model Overrides (.env file)
+
+Each provider has a `<PROVIDER>_DEFAULT_MODEL` variable that sets the model used for its bare provider name (`codex`, `openai`, ...) and for `auto`. The value must be a model ID or alias from that provider's list; startup fails with "Did you mean" suggestions otherwise. OpenRouter also accepts any `vendor/model` slug.
+
+```bash
+CODEX_DEFAULT_MODEL=gpt-6-sol                # CODEX_MODEL is honored as a legacy fallback
+CLAUDE_DEFAULT_MODEL=claude-opus-5-5
+AGY_DEFAULT_MODEL=gemini-3.8-flash           # Antigravity CLI (gemini)
+COPILOT_DEFAULT_MODEL=gpt-6-sol              # COPILOT_MODEL is honored as a legacy fallback
+OPENAI_DEFAULT_MODEL=gpt-6-sol
+GOOGLE_DEFAULT_MODEL=gemini-3.1-pro-preview
+XAI_DEFAULT_MODEL=grok-4.5
+ANTHROPIC_DEFAULT_MODEL=claude-opus-5-5
+MISTRAL_DEFAULT_MODEL=mistral-medium-3-5
+DEEPSEEK_DEFAULT_MODEL=deepseek-v4-pro
+OPENROUTER_DEFAULT_MODEL=z-ai/glm-5.2        # any vendor/model slug is accepted
+```
+
 ### Claude Configuration (claude_desktop_config.json)
 ```json
 {
@@ -311,6 +343,7 @@ All providers support streaming responses for real-time output.
 
 ### Local Execution
 - **Codex**: Runs locally with direct filesystem access and thread-based sessions
+- **Claude Agent SDK, Antigravity CLI, Copilot SDK**: Run through a local SDK or CLI using your subscription login
 - **All Others**: API-based remote execution
 
 ## Model Selection in Tools
@@ -319,42 +352,47 @@ When using the chat tool in any mode, specify models using their identifiers:
 
 ### Model Routing Logic
 
-1. **SDK Providers** (exact matches and prefixes, checked first):
+Routing is derived entirely from each provider's model list (canonical IDs plus aliases, matched case-insensitively). Every entry in `models` takes one of four forms:
+
+1. **`provider`** — that provider's default model (hardcoded, or `<PROVIDER>_DEFAULT_MODEL`). Namespace tokens:
    - `codex` → Codex
-   - `gemini`, `gemini-cli`, and any `gemini:`-prefixed name (e.g., `gemini:flash`, `gemini:pro`) → Gemini via Antigravity CLI
-   - `claude`, `claude-sdk`, `claude-code` and any `claude:`-prefixed name (e.g., `claude:fable`, `claude:opus`) → Claude Agent SDK
-   - `copilot`, `copilot-sdk`, `github-copilot` and any `copilot:`-prefixed name (e.g., `copilot:codex`) → Copilot SDK
+   - `gemini`, `agy`, `antigravity`, `gemini-cli` → Gemini via Antigravity CLI
+   - `claude`, `claude-code`, `claude-sdk` → Claude Agent SDK
+   - `copilot`, `github-copilot`, `copilot-sdk` → Copilot SDK
+   - `openai`, `google`, `xai`, `anthropic`, `mistral`, `deepseek`, `openrouter` → the matching API provider
+
+2. **`provider:model`** — that model on that provider only (e.g. `codex:astra`, `gemini:pro`, `google:pro`, `anthropic:opus`, `copilot:sonnet`). The model must be in that provider's list; there is no failover to another provider.
+
+3. **Bare `model`** — an ID or alias without a namespace goes to the first provider, in this order, whose list contains the name and that is set up: Codex, Antigravity CLI, Claude Agent SDK, OpenAI, Google, X.AI, Anthropic, Mistral, DeepSeek, OpenRouter.
+   - "Set up" means an API key for API providers; for Codex, the SDK plus a login file or `CODEX_API_KEY`; for the Claude Agent SDK, the SDK plus a login file, a macOS login, or `CLAUDE_CODE_OAUTH_TOKEN`/`ANTHROPIC_API_KEY`; for Antigravity, the `agy` binary.
+   - If that provider fails with an authentication or availability error (including an expired login, which is only detected at call time), the next set-up provider that serves **the same model** takes over. A provider whose alias of that name points at a different model is never substituted (bare `fable` is Fable 5.1 on the Claude Agent SDK and Fable 5 on the Anthropic API; bare `flash` is Gemini 3.8 Flash on Antigravity and Gemini 2.5 Flash on the Google API).
+   - Copilot never serves bare names; use `copilot:<model>`.
+
+4. **`auto`** — the first available provider's default model, in the priority order above with Copilot between the Claude Agent SDK and OpenAI.
 
-2. **Simple Names**: Other models without "/" are routed by keyword matching:
-   - Contains "gpt", "o1", "o3", "o4" → OpenAI
-   - Contains "claude", "fable", "opus", "sonnet", "haiku" → Anthropic
-   - Contains "gemini", "flash", "pro" → Google
-   - Contains "grok" → X.AI
-   - Contains "mistral", "magistral" → Mistral
-   - Contains "deepseek", "reasoner", "r1" → DeepSeek
-   - Contains "qwen", "kimi", "k2" → OpenRouter
+**Unknown names are rejected**, never guessed or forwarded: a typo or an unlisted model returns an error with up to three close matches, e.g. `Unknown model "gtp-6-astra". Did you mean: gpt-6-astra?` or `Unknown openai model "spark" in "openai:spark". Did you mean: codex:spark?`.
 
-3. **Slash Format**: Models with "/" check native providers first:
-   - If exact model exists in a native provider → Routes to that provider
-   - If not found in any native provider → Routes to OpenRouter
-   - This allows using models like "anthropic/claude-3.5-sonnet" via OpenRouter
+**OpenRouter slugs** are the one open-ended case: a full `vendor/model` slug (bare, or with the `openrouter:` namespace) routes to OpenRouter and is validated against OpenRouter's live catalog. `openrouter/auto` (aliases `auto-router`, `openrouter-auto`) selects OpenRouter's auto-router.
 
-4. **OpenRouter Auto**: Special aliases route to OpenRouter's auto-selection:
-   - "openrouter/auto", "openrouter auto", "auto router", "auto-router"
+**Local agent permissions**: Bare names and `auto` reach the local agent providers whenever they are set up. The Antigravity CLI auto-approves every tool request (`--dangerously-skip-permissions`) and the Claude Agent SDK runs with `bypassPermissions`. Name the API provider (`google:pro`, `anthropic:opus`, `openai:gpt-6-astra`) to keep a request off the local agents.
 
-The `models` array always holds plain model-name strings. Each string routes as follows:
+Examples:
 
 ```text
-"gpt-6"                    // OpenAI (keyword match -> gpt-6-sol)
-"fable"                    // Anthropic (keyword match -> claude-fable-5)
-"opus"                     // Anthropic (keyword match -> claude-opus-5-5)
-"sonnet"                   // Anthropic (keyword match -> claude-sonnet-4-6)
+"gpt-6"                    // Codex (gpt-6-sol), else OpenAI API
+"openai:gpt-6"             // OpenAI API only
+"fable"                    // Claude Agent SDK (claude-fable-5-1) when set up, otherwise Anthropic API (claude-fable-5)
+"opus"                     // Claude Agent SDK (claude-opus-5-5), else Anthropic API
+"anthropic:opus"           // Anthropic API only
+"sonnet"                   // Anthropic API (claude-sonnet-4-6)
 "claude"                   // Claude Agent SDK (defaults to Claude Opus 5.5)
 "claude:fable"             // Claude Agent SDK (Claude Fable 5.1)
-"gemini-2.5-pro"           // Google (keyword match)
-"grok-4.5"                 // X.AI (keyword match)
+"pro"                      // Antigravity CLI (gemini-3.1-pro-preview), else Google API
+"google:pro"               // Google API only
+"gemini-2.5-pro"           // Google API
+"grok-4.5"                 // X.AI
 "mistral-large"            // Mistral (alias -> mistral-large-2512)
-"deepseek"                 // DeepSeek (alias -> deepseek-v4-pro)
+"deepseek"                 // DeepSeek default model (deepseek-v4-pro)
 "z-ai/glm-5.2"             // OpenRouter (curated slug)
 "z-ai/glm-5.2:online"      // OpenRouter with web search opt-in
 "anthropic/claude-sonnet-5" // OpenRouter (any full slug routes as-is)
@@ -381,9 +419,11 @@ The `models` array always holds plain model-name strings. Each string routes as
 - Verify API keys are active and have available quota
 
 ### Model Not Found
-- Use exact model identifiers as listed above
-- Some providers support aliases (e.g., "fable" → "claude-fable-5", "opus" → "claude-opus-5-5")
+- Use model identifiers or aliases as listed above; anything else is rejected with up to three "Did you mean" suggestions
+- Check the namespace: a model must be in that provider's list (`openai:spark` fails and suggests `codex:spark`)
+- Aliases can differ per provider (e.g., bare "fable" → "claude-fable-5-1" on the Claude Agent SDK, `anthropic:fable` → "claude-fable-5")
 - Note: bare "claude" routes to the Claude Agent SDK provider, not the Anthropic API
+- A "none is available" error means the model exists but no provider serving it is set up; the message names the setup step for each
 - Check provider documentation for model availability in your region
 
 ### Rate Limits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "3.7.1",
+  "version": "4.1.0",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -13,6 +13,10 @@ import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
 import { readFileSync } from 'fs';
 import { findAgyBinary } from './providers/gemini-cli.js';
+import {
+  DEFAULT_MODEL_ENV_VARS,
+  validateDefaultModelOverrides,
+} from './utils/modelRouting.js';
 
 // Load environment variables from appropriate .env file
 // Priority: .env.test (for test env) > .env (default)
@@ -210,6 +214,12 @@ const CONFIG_SCHEMA = {
       secret: true,
       description: 'OpenRouter API key',
     },
+    TYPESAFE_API_KEY: {
+      type: 'string',
+      required: false,
+      secret: true,
+      description: 'TypeSafe API key (System One decision models for the decide tool)',
+    },
   },
 
   // Provider-specific configuration
@@ -280,9 +290,8 @@ const CONFIG_SCHEMA = {
     },
     CODEX_MODEL: {
       type: 'string',
-      default: 'gpt-6-sol',
-      description:
-        'Default Codex backend model (e.g., gpt-6-sol, gpt-6-luna, gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5)',
+      required: false,
+      description: 'Deprecated alias of CODEX_DEFAULT_MODEL',
     },
 
     // Copilot configuration
@@ -294,8 +303,7 @@ const CONFIG_SCHEMA = {
     COPILOT_MODEL: {
       type: 'string',
       required: false,
-      description:
-        'Default model for Copilot SDK sessions (e.g., gpt-6-sol, claude-opus-5.5, claude-sonnet-5)',
+      description: 'Deprecated alias of COPILOT_DEFAULT_MODEL',
     },
     COPILOT_CLI_PATH: {
       type: 'string',
@@ -303,6 +311,20 @@ const CONFIG_SCHEMA = {
       description:
         'Explicit path to the Copilot CLI runtime (index.js or copilot binary). Overrides automatic resolution.',
     },
+
+    // Per-provider default models: the model a bare provider name (`codex`,
+    // `openai`, ...) or "auto" uses. Each must name a model or alias in that
+    // provider's catalog; startup fails with suggestions otherwise.
+    ...Object.fromEntries(
+      Object.entries(DEFAULT_MODEL_ENV_VARS).map(([provider, envVar]) => [
+        envVar,
+        {
+          type: 'string',
+          required: false,
+          description: `Default model for the ${provider} provider`,
+        },
+      ]),
+    ),
   },
 
   // MCP configuration
@@ -691,7 +713,7 @@ export async function loadConfig() {
 
     if (availableKeys.length === 0 && !hasVertexAI && !hasSdkProvider) {
       errors.push(
-        'At least one API key must be configured: OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, or OPENROUTER_API_KEY. Alternatively, configure Google Vertex AI or use an SDK-based provider (codex, claude, copilot) or the Antigravity CLI (gemini-cli).',
+        'At least one API key must be configured: OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, or TYPESAFE_API_KEY. Alternatively, configure Google Vertex AI or use an SDK-based provider (codex, claude, copilot) or the Antigravity CLI (gemini-cli).',
       );
     }
 
@@ -892,6 +914,14 @@ export async function validateRuntimeConfig(config) {
     // Validate Codex configuration
     validateCodexConfig(config);
 
+    // Validate per-provider default-model overrides against provider catalogs.
+    // Imported lazily: the provider registry pulls in every provider SDK.
+    const { getProviders } = await import('./providers/index.js');
+    const defaultModelErrors = validateDefaultModelOverrides(getProviders(), config);
+    if (defaultModelErrors.length > 0) {
+      throw new ConfigurationError(defaultModelErrors.join('\n'));
+    }
+
     // Validate environment
     const validEnvs = ['development', 'production', 'test'];
     if (!validEnvs.includes(config.environment.nodeEnv)) {

package/src/decisionProviders/index.js

@@ -0,0 +1,174 @@
+/**
+ * Decision Providers
+ *
+ * Hosts of System One decision models (TypeSafe's Jev family). These are kept
+ * apart from the chat provider registry on purpose: a decision model takes a
+ * state plus typed questions and returns probabilities, never text, so it must
+ * never be reachable from `chat` routing ("auto", bare names, failover), and
+ * the `decide` tool must never reach a chat model.
+ *
+ * Spec grammar mirrors chat routing:
+ * - `auto` (or empty) — every configured provider's default, in priority order
+ * - `provider` / `provider:` — that provider's default model
+ * - `provider:model` — that provider only
+ * - `model` — every provider that serves the name, in priority order; the
+ *   first is used and the rest are failover candidates
+ */
+
+import { getCustomHeaders as getOpenRouterAttributionHeaders } from '../providers/openrouter.js';
+
+/**
+ * Model catalogs map each provider's own model ID to the names that route to
+ * it. OpenRouter only knows `~typesafe/jev-latest` and `typesafe/jev-1.13`
+ * (it rejects `jev-1.13.0` and `jev-preview`), so native IDs are translated
+ * per provider rather than by a blanket prefix rewrite.
+ */
+export const DECISION_PROVIDERS = {
+  typesafe: {
+    name: 'typesafe',
+    label: 'TypeSafe',
+    baseURL: 'https://api.typesafe.ai',
+    apiKeyEnv: 'TYPESAFE_API_KEY',
+    defaultModel: 'jev-latest',
+    models: {
+      'jev-latest': ['jev', '~typesafe/jev-latest'],
+      'jev-1.13.0': ['jev-1.13', 'typesafe/jev-1.13'],
+      'jev-preview': [],
+    },
+    // TypeSafe accepts every published versioned ID, listed or not.
+    passthrough: (name) => /^jev-\d+\.\d+(\.\d+)?$/i.test(name),
+    headers: (config) => ({ Authorization: `Bearer ${config.apiKeys.typesafe}` }),
+    isAvailable: (config) => Boolean(config?.apiKeys?.typesafe),
+  },
+  openrouter: {
+    name: 'openrouter',
+    label: 'OpenRouter',
+    baseURL: 'https://openrouter.ai/api',
+    apiKeyEnv: 'OPENROUTER_API_KEY',
+    defaultModel: '~typesafe/jev-latest',
+    models: {
+      '~typesafe/jev-latest': ['jev-latest', 'jev'],
+      'typesafe/jev-1.13': ['jev-1.13', 'jev-1.13.0'],
+    },
+    // Decision models OpenRouter adds later are reachable by full slug.
+    passthrough: (name) => name.includes('/'),
+    headers: (config) => ({
+      Authorization: `Bearer ${config.apiKeys.openrouter}`,
+      ...getOpenRouterAttributionHeaders(config),
+    }),
+    isAvailable: (config) => Boolean(config?.apiKeys?.openrouter),
+  },
+};
+
+/** Failover order: the native host first, then OpenRouter. */
+export const DECISION_PROVIDER_PRIORITY = ['typesafe', 'openrouter'];
+
+/**
+ * Resolve a name against one provider's catalog, then its passthrough rule.
+ * @returns {string|null} The model ID to send to that provider
+ */
+export function findDecisionModel(provider, name) {
+  const wanted = String(name).trim().toLowerCase();
+  if (!wanted) return null;
+  for (const [id, aliases] of Object.entries(provider.models)) {
+    if (id.toLowerCase() === wanted || aliases.some((a) => a.toLowerCase() === wanted)) {
+      return id;
+    }
+  }
+  return provider.passthrough(String(name).trim()) ? String(name).trim() : null;
+}
+
+function setupHint(provider) {
+  return `set ${provider.apiKeyEnv}`;
+}
+
+function knownModels() {
+  const names = new Set();
+  for (const providerName of DECISION_PROVIDER_PRIORITY) {
+    const provider = DECISION_PROVIDERS[providerName];
+    for (const [id, aliases] of Object.entries(provider.models)) {
+      names.add(id);
+      aliases.forEach((a) => names.add(a));
+    }
+  }
+  return [...names];
+}
+
+function ok(candidates) {
+  return { status: 'ok', candidates, error: null };
+}
+
+function fail(status, error) {
+  return { status, candidates: [], error };
+}
+
+/**
+ * Resolve a decision model spec into an ordered candidate list.
+ * @param {string} spec - Model spec (see module grammar)
+ * @param {object} config - Server configuration (for API keys)
+ * @returns {{ status: 'ok'|'unknown'|'unavailable', candidates: Array<{ providerName: string, provider: object, model: string }>, error: string|null }}
+ */
+export function resolveDecisionModel(spec, config) {
+  const raw = String(spec ?? '').trim();
+  const namespaces = DECISION_PROVIDER_PRIORITY.join(', ');
+
+  if (!raw || raw.toLowerCase() === 'auto') {
+    const candidates = DECISION_PROVIDER_PRIORITY
+      .map((name) => DECISION_PROVIDERS[name])
+      .filter((provider) => provider.isAvailable(config))
+      .map((provider) => ({ providerName: provider.name, provider, model: provider.defaultModel }));
+    if (candidates.length === 0) {
+      return fail(
+        'unavailable',
+        `No decision provider is configured: ${DECISION_PROVIDER_PRIORITY.map((n) => `${n} (${setupHint(DECISION_PROVIDERS[n])})`).join('; ')}.`,
+      );
+    }
+    return ok(candidates);
+  }
+
+  const colon = raw.indexOf(':');
+  const hasNamespace = colon > 0 && !raw.slice(0, colon).includes('/');
+  const namespace = hasNamespace ? raw.slice(0, colon).toLowerCase() : raw.toLowerCase();
+
+  if (hasNamespace || DECISION_PROVIDERS[namespace]) {
+    const provider = DECISION_PROVIDERS[namespace];
+    if (!provider) {
+      return fail('unknown', `Unknown decision provider "${raw.slice(0, colon)}". Providers: ${namespaces}.`);
+    }
+    const name = hasNamespace ? raw.slice(colon + 1).trim() : '';
+    const model = name ? findDecisionModel(provider, name) : provider.defaultModel;
+    if (!model) {
+      return fail(
+        'unknown',
+        `${provider.label} does not serve "${name}". Models: ${Object.keys(provider.models).join(', ')}.`,
+      );
+    }
+    if (!provider.isAvailable(config)) {
+      return fail('unavailable', `${provider.label} is not configured (${setupHint(provider)}).`);
+    }
+    return ok([{ providerName: provider.name, provider, model }]);
+  }
+
+  const matches = DECISION_PROVIDER_PRIORITY
+    .map((providerName) => {
+      const provider = DECISION_PROVIDERS[providerName];
+      const model = findDecisionModel(provider, raw);
+      return model ? { providerName, provider, model } : null;
+    })
+    .filter(Boolean);
+
+  if (matches.length === 0) {
+    return fail(
+      'unknown',
+      `Unknown decision model "${raw}". Use "auto", a provider (${namespaces}), "provider:model", or one of: ${knownModels().join(', ')}.`,
+    );
+  }
+  const available = matches.filter((m) => m.provider.isAvailable(config));
+  if (available.length === 0) {
+    return fail(
+      'unavailable',
+      `"${raw}" is served by ${matches.map((m) => `${m.providerName} (${setupHint(m.provider)})`).join('; ')}, but none is configured.`,
+    );
+  }
+  return ok(available);
+}