converse-mcp-server 3.7.1 → 4.1.0

package/.env.example

@@ -51,6 +51,11 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # OPENROUTER_REFERER=https://github.com/FallDownTheSystem/converse
 # OPENROUTER_TITLE=Converse
 
+# Get your TypeSafe API key from: https://typesafe.ai
+# Enables the decide tool's native host for Jev decision models. Without it,
+# decide reaches Jev through OPENROUTER_API_KEY instead.
+TYPESAFE_API_KEY=your_typesafe_api_key_here
+
 # ============================================
 # Codex Configuration (Optional)
 # ============================================
@@ -80,9 +85,23 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # WARNING: Interactive policies may cause hangs in server/headless mode
 # CODEX_APPROVAL_POLICY=never
 
-# Default Codex backend model (default: gpt-6-sol). Per-request override: models: ["codex:<model>"]
-# Options: gpt-6-sol, gpt-6-luna, gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.3-codex-spark
-# CODEX_MODEL=gpt-6-sol
+# ============================================
+# Per-provider Default Models
+# ============================================
+# The model a bare provider name ("codex", "openai", ...) and "auto" use.
+# Each must be a model ID or alias from that provider's catalog; startup fails
+# with "did you mean" suggestions otherwise. Per request, use "provider:model".
+# CODEX_DEFAULT_MODEL=gpt-6-sol       # gpt-6-sol, gpt-6-luna, gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.3-codex-spark (CODEX_MODEL is the legacy name)
+# CLAUDE_DEFAULT_MODEL=claude-opus-5-5
+# AGY_DEFAULT_MODEL=gemini-3.8-flash  # Antigravity CLI: gemini-3.8-flash, gemini-3.1-pro-preview
+# COPILOT_DEFAULT_MODEL=gpt-6-sol     # COPILOT_MODEL is the legacy name
+# 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
 
 # ============================================
 # Server Configuration

package/README.md

@@ -182,6 +182,25 @@ Cancel running asynchronous operations when needed.
 }
 ```
 
+### 4. Decide Tool
+
+Ask a System One decision model (TypeSafe's Jev) typed questions about a state and get calibrated answers instead of text: a yes probability (`noul`), a chosen option with per-option probabilities (`choice`), or a rubric position with per-level probabilities (`score`). Batch many questions into one call; they are judged in parallel against the same state. Needs `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY` (TypeSafe first, falling back to OpenRouter).
+
+```javascript
+{
+  "state": { "message": "I was charged twice for order A-104. Please fix this ASAP." },
+  "questions": {
+    "urgent": { "type": "noul", "instructions": "Does the message convey urgency?" },
+    "team": { "type": "choice", "instructions": "Which team should handle this?",
+              "criteria": { "billing": "Payments, refunds", "technical": "Bugs, outages" } },
+    "frustration": { "type": "score", "instructions": "How frustrated is the customer?",
+                     "criteria": ["Calm", "Frustrated", "Very angry"] }
+  }
+}
+```
+
+See [docs/API.md](docs/API.md#decide-tool) for the full schema, model routing, and usage guidance.
+
 ## 🤖 AI Summarization Feature
 
 When enabled, the server automatically generates intelligent titles and summaries for better context understanding:
@@ -242,11 +261,11 @@ SUMMARIZATION_MODEL=gpt-5-nano        # Default: gpt-5-nano
 - **gemini-2.5-flash** (alias: `flash`): Ultra-fast (1M context, 65K output)
 - **gemini-2.5-flash-lite** (alias: `flash-lite`): Lightweight fast model (1M context, 65K output)
 
-**Note**: The bare aliases `pro` and `gemini-pro` route to Gemini 3.1 Pro through the Google API. The short name `gemini` (and `gemini:pro`/`gemini:flash`) routes to the Antigravity CLI provider instead — see below.
+**Note**: The Antigravity CLI provider serves `gemini-3.8-flash` and `gemini-3.1-pro-preview` under the same names and aliases, so bare `pro`, `gemini-pro`, `flash` and those IDs go to Antigravity first when it is installed (see [Model Selection](#model-selection)). Use `google:<model>` to always use the Google API.
 
 ### X.AI/Grok Models
 
-- **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 maps to `low`/`medium`/`high` and cannot be disabled; web search is automatic. Older Grok IDs still pass through as explicit model strings.
+- **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 maps to `low`/`medium`/`high` and cannot be disabled; web search is automatic.
 
 ### Anthropic Models
 
@@ -285,8 +304,10 @@ Any other model works via its full `provider/model` slug or the `openrouter:` na
 
 ### Codex Models
 
-- **codex**: OpenAI Codex agentic coding assistant (GPT-6 Sol by default)
-  - Pick another backend per request with `codex:<model>` (e.g. `codex:luna`, `codex:astra`, `codex:gpt-5.6-terra`) or globally with `CODEX_MODEL`; backends: `gpt-6-sol` (aliases `sol`, `gpt-6`), `gpt-6-luna` (`luna`), `gpt-6-astra` (`astra`), `gpt-5.6-sol`, `gpt-5.6-terra` (`terra`), `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.3-codex-spark` (`spark`)
+OpenAI Codex agentic coding assistant. `codex` uses its default model (GPT-6 Sol, or `CODEX_DEFAULT_MODEL`); `codex:<model>` picks one (e.g. `codex:luna`, `codex:astra`, `codex:gpt-5.6-terra`):
+
+- **gpt-6-sol** (default; 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`)
   - `reasoning_effort` maps onto the tiers the chosen backend accepts (Sol/Luna: `none` through `max`; GPT-6 Astra: `low` through `max`, no `none`)
   - Thread-based sessions with persistent context
   - Direct filesystem access from working directory
