converse-mcp-server 2.29.2 → 3.0.1

package/docs/API.md

@@ -1,1562 +1,703 @@
-# Converse MCP Server - API Reference
-
-## Overview
-
-The Converse MCP Server provides five main tools through the Model Context Protocol (MCP):
-
-1. **Chat Tool** - Single-provider conversational AI with context support and AI summarization
-2. **Consensus Tool** - Multi-provider parallel execution with response aggregation and combined summaries
-3. **Conversation Tool** - Turn-based multi-model round-table where models respond sequentially, each seeing the full running transcript
-4. **Check Status Tool** - Monitor and retrieve results from asynchronous operations with intelligent summaries
-5. **Cancel Job Tool** - Cancel running background operations
-
-All tools support both **synchronous** (immediate response) and **asynchronous** (background processing) execution modes. When AI summarization is enabled, tools automatically generate titles and summaries for better context understanding.
-
-## Transport Protocols
-
-The server supports two transport modes:
-
-### HTTP Transport (Default)
-- **Endpoint**: `http://localhost:3157/mcp` 
-- **Protocol**: HTTP streaming with JSON-RPC 2.0
-- **Usage**: Best for development, debugging, and web integrations
-- **Features**: Health endpoints, CORS support, session management
-
-### Stdio Transport (Legacy)
-- **Protocol**: Standard input/output with JSON-RPC 2.0
-- **Usage**: Traditional MCP client integrations
-- **Features**: Process-based communication, lower latency
-
-**Transport Selection:**
-```bash
-# Default (HTTP)
-npm start
-
-# Explicit HTTP
-npm start -- --transport=http
-
-# Stdio transport
-npm start -- --transport=stdio
-
-# Environment variable
-MCP_TRANSPORT=stdio npm start
-```
-
-## Tool Schemas
-
-### Chat Tool
-
-**Description**: General conversational AI with context and continuation support.
-
-#### Request Schema
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "prompt": {
-      "type": "string",
-      "description": "Your question or topic with relevant context. Example: 'How should I structure the authentication module for this Express.js API?'"
-    },
-    "model": {
-      "type": "string", 
-      "description": "AI model to use. Examples: 'auto' (recommended), 'gemini-2.5-flash', 'gpt-5', 'grok-4'. Default: 'auto'"
-    },
-    "files": {
-      "type": "array",
-      "items": {"type": "string"},
-      "description": "File paths to include as context (absolute paths required). Example: ['/path/to/src/auth.js', '/path/to/config.json']"
-    },
-    "images": {
-      "type": "array", 
-      "items": {"type": "string"},
-      "description": "Image paths for visual context (absolute paths or base64). Example: ['/path/to/diagram.png', 'data:image/jpeg;base64,...']"
-    },
-    "continuation_id": {
-      "type": "string",
-      "description": "Continuation ID for persistent conversation. Example: 'chat_1703123456789_abc123'"
-    },
-    "temperature": {
-      "type": "number",
-      "minimum": 0.0,
-      "maximum": 1.0,
-      "default": 0.5,
-      "description": "Response randomness (0.0-1.0). Examples: 0.2 (focused), 0.5 (balanced), 0.8 (creative)"
-    },
-    "reasoning_effort": {
-      "type": "string",
-      "enum": ["minimal", "low", "medium", "high", "max"],
-      "default": "medium", 
-      "description": "Reasoning depth for thinking models. Examples: 'minimal' (fastest, few reasoning tokens), 'low' (light analysis), 'medium' (balanced), 'high' (complex analysis)"
-    },
-    "verbosity": {
-      "type": "string",
-      "enum": ["low", "medium", "high"],
-      "default": "medium",
-      "description": "Output verbosity for GPT-5 models. Examples: 'low' (concise answers), 'medium' (balanced), 'high' (thorough explanations)"
-    },
-    "use_websearch": {
-      "type": "boolean",
-      "default": false,
-      "description": "Enable web search for current information. Example: true for framework docs, false for private code analysis"
-    },
-    "media_resolution": {
-      "type": "string",
-      "enum": ["MEDIA_RESOLUTION_LOW", "MEDIA_RESOLUTION_MEDIUM", "MEDIA_RESOLUTION_HIGH", "MEDIA_RESOLUTION_UNSPECIFIED"],
-      "default": "MEDIA_RESOLUTION_HIGH",
-      "description": "Control image/PDF/video processing quality (Gemini 3.0). Defaults to 'MEDIA_RESOLUTION_HIGH' for Gemini 3.0. Examples: 'MEDIA_RESOLUTION_LOW' (faster, less detail), 'MEDIA_RESOLUTION_MEDIUM' (balanced), 'MEDIA_RESOLUTION_HIGH' (maximum detail)"
-    },
-    "async": {
-      "type": "boolean",
-      "default": false,
-      "description": "Execute in background mode. Returns continuation_id immediately for status monitoring. Example: true for long-running analysis"
-    },
-    "export": {
-      "type": "boolean",
-      "default": false,
-      "description": "Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata. Example: true to save for documentation"
-    }
-  },
-  "required": ["prompt"]
-}
-```
-
-#### Response Format
-
-**Synchronous Response (async=false):**
-```json
-{
-  "content": "AI response text",
-  "continuation": {
-    "id": "conv_d6a6a5ec-6900-4fd8-a4e0-1fa4f75dfc42",
-    "provider": "openai",
-    "model": "gpt-5-mini",
-    "messageCount": 3
-  },
-  "metadata": {
-    "model": "gpt-5-mini",
-    "usage": {
-      "input_tokens": 150,
-      "output_tokens": 85,
-      "total_tokens": 235
-    },
-    "response_time_ms": 1247,
-    "provider": "openai"
-  },
-  "title": "Authentication Module Structure Guide",  // When summarization enabled
-  "final_summary": "Provided architectural recommendations for Express.js auth module with JWT tokens and role-based access control."  // When summarization enabled
-}
-```
-
-**Asynchronous Response (async=true):**
-```json
-{
-  "content": "⏳ PROCESSING | CHAT | conv_abc123def | 1/1 | Started: 2023-12-01 10:30:00 | openai/gpt-5",
-  "continuation": {
-    "id": "conv_abc123def",
-    "status": "processing"
-  },
-  "async_execution": true
-}
-```
-
-#### Example Usage
-
-**Basic query:**
-```json
-{
-  "prompt": "Review this authentication function for security issues",
-  "model": "o3",
-  "files": ["/project/src/auth.js", "/project/config/security.json"],
-  "temperature": 0.2,
-  "reasoning_effort": "high"
-}
-```
-
-**With conversation export:**
-```json
-{
-  "prompt": "Help me design a scalable architecture for our system",
-  "model": "gpt-5",
-  "export": true,
-  "continuation_id": "conv_architecture_design"
-}
-```
-
-When export is enabled, the conversation will be saved to disk in the following structure:
-```
-conv_architecture_design/
-├── 1_request.txt      # First user prompt
-├── 1_response.txt     # First AI response
-├── 2_request.txt      # Second user prompt (if continuing)
-├── 2_response.txt     # Second AI response
-└── metadata.json      # Conversation metadata and settings
-```
-
-### Consensus Tool
-
-**Description**: Multi-provider parallel execution with cross-model feedback for gathering perspectives from multiple AI models.
-
-#### Request Schema
-
-```json
-{
-  "type": "object", 
-  "properties": {
-    "prompt": {
-      "type": "string",
-      "description": "The problem or proposal to gather consensus on. Example: 'Should we use microservices or monolith architecture for our e-commerce platform?'"
-    },
-    "models": {
-      "type": "array",
-      "items": {"type": "string"},
-      "minItems": 1,
-      "description": "List of models to consult. Example: ['o3', 'gemini-2.5-flash', 'grok-4']"
-    },
-    "files": {
-      "type": "array",
-      "items": {"type": "string"},
-      "description": "File paths for additional context. Example: ['/path/to/architecture.md', '/path/to/requirements.txt']"
-    },
-    "images": {
-      "type": "array",
-      "items": {"type": "string"}, 
-      "description": "Image paths for visual context. Example: ['/path/to/architecture.png', '/path/to/user_flow.jpg']"
-    },
-    "continuation_id": {
-      "type": "string",
-      "description": "Thread continuation ID for multi-turn conversations. Example: 'consensus_1703123456789_xyz789'"
-    },
-    "enable_cross_feedback": {
-      "type": "boolean",
-      "default": true,
-      "description": "Enable refinement phase where models see others' responses. Example: true (recommended), false (faster)"
-    },
-    "cross_feedback_prompt": {
-      "type": "string",
-      "description": "Custom prompt for refinement phase. Example: 'Focus on scalability trade-offs in your refinement'"
-    },
-    "temperature": {
-      "type": "number",
-      "minimum": 0.0, 
-      "maximum": 1.0,
-      "default": 0.2,
-      "description": "Response randomness. Examples: 0.1 (very focused), 0.2 (analytical), 0.5 (balanced)"
-    },
-    "reasoning_effort": {
-      "type": "string",
-      "enum": ["minimal", "low", "medium", "high", "max"],
-      "default": "medium",
-      "description": "Reasoning depth. Examples: 'medium' (balanced), 'high' (complex analysis), 'max' (thorough evaluation)"
-    },
-    "async": {
-      "type": "boolean",
-      "default": false,
-      "description": "Execute in background mode with per-provider progress tracking. Returns continuation_id immediately for monitoring."
-    },
-    "export": {
-      "type": "boolean",
-      "default": false,
-      "description": "Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata. Example: true to save consensus results"
-    }
-  },
-  "required": ["prompt", "models"]
-}
-```
-
-#### Response Format
-
-**Synchronous Response (async=false):**
-```json
-{
-  "status": "consensus_complete",
-  "models_consulted": 3,
-  "successful_initial_responses": 3,
-  "failed_responses": 0,
-  "refined_responses": 3,
-  "title": "Architecture Review Recommendations",  // When summarization enabled
-  "final_summary": "All models agree on microservices approach with event-driven architecture for scalability.",  // When summarization enabled  
-  "phases": {
-    "initial": [
-      {
-        "model": "o3",
-        "status": "success",
-        "response": "Initial analysis from O3...",
-        "metadata": {
-          "provider": "openai",
-          "input_tokens": 200,
-          "output_tokens": 150,
-          "response_time": 2500
-        }
-      }
-    ],
-    "refined": [
-      {
-        "model": "o3", 
-        "status": "success",
-        "initial_response": "Initial analysis...",
-        "refined_response": "After considering other perspectives...",
-        "metadata": {
-          "total_response_time": 4800,
-          "total_input_tokens": 450,
-          "total_output_tokens": 320
-        }
-      }
-    ],
-    "failed": []
-  },
-  "continuation": {
-    "id": "consensus_xyz789",
-    "messageCount": 2
-  },
-  "settings": {
-    "enable_cross_feedback": true,
-    "temperature": 0.2,
-    "models_requested": ["o3", "gemini-2.5-flash", "grok-4"]
-  }
-}
-```
-
-**Asynchronous Response (async=true):**
-```json
-{
-  "content": "⏳ PROCESSING | CONSENSUS | consensus_xyz789 | 0/3 | Started: 2023-12-01 10:30:00 | gpt-5,gemini-2.5-pro,grok-4",
-  "continuation": {
-    "id": "consensus_xyz789",
-    "status": "processing"
-  },
-  "async_execution": true,
-  "metadata": {
-    "total_models": 3,
-    "successful_models": 0,
-    "models_list": "gpt-5,gemini-2.5-pro,grok-4"
-  }
-}
-```
-
-#### Example Usage
-
-```json
-{
-  "prompt": "What's the best database solution for a high-traffic social media platform?",
-  "models": [
-    {"model": "o3"},
-    {"model": "gemini-2.5-pro"}, 
-    {"model": "grok-4"}
-  ],
-  "files": ["/docs/requirements.md", "/docs/current_architecture.md"],
-  "enable_cross_feedback": true,
-  "temperature": 0.1,
-  "reasoning_effort": "high"
-}
-```
-
-### Conversation Tool
-
-**Description**: Turn-based multi-model round-table. Unlike consensus (parallel, all models answer the same prompt), models here respond **sequentially in the order given**, and each model sees the full running transcript of every turn before it. One tool call runs exactly **one lap** (one turn per model). The caller drives more laps by passing back the returned `continuation_id`; every lap appends to one shared, accumulating transcript that all models see.
-
-#### Request Schema
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "prompt": {
-      "type": "string",
-      "description": "The topic or question to open the round-table with. Example: 'Critique this caching strategy and propose improvements.'"
-    },
-    "models": {
-      "type": "array",
-      "items": {"type": "string"},
-      "minItems": 1,
-      "description": "Ordered list of models. ORDER MATTERS: models speak one after another in this exact order, each seeing the transcript of those before it. Example: ['codex', 'gemini', 'claude']"
-    },
-    "continuation_id": {
-      "type": "string",
-      "description": "Thread continuation ID for running more laps. Auto-generated in the first response; pass it back to run another lap where every model again sees the full accumulated transcript. You MAY change the models list on a resuming lap."
-    },
-    "turn_prompt": {
-      "type": "string",
-      "description": "Optional custom per-turn instruction appended to the round-table framing each model receives. Example: 'Focus on security implications in your turn.'"
-    },
-    "files": {
-      "type": "array",
-      "items": {"type": "string"},
-      "description": "File paths shared with every participant in the lap. Supports line ranges: file.txt{10:50}."
-    },
-    "images": {
-      "type": "array",
-      "items": {"type": "string"},
-      "description": "Image paths for visual context (absolute paths or base64)."
-    },
-    "temperature": {
-      "type": "number",
-      "minimum": 0.0,
-      "maximum": 1.0,
-      "default": 0.2,
-      "description": "Response randomness. Examples: 0.1 (very focused), 0.2 (analytical), 0.5 (balanced)"
-    },
-    "reasoning_effort": {
-      "type": "string",
-      "enum": ["none", "minimal", "low", "medium", "high", "max"],
-      "default": "medium",
-      "description": "Reasoning depth for thinking models."
-    },
-    "use_websearch": {
-      "type": "boolean",
-      "default": false,
-      "description": "Enable web search for current information (models that support it)."
-    },
-    "async": {
-      "type": "boolean",
-      "default": false,
-      "description": "Execute the lap in background with per-turn progress tracking. Returns continuation_id immediately."
-    },
-    "export": {
-      "type": "boolean",
-      "default": false,
-      "description": "Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata."
-    }
-  },
-  "required": ["prompt", "models"]
-}
-```
-
-#### Response Format
-
-**Synchronous Response (async=false):**
-
-The response content begins with a status line and `continuation_id:` line (the status line is omitted in the test environment), followed by a JSON result object:
-
-```
-✅ COMPLETED | CONVERSATION | conv_abc123 | 3.2s elapsed | 2/2 turns | codex, gemini
-continuation_id: conv_abc123
-
-{
-  "status": "conversation_complete",
-  "models_consulted": 2,
-  "successful_turns": 2,
-  "failed_turns": 0,
-  "turns": [
-    {
-      "model": "codex",
-      "provider": "codex",
-      "status": "success",
-      "response": "Opening analysis of the caching strategy...",
-      "position": 0
-    },
-    {
-      "model": "gemini",
-      "provider": "gemini-cli",
-      "status": "success",
-      "response": "Building on codex's point about TTLs, I'd add...",
-      "position": 1
-    }
-  ],
-  "continuation": {
-    "id": "conv_abc123",
-    "messageCount": 3
-  },
-  "settings": {
-    "temperature": 0.2,
-    "models_requested": ["codex", "gemini"]
-  }
-}
-```
-
-A turn that failed is recorded with `"status": "failed"` and an `"error"` note rather than aborting the lap; the response reports `successful_turns`/`models_consulted` accordingly and lists failed models in trailing failure details.
-
-**Asynchronous Response (async=true):**
-```json
-{
-  "content": "⏳ SUBMITTED | CONVERSATION | conv_xyz789 | 1/1 | Started: 01/12/2023 10:30:00 | \"Caching Round-Table\" | codex, gemini",
-  "continuation": {
-    "id": "conv_xyz789",
-    "status": "processing"
-  },
-  "async_execution": true
-}
-```
-
-When complete, `check_status` for the continuation_id renders the full lap transcript (the async result carries a top-level `content` field with the rendered transcript) plus the AI-generated title and final summary.
-
-#### Example Usage
-
-**Basic two-model lap:**
-```json
-{
-  "prompt": "Should we adopt event sourcing for the order service?",
-  "models": ["codex", "gemini"]
-}
-```
-
-**Continuing the round-table (another lap):**
-```json
-{
-  "prompt": "Now focus specifically on the migration path.",
-  "models": ["codex", "gemini"],
-  "continuation_id": "conv_abc123"
-}
-```
-
-**Async round-table with a custom per-turn instruction:**
-```json
-{
-  "prompt": "Review this module design.",
-  "models": ["codex", "gemini", "claude"],
-  "files": ["/project/src/orders/design.md"],
-  "turn_prompt": "Call out concrete failure modes you would test for.",
-  "async": true
-}
-```
-
-## Supported Models
-
-### OpenAI Models
-
-| Model | Context | Tokens | Features | Use Cases |
-|-------|---------|--------|----------|-----------|
-| `gpt-5.6-sol` (`gpt-5.6`, `gpt-5`, `sol`) | 1M | 128K | Flagship, default | Frontier reasoning, coding, agentic workflows |
-| `gpt-5.6-terra` (`terra`) | 400K | 128K | Lower cost | Strong performance at half the flagship price |
-| `gpt-5.6-luna` (`luna`) | 400K | 128K | Fastest | High-volume, latency-sensitive workloads |
-| `gpt-5.4` | 1M | 128K | Previous flagship | Complex reasoning, analysis |
-| `gpt-5.4-pro` | 1M | 272K | Pro tier | Extended capabilities (expensive) |
-| `gpt-5-mini` | 400K | 128K | Fast | Balanced performance/speed |
-| `gpt-5-nano` | 400K | 128K | Ultra-fast | Quick responses, simple queries |
-| `o3` | 200K | 100K | Reasoning | Logic, analysis, complex problems |
-| `o3-pro` | 200K | 100K | Extended reasoning | Deep analysis |
-| `o4-mini` | 200K | 100K | Fast reasoning | General purpose, rapid reasoning |
-| `gpt-4.1` | 1M | 32K | Large context | Long documents, analysis |
-
-### Google/Gemini Models (API-based)
-
-| Model | Alias | Context | Tokens | Features | Use Cases |
-|-------|-------|---------|--------|----------|-----------|
-| `gemini-3-pro-preview` | `pro` | 1M | 64K | Thinking levels, enhanced reasoning | Complex problems, deep analysis |
-| `gemini-2.5-pro` | `pro 2.5` | 1M | 65K | Thinking mode | Deep reasoning, architecture |
-| `gemini-2.5-flash` | `flash` | 1M | 65K | Ultra-fast | Quick analysis, simple queries |
-
-**Note:** The short model name `gemini` (and `gemini:flash` / `gemini:pro`) routes to the **Antigravity CLI** (`agy`, OAuth-based). For Google API access, use specific model names like `gemini-2.5-pro` or `gemini-2.5-flash` (bare `gemini-pro`/`gemini-flash` also route to the Google API).
-
-### X.AI/Grok Models
-
-| Model | Alias | Context | Tokens | Features | Use Cases |
-|-------|-------|---------|--------|----------|-----------|
-| `grok-4-0709` | `grok`, `grok-4` | 256K | 256K | Advanced | Latest capabilities |
-| `grok-code-fast-1` | `grok-code-fast` | 256K | 256K | Code optimization | Agentic coding |
-
-### Anthropic Models
-
-| Model | Alias | Context | Tokens | Features | Use Cases |
-|-------|-------|---------|--------|----------|-----------|
-| `claude-fable-5` | `fable`, `fable-5` | 1M | 128K | Adaptive thinking, effort, images, caching, compaction | Most demanding reasoning, long-horizon agentic work |
-| `claude-opus-4-8` | `opus`, `opus-4.8` | 200K (1M beta) | 128K | Adaptive thinking, effort, images, caching, compaction | Complex reasoning, agentic coding |
-| `claude-opus-4-7` | `opus-4.7` | 200K (1M beta) | 128K | Adaptive thinking, effort, images, caching, compaction | Previous Opus generation |
-| `claude-opus-4-6` | `opus-4.6` | 200K (1M beta) | 128K | Adaptive thinking, effort, images, caching, compaction | Previous Opus generation |
-| `claude-opus-4-5-20251101` | `opus-4.5` | 200K | 64K | Extended thinking, effort (beta), images, caching | Legacy Opus |
-| `claude-opus-4-1-20250805` | `opus-4.1`, `opus-4` | 200K | 32K | Extended thinking, images, caching | Legacy Opus |
-| `claude-sonnet-4-6` | `sonnet`, `sonnet-4.6` | 200K (1M beta) | 64K | Adaptive thinking, effort, images, caching, compaction | Best speed/intelligence balance |
-| `claude-sonnet-4-5-20250929` | `sonnet-4.5` | 200K (1M beta) | 64K | Extended thinking, images, caching | Legacy Sonnet |
-| `claude-haiku-4-5-20251001` | `haiku`, `haiku-4.5` | 200K | 64K | Extended thinking, images, caching | Fast and intelligent |
-
-**Note:** Claude Fable 5 does not accept the `temperature` parameter (it is silently omitted). Models with adaptive thinking control thinking depth via `reasoning_effort`, which maps to Anthropic's `effort` parameter.
-
-**Prompt Caching (Always Enabled):**
-- System prompts are automatically cached for 1 hour using Anthropic's prompt caching
-- Reduces latency and costs for repeated requests with the same system prompt
-- Minimum 1024 tokens required for caching (2048 for Haiku models)
-- Cache information available in response metadata: `cache_creation_input_tokens` and `cache_read_input_tokens`
-
-### DeepSeek Models
-
-| Model | Alias | Context | Tokens | Features | Use Cases |
-|-------|-------|---------|--------|----------|-----------|
-| `deepseek-v3` | `deepseek-chat`, `deepseek` | 128K | 64K | Latest model | General purpose AI |
-| `deepseek-coder-v2.5` | `deepseek-coder` | 128K | 16K | Code optimization | Programming tasks |
-
-### Mistral Models
-
-| Model | Alias | Context | Tokens | Features | Use Cases |
-|-------|-------|---------|--------|----------|-----------|
-| `magistral-medium-2506` | `magistral`, `magistral-medium` | 40K | 8K | Reasoning model | Complex reasoning |
-| `magistral-small-2506` | `magistral-small` | 40K | 8K | Small reasoning | Fast reasoning |
-| `mistral-medium-2505` | `mistral-medium`, `mistral` | 128K | 32K | Multimodal | General + images |
-
-### OpenRouter Models
-
-| Model | Alias | Context | Tokens | Features | Use Cases |
-|-------|-------|---------|--------|----------|-----------|
-| `kimi/k2` | `k2`, `kimi-k2` | 256K | 128K | Latest Kimi | Large context tasks |
-| `qwen/qwen-2.5-coder-32b-instruct` | `qwen-coder` | 32K | 32K | Code focus | Programming |
-| `qwen/qwq-32b-preview` | `qwen-thinking`, `qwq` | 32K | 32K | Reasoning | Step-by-step thinking |
-
-### Codex Models
-
-**Codex** is an agentic coding assistant with direct filesystem access:
-
-- **Model**: `codex`
-- **Thread-based sessions**: Persistent conversation history via continuation_id
-- **Direct file access**: Reads files from working directory (paths relative to CLIENT_CWD)
-- **Response times**: 6-20 seconds typical (complex tasks may take minutes)
-- **Authentication**: Requires ChatGPT login OR `CODEX_API_KEY` environment variable
-
-### Claude Agent SDK Models
-
-**Claude** is also 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 Fable 5
-- **Model selection**: `claude:fable` (Claude Fable 5) or `claude:opus` (Claude Opus 4.8); unknown `claude:`-prefixed names pass through to the SDK (e.g. `claude:claude-sonnet-4-6`)
-- **Authentication**: Claude Code login (`claude login`) - no `ANTHROPIC_API_KEY` needed
-- **Direct file access**: Reads files from working directory
-- **Note**: `temperature`, `use_websearch`, and `reasoning_effort` are managed by the SDK (ignored if specified)
-
-### Gemini Models via Antigravity CLI (OAuth-based)
-
-The **Antigravity CLI** (`agy`) provides subscription-based access to Gemini models through Google OAuth:
-
-- **Models** (text-only): `gemini` (= `gemini:pro`, Gemini 3.1 Pro), `gemini:flash` (Gemini 3.5 Flash)
-- **Authentication**: Google OAuth via `agy` (requires 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
-- **Detection**: The provider locates the `agy` binary on PATH or at the platform install location (no credentials file)
-- **Reasoning effort**: `low`/`medium`/`high`/`max` select the model variant (e.g. Flash Low/Medium/High; Pro Low/High)
-- **Context**: 1M tokens
-- **Note**: One-shot responses (no token-level streaming); ~7s minimum per call
-
-> Replaces the previous `@google/gemini-cli` integration, whose OAuth access Google sunsets on 2026-06-18.
-
-**Authentication Setup:**
-```bash
-# Install the Antigravity CLI (agy)
-# Windows (PowerShell):
-irm https://antigravity.google/cli/install.ps1 | iex
-# macOS/Linux:
-curl -fsSL https://antigravity.google/cli/install.sh | bash
-
-# Run interactive login (one-time) — also establishes workspace trust
-agy
-```
-
-**Usage Example:**
-```json
-{
-  "name": "chat",
-  "arguments": {
-    "prompt": "Explain the event loop in JavaScript",
-    "model": "gemini"
-  }
-}
-```
-
-**Codex-Specific Behavior:**
-- `continuation_id` - Required for thread continuation (maintains full conversation history)
-- `files` parameter - Files accessed directly from working directory, not passed as message content
-- `temperature`, `use_websearch` - Not supported by Codex (ignored if specified)
-- Responses significantly longer than API-based providers
-
-**Configuration (see [Codex Configuration](#codex-configuration) section):**
-- `CODEX_SANDBOX_MODE` - Filesystem access control
-- `CODEX_SKIP_GIT_CHECK` - Git repository requirement
-- `CODEX_APPROVAL_POLICY` - Command approval behavior
-
-### Model Selection
-
-Use `"auto"` for automatic selection or specify exact models:
-
-```json
-// Automatic selection (recommended)
-{"model": "auto"}
-
-// Specific models  
-{"model": "gemini-2.5-flash"}
-{"model": "o3"}
-{"model": "grok-4-0709"}
-
-// Using aliases
-{"model": "flash"}  // -> gemini-2.5-flash
-{"model": "pro"}    // -> gemini-2.5-pro  
-{"model": "grok"}   // -> grok-4-0709
-{"model": "grok-4"}  // -> grok-4-0709
-{"model": "fable"}  // -> claude-fable-5 (Anthropic API)
-{"model": "opus"}   // -> claude-opus-4-8 (Anthropic API)
-
-// SDK providers (subscription-based)
-{"model": "claude"}        // -> Claude Agent SDK (Claude Fable 5)
-{"model": "claude:opus"}   // -> Claude Agent SDK (Claude Opus 4.8)
-{"model": "copilot:codex"} // -> GitHub Copilot SDK (gpt-5.3-codex)
-```
-
-## Configuration
-
-### AI Summarization
-
-Configure intelligent title and summary generation for better context understanding:
-
-```bash
-# Environment variables
-ENABLE_RESPONSE_SUMMARIZATION=true    # Enable AI-powered summarization (default: false)
-SUMMARIZATION_MODEL=gpt-5-nano        # Model for summarization (default: gpt-5-nano)
-```
-
-**When Enabled:**
-- Automatic title generation (up to 60 chars) for each request
-- Status check returns an up-to-date summary of the progress based on the partially streamed response  
-- Final summaries (1-2 sentences) for completed responses
-- Enhanced check_status display with titles and summaries
-- Persistent storage of summaries with async jobs
-
-**Implementation Details:**
-- Uses fast models (gpt-5-nano, gemini-2.5-flash) for minimal latency
-- Temperature set to 0.3 for consistent, focused summaries
-- Graceful fallback to text snippets when disabled or on errors
-- Non-blocking - summarization failures don't affect main flow
-
-### Codex Configuration
-
-Control Codex behavior through environment variables:
-
-**CODEX_SANDBOX_MODE** - Filesystem access control:
-- `read-only` (default): Can read files but not modify
-- `workspace-write`: Can modify files in workspace only
-- `danger-full-access`: Full filesystem access (use in containers only)
-
-**CODEX_SKIP_GIT_CHECK** - Git repository requirement:
-- `true` (default): Works in any directory
-- `false`: Requires working directory to be a Git repository
-
-**CODEX_APPROVAL_POLICY** - Command approval behavior:
-- `never` (default): Never prompt for approval (recommended for servers)
-- `untrusted`: Prompt for untrusted commands
-- `on-failure`: Prompt when commands fail
-- `on-request`: Let model decide (may hang in headless mode)
-
-**Authentication:**
-- Requires ChatGPT login (system-wide, persists across restarts)
-- Alternative: Set `CODEX_API_KEY` environment variable for headless deployments
-
-**Example Configuration (.env file):**
-```bash
-# Codex authentication (optional if ChatGPT login available)
-CODEX_API_KEY=your_codex_api_key_here
-
-# Codex behavior
-CODEX_SANDBOX_MODE=read-only                 # Default: read-only
-CODEX_SKIP_GIT_CHECK=true                    # Default: true
-CODEX_APPROVAL_POLICY=never                  # Default: never
-```
-
-## Context Processing
-
-### File Support
-
-**Supported Text Formats:**
-- `.txt`, `.md`, `.js`, `.ts`, `.json`, `.yaml`, `.yml`
-- `.py`, `.java`, `.c`, `.cpp`, `.h`, `.css`, `.html`
-- `.xml`, `.csv`, `.sql`, `.sh`, `.bat`, `.log`
-
-**Supported Image Formats:**
-- `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp`
-
-**Size Limits:**
-- Text files: 1MB default
-- Image files: 10MB default
-
-### File Processing
-
-```json
-{
-  "files": [
-    "/absolute/path/to/file.js",
-    "./relative/path/to/file.md"
-  ]
-}
-```
-
-**Response includes:**
-- File content with line numbers
-- Metadata (size, last modified)
-- Error handling for inaccessible files
-
-### Image Processing
-
-```json
-{
-  "images": [
-    "/path/to/diagram.png",
-    "data:image/jpeg;base64,/9j/4AAQ..."
-  ]
-}
-```
-
-**Features:**
-- Base64 encoding for AI processing
-- MIME type detection
-- Size validation
-- Security path checking
-
-## Continuation System
-
-### Creating Conversations
-
-First request creates a continuation automatically:
-
-```json
-{
-  "prompt": "Start a conversation about architecture",
-  "model": "auto"
-}
-```
-
-Response includes continuation ID:
-
-```json
-{
-  "content": "Let's discuss architecture...",
-  "continuation": {
-    "id": "conv_abc123",
-    "provider": "openai",
-    "model": "gpt-5-mini",
-    "messageCount": 2
-  }
-}
-```
-
-### Continuing Conversations
-
-Use the continuation ID in subsequent requests:
-
-```json
-{
-  "prompt": "What about microservices?",
-  "continuation_id": "conv_abc123"
-}
-```
-
-**Features:**
-- Persistent conversation history
-- Provider and model consistency
-- Message count tracking
-- Automatic expiration
-
-### ⚠️ Known Issues
-
-**Continuation ID Missing (Critical):**
-```json
-// Some responses may not include continuation metadata
-{
-  "content": "Response without continuation...",
-  // Missing: continuation field
-}
-```
-
-**Workaround:** Use single-turn interactions until fixed. Track conversation manually if needed.
-
-**Status:** Implementation gap identified in integration testing. High priority fix planned.
-
-## Error Handling
-
-### Common Error Responses
-
-**Missing API Key:**
-```json
-{
-  "error": "Provider not available. Check API key configuration.",
-  "code": "PROVIDER_UNAVAILABLE",
-  "provider": "openai"
-}
-```
-
-**Invalid Model:**
-```json
-{
-  "error": "Model not found: invalid-model",
-  "code": "MODEL_NOT_FOUND",
-  "provider": "openai"
-}
-```
-
-**Rate Limiting:**
-```json
-{
-  "error": "OpenAI rate limit exceeded", 
-  "code": "RATE_LIMIT_EXCEEDED",
-  "provider": "openai",
-  "retry_after": 60
-}
-```
-
-**Context Too Large:**
-```json
-{
-  "error": "Context length exceeded for model",
-  "code": "CONTEXT_LENGTH_EXCEEDED", 
-  "max_tokens": 128000,
-  "provided_tokens": 150000
-}
-```
-
-## Rate Limits & Quotas
-
-### Provider Limits
-
-**OpenAI:**
-- Rate limits vary by model and tier
-- Automatic retry with exponential backoff
-- Error codes: `rate_limit_error`, `insufficient_quota`
-
-**Google:**
-- Free tier: 50 requests/day
-- Paid: Based on quota settings
-- Automatic retry for temporary failures
-
-**X.AI:**
-- Based on account tier
-- Higher limits for paid accounts
-- Standard HTTP 429 handling
-
-### Server Limits
-
-**Default Limits:**
-- Max output tokens: 25,000 (configurable to 200,000)
-- Request timeout: 5 minutes
-- Concurrent requests: Unlimited
-
-**Configuration:**
-```bash
-MAX_MCP_OUTPUT_TOKENS=200000
-REQUEST_TIMEOUT_MS=300000
-```
-
-## Authentication
-
-### API Key Management
-
-**Environment Variables:**
-```bash
-OPENAI_API_KEY=sk-proj-...
-GOOGLE_API_KEY=AIzaSy...
-XAI_API_KEY=xai-...
-```
-
-**MCP Client Configuration:**
-```json
-{
-  "env": {
-    "OPENAI_API_KEY": "sk-proj-...",
-    "GOOGLE_API_KEY": "AIzaSy...", 
-    "XAI_API_KEY": "xai-..."
-  }
-}
-```
-
-### Security
-
-**Features:**
-- API keys never logged or exposed
-- Path traversal protection for files
-- File access limited to allowed directories
-- Input validation on all parameters
-
-## Performance
-
-### Response Times
-
-**Typical Performance:**
-- Simple chat: 500-2000ms
-- Complex reasoning: 2-10 seconds  
-- Consensus (3 models): 3-15 seconds
-- File processing: <100ms per file
-
-**Optimization:**
-- Parallel consensus execution
-- Efficient context processing
-- Connection pooling
-- Response caching for repeated requests
-
-### Monitoring
-
-**Metrics Available:**
-- Response times per provider
-- Token usage statistics
-- Error rates and types
-- Request concurrency
-
-**Logging:**
-```bash
-LOG_LEVEL=debug  # Detailed operation logs
-LOG_LEVEL=info   # Standard operation logs
-LOG_LEVEL=error  # Errors only
-```
-
-## Examples
-
-### Basic Chat
-
-```json
-{
-  "tool": "chat",
-  "arguments": {
-    "prompt": "Explain the benefits of TypeScript over JavaScript",
-    "model": "gemini-2.5-flash",
-    "temperature": 0.3
-  }
-}
-```
-
-### Chat with Context
-
-```json
-{
-  "tool": "chat", 
-  "arguments": {
-    "prompt": "Review this code for potential security vulnerabilities",
-    "model": "o3",
-    "files": ["/project/src/auth.js", "/project/src/middleware.js"],
-    "reasoning_effort": "high",
-    "temperature": 0.1
-  }
-}
-```
-
-### Simple Consensus
-
-```json
-{
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "What's the best approach for implementing real-time notifications?",
-    "models": [
-      {"model": "o3"},
-      {"model": "flash"}, 
-      {"model": "grok"}
-    ],
-    "enable_cross_feedback": false,
-    "temperature": 0.2
-  }
-}
-```
-
-### Advanced Consensus
-
-```json
-{
-  "tool": "consensus",
-  "arguments": {
-    "prompt": "Design a scalable architecture for a video streaming platform",
-    "models": [
-      {"model": "o3"},
-      {"model": "gemini-2.5-pro"},
-      {"model": "grok-4"}
-    ],
-    "files": [
-      "/docs/requirements.md",
-      "/docs/current_architecture.md",
-      "/docs/performance_goals.md"
-    ],
-    "images": ["/diagrams/current_system.png"],
-    "enable_cross_feedback": true,
-    "cross_feedback_prompt": "Focus on scalability and cost optimization in your refinement",
-    "temperature": 0.15,
-    "reasoning_effort": "max"
-  }
-}
-```
-
-## Troubleshooting
-
-### Debug Mode
-
-Enable detailed logging:
-
-```bash
-LOG_LEVEL=debug npx converse-mcp-server
-```
-
-### Test API Keys
-
-```bash
-# Test OpenAI
-curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models
-
-# Test Google (replace YOUR_KEY)
-curl "https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_KEY"
-
-# Test X.AI  
-curl -H "Authorization: Bearer $XAI_API_KEY" https://api.x.ai/v1/models
-```
-
-### Common Issues
-
-**"No providers available":**
-- Check API key environment variables
-- Verify API key format and validity
-- Ensure at least one provider is configured
-
-**"Context length exceeded":**
-- Reduce file content or prompt length
-- Use shorter conversation history
-- Switch to model with larger context window
-
-**Slow responses:**
-- Check network connectivity
-- Verify API service status
-- Consider using faster models (flash, mini variants)
-
-### 🔍 Integration Test Results & Known Issues
-
-**Provider-Specific Issues:**
-
-**Google Provider:**
-```json
-{
-  "error": "genAI.getGenerativeModel is not a function",
-  "status": "connected_with_issues",
-  "workaround": "Provider handles gracefully, requests still processed"
-}
-```
-
-**XAI Provider:**
-```json
-{
-  "error": "grok-beta does not exist or your team does not have access",
-  "status": "api_key_limitations", 
-  "workaround": "Try different model names or contact XAI support"
-}
-```
-
-**Input Validation:**
-```json
-{
-  "issue": "Missing required parameters may not be rejected",
-  "impact": "Some invalid requests may be processed",
-  "workaround": "Always provide required parameters like 'prompt'"
-}
-```
-
-**Performance Benchmarks (From Integration Testing):**
-- **Chat Tool**: 581ms average (OpenAI), excellent performance
-- **Consensus Tool**: 496ms parallel execution (3 providers), excellent
-- **File Processing**: 1779ms for analysis, good performance
-- **Auto Selection**: 1900ms, acceptable for complex selection
-- **Success Rate**: 75% (6/8 tests passing), core functionality working
-
-**Validated Functionality:**
-- ✅ Real API connectivity to all three providers
-- ✅ Chat tool with actual AI responses
-- ✅ Consensus tool with parallel execution  
-- ✅ File context processing and analysis
-- ✅ HTTP transport for MCP protocol
-- ✅ Automatic provider selection
-- ✅ Graceful error handling for provider issues
-
-## 🔧 Extension Guide
-
-### Adding New Providers
-
-Create a new provider by implementing the standard interface:
-
-```javascript
-// src/providers/newprovider.js
-export async function invoke(messages, options = {}) {
-  // Validate API key availability
-  if (!process.env.NEWPROVIDER_API_KEY) {
-    throw new Error('NEWPROVIDER_API_KEY not configured');
-  }
-
-  try {
-    // Implement API call logic
-    const response = await apiCall(messages, options);
-    
-    return {
-      content: response.text,
-      stop_reason: response.stop_reason || 'stop',
-      rawResponse: response
-    };
-  } catch (error) {
-    throw new Error(`New Provider error: ${error.message}`);
-  }
-}
-
-export function isAvailable() {
-  return Boolean(process.env.NEWPROVIDER_API_KEY);
-}
-
-export const supportedModels = ['model-1', 'model-2'];
-export const name = 'newprovider';
-```
-
-**Registration:**
-Add to `src/providers/index.js`:
-```javascript
-import * as newprovider from './newprovider.js';
-
-export const providers = {
-  // ... existing providers
-  newprovider: newprovider
-};
-```
-
-### Adding New Tools
-
-Create a new tool following the MCP tool pattern:
-
-```javascript
-// src/tools/newtool.js
-import { createToolResponse, createToolError } from './index.js';
-
-export async function newTool(args, dependencies) {
-  const { config, providers, continuationStore } = dependencies;
-  
-  try {
-    // Validate required arguments
-    if (!args.requiredParam) {
-      return createToolError('requiredParam is required');
-    }
-    
-    // Implement tool logic
-    const result = await processToolLogic(args, dependencies);
-    
-    return createToolResponse(result);
-  } catch (error) {
-    return createToolError(`Tool execution failed: ${error.message}`);
-  }
-}
-
-// Tool definition for MCP registration
-export const newToolDefinition = {
-  name: 'newtool',
-  description: 'Description of what the new tool does',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      requiredParam: {
-        type: 'string',
-        description: 'Description of required parameter'
-      },
-      optionalParam: {
-        type: 'boolean',
-        default: false,
-        description: 'Description of optional parameter'
-      }
-    },
-    required: ['requiredParam']
-  }
-};
-```
-
-**Registration:**
-Add to `src/tools/index.js`:
-```javascript
-import { newTool, newToolDefinition } from './newtool.js';
-
-export const tools = {
-  // ... existing tools
-  newtool: newTool
-};
-
-export const toolDefinitions = {
-  // ... existing definitions
-  newtool: newToolDefinition
-};
-```
-
-### Configuration Extensions
-
-Add new configuration options:
-
-```javascript
-// src/config.js
-export const config = {
-  // ... existing config
-  
-  newFeature: {
-    enabled: process.env.NEW_FEATURE_ENABLED === 'true',
-    timeout: parseInt(process.env.NEW_FEATURE_TIMEOUT) || 30000,
-    customOption: process.env.NEW_FEATURE_OPTION || 'default'
-  }
-};
-```
-
-### Testing Extensions
-
-Create tests for new components:
-
-```javascript
-// tests/providers/newprovider.test.js
-import { describe, it, expect } from 'vitest';
-import * as newProvider from '../../src/providers/newprovider.js';
-
-describe('New Provider', () => {
-  it('should implement required interface', () => {
-    expect(newProvider.invoke).toBeDefined();
-    expect(newProvider.isAvailable).toBeDefined();
-    expect(newProvider.name).toBe('newprovider');
-  });
-  
-  it('should handle API calls correctly', async () => {
-    // Test implementation
-  });
-});
-```
-
-### Check Status Tool
-
-**Description**: Monitor progress and retrieve results from asynchronous operations.
-
-#### Request Schema
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "continuation_id": {
-      "type": "string",
-      "description": "Optional job continuation ID to query. If not provided, returns the 10 most recent jobs."
-    },
-    "full_history": {
-      "type": "boolean",
-      "default": false,
-      "description": "When used with continuation_id, returns the full conversation history for that continuation ID."
-    }
-  },
-  "additionalProperties": false
-}
-```
-
-#### Response Format
-
-**Status Check Response:**
-```json
-{
-  "content": {
-    "id": "conv_abc123def",
-    "status": "completed",
-    "tool": "chat",
-    "progress": {
-      "completed": 1,
-      "total": 1,
-      "percentage": 100
-    },
-    "result": {
-      "content": "Final AI response...",
-      "metadata": {
-        "provider": "openai",
-        "model": "gpt-5",
-        "usage": {
-          "input_tokens": 150,
-          "output_tokens": 85
-        }
-      }
-    },
-    "elapsed_seconds": 4.2,
-    "completed_at": "2023-12-01T10:30:04.200Z"
-  }
-}
-```
-
-**Recent Jobs List Response:**
-```json
-{
-  "content": {
-    "jobs": [
-      {
-        "id": "conv_abc123def",
-        "status": "completed",
-        "tool": "chat",
-        "elapsed_seconds": 4.2,
-        "completed_at": "2023-12-01T10:30:04.200Z"
-      },
-      {
-        "id": "consensus_xyz789",
-        "status": "processing",
-        "tool": "consensus",
-        "progress": {
-          "completed": 2,
-          "total": 3,
-          "percentage": 67
-        },
-        "elapsed_seconds": 8.5
-      }
-    ]
-  }
-}
-```
-
-#### Example Usage
-
-```json
-// Check specific job
-{
-  "continuation_id": "conv_abc123def"
-}
-
-// List recent jobs
-{}
-
-// Get full history for completed job
-{
-  "continuation_id": "conv_abc123def",
-  "full_history": true
-}
-```
-
-### Cancel Job Tool
-
-**Description**: Cancel running asynchronous operations when needed.
-
-#### Request Schema
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "continuation_id": {
-      "type": "string",
-      "description": "The continuation_id of the job to cancel"
-    }
-  },
-  "required": ["continuation_id"],
-  "additionalProperties": false
-}
-```
-
-#### Response Format
-
-**Successful Cancellation:**
-```json
-{
-  "content": {
-    "status": "cancelled",
-    "message": "Job conv_abc123def cancelled successfully",
-    "job_id": "conv_abc123def",
-    "elapsed_seconds": 2.1,
-    "cancelled_at": "2023-12-01T10:30:02.100Z"
-  }
-}
-```
-
-**Already Completed:**
-```json
-{
-  "content": {
-    "status": "completed",
-    "message": "Job conv_abc123def has already completed and cannot be cancelled",
-    "job_id": "conv_abc123def"
-  }
-}
-```
-
-#### Example Usage
-
-```json
-{
-  "continuation_id": "conv_abc123def"
-}
-```
-
-## Asynchronous Execution
-
-### Overview
-
-The Chat, Consensus, and Conversation tools support asynchronous execution mode for long-running operations. When `async: true` is specified:
-
-1. **Immediate Response**: Returns a `continuation_id` instantly
-2. **Background Processing**: Job runs in the background with streaming support
-3. **Status Monitoring**: Use `check_status` tool to monitor progress
-4. **Result Retrieval**: Full results available when job completes
-5. **Cancellation**: Use `cancel_job` tool to stop running operations
-
-### Async Workflow
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant Server
-    participant Provider
-    
-    Client->>Server: chat(prompt, async=true)
-    Server-->>Client: continuation_id (immediate)
-    
-    Server->>Provider: Background execution
-    Provider-->>Server: Streaming response
-    
-    loop Status Checking
-        Client->>Server: check_status(continuation_id)
-        Server-->>Client: Progress update
-    end
-    
-    Provider->>Server: Final response
-    Server->>Server: Cache result
-    
-    Client->>Server: check_status(continuation_id)
-    Server-->>Client: Complete result
-```
-
-### Status Types
-
-| Status | Description | Actions Available |
-|--------|-------------|------------------|
-| `processing` | Job is running | Cancel, Check Status |
-| `completed` | Job finished successfully | Get Results |
-| `failed` | Job encountered an error | Check Error Details |
-| `cancelled` | Job was cancelled by user | None |
-| `completed_with_errors` | Partial success (consensus only) | Get Partial Results |
-
-### Caching System
-
-**Memory Cache (24 hours):**
-- Active jobs and recent completions
-- Fast lookup for status checks
-- Automatic cleanup
-
-**Disk Cache (3 days):**
-- Long-term result storage
-- Survives server restarts
-- Automatic cleanup of old results
-
-### Performance Considerations
-
-**Async Benefits:**
-- Non-blocking client operations
-- Better resource utilization
-- Parallel processing for consensus
-- Graceful handling of long operations
-
-**When to Use Async:**
-- Long analysis tasks (>30 seconds)
-- Large file processing
-- Multi-model consensus
-- Complex reasoning operations
-- Batch operations
-
-### Best Practices
-
-**Provider Development:**
-- Always check API key availability in `isAvailable()`
-- Implement consistent error handling
-- Follow the standard response format
-- Add comprehensive logging
-- Handle rate limiting gracefully
-
-**Tool Development:**
-- Validate all input parameters
-- Use dependency injection pattern
-- Return standardized responses
-- Implement proper error handling
-- Add detailed input schema
-
-**Testing:**
-- Write unit tests for core logic
-- Add integration tests with mocked APIs
-- Test error conditions thoroughly
-- Validate input/output formats
-
-**Documentation:**
-- Update API documentation with new tools/providers
-- Add usage examples
-- Document configuration options
-- Include troubleshooting guides
-
----
-
-For more examples and integration patterns, see [EXAMPLES.md](EXAMPLES.md).
+# Converse MCP Server - API Reference
+
+## Overview
+
+The Converse MCP Server exposes three tools through the Model Context Protocol (MCP):
+
+1. **Chat Tool** (`chat`) — a single conversational tool with three execution modes:
+   - **`chat`** (default): 1..N models answer independently, in parallel.
+   - **`consensus`**: ≥2 models answer in parallel, then refine their answers after seeing each other.
+   - **`roundtable`**: models answer sequentially, each building on the running transcript.
+2. **Check Status Tool** (`check_status`) — monitor and retrieve results from asynchronous jobs.
+3. **Cancel Job Tool** (`cancel_job`) — cancel a running background job.
+
+The chat tool runs **synchronously** (immediate response) or **asynchronously** (`async: true`, background processing polled with `check_status`). When AI summarization is enabled, the server generates titles and summaries for better context tracking.
+
+## Transport Protocols
+
+The server supports two transport modes:
+
+### HTTP Transport (Default)
+- **Endpoint**: `http://localhost:3157/mcp`
+- **Protocol**: HTTP streaming with JSON-RPC 2.0
+- **Usage**: Best for development, debugging, and web integrations
+- **Features**: Health endpoints, CORS support, session management
+
+### Stdio Transport (Legacy)
+- **Protocol**: Standard input/output with JSON-RPC 2.0
+- **Usage**: Traditional MCP client integrations
+- **Features**: Process-based communication, lower latency
+
+**Transport Selection:**
+```bash
+# Default (HTTP)
+npm start
+
+# Explicit HTTP
+npm start -- --transport=http
+
+# Stdio transport
+npm start -- --transport=stdio
+
+# Environment variable
+MCP_TRANSPORT=stdio npm start
+```
+
+## Chat Tool
+
+**Description**: Talk to one or more AI models. The `mode` parameter selects how the models are orchestrated. Supports files, images, reasoning control, background execution, disk export, and multi-turn threads via `continuation_id`.
+
+### Request Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "prompt": {
+      "type": "string",
+      "description": "Your question, topic, or task with relevant context. Example: 'How should I structure the authentication module for this Express.js API?'"
+    },
+    "models": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Models to use, as plain name strings. Examples: ['auto'], ['codex'], ['codex', 'gemini', 'claude']. Default: ['auto']."
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["chat", "consensus", "roundtable"],
+      "description": "Execution mode. 'chat' (default): independent parallel answers. 'consensus': >=2 models answer then refine via cross-feedback. 'roundtable': sequential turn-based dialogue in the given model order. Default: 'chat'."
+    },
+    "continuation_id": {
+      "type": "string",
+      "description": "Continuation ID for a persistent multi-turn thread. Auto-generated in the first response; pass it back to continue. You MAY change the mode or models on a resuming turn."
+    },
+    "files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "File paths to include as context (absolute or relative). Supports line ranges: file.txt{10:50}, file.txt{100:}. Example: ['./src/utils/auth.js{50:100}', './config.json']."
+    },
+    "images": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Image paths for visual context (absolute or relative paths, or base64 data). Example: ['C:\\Users\\username\\diagram.png', './screenshot.jpg', 'data:image/jpeg;base64,/9j/4AAQ...']."
+    },
+    "reasoning_effort": {
+      "type": "string",
+      "enum": ["none", "minimal", "low", "medium", "high", "max"],
+      "description": "Reasoning depth for thinking models. 'none' (fastest, GPT-5.1+ only), 'minimal', 'low', 'medium' (balanced), 'high', 'max'. Default: 'medium'."
+    },
+    "async": {
+      "type": "boolean",
+      "description": "Execute in the background. When true, returns a continuation_id immediately and processes the request asynchronously; poll with check_status. Default: false."
+    },
+    "export": {
+      "type": "boolean",
+      "description": "Export the conversation to disk. Creates a folder named for the continuation_id with numbered request/response files and metadata. Default: false."
+    }
+  },
+  "required": ["prompt"]
+}
+```
+
+Only `prompt` is required. `models` defaults to `["auto"]`, `mode` to `"chat"`, and `reasoning_effort` to `"medium"`.
+
+### Validation Rules
+
+- `models` must be a non-empty array of non-empty strings.
+- Duplicate model entries are rejected in `chat` and `consensus` modes; they are allowed only in `roundtable` (a model may talk to itself across turns).
+- `consensus` mode requires at least **2 available** models after resolution. A single explicit model is rejected — use `chat` mode instead. `["auto"]` is valid in consensus when 2+ providers are configured (it expands to the first 3 available providers).
+
+### Modes
+
+**`chat` (default) — independent parallel answers**
+
+Each model is invoked in parallel and answers independently; models never see each other. With a single model (or `["auto"]`), the response is that model's answer, with automatic provider failover for `"auto"` and Codex thread reuse across turns. With multiple models, the response contains one labeled `### <model>:` section per successful model.
+
+**`consensus` — parallel answers, then cross-feedback refinement**
+
+All models answer the prompt in parallel (phase 1). A cross-feedback refinement phase then always runs when at least 2 phase-1 responses succeed: each model sees the others' answers and refines its own. The result reports both the initial and refined responses. A single `["auto"]` spec expands to the first 3 available providers' default models.
+
+**`roundtable` — sequential turn-based dialogue**
+
+Models respond one after another in the exact order given, and each model sees the full running transcript of every turn before it. One tool call runs exactly **one lap** (one turn per model). Pass the returned `continuation_id` to run more laps; every lap appends to one shared, accumulating transcript. A turn that fails is recorded with a note and does not abort the lap.
+
+### Response Format
+
+**Synchronous — `chat` mode:** the content is a status line, a `continuation_id:` line, then the answer (the status line is omitted in the test environment).
+
+```
+✅ COMPLETED | CHAT | conv_abc123 | 2.4s elapsed | openai/gpt-5.6-sol
+continuation_id: conv_abc123
+
+<model answer text>
+```
+
+```json
+{
+  "content": "…status line + continuation_id + answer…",
+  "continuation": {
+    "id": "conv_abc123",
+    "messageCount": 2,
+    "provider": "openai",
+    "model": "gpt-5.6-sol"
+  }
+}
+```
+
+For a multi-model `chat` request, the status line reports `N/M succeeded` and lists the models, and `continuation.models` replaces `provider`/`model`.
+
+**Synchronous — `consensus` mode:** a status line and `continuation_id:` line, followed by a JSON result object.
+
+```
+✅ COMPLETED | CONSENSUS | conv_xyz789 | 6.1s elapsed | 3/3 succeeded | gpt-5.6, gemini-2.5-pro, grok-4.5
+continuation_id: conv_xyz789
+
+{
+  "status": "consensus_complete",
+  "models_consulted": 3,
+  "successful_initial_responses": 3,
+  "failed_responses": 0,
+  "refined_responses": 3,
+  "phases": {
+    "initial": [
+      {
+        "model": "gpt-5.6",
+        "status": "success",
+        "response": "Initial analysis…"
+      }
+    ],
+    "refined": [
+      {
+        "model": "gpt-5.6",
+        "status": "success",
+        "initial_response": "Initial analysis…",
+        "refined_response": "After considering the other perspectives…"
+      }
+    ],
+    "failed": []
+  },
+  "continuation": {
+    "id": "conv_xyz789",
+    "messageCount": 3
+  },
+  "settings": {
+    "models_requested": ["gpt-5.6", "gemini-2.5-pro", "grok-4.5"]
+  }
+}
+```
+
+**Synchronous — `roundtable` mode:** a status line, `continuation_id:` line, and a JSON result object whose top-level `content` holds the rendered transcript.
+
+```
+✅ COMPLETED | ROUNDTABLE | conv_abc123 | 3.2s elapsed | 2/2 turns | codex, gemini
+continuation_id: conv_abc123
+
+{
+  "status": "roundtable_complete",
+  "content": "…full rendered transcript of the lap…",
+  "models_consulted": 2,
+  "successful_turns": 2,
+  "failed_turns": 0,
+  "turns": [
+    { "model": "codex", "provider": "codex", "status": "success", "response": "Opening analysis…" },
+    { "model": "gemini", "provider": "gemini-cli", "status": "success", "response": "Building on codex's point…" }
+  ],
+  "continuation": {
+    "id": "conv_abc123",
+    "messageCount": 3
+  },
+  "settings": {
+    "models_requested": ["codex", "gemini"]
+  }
+}
+```
+
+**Asynchronous (any mode, `async: true`):**
+```json
+{
+  "content": "⏳ SUBMITTED | CONSENSUS | conv_xyz789 | 1/1 | Started: 01/12/2026 10:30:00 | \"Architecture Review\" | gpt-5.6, gemini-2.5-pro, grok-4.5\ncontinuation_id: conv_xyz789",
+  "continuation": {
+    "id": "conv_xyz789",
+    "status": "processing"
+  },
+  "async_execution": true
+}
+```
+
+Poll with `check_status` using the returned `continuation_id`. When complete, the async result carries the full content (answer or rendered transcript) plus the AI-generated title and final summary.
+
+### Example Usage
+
+**Single-model chat:**
+```json
+{
+  "prompt": "Review this authentication function for security issues",
+  "models": ["gpt-5.6"],
+  "files": ["/project/src/auth.js{1:120}", "/project/config/security.json"],
+  "reasoning_effort": "high"
+}
+```
+
+**Multi-model chat (independent answers):**
+```json
+{
+  "prompt": "Suggest a caching strategy for this endpoint",
+  "models": ["gpt-5.6", "gemini-2.5-flash", "grok-4.5"],
+  "files": ["/project/src/api/routes.js"]
+}
+```
+
+**Consensus:**
+```json
+{
+  "prompt": "Should we use microservices or a monolith for our e-commerce platform?",
+  "models": ["gpt-5.6", "gemini-2.5-pro", "grok-4.5"],
+  "mode": "consensus",
+  "files": ["/docs/requirements.md", "/docs/current_architecture.md"],
+  "reasoning_effort": "high"
+}
+```
+
+**Roundtable (one lap):**
+```json
+{
+  "prompt": "Should we adopt event sourcing for the order service?",
+  "models": ["codex", "gemini", "claude"],
+  "mode": "roundtable"
+}
+```
+
+**Roundtable (another lap on the same thread):**
+```json
+{
+  "prompt": "Now focus specifically on the migration path.",
+  "models": ["codex", "gemini", "claude"],
+  "mode": "roundtable",
+  "continuation_id": "conv_abc123"
+}
+```
+
+**Async chat with conversation export:**
+```json
+{
+  "prompt": "Design a scalable architecture for our system",
+  "models": ["gpt-5.6"],
+  "async": true,
+  "export": true,
+  "continuation_id": "conv_architecture_design"
+}
+```
+
+When `export` is enabled, the conversation is saved to disk under a folder named for the `continuation_id`:
+```
+conv_architecture_design/
+├── 1_request.txt      # First user prompt
+├── 1_response.txt     # First model response
+├── 2_request.txt      # Second user prompt (if continuing)
+├── 2_response.txt     # Second model response
+└── metadata.json      # Conversation metadata and settings
+```
+
+## Check Status Tool
+
+**Description**: Query the status and progress of async jobs, or list the most recent jobs.
+
+### Request Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "continuation_id": {
+      "type": "string",
+      "description": "Optional job continuation ID to query. If not provided, returns the 10 most recent jobs."
+    },
+    "full_history": {
+      "type": "boolean",
+      "default": false,
+      "description": "When used with continuation_id, returns the full conversation history for that continuation ID. Only use when there are multiple turns and you need the whole conversation."
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+### Example Usage
+
+```json
+// Check a specific job
+{ "continuation_id": "conv_abc123" }
+
+// List the 10 most recent jobs
+{}
+
+// Get the full conversation history for a thread
+{ "continuation_id": "conv_abc123", "full_history": true }
+```
+
+The response renders a human-readable status (start time, elapsed time, turn/model progress, and, when summarization is enabled, an AI-generated title and summary) plus the completed result content when available.
+
+## Cancel Job Tool
+
+**Description**: Cancel a queued or running async job. Preserves partial results when available.
+
+### Request Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "continuation_id": {
+      "type": "string",
+      "description": "The continuation_id of the job to cancel"
+    }
+  },
+  "required": ["continuation_id"],
+  "additionalProperties": false
+}
+```
+
+### Example Usage
+
+```json
+{ "continuation_id": "conv_abc123" }
+```
+
+Only jobs in a `queued` or `running` state can be cancelled; already-completed, failed, or cancelled jobs return a non-cancellable status.
+
+## 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.
+
+### OpenAI Models
+
+| Model | Aliases | Context | Output | Notes |
+|-------|---------|---------|--------|-------|
+| `gpt-5.6-sol` | `gpt-5.6`, `gpt-5`, `sol` | 1M | 128K | Flagship, default OpenAI model |
+| `gpt-5.6-terra` | `terra` | 400K | 128K | Lower-cost flagship-class tier |
+| `gpt-5.6-luna` | `luna` | 400K | 128K | Fastest, most affordable tier |
+| `gpt-5.4` | — | 1M | 128K | Flagship-class reasoning |
+| `gpt-5.4-pro` | `gpt-5-pro` | 1M | 272K | Maximum performance (expensive) |
+| `gpt-5-mini`, `gpt-5-nano` | — | 400K | 128K | Fast, cost-efficient tiers |
+| `gpt-5.4-mini`, `gpt-5.4-nano` | — | 400K | 128K | Fast GPT-5.4 tiers |
+| `o3`, `o3-pro`, `o4-mini` | — | 200K | 100K | Reasoning models |
+| `gpt-4.1` | `gpt-4.1` | 1M | 32K | Large context |
+| `o3-deep-research`, `o4-mini-deep-research` | — | 200K | 100K | Deep research (long runtime) |
+
+### Google / Gemini Models (API-based)
+
+| Model | Aliases | Context | Output | Notes |
+|-------|---------|---------|--------|-------|
+| `gemini-3.1-pro-preview` | `pro`, `gemini-pro` | 1M | 64K | Most advanced reasoning, expanded thinking levels |
+| `gemini-3.5-flash` | `gemini-3.5`, `flash-3.5` | 1M | 65K | Frontier agentic/coding at Flash speed |
+| `gemini-2.5-pro` | `pro 2.5` | 1M | 65K | Deep reasoning with thinking budget |
+| `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).
+
+### X.AI / Grok Models
+
+| Model | Aliases | Context | Notes |
+|-------|---------|---------|-------|
+| `grok-4.5` | `grok`, `grok-4.5-latest`, `grok-build-latest` | 500K | Flagship: image input, reasoning content, native web/X search via Agent Tools |
+
+`reasoning_effort` maps to Grok's `low`/`medium`/`high`; Grok 4.5 always reasons and cannot be disabled. Web search is attached automatically and the model decides whether to use it.
+
+### Anthropic Models (API-based)
+
+| Model | Aliases | Context | Output | Notes |
+|-------|---------|---------|--------|-------|
+| `claude-fable-5` | `fable`, `fable-5` | 1M | 128K | Most capable, adaptive thinking + effort, images, caching, compaction |
+| `claude-opus-4-8` | `opus`, `opus-4.8` | 200K (1M beta) | 128K | Complex reasoning and agentic coding |
+| `claude-opus-4-7`, `claude-opus-4-6` | `opus-4.7`, `opus-4.6` | 200K (1M beta) | 128K | Previous Opus generations |
+| `claude-opus-4-5-20251101`, `claude-opus-4-1-20250805` | `opus-4.5`, `opus-4.1` | 200K | 64K / 32K | Earlier Opus tiers |
+| `claude-sonnet-4-6` | `sonnet`, `sonnet-4.6` | 200K (1M beta) | 64K | Best speed/intelligence balance, adaptive thinking |
+| `claude-haiku-4-5-20251001` | `haiku`, `haiku-4.5` | 200K | 64K | Fast and intelligent |
+
+Models with adaptive thinking control depth via `reasoning_effort`, which maps to Anthropic's `effort` parameter. System prompts are automatically cached for 1 hour; cache stats appear in response metadata as `cache_creation_input_tokens` / `cache_read_input_tokens`.
+
+### Mistral Models
+
+| Model | Aliases | Context | Notes |
+|-------|---------|---------|-------|
+| `mistral-medium-3-5` | `mistral`, `mistral-medium` | 256K | Frontier-class multimodal, adjustable reasoning |
+| `mistral-small-2603` | `mistral-small` | 256K | Hybrid multimodal (instruct + reasoning + coding) |
+| `mistral-large-2512` | `mistral-large` | 256K | Open-weight MoE flagship, image-capable, no adjustable reasoning |
+
+`reasoning_effort` maps to `high` (any enabled level) or `none` on Medium 3.5 and Small; Large has no adjustable reasoning.
+
+### DeepSeek Models
+
+| Model | Aliases | Context | Output | Notes |
+|-------|---------|---------|--------|-------|
+| `deepseek-v4-pro` | `deepseek`, `deepseek-pro` | 1M | 384K | Flagship MoE, thinking mode, text-only |
+| `deepseek-v4-flash` | `deepseek-flash` | 1M | 384K | Faster, lower-cost V4 tier, text-only |
+
+`reasoning_effort`: `none` disables thinking; enabled levels use `high`; `max` uses `max`.
+
+### OpenRouter Models
+
+| Model | Aliases | Context | Notes |
+|-------|---------|---------|-------|
+| `z-ai/glm-5.2` | `glm`, `glm-5.2` | 1M | Large-scale reasoning, text-only, default OpenRouter model |
+| `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash` | — | 1M | DeepSeek V4 tiers, text-only |
+| `qwen/qwen3.7-max` | `qwen3.7-max` | 1M | Flagship Qwen, text-only |
+| `qwen/qwen3.7-plus` | `qwen3.7-plus` | 1M | Image-capable Qwen |
+| `moonshotai/kimi-k2.7-code` | `kimi-k2.7-code` | 256K | Coding model, image-capable, reasoning always on |
+| `moonshotai/kimi-k2.6` | `kimi-k2.6` | 256K | Image-capable general model |
+| `openrouter/auto` | `auto-router`, `openrouter-auto` | — | Auto-selects the best model for the prompt |
+
+Any other model works via its full `provider/model` slug (e.g. `anthropic/claude-sonnet-5`) or the `openrouter:` namespace. Append `:online` to a slug (e.g. `z-ai/glm-5.2:online`) to opt into web search, which adds a real per-request cost.
+
+### Codex (agentic, local)
+
+**Codex** is an agentic coding assistant with direct filesystem access:
+
+- **Model**: `codex` (underlying model: GPT-5.6)
+- **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)
+- **Authentication**: ChatGPT login OR `CODEX_API_KEY` (NOT `OPENAI_API_KEY`)
+- `reasoning_effort` and web search are not applicable — Codex manages its own execution
+
+### Claude Agent SDK (subscription)
+
+**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 Fable 5
+- **Model selection**: `claude:fable` (Claude Fable 5) or `claude:opus` (Claude Opus 4.8); unknown `claude:`-prefixed names pass through to the SDK (e.g. `claude:claude-sonnet-4-6`)
+- **Authentication**: `claude login` — no `ANTHROPIC_API_KEY` needed
+- **Direct file access**: reads files from the working directory
+- `reasoning_effort` and sampling parameters are managed by the SDK
+
+### Gemini via Antigravity CLI (subscription)
+
+The **Antigravity CLI** (`agy`) provides subscription-based access to Gemini models through Google OAuth:
+
+- **Models** (text-only): `gemini` (= `gemini:pro`, Gemini 3.1 Pro), `gemini:flash` (Gemini 3.5 Flash)
+- **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
+- **Reasoning effort**: `low`/`medium`/`high`/`max` select the model variant
+- **Context**: 1M tokens
+- One-shot responses (no token-level streaming); ~7s minimum per call
+
+**Authentication Setup:**
+```bash
+# Install the Antigravity CLI (agy)
+# Windows (PowerShell):
+irm https://antigravity.google/cli/install.ps1 | iex
+# macOS/Linux:
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+
+# Run interactive login (one-time) — also establishes workspace trust
+agy
+```
+
+### GitHub Copilot SDK (subscription)
+
+Reach these with the `copilot:` namespace (e.g. `copilot:gpt-5.6-terra`); uses your GitHub Copilot subscription (`gh auth login`) — no API key needed:
+
+- **OpenAI**: `gpt-5.6-sol` (aliases: `gpt-5.6`, `gpt-5`), `gpt-5.6-terra`, `gpt-5.6-luna` (all accept `reasoning_effort`)
+- **Anthropic**: `claude-fable-5` (alias: `fable`), `claude-sonnet-5` (alias: `sonnet`), `claude-opus-4.8` (aliases: `opus`, `claude`)
+- **Google**: `gemini-3.1-pro-preview` (aliases: `gemini`, `gemini-3.1-pro`), `gemini-3.5-flash` (alias: `gemini-flash`)
+- Any other `copilot:<id>` is forwarded to the Copilot backend verbatim
+
+### Model Selection
+
+Use `"auto"` for automatic selection, or specify exact models:
+
+```text
+"auto"                     // First available provider (chat); first 3 (consensus)
+"gpt-5.6"                  // OpenAI flagship
+"gemini-2.5-flash"         // Google API
+"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-4-8)
+"claude"                   // Claude Agent SDK (-> Claude Fable 5)
+"claude:opus"              // Claude Agent SDK (Claude Opus 4.8)
+"gemini"                   // Antigravity CLI (Gemini 3.1 Pro)
+"copilot:gpt-5.6-terra"    // GitHub Copilot SDK
+```
+
+**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.
+
+Provider auto-selection priority (subscription-based CLI/SDK providers first, then API-key providers): `codex`, `gemini-cli`, `claude`, `copilot`, `openai`, `google`, `xai`, `anthropic`, `mistral`, `deepseek`, `openrouter`.
+
+## Configuration
+
+### AI Summarization
+
+```bash
+ENABLE_RESPONSE_SUMMARIZATION=true    # Enable AI-generated titles and summaries (default: false)
+SUMMARIZATION_MODEL=gpt-5-nano        # Model used for summarization (default: gpt-5-nano)
+```
+
+When enabled: title generation (up to 60 chars) per request, streaming progress summaries during async jobs, 1-2 sentence final summaries, and enhanced `check_status` display. Summarization is non-blocking — failures fall back to text snippets and never affect the main flow.
+
+### Codex Configuration
+
+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-5.6-sol`)
+- **`CODEX_API_KEY`** — optional API key for headless deployments (alternative to ChatGPT login)
+
+**Example (.env):**
+```bash
+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-5.6-sol
+```
+
+## Context Processing
+
+### File Support
+
+**Supported text formats:** `.txt`, `.md`, `.js`, `.ts`, `.json`, `.yaml`, `.yml`, `.py`, `.java`, `.c`, `.cpp`, `.h`, `.css`, `.html`, `.xml`, `.csv`, `.sql`, `.sh`, `.bat`, `.log`
+
+**Supported image formats:** `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp`
+
+**Size limits:** text files 1MB default; image files 10MB default
+
+### File Processing
+
+Provide paths in the `files` array. Line ranges are supported: `file.txt{10:50}` for lines 10-50, `file.txt{100:}` from line 100 onward.
+
+```json
+{
+  "files": [
+    "/absolute/path/to/file.js",
+    "./relative/path/to/file.md{1:80}"
+  ]
+}
+```
+
+The processed context includes file content with line numbers and metadata (size, last modified) and reports inaccessible files as errors.
+
+### Image Processing
+
+```json
+{
+  "images": [
+    "/path/to/diagram.png",
+    "data:image/jpeg;base64,/9j/4AAQ..."
+  ]
+}
+```
+
+Images are base64-encoded and sent to models that support vision. When a request includes images, `"auto"` selection skips text-only providers.
+
+## Continuation System
+
+The first request creates a continuation automatically and returns its ID; pass it back on subsequent requests to continue the thread. The continuation persists across modes — you may switch `mode` and `models` on a resuming turn, and the shared transcript is the context. Custom continuation IDs are accepted (letters, numbers, hyphens, underscores; max 128 chars). Conversations expire after 24 hours of inactivity.
+
+```json
+// First request (no continuation_id)
+{ "prompt": "Start a discussion about architecture", "models": ["auto"] }
+
+// Follow-up (reuse the returned id)
+{ "prompt": "What about microservices?", "continuation_id": "conv_abc123" }
+```
+
+## Asynchronous Execution
+
+Set `async: true` on a chat request for long-running work:
+
+1. **Immediate response**: returns a `continuation_id` instantly.
+2. **Background processing**: the job runs with streaming support.
+3. **Status monitoring**: poll with `check_status`.
+4. **Result retrieval**: full results (answer or transcript) available when the job completes.
+5. **Cancellation**: use `cancel_job` to stop a running job.
+
+### Status Types
+
+| Status | Description | Actions Available |
+|--------|-------------|-------------------|
+| `processing` | Job is running | Cancel, Check Status |
+| `completed` | Job finished successfully | Get Results |
+| `failed` | Job encountered an error | Check Error Details |
+| `cancelled` | Job was cancelled | None |
+
+### Caching
+
+- **Memory cache (24 hours)**: active jobs and recent completions for fast status lookups.
+- **Disk cache (3 days)**: long-term result storage that survives server restarts.
+
+### When to Use Async
+
+- Long analysis tasks (>30 seconds)
+- Large file processing
+- Multi-model consensus or multi-lap roundtables
+- Deep-research and other long-running models
+
+## Error Handling
+
+**Missing API key / unavailable provider:**
+```json
+{ "error": "Provider openai is not available. Check API key configuration." }
+```
+
+**Invalid model:**
+```json
+{ "error": "Provider not found for model: invalid-model" }
+```
+
+**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.
+
+## Authentication
+
+**Environment variables:**
+```bash
+OPENAI_API_KEY=sk-proj-...
+GOOGLE_API_KEY=AIzaSy...        # or GEMINI_API_KEY (GEMINI_API_KEY takes priority)
+XAI_API_KEY=xai-...
+ANTHROPIC_API_KEY=sk-ant-...
+MISTRAL_API_KEY=...
+DEEPSEEK_API_KEY=...
+OPENROUTER_API_KEY=sk-or-...
+```
+
+**MCP client configuration:**
+```json
+{
+  "env": {
+    "OPENAI_API_KEY": "sk-proj-...",
+    "GOOGLE_API_KEY": "AIzaSy...",
+    "XAI_API_KEY": "xai-..."
+  }
+}
+```
+
+Subscription providers (Codex, Claude Agent SDK, Antigravity CLI, Copilot SDK) use local CLI authentication instead of API keys — see [PROVIDERS.md](PROVIDERS.md).
+
+### Security
+
+- API keys are never logged or exposed
+- Path traversal protection for file access
+- File access limited to allowed directories
+- Input validation on all parameters
+
+## Server Limits
+
+```bash
+MAX_MCP_OUTPUT_TOKENS=200000   # Max output tokens (default 25,000)
+```
+
+Response bodies are token-limited to fit the configured MCP output ceiling.
+
+---
+
+For usage examples across common scenarios, see [EXAMPLES.md](EXAMPLES.md).