ur-agent 1.25.3 → 1.27.1

package/docs/providers.md

@@ -59,6 +59,199 @@ ur config set base_url <url>
 ur config set provider.fallback ollama
 ```
 
+## Provider-scoped model selection
+
+UR-AGENT shows only models available for the selected provider. This prevents selecting incompatible model/provider combinations.
+
+## Runtime provider routing
+
+When you select a provider and model, all agent requests are routed through that provider's backend:
+
+- **Subscription providers** spawn the official CLI command
+- **API providers** make direct HTTP API calls with your API key
+- **Local providers** connect to the configured local endpoint
+
+The selected provider determines:
+- Which backend receives your requests
+- Which models are available
+- How authentication works
+- What error messages you see
+
+**Important:** Ollama is only used when `ollama` is the selected provider. Selecting another provider routes all requests through that provider's backend.
+
+### `/model` command flow
+
+When you run `/model` in the interactive agent, you get a **two-step provider-first selection**:
+
+**Step 1: Provider Selection**
+
+You see all configured providers with:
+- Provider name (e.g., "ChatGPT/Codex", "OpenAI API", "Ollama")
+- Access type: `subscription`, `api`, `local`, or `server`
+- Connection status: `connected`, `missing`, `unavailable`, or `unknown`
+- Credential type: `cli-login`, `api-key`, `local-runtime`, or `openai-compatible-endpoint`
+- Short status message (e.g., "OPENAI_API_KEY found", "CLI not found", "localhost reachable")
+
+**Step 2: Model Selection**
+
+After selecting a provider:
+- Only models from that provider are shown
+- Each model shows its description
+- Model source is displayed: `live` (dynamic discovery), `cache` (fallback), or `static` (predefined)
+- Press Esc to go back and change provider
+
+**Confirmation**
+
+After selecting a model, the confirmation shows:
+- Selected provider and access type
+- Selected model name
+- Model source (live/cache/static)
+- Effort level (if applicable)
+- Thinking status (if enabled)
+
+**Example:**
+```
+/model
+→ Step 1: Select provider
+  ChatGPT/Codex · subscription · connected
+  OpenAI API · api · OPENAI_API_KEY found
+  Ollama · local · localhost reachable
+  
+→ Select: ChatGPT/Codex
+
+→ Step 2: Select model
+  gpt-4o · Most capable GPT-4 model
+  gpt-4o-mini · Fast and efficient variant
+  o1 · Reasoning model
+  
+→ Select: gpt-4o
+
+→ Confirmation:
+  Provider: ChatGPT/Codex (subscription)
+  Model: gpt-4o
+  Source: static
+```
+
+### CLI workflow
+
+```sh
+# 1. Select a provider
+ur config set provider openai-api
+
+# 2. View available models for that provider (in model picker)
+/model
+
+# 3. Select a model from the filtered list
+ur config set model gpt-4o
+
+# 4. Switch to a different provider - model list updates automatically
+ur config set provider anthropic-api
+# Now /model shows only Claude models, not GPT models
+```
+
+### Model discovery behavior
+
+| Provider type | Model discovery | Source label |
+| --- | --- | --- |
+| Subscription CLI (codex-cli, claude-code-cli, gemini-cli, antigravity-cli) | Static list of provider-specific models | static |
+| API providers (openai-api, anthropic-api, gemini-api, openrouter) | Static list of provider-specific models | static |
+| Local providers (ollama, lmstudio, llama.cpp, vllm) | Dynamic discovery from local server | live |
+| OpenAI-compatible | Dynamic discovery from configured endpoint | live |
+
+### API vs Subscription distinction
+
+**Subscription providers** require official CLI login:
+- `codex-cli` — ChatGPT/Codex subscription via `codex login`
+- `claude-code-cli` — Claude Code subscription via `claude auth login`
+- `gemini-cli` — Gemini Code Assist enterprise login
+- `antigravity-cli` — Antigravity subscription login
+
+**API providers** require environment variable with API key:
+- `openai-api` — requires `OPENAI_API_KEY`
+- `anthropic-api` — requires `ANTHROPIC_API_KEY`
+- `gemini-api` — requires `GEMINI_API_KEY`
+- `openrouter` — requires `OPENROUTER_API_KEY`
+
+**Local providers** require local runtime:
+- `ollama` — localhost Ollama server
+- `lmstudio` — LM Studio OpenAI-compatible server
+- `llama.cpp` — llama.cpp server mode
+- `vllm` — vLLM server
+
+**Important:**
+- A ChatGPT/Claude/Gemini subscription does NOT give API access
+- An API key does NOT give subscription CLI access
+- OpenAI API and Codex CLI are separate providers
+- Claude API and Claude Code are separate providers
+- Gemini API and Gemini CLI are separate providers
+
+### Validation
+
+When you set a model that is incompatible with the current provider, UR-AGENT shows an error:
+
+```
+Invalid model for current provider:
+  Selected provider: openai-api
+  Selected model: claude-sonnet-4-20250514
+  Error: Model "claude-sonnet-4-20250514" is not available for provider "openai-api".
+  Valid models for openai-api: gpt-4o, gpt-4o-mini, o1, o3-mini, gpt-4-turbo
+  Suggested: ur config set model gpt-4o
+```
+
+When you change providers, UR-AGENT warns if the current model is incompatible:
+
+```
+Warning: Current model "gpt-4o" is not available for provider "anthropic-api".
+  Valid models for anthropic-api: claude-sonnet-4-20250514, claude-opus-4-20250514, claude-3-5-sonnet-20241022, claude-3-haiku-20240307
+  After changing provider, run: ur config set model claude-sonnet-4-20250514
+```
+
+### Troubleshooting
+
+**Check active provider and model:**
+```sh
+# Show current configuration
+ur config get provider
+ur config get model
+
+# Or use the status command
+ur provider status
+```
+
+**Provider shows "missing":**
+- Install the official CLI: `brew install codex` or equivalent
+- Run: `ur auth <provider>` to complete login
+
+**Provider shows "unavailable":**
+- Check API key: `echo $OPENAI_API_KEY`
+- Check local server: `curl http://localhost:11434/api/tags`
+- Run: `ur provider doctor <provider>` for detailed diagnostics
+
+**Model not in list:**
+- Verify provider is correct: `/provider`
+- Check model belongs to provider (API models ≠ CLI models)
+- For local providers, ensure server is running and model is pulled
+
+**Requests going to wrong backend:**
+- Verify selected provider: `ur config get provider`
+- Change provider: `ur config set provider <provider-id>`
+- The selected provider determines which backend receives requests
+- Ollama is only used when `ollama` is the selected provider
+
+**Dynamic discovery fails:**
+- Local providers: check server is running at configured URL
+- OpenAI-compatible: verify base_url and API key (if required)
+- Fallback only to same provider's cached models (never other providers)
+
+**Debug active runtime backend:**
+```sh
+# Show detailed provider status
+ur provider doctor
+
+# Check which backend will be used
+# After selecting provider, all requests go through that provider's backend
+```
+
 Provider config and doctor commands accept canonical IDs and common aliases:
 
 | Canonical ID | Accepted examples |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ur-agent",
-  "version": "1.25.3",
+  "version": "1.27.1",
   "description": "UR-AGENT — autonomous engineering workflow engine (plan, execute, test, verify, document, benchmark, reproduce)",
   "type": "module",
   "packageManager": "bun@1.3.14",