@@ -296,20 +317,20 @@ Any other model works via its full `provider/model` slug or the `openrouter:` na
 
 ### Claude Agent SDK Models
 
-- **claude** (aliases: `claude-sdk`, `claude-code`): Claude via the Claude Agent SDK
-  - Defaults to Claude Opus 5.5 (`claude-opus-5-5`); `claude:opus` selects Opus 5.5, `claude:opus-5` selects Opus 5, `claude:fable` / `claude:fable-5.1` select Fable 5.1, and `claude:fable-5` selects Fable 5.0
-  - Uses Claude Code CLI authentication (`claude login`) - no API key needed
-  - Direct filesystem access from working directory
-  - Unknown `claude:`-prefixed names pass through to the SDK (e.g. `claude:claude-sonnet-4-6`)
+Claude via the Claude Agent SDK. `claude` uses its default model (Opus 5.5, or `CLAUDE_DEFAULT_MODEL`); `claude:<model>` picks one:
+
+- **claude-opus-5-5** (default; aliases: `opus`, `claude-opus`, `opus-5.5`), **claude-opus-5** (`opus-5`)
+- **claude-fable-5-1** (aliases: `fable`, `claude-fable`, `fable-5.1`), **claude-fable-5** (`fable-5`)
+- Uses Claude Code CLI authentication (`claude login`) - no API key needed
+- Direct filesystem access from working directory
 
 ### GitHub Copilot SDK Models
 
-Reach these with the `copilot:` namespace (e.g. `copilot:gpt-6-sol`); uses your GitHub Copilot subscription (`gh auth login`) - no API key needed:
+Reach these only with the `copilot:` namespace (e.g. `copilot:gpt-6-sol`) — Copilot never serves bare model names. `copilot` alone uses GPT-6 Sol, or `COPILOT_DEFAULT_MODEL`. Uses your GitHub Copilot subscription (`gh auth login`) - no API key needed:
 
 - **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` (all support `reasoning_effort`)
 - **Anthropic**: `claude-opus-5.5` (aliases: `opus`, `claude`), `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`)
-- Any other `copilot:<id>` is forwarded to the Copilot backend verbatim
 
 ## 📚 Help & Documentation
 
@@ -363,7 +384,21 @@ CODEX_API_KEY=your_codex_api_key_here       # Optional if ChatGPT login availabl
 CODEX_SANDBOX_MODE=read-only                 # read-only (default), workspace-write, danger-full-access
 CODEX_SKIP_GIT_CHECK=true                    # true (default), false
 CODEX_APPROVAL_POLICY=never                  # never (default), untrusted, on-failure, on-request
-CODEX_MODEL=gpt-6-sol                        # gpt-6-sol (default), gpt-6-luna, gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5
+
+# Optional: per-provider default model, used for a bare provider name (`codex`,
+# `openai`, ...) and for "auto". Must be a model or alias from that provider's
+# list; startup fails with suggestions otherwise.
+CODEX_DEFAULT_MODEL=gpt-6-sol                # CODEX_MODEL still works as a 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 still works as a 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
 ```
 
 ### Configuration Options
@@ -417,57 +452,59 @@ tool_timeout_sec = 3600  # default 300 kills long calls at 5 minutes
 
 ### Model Selection
 
