ur-agent 1.27.5 → 1.28.0

package/docs/CONFIGURATION.md

@@ -58,7 +58,18 @@ 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.
+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:
@@ -98,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

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 |
-| --- | --- | --- |
-| Codex CLI | 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
 
@@ -65,11 +65,12 @@ UR-AGENT shows providers first, then only models available for the selected prov
 
 ## 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/server providers** connect to the configured local or OpenAI-compatible endpoint
+- **Subscription providers** spawn the official CLI command (e.g. `codex`, `claude`, `gemini`) in non-interactive mode, pass the prompt and the provider-scoped model, and map its stdout to the response. A non-zero exit or empty output fails clearly — it is never replaced with placeholder text.
+- **API providers** make direct HTTP calls in each provider's native wire format: Anthropic uses `x-api-key` + `anthropic-version` against `/v1/messages`; OpenAI uses `Authorization: Bearer` against `/v1/chat/completions`; Gemini uses `x-goog-api-key` against `…:generateContent`; OpenRouter uses its OpenAI-compatible chat endpoint.
+- **Local/server providers** connect to the configured local or OpenAI-compatible endpoint (`/v1/chat/completions` for LM Studio, llama.cpp and vLLM; the native tags/chat API for Ollama)
 
 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
 
@@ -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)
 
@@ -129,6 +134,7 @@ After selecting a model, the confirmation shows:
   Selected provider: Codex CLI (subscription)
   Selected model: codex/gpt-5.5
   Model source: static
+  Runtime backend: subscription-cli:codex
 ```
 
 ### CLI workflow
@@ -209,11 +215,7 @@ Warning: Current model "gpt-5.5" is not available for provider "anthropic-api" a
 
 **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
 ```
 
@@ -232,25 +234,28 @@ 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/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)
 
+**Saved local/server model rejected after restart:**
+- A model saved via `/model` for a live-discovery provider (`ollama`, `lmstudio`, `llama.cpp`, `vllm`, `openai-compatible`) is accepted on a fresh process even before discovery has repopulated the in-memory model cache. The endpoint is the source of truth, so a saved model is not rejected pre-discovery. Static providers (API/subscription) remain strictly validated against their model list.
+
 **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 |

package/package.json

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