ur-agent 1.27.4 → 1.27.6

package/docs/CONFIGURATION.md

@@ -10,7 +10,7 @@ UR-AGENT supports official provider access paths only:
   and Antigravity CLI where officially supported.
 - Explicit API providers: OpenAI, Anthropic, Gemini, OpenRouter, and
   OpenAI-compatible endpoints.
-- Local providers: Ollama, LM Studio, llama.cpp, and vLLM OpenAI-compatible
+- Local/server providers: Ollama, LM Studio, llama.cpp, and vLLM OpenAI-compatible
   server mode.
 
 UR-AGENT never scrapes browser sessions, extracts OAuth refresh tokens, reads
@@ -54,6 +54,23 @@ Provider values accept canonical IDs and common aliases. Examples:
 `agy`, `ollama`, `lmstudio`, `LM Studio`, `llama.cpp`, and `vllm`.
 Values with spaces should be quoted in shell commands.
 
+In the interactive app, `/model` is provider-first: choose a provider, then
+choose a model from that provider only. The picker labels providers as
+subscription login, API key, local runtime, or OpenAI-compatible endpoint and
+shows model source as `live`, `cache`, or `static`. Changing providers clears an
+incompatible saved model instead of silently carrying it across providers. The
+saved provider/model pair controls the runtime backend for the next agent
+request; Ollama is only used when `ollama` is the selected provider.
+
+Use this to inspect the active runtime path:
+
+```sh
+ur provider status
+```
+
+The status output includes active provider, active model, access type,
+credential type, and runtime backend.
+
 API keys are not written to UR settings. Set them in the environment when you
 explicitly choose API mode:
 
@@ -92,7 +109,9 @@ OLLAMA_MODEL=qwen3-coder:480b-cloud
 UR_MODEL=qwen3-coder:480b-cloud
 ```
 
-`OLLAMA_MODEL` selects the model name and takes precedence over `UR_MODEL`. If neither is set, UR lets its Ollama router choose from the model list advertised by the configured Ollama app. If that discovery fails, the built-in fallback is `qwen3-coder:480b-cloud`.
+`OLLAMA_MODEL` selects the model name and takes precedence over `UR_MODEL` only
+for Ollama runtime sessions. If neither is set, UR lets its Ollama router choose
+from the model list advertised by the configured Ollama app.
 
 ### Discovering LAN Ollama servers
 

package/docs/USAGE.md

@@ -51,15 +51,14 @@ ur -p \
 
 ## Models And Providers
 
-The wrapper in `bin/ur.js` honors explicit model choices in this order:
+For Ollama sessions, the wrapper in `bin/ur.js` honors explicit model choices
+in this order:
 
 1. `OLLAMA_MODEL`
 2. `UR_MODEL`
 
-If neither variable is set, UR lets its Ollama router choose from the models
-exposed by your local Ollama app. That list can include local models and
-Ollama Cloud-backed models. If routing cannot discover a model list, the
-built-in fallback is `qwen3-coder:480b-cloud`.
+If neither variable is set and `ollama` is the selected provider, UR lets its
+Ollama router choose from the models exposed by your local Ollama app.
 
 You can also choose the model for a single session:
 
@@ -110,6 +109,13 @@ ur config set base_url <url>
 ur config set provider.fallback ollama
 ```
 
+In the interactive app, `/model` chooses a provider first and then a model from
+that provider only. The saved pair controls the runtime backend for the next
+agent request. There is no cross-provider fallback: OpenAI API does not fall
+back to Codex CLI or Ollama, Claude Code does not fall back to Claude API, and
+local/server providers do not leak cloud model lists. Use `ur provider status`
+to inspect the active provider, model, access type, and runtime backend.
+
 Provider values accept canonical IDs and common aliases. For example,
 `claude`, `Claude Code`, and `claude-code-cli` all select
 `claude-code-cli`; `antigravity`, `agy`, and `antigravity-cli` all select
@@ -122,6 +128,11 @@ Claude Code, Gemini CLI, or Antigravity where supported. UR-AGENT never scrapes
 browser sessions, extracts OAuth tokens, or bypasses provider restrictions.
 OpenAI-compatible local or cloud endpoints use `base_url` plus `model`.
 