-Use `"auto"` for automatic model selection, or specify exact models:
+Every entry in `models` takes one of four forms:
 
 ```javascript
-// Auto-selection (recommended)
+// Auto-selection (recommended): the first available provider's default model
 "auto";
 
-// Specific models
-"gemini-2.5-flash";
-"gpt-5.6";
-"grok-4.5";
-"z-ai/glm-5.2"; // -> OpenRouter (full slug)
-"z-ai/glm-5.2:online"; // -> OpenRouter with web search opt-in
-
-// Using aliases
-"flash"; // -> gemini-2.5-flash
-"pro"; // -> gemini-3.1-pro-preview
-"grok"; // -> grok-4.5
-"deepseek"; // -> deepseek-v4-pro
-"mistral"; // -> mistral-medium-3-5
-"fable"; // -> claude-fable-5 (Anthropic API)
-"opus"; // -> claude-opus-5-5 (Anthropic API)
-
-// SDK providers (subscription-based, no API key)
+// A provider: its default model (hardcoded, or <PROVIDER>_DEFAULT_MODEL)
+"codex"; // -> Codex (GPT-6 Sol)
 "claude"; // -> Claude Agent SDK (Claude Opus 5.5)
-"claude:fable"; // -> Claude Agent SDK (Claude Fable 5.1)
-"codex:luna"; // -> Codex (GPT-6 Luna)
-"copilot:gpt-6-sol"; // -> GitHub Copilot SDK
+"gemini"; // -> Antigravity CLI (Gemini 3.8 Flash); `agy` works too
+"openai"; // -> OpenAI API (GPT-6 Sol)
+
+// provider:model — that model on that provider only
+"codex:astra"; // -> Codex (GPT-6 Astra)
+"openai:gpt-6-astra"; // -> OpenAI API, even when Codex is available
+"gemini:pro"; // -> Antigravity CLI (Gemini 3.1 Pro)
+"google:gemini-3.1-pro-preview"; // -> Google API
+"copilot:sonnet"; // -> GitHub Copilot (Claude Sonnet 5)
+"openrouter:z-ai/glm-5.2:online"; // -> OpenRouter with web search opt-in
+
+// A bare model ID or alias — the first configured provider that offers it
+"gpt-6-astra"; // -> Codex, else OpenAI API
+"opus"; // -> Claude Agent SDK, else Anthropic API
+"pro"; // -> Antigravity CLI, else Google API
+"grok"; // -> grok-4.5 (XAI)
+"z-ai/glm-5.2"; // -> OpenRouter (any vendor/model slug)
 ```
 
+**Bare model names** go to the first provider, in the order below, whose model list contains the name and that is set up (API key present; for Codex and Claude, a login file or token; for Antigravity, the `agy` binary). If that provider then fails with an authentication or availability error, the next 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, so it does not fail over between them). Copilot is never picked for bare names; use `copilot:<model>`.
+
+**Unknown names are rejected**, never guessed: 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?`. OpenRouter is the exception for full `vendor/model` slugs, which are checked against OpenRouter's live catalog.
+
 **Auto Model Behavior:**
 
-- **chat mode**: `["auto"]` selects the first available provider and uses its default model
+- **chat mode**: `["auto"]` selects the first available provider and uses its default model, failing over down the list
 - **consensus mode**: `["auto"]` automatically expands to the first 3 available providers
+- **roundtable mode**: `["auto"]` uses the first available provider
 
-Provider priority order (subscription-based SDK providers first, then API-key providers):
+Provider priority order (subscription-based local providers first, then API-key providers), used by both `auto` and bare model names:
 
 1. Codex (`codex` → GPT-6 Sol)
-2. Gemini via Antigravity CLI (`gemini` → Gemini 3.8 Flash, `gemini:pro`)
+2. Gemini via Antigravity CLI (`gemini` / `agy` → Gemini 3.8 Flash)
 3. Claude Agent SDK (`claude` → Claude Opus 5.5)
-4. Copilot (`copilot`)
-5. OpenAI (`gpt-6` → GPT-6 Sol)
-6. Google (`gemini-pro`)
-7. XAI (`grok-4.5`)
-8. Anthropic (`claude-opus-5-5`)
-9. Mistral (`mistral-medium-3-5`)
-10. DeepSeek (`deepseek-v4-pro`)
-11. OpenRouter (`z-ai/glm-5.2`)
-
-The system will use the first 3 providers that are available (authenticated SDK or valid API key). This enables automatic multi-model consensus without manually specifying models.
-
-**Antigravity CLI permissions:** The `gemini`, `gemini:flash`, and `gemini:pro` aliases launch `agy` with `--dangerously-skip-permissions` because headless calls cannot prompt for tool approval. All tool permission requests are auto-approved, including shell commands and file writes; a read-only prompt is not an enforced security boundary. Use this provider only with trusted prompts and context. This also applies when `auto` selects it. The Google API provider is unaffected.
+4. Copilot (`copilot` → GPT-6 Sol; `auto` only, never bare names)
+5. OpenAI (`openai` → GPT-6 Sol)
+6. Google (`google` → Gemini 3.1 Pro)
+7. XAI (`xai` → Grok 4.5)
+8. Anthropic (`anthropic` → Claude Opus 5.5)
+9. Mistral (`mistral` → Mistral Medium 3.5)
+10. DeepSeek (`deepseek` → DeepSeek V4 Pro)
+11. OpenRouter (`openrouter` → GLM 5.2)
+
+**Local agent permissions:** Bare model names and `auto` reach the local agent providers whenever they are set up, not only when named explicitly. The Antigravity CLI runs `agy` with `--dangerously-skip-permissions` because headless calls cannot prompt for tool approval — every tool request is auto-approved, including shell commands and file writes. The Claude Agent SDK runs with `bypassPermissions`. Codex uses `CODEX_SANDBOX_MODE` (read-only by default). A read-only prompt is not an enforced security boundary for these providers, so use them only with trusted prompts and context. To keep a request on a plain API, name the provider: `google:pro`, `anthropic:opus`, `openai:gpt-6-astra`.
 
 ### Advanced Configuration
 

package/docs/API.md

@@ -366,9 +366,113 @@ The response renders a human-readable status (start time, elapsed time, turn/mod
 
 Only jobs in a `queued` or `running` state can be cancelled; already-completed, failed, or cancelled jobs return a non-cancellable status.
 
+## Decide Tool
+
+**Description**: Ask a System One decision model (TypeSafe's Jev family) typed questions about a state. Decision models return calibrated probabilities, never text, so they have their own tool and their own providers: `chat` routing never reaches them, and `decide` never reaches a chat model.
+
+### Request Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "state": { "anyOf": [{ "type": "string" }, { "type": "object" }, { "type": "array" }] },
+    "questions": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": { "type": "string", "enum": ["noul", "choice", "score"] },
+          "instructions": { "anyOf": [{ "type": "string" }, { "type": "object" }, { "type": "array" }] },
+          "criteria": { "anyOf": [{ "type": "object" }, { "type": "array" }] }
+        },
+        "required": ["type", "instructions"]
+      }
+    },
+    "model": { "type": "string", "description": "Default: \"auto\"" },
+    "files": { "type": "array", "items": { "type": "string" } }
+  },
+  "required": ["questions"],
+  "additionalProperties": false
+}
+```
+
+- **`state`**: the material to judge. An object with descriptively named fields works best; use an array for sequences such as chat messages. Optional when `files` is given.
+- **`questions`**: named questions, each judged in parallel and in isolation against the same state. The name is your own label and becomes the answer key. Batching many questions into one call adds almost no latency or cost.
+- **`files`**: text files added to the state as `{ "files": { "<path>": "<content>" } }`. When `state` is also given, it moves to `input`. Line ranges (`file.txt{10:50}`) are supported; images are rejected.
+
+| Type | `criteria` | Answer |
+|---|---|---|
+| `noul` | Optional `{ "true": "...", "false": "..." }` | `noul`: probability 0..1 of yes |
+| `choice` | Required `{ "<option>": "description" \| null }`, 2–255 options | `choice`, per-option `probabilities`, `confidence` |
+| `score` | Required ordered array of levels, lowest first, 2–10 levels | `score` (probability-weighted level position), `legend`, per-level `probabilities`, `confidence` |
+
+`instructions` and criteria descriptions may be objects or arrays that bundle reference data with the question; refer to their fields by `` `name` `` in the text. Questions are validated before any request is sent.
+
+### Models and Providers
+
+| Provider | Key | Models |
+|---|---|---|
+| `typesafe` (native, `https://api.typesafe.ai/v1/systemone`) | `TYPESAFE_API_KEY` | `jev-latest`, `jev-1.13.0` (alias `jev-1.13`), `jev-preview`, any versioned `jev-X.Y.Z` |
+| `openrouter` (`https://openrouter.ai/api/v1/systemone`) | `OPENROUTER_API_KEY` | `~typesafe/jev-latest` (alias `jev-latest`), `typesafe/jev-1.13` (aliases `jev-1.13`, `jev-1.13.0`), any `vendor/model` slug |
+
+- `auto` (default): TypeSafe's default model, falling back to OpenRouter's.
+- A bare name such as `jev-1.13` goes to every configured provider that serves it, native first, and each provider receives its own model ID. OpenRouter does not serve `jev-preview` or patch-level IDs other than those listed above.
+- `typesafe:jev-1.13.0` or `openrouter:~typesafe/jev-latest` pins one provider.
+
+Each provider call retries timeouts, 408, 429 and 5xx with backoff, honoring `Retry-After`. Auth failures, exhausted retries and malformed responses fall back to the next provider. A 400/422 request fault stops immediately, because every host would reject it the same way.
+
+### Example Usage
+
+```json
+{
+  "state": { "message": "I was charged twice for order A-104. Please fix this ASAP." },
+  "questions": {
+    "urgent": { "type": "noul", "instructions": "Does the message convey urgency?" },
+    "team": {
+      "type": "choice",
+      "instructions": "Which team should handle this?",
+      "criteria": { "billing": "Payments, invoicing, refunds", "technical": "Bugs, outages", "sales": null }
+    },
+    "frustration": {
+      "type": "score",
+      "instructions": "How frustrated is the customer?",
+      "criteria": ["Calm", "Frustrated", "Very angry"]
+    }
+  }
+}
+```
+
+### Response Format
+
+A one-line summary per answer, followed by the answers in the same JSON shape whichever provider served them:
+
+````
+Decision · typesafe/jev-1.13-20260917 via OpenRouter · 394 input tokens · $0.000017
+- urgent (noul): 0.97
+- team (choice): billing · confidence 1.00 · billing 1.00, technical 0.00, sales 0.00
+- frustration (score): 1.24 on 0–2 · confidence 0.64 · 1 Frustrated 0.76, 2 Very angry 0.24, 0 Calm 0.00
+
+```json
+{
+  "model": "typesafe/jev-1.13-20260917",
+  "provider": "openrouter",
+  "answers": { "urgent": { "type": "noul", "noul": 0.97 }, "...": {} },
+  "usage": { "input_tokens": 394, "output_tokens": 70, "cost": 0.000016548 },
+  "id": "gen-dec-..."
+}
+```
+````
+
+`usage.cost` is reported by OpenRouter only (`null` from TypeSafe). A fallback is noted under the summary line.
+
+### Usage Guidance
+
+Jev reads questions literally and is weak at counting, arithmetic, date comparison, and multi-hop reasoning; do those in code and ask narrow, atomic questions. Split compound judgments into separate questions and combine them in code. Treat low `confidence` as a signal to escalate to a generative model or a human. Limits: text only, about 64k tokens per request and 32k for the state plus the longest single question.
+
 ## Supported Models
 