+Use `/model` in an interactive session to select provider first and model
+second. OpenAI API and Codex CLI, Claude API and Claude Code, and Gemini API and
+Gemini CLI are separate providers; a subscription login does not grant API-key
+access, and an API key does not grant subscription CLI access.
+
 ## Project Instructions
 
 Add a `UR.md` file to the repository root for team-shared instructions. UR loads it as project context.

package/docs/providers.md

@@ -21,20 +21,20 @@ environment variables only when the user explicitly selects API mode.
 
 ## Provider matrix
 
-| Provider | Access type | Legal path |
-| --- | --- | --- |
-| ChatGPT/Codex | subscription | official Codex CLI login |
-| Claude Code | subscription | official Claude Code login |
-| Gemini CLI | subscription | official Gemini Code Assist login |
-| Antigravity | subscription | official Antigravity login, where supported |
-| OpenAI | API | `OPENAI_API_KEY` |
-| Anthropic Claude | API | `ANTHROPIC_API_KEY` |
-| Gemini | API | `GEMINI_API_KEY` |
-| OpenRouter | API/router | `OPENROUTER_API_KEY` |
-| Ollama | local | localhost Ollama runtime |
-| LM Studio | local | local OpenAI-compatible server |
-| llama.cpp | local | local OpenAI-compatible server |
-| vLLM | local/server | OpenAI-compatible server |
+| Provider | Access type | Runtime backend | Legal path |
+| --- | --- | --- | --- |
+| Codex CLI | subscription | `subscription-cli:codex` | official Codex CLI login |
+| Claude Code | subscription | `subscription-cli:claude-code` | official Claude Code login |
+| Gemini CLI | subscription | `subscription-cli:gemini` | official Gemini Code Assist login |
+| Antigravity | subscription | `subscription-cli:antigravity` | official Antigravity login, where supported |
+| OpenAI API | API | `api:openai` | `OPENAI_API_KEY` |
+| Claude API | API | `api:anthropic` | `ANTHROPIC_API_KEY` |
+| Gemini API | API | `api:gemini` | `GEMINI_API_KEY` |
+| OpenRouter | API/router | `api:openrouter` | `OPENROUTER_API_KEY` |
+| Ollama | local | `ollama` | localhost Ollama runtime |
+| LM Studio | local/server | `openai-compatible:lmstudio` | local OpenAI-compatible server |
+| llama.cpp | local/server | `openai-compatible:llama.cpp` | local OpenAI-compatible server |
+| vLLM | local/server | `openai-compatible:vllm` | OpenAI-compatible server |
 
 ## Commands
 
@@ -61,15 +61,16 @@ 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.
+UR-AGENT shows providers first, then only models available for the selected provider. This prevents incompatible model/provider pairs and keeps subscription CLI, API-key, and local/server runtime model lists separate.
 
 ## Runtime provider routing
 
-When you select a provider and model, all agent requests are routed through that provider's backend:
+When you select a provider and model, every agent request is 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
+- **Local/server providers** connect to the configured local or OpenAI-compatible endpoint
 
 The selected provider determines:
 - Which backend receives your requests
@@ -77,7 +78,10 @@ The selected provider determines:
 - 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.
+**Important:** Ollama is only used when `ollama` is the selected provider.
+Selecting another provider routes requests through that provider's backend. If
+runtime dispatch fails, UR reports the selected provider, selected model, and
+runtime backend instead of switching to Ollama.
 
 ### `/model` command flow
 
@@ -86,7 +90,7 @@ When you run `/model` in the interactive agent, you get a **two-step provider-fi
 **Step 1: Provider Selection**
 
 You see all configured providers with:
-- Provider name (e.g., "ChatGPT/Codex", "OpenAI API", "Ollama")
+- Provider name (e.g., "Codex CLI", "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`
@@ -106,6 +110,7 @@ After selecting a model, the confirmation shows:
 - Selected provider and access type
 - Selected model name
 - Model source (live/cache/static)
+- Runtime backend
 - Effort level (if applicable)
 - Thinking status (if enabled)
 
@@ -113,23 +118,23 @@ After selecting a model, the confirmation shows:
 ```
 /model
 → Step 1: Select provider
-  ChatGPT/Codex · subscription · connected
+  Codex CLI · subscription · subscription login connected
   OpenAI API · api · OPENAI_API_KEY found
   Ollama · local · localhost reachable
   
-→ Select: ChatGPT/Codex
+→ Select: Codex CLI
 
 → Step 2: Select model
-  gpt-4o · Most capable GPT-4 model
-  gpt-4o-mini · Fast and efficient variant
-  o1 · Reasoning model
+  codex/gpt-5.5 · Subscription model through official Codex CLI login · static
+  codex/gpt-5.4-mini · Fast subscription model through official Codex CLI login · static
   
-→ Select: gpt-4o
+→ Select: codex/gpt-5.5
 
 → Confirmation:
-  Provider: ChatGPT/Codex (subscription)
-  Model: gpt-4o
-  Source: static
+  Selected provider: Codex CLI (subscription)
+  Selected model: codex/gpt-5.5
+  Model source: static
+  Runtime backend: subscription-cli:codex
 ```
 
 ### CLI workflow
@@ -142,11 +147,11 @@ ur config set provider openai-api
 /model
 
 # 3. Select a model from the filtered list
-ur config set model gpt-4o
+ur config set model gpt-5.5
 
 # 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
+# Now /model shows only Claude API models, not Codex CLI or OpenAI API models
 ```
 
 ### Model discovery behavior
@@ -155,13 +160,13 @@ ur config set provider anthropic-api
 | --- | --- | --- |
 | 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 |
+| Local/server providers (ollama, lmstudio, llama.cpp, vllm) | Dynamic discovery from the selected provider endpoint | 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`
+- `codex-cli` — Codex CLI 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
@@ -172,7 +177,7 @@ ur config set provider anthropic-api
 - `gemini-api` — requires `GEMINI_API_KEY`
 - `openrouter` — requires `OPENROUTER_API_KEY`
 
-**Local providers** require local runtime:
+**Local/server providers** require local runtime or endpoint:
 - `ollama` — localhost Ollama server
 - `lmstudio` — LM Studio OpenAI-compatible server
 - `llama.cpp` — llama.cpp server mode
@@ -192,29 +197,25 @@ When you set a model that is incompatible with the current provider, UR-AGENT sh
 ```
 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
+  Selected model: claude-sonnet-5
+  Valid models for openai-api: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-4o, gpt-4o-mini, o1, o3-mini
+  Suggested action: Run /model and choose a model from openai-api, or run: ur config set model gpt-5.5
+  Error: Model "claude-sonnet-5" is not available for provider "openai-api".
 ```
 
 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
+Warning: Current model "gpt-5.5" is not available for provider "anthropic-api" and will be cleared.
+  Valid models for anthropic-api: claude-sonnet-5, claude-opus-4-8, claude-opus-4-7
+  After changing provider, run /model or: ur config set model claude-sonnet-5
 ```
 
 ### Troubleshooting
 
 **Check active provider and model:**
 ```sh
-# Show current configuration
-ur config get provider
-ur config get model
-
-# Or use the status command
+# Show selected provider, model, access type, credential, readiness, and backend
 ur provider status
 ```
 
@@ -233,25 +234,25 @@ ur provider status
 - For local providers, ensure server is running and model is pulled
 
 **Requests going to wrong backend:**
-- Verify selected provider: `ur config get provider`
+- Verify selected provider and runtime backend: `ur provider status`
 - Change provider: `ur config set provider <provider-id>`
+- Choose a scoped model: `/model`
 - The selected provider determines which backend receives requests
 - Ollama is only used when `ollama` is the selected provider
+- Runtime dispatch validates the provider/model pair before sending a request
 
 **Dynamic discovery fails:**
-- Local providers: check server is running at configured URL
+- Local/server 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
+ur provider status
 ```
 
+`ur provider doctor` adds detailed diagnostics for the same selected provider.
+
 Provider config and doctor commands accept canonical IDs and common aliases:
 
 | Canonical ID | Accepted examples |
@@ -293,7 +294,7 @@ fallback option.
   where installed. It launches only an installed official CLI command where
   supported; UR-AGENT does not invent flags.
 
-## API and local providers
+## API and local/server providers
 
 API providers require explicit user selection and environment keys:
 
@@ -312,7 +313,7 @@ ur config set base_url http://localhost:1234/v1
 ur config set model local-model-name
 ```
 
-Local providers use their normal servers:
+Local/server providers use their normal endpoints:
 
 - Ollama: `http://localhost:11434`
 - LM Studio: `http://localhost:1234/v1`

package/package.json

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