-Provide models as plain name strings in the `models` array. Bare names and aliases resolve to a provider automatically; use a namespace prefix (`claude:`, `gemini:`, `copilot:`, `openrouter:`) or a full `provider/model` slug for explicit routing.
+Provide models as plain name strings in the `models` array. Each entry is `auto`, a provider name (its default model), `provider:model` (that model on that provider only), or a bare model ID/alias (the first set-up provider that offers it). Names that match no provider's list are rejected with suggestions. See [Model Selection](#model-selection) for the full rules.
 
 ### OpenAI Models
 
@@ -399,7 +503,7 @@ Provide models as plain name strings in the `models` array. Bare names and alias
 | `gemini-2.5-flash` | `flash` | 1M | 65K | Ultra-fast |
 | `gemini-2.5-flash-lite` | `flash-lite` | 1M | 65K | Lightweight fast model |
 
-**Note:** The short name `gemini` (and `gemini:pro` / `gemini:flash`) routes to the **Antigravity CLI** (`agy`, OAuth-based). 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) serves `gemini-3.8-flash` and `gemini-3.1-pro-preview` under the same IDs and aliases, so bare `pro`, `gemini-pro`, `flash` and those IDs go to Antigravity first when `agy` is installed; the bare name `gemini` is the Antigravity namespace. Use `google:<model>` (e.g. `google:pro`) to always use the Google API.
 
 ### X.AI / Grok Models
 
@@ -460,8 +564,9 @@ Any other model works via its full `provider/model` slug (e.g. `anthropic/claude
 
 **Codex** is an agentic coding assistant with direct filesystem access:
 
-- **Model**: `codex` (underlying model: GPT-6 Sol by default)
-- **Backend selection**: `codex:<model>` per request (e.g. `codex:luna`, `codex:astra`, `codex:gpt-5.6-terra`), or `CODEX_MODEL` globally; `sol`/`luna`/`gpt-6` name the GPT-6 tiers, the GPT-5.6 tiers are reached by full slug; unknown names pass through to the CLI verbatim
+- **Model**: `codex` (underlying model: GPT-6 Sol by default, or `CODEX_DEFAULT_MODEL`)
+- **Backend selection**: `codex:<model>` per request (e.g. `codex:luna`, `codex:astra`, `codex:gpt-5.6-terra`) from the Codex catalog: `gpt-6-sol` (`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`). Other names are rejected with suggestions. Bare IDs from this list (e.g. `gpt-6-astra`) go to Codex first, then the OpenAI API.
+- **Availability**: the Codex SDK is installed and `~/.codex/auth.json` exists (`$CODEX_HOME/auth.json` when set) or `CODEX_API_KEY` is set
 - **Thread-based sessions**: persistent conversation history via `continuation_id` in `chat` mode
 - **Direct file access**: reads files from the working directory (paths relative to `CLIENT_CWD`)
 - **Response times**: 6-20 seconds typical (complex tasks may take minutes)
@@ -472,9 +577,11 @@ Any other model works via its full `provider/model` slug (e.g. `anthropic/claude
 
 **Claude** is available through the Claude Agent SDK, using Claude Code CLI authentication instead of an API key:
 
-- **Model**: `claude` (aliases: `claude-sdk`, `claude-code`) — defaults to Claude Opus 5.5 (`claude-opus-5-5`)
-- **Model selection**: `claude:opus` or `claude:opus-5.5` (Claude Opus 5.5), `claude:opus-5` (Claude Opus 5), `claude:fable` or `claude:fable-5.1` (Claude Fable 5.1), `claude:fable-5` (Claude Fable 5.0); unknown `claude:`-prefixed names pass through to the SDK (e.g. `claude:claude-sonnet-4-6`)
+- **Model**: `claude` (namespaces: `claude`, `claude-code`, `claude-sdk`) — defaults to Claude Opus 5.5 (`claude-opus-5-5`), or `CLAUDE_DEFAULT_MODEL`
+- **Model selection**: `claude-opus-5-5` (`opus`, `claude-opus`, `opus-5.5`), `claude-opus-5` (`opus-5`), `claude-fable-5-1` (`fable`, `claude-fable`, `fable-5.1`), `claude-fable-5` (`fable-5`), e.g. `claude:opus`, `claude:fable`. Other names are rejected with suggestions.
 - **Authentication**: `claude login` — no `ANTHROPIC_API_KEY` needed
+- **Availability**: the Claude Agent SDK is installed and `~/.claude/.credentials.json` exists (`$CLAUDE_CONFIG_DIR` when set), or `CLAUDE_CODE_OAUTH_TOKEN`/`ANTHROPIC_API_KEY` is in the environment; on macOS the Keychain login is assumed. An expired login is caught at call time and bare-name/`auto` routing fails over.
+- **Permissions**: runs with `bypassPermissions`
 - **Direct file access**: reads files from the working directory
 - **Reasoning effort**: `reasoning_effort` maps to the SDK's `effort` option: `low`, `medium`, `high`, `xhigh`, or `max`; `none` and `minimal` become `low`. Omitting it retains the SDK default.
 - **Turn limit**: SDK requests allow up to 100 turns (`maxTurns: 100`).
@@ -484,7 +591,10 @@ Any other model works via its full `provider/model` slug (e.g. `anthropic/claude
 
 The **Antigravity CLI** (`agy`) provides subscription-based access to Gemini models through Google OAuth:
 
-- **Models** (text-only): `gemini` (= `gemini:flash`, Gemini 3.8 Flash), `gemini:pro` (Gemini 3.1 Pro)
+- **Models** (text-only): `gemini-3.8-flash` (`flash`, `gemini-3.8`, `flash-3.8`, ...; default, `gemini` = `gemini:flash`), `gemini-3.1-pro-preview` (`pro`, `gemini-pro`, `gemini-3.1-pro`, ...; `gemini:pro`). Default override: `AGY_DEFAULT_MODEL`.
+- **Namespaces**: `gemini`, `agy`, `antigravity`, `gemini-cli`
+- **Availability**: the `agy` binary is found on PATH or at the platform install location
+- **Permissions**: `agy` runs with `--dangerously-skip-permissions`, so every tool request is auto-approved
 - **Authentication**: Google OAuth via `agy` (one-time interactive login)
 - **Setup**: install the Antigravity CLI and run `agy` once to log in
 - **Billing**: uses your Antigravity subscription/compute allowance instead of API credits
@@ -506,28 +616,39 @@ agy
 
 ### GitHub Copilot SDK (subscription)
 
-Reach these with the `copilot:` namespace (e.g. `copilot:gpt-6-sol`); uses your GitHub Copilot subscription (`gh auth login`) — no API key needed:
+Reach these only with the `copilot:` namespace (also `github-copilot:`, `copilot-sdk:`; e.g. `copilot:gpt-6-sol`) — Copilot never serves bare model names. `copilot` alone uses GPT-6 Sol, or `COPILOT_DEFAULT_MODEL`. Available when the Copilot SDK is installed; uses your GitHub Copilot subscription (`gh auth login`) — no API key needed:
 
 - **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` (all accept `reasoning_effort`)
 - **Anthropic**: `claude-opus-5.5` (aliases: `opus`, `claude`), `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`)
-- Any other `copilot:<id>` is forwarded to the Copilot backend verbatim
+- Any other `copilot:<id>` is rejected with suggestions
 
 ### Model Selection
 
-Use `"auto"` for automatic selection, or specify exact models:
+Every entry in `models` takes one of four forms:
+
+- **`auto`** — the first available provider's default model.
+- **`provider`** — that provider's default model (hardcoded, or `<PROVIDER>_DEFAULT_MODEL`). Namespaces: `codex`; `gemini`/`agy`/`antigravity`/`gemini-cli` (Antigravity CLI); `claude`/`claude-code`/`claude-sdk` (Claude Agent SDK); `copilot`/`github-copilot`/`copilot-sdk`; `openai`; `google`; `xai`; `anthropic`; `mistral`; `deepseek`; `openrouter`.
+- **`provider:model`** — that model on that provider only; the model must be in that provider's list.
+- **Bare `model`** — the first provider, in the order `codex`, `gemini-cli`, `claude`, `openai`, `google`, `xai`, `anthropic`, `mistral`, `deepseek`, `openrouter`, whose list contains the ID or alias and that is set up (API key for API providers; SDK plus login for Codex and the Claude Agent SDK; the `agy` binary for Antigravity). On an authentication or availability error, the next set-up provider serving **the same model** takes over; a provider whose alias 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). Copilot never serves bare names.
+
+**Unknown names are rejected**, never forwarded: the error lists 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?`. The exception is OpenRouter: a full `vendor/model` slug (bare or `openrouter:`) is validated against OpenRouter's live catalog.
 
 ```text
 "auto"                     // First available provider (chat); first 3 (consensus)
-"gpt-6"                    // OpenAI flagship (-> gpt-6-sol)
+"gpt-6"                    // Codex (-> gpt-6-sol), else OpenAI API
+"openai:gpt-6"             // OpenAI API only
 "gemini-2.5-flash"         // Google API
+"pro"                      // Antigravity CLI (-> gemini-3.1-pro-preview), else Google API
+"google:pro"               // Google API only
 "grok-4.5"                 // X.AI
 "deepseek"                 // DeepSeek (-> deepseek-v4-pro)
 "mistral"                  // Mistral (-> mistral-medium-3-5)
 "z-ai/glm-5.2"             // OpenRouter (full slug)
 "z-ai/glm-5.2:online"      // OpenRouter with web search opt-in
-"fable"                    // Anthropic API (-> claude-fable-5)
-"opus"                     // Anthropic API (-> claude-opus-5-5)
+"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
 "claude"                   // Claude Agent SDK (-> Claude Opus 5.5)
 "claude:fable"             // Claude Agent SDK (Claude Fable 5.1)
 "codex:luna"               // Codex (GPT-6 Luna)
@@ -535,6 +656,8 @@ Use `"auto"` for automatic selection, or specify exact models:
 "copilot:gpt-6-sol"        // GitHub Copilot SDK
 ```
 
+**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 and the Claude Agent SDK runs with `bypassPermissions`, so a read-only prompt is not an enforced boundary there. Name the API provider (`google:pro`, `anthropic:opus`, `openai:gpt-6-astra`) to keep a request on a plain API.
+
 **Auto behavior:**
 - **chat mode**: `["auto"]` selects the first available provider and uses its default model, with failover to the next provider on error.
 - **consensus mode**: `["auto"]` expands to the first 3 available providers.
@@ -559,7 +682,7 @@ Control Codex behavior through environment variables:
 - **`CODEX_SANDBOX_MODE`** — filesystem access: `read-only` (default), `workspace-write`, `danger-full-access` (containers only)
 - **`CODEX_SKIP_GIT_CHECK`** — `true` (default) works in any directory; `false` requires a Git repository
 - **`CODEX_APPROVAL_POLICY`** — `never` (default, recommended for servers), `untrusted`, `on-failure`, `on-request`
-- **`CODEX_MODEL`** — underlying model for Codex sessions (default: `gpt-6-sol`)
+- **`CODEX_DEFAULT_MODEL`** — model used for `codex` and `auto` (default: `gpt-6-sol`); the legacy name `CODEX_MODEL` is honored when it is unset
 - **`CODEX_API_KEY`** — optional API key for headless deployments (alternative to ChatGPT login)
 
 **Example (.env):**
@@ -568,7 +691,25 @@ CODEX_API_KEY=your_codex_api_key_here
 CODEX_SANDBOX_MODE=read-only
 CODEX_SKIP_GIT_CHECK=true
 CODEX_APPROVAL_POLICY=never
-CODEX_MODEL=gpt-6-sol
+CODEX_DEFAULT_MODEL=gpt-6-sol
+```
+
+### Default Models
+
+Each provider's default model (used for its bare provider name and for `auto`) can be set with `<PROVIDER>_DEFAULT_MODEL`. 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
 ```
 
 ## Context Processing
@@ -656,12 +797,12 @@ Set `async: true` on a chat request for long-running work:
 
 **Missing API key / unavailable provider:**
 ```json
-{ "error": "Provider openai is not available. Check API key configuration." }
+{ "error": "Provider openai is not available: set OPENAI_API_KEY." }
 ```
 
-**Invalid model:**
+**Invalid model** (unknown names are rejected with up to three suggestions):
 ```json
-{ "error": "Provider not found for model: invalid-model" }
+{ "error": "Unknown model \"gtp-6-astra\". Did you mean: gpt-6-astra?" }
 ```
 
 **All models failed (multi-model chat):** the error lists each model and its failure. In consensus/roundtable, individual model/turn failures are recorded in the result (`failed` entries and trailing failure details) rather than aborting the whole request.
@@ -677,6 +818,7 @@ ANTHROPIC_API_KEY=sk-ant-...
 MISTRAL_API_KEY=...
 DEEPSEEK_API_KEY=...
 OPENROUTER_API_KEY=sk-or-...
+TYPESAFE_API_KEY=...            # decide tool only
 ```
 
 **MCP client configuration:**

package/docs/EXAMPLES.md

@@ -74,6 +74,24 @@ I'd be happy to help you understand JavaScript promises! Promises are objects th
 }
 ```
 
+A bare model name goes to the first set-up provider that offers it (here Codex, then the OpenAI API), failing over only to providers serving the same model. Unknown names are rejected with "Did you mean" suggestions.
+
+### Pinning a provider
+
+Use `provider:model` to run a model on one provider only, or a provider name alone for its default model:
+
+```json
+{
+  "tool": "chat",
+  "arguments": {
+    "prompt": "Compare these two approaches to request batching",
+    "models": ["openai:gpt-6-astra", "google:pro", "anthropic:opus", "codex:luna", "copilot:sonnet"]
+  }
+}
+```
+
+Naming the API provider (`google:pro`, `anthropic:opus`) keeps the request off the local agent providers (Antigravity CLI, Claude Agent SDK), which bare names and `auto` otherwise reach first when they are set up.
+
 ### Fast responses with a lightweight model
 
 ```json
@@ -426,6 +444,26 @@ Codex maintains conversation history through threads in `chat` mode:
 }
 ```
 
+### Choosing the Codex Model
+
+`codex` uses GPT-6 Sol (or `CODEX_DEFAULT_MODEL`); `codex:<model>` picks another model from the Codex list:
+
+```json
+{
+  "tool": "chat",
+  "arguments": {
+    "prompt": "Find the race condition in the job scheduler",
+    "models": ["codex:astra"],
+    "files": ["/path/to/src/scheduler.js"]
+  }
+}
+```
+
+```bash
+# Default model for "codex" and "auto" (CODEX_MODEL is honored as a legacy fallback)
+CODEX_DEFAULT_MODEL=gpt-6-luna
+```
+
 ### Sandbox Modes
 
 Control filesystem access through `CODEX_SANDBOX_MODE`: