durar-ai 2026.4.4

package/docs/concepts/models.md

@@ -0,0 +1,255 @@
+---
+summary: "Models CLI: list, set, aliases, fallbacks, scan, status"
+read_when:
+  - Adding or modifying models CLI (models list/set/scan/aliases/fallbacks)
+  - Changing model fallback behavior or selection UX
+  - Updating model scan probes (tools/images)
+title: "Models CLI"
+---
+
+# Models CLI
+
+See [/concepts/model-failover](/concepts/model-failover) for auth profile
+rotation, cooldowns, and how that interacts with fallbacks.
+Quick provider overview + examples: [/concepts/model-providers](/concepts/model-providers).
+
+## How model selection works
+
+Durar selects models in this order:
+
+1. **Primary** model (`agents.defaults.model.primary` or `agents.defaults.model`).
+2. **Fallbacks** in `agents.defaults.model.fallbacks` (in order).
+3. **Provider auth failover** happens inside a provider before moving to the
+   next model.
+
+Related:
+
+- `agents.defaults.models` is the allowlist/catalog of models Durar can use (plus aliases).
+- `agents.defaults.imageModel` is used **only when** the primary model can’t accept images.
+- `agents.defaults.pdfModel` is used by the `pdf` tool. If omitted, the tool
+  falls back to `agents.defaults.imageModel`, then the resolved session/default
+  model.
+- `agents.defaults.imageGenerationModel` is used by the shared image-generation capability. If omitted, `image_generate` can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered image-generation providers in provider-id order. If you set a specific provider/model, also configure that provider's auth/API key.
+- `agents.defaults.videoGenerationModel` is used by the shared video-generation capability. Unlike image generation, this does not infer a provider default today. Set an explicit `provider/model` such as `qwen/wan2.6-t2v`, and configure that provider's auth/API key too.
+- Per-agent defaults can override `agents.defaults.model` via `agents.list[].model` plus bindings (see [/concepts/multi-agent](/concepts/multi-agent)).
+
+## Quick model policy
+
+- Set your primary to the strongest latest-generation model available to you.
+- Use fallbacks for cost/latency-sensitive tasks and lower-stakes chat.
+- For tool-enabled agents or untrusted inputs, avoid older/weaker model tiers.
+
+## Onboarding (recommended)
+
+If you don’t want to hand-edit config, run onboarding:
+
+```bash
+Durar onboard
+```
+
+It can set up model + auth for common providers, including **OpenAI Code (Codex)
+subscription** (OAuth) and **Anthropic** (API key or Claude CLI).
+
+## Config keys (overview)
+
+- `agents.defaults.model.primary` and `agents.defaults.model.fallbacks`
+- `agents.defaults.imageModel.primary` and `agents.defaults.imageModel.fallbacks`
+- `agents.defaults.pdfModel.primary` and `agents.defaults.pdfModel.fallbacks`
+- `agents.defaults.imageGenerationModel.primary` and `agents.defaults.imageGenerationModel.fallbacks`
+- `agents.defaults.videoGenerationModel.primary` and `agents.defaults.videoGenerationModel.fallbacks`
+- `agents.defaults.models` (allowlist + aliases + provider params)
+- `models.providers` (custom providers written into `models.json`)
+
+Model refs are normalized to lowercase. Provider aliases like `z.ai/*` normalize
+to `zai/*`.
+
+Provider configuration examples (including OpenCode) live in
+[/providers/opencode](/providers/opencode).
+
+## "Model is not allowed" (and why replies stop)
+
+If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and for
+session overrides. When a user selects a model that isn’t in that allowlist,
+Durar returns:
+
+```
+Model "provider/model" is not allowed. Use /model to list available models.
+```
+
+This happens **before** a normal reply is generated, so the message can feel
+like it “didn’t respond.” The fix is to either:
+
+- Add the model to `agents.defaults.models`, or
+- Clear the allowlist (remove `agents.defaults.models`), or
+- Pick a model from `/model list`.
+
+Example allowlist config:
+
+```json5
+{
+  agent: {
+    model: { primary: "anthropic/claude-sonnet-4-6" },
+    models: {
+      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
+      "anthropic/claude-opus-4-6": { alias: "Opus" },
+    },
+  },
+}
+```
+
+## Switching models in chat (`/model`)
+
+You can switch models for the current session without restarting:
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.4
+/model status
+```
+
+Notes:
+
+- `/model` (and `/model list`) is a compact, numbered picker (model family + available providers).
+- On Discord, `/model` and `/models` open an interactive picker with provider and model dropdowns plus a Submit step.
+- `/model <#>` selects from that picker.
+- `/model` persists the new session selection immediately.
+- If the agent is idle, the next run uses the new model right away.
+- If a run is already active, Durar marks a live switch as pending and only restarts into the new model at a clean retry point.
+- If tool activity or reply output has already started, the pending switch can stay queued until a later retry opportunity or the next user turn.
+- `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
+- Model refs are parsed by splitting on the **first** `/`. Use `provider/model` when typing `/model <ref>`.
+- If the model ID itself contains `/` (OpenRouter-style), you must include the provider prefix (example: `/model openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, Durar resolves the input in this order:
+  1. alias match
+  2. unique configured-provider match for that exact unprefixed model id
+  3. deprecated fallback to the configured default provider
+     If that provider no longer exposes the configured default model, Durar
+     instead falls back to the first configured provider/model to avoid
+     surfacing a stale removed-provider default.
+
+Full command behavior/config: [Slash commands](/tools/slash-commands).
+
+## CLI commands
+
+```bash
+Durar models list
+Durar models status
+Durar models set <provider/model>
+Durar models set-image <provider/model>
+
+Durar models aliases list
+Durar models aliases add <alias> <provider/model>
+Durar models aliases remove <alias>
+
+Durar models fallbacks list
+Durar models fallbacks add <provider/model>
+Durar models fallbacks remove <provider/model>
+Durar models fallbacks clear
+
+Durar models image-fallbacks list
+Durar models image-fallbacks add <provider/model>
+Durar models image-fallbacks remove <provider/model>
+Durar models image-fallbacks clear
+```
+
+`Durar models` (no subcommand) is a shortcut for `models status`.
+
+### `models list`
+
+Shows configured models by default. Useful flags:
+
+- `--all`: full catalog
+- `--local`: local providers only
+- `--provider <name>`: filter by provider
+- `--plain`: one model per line
+- `--json`: machine‑readable output
+
+### `models status`
+
+Shows the resolved primary model, fallbacks, image model, and an auth overview
+of configured providers. It also surfaces OAuth expiry status for profiles found
+in the auth store (warns within 24h by default). `--plain` prints only the
+resolved primary model.
+OAuth status is always shown (and included in `--json` output). If a configured
+provider has no credentials, `models status` prints a **Missing auth** section.
+JSON includes `auth.oauth` (warn window + profiles) and `auth.providers`
+(effective auth per provider).
+Use `--check` for automation (exit `1` when missing/expired, `2` when expiring).
+Use `--probe` for live auth checks; probe rows can come from auth profiles, env
+credentials, or `models.json`.
+If explicit `auth.order.<provider>` omits a stored profile, probe reports
+`excluded_by_auth_order` instead of trying it. If auth exists but no probeable
+model can be resolved for that provider, probe reports `status: no_model`.
+
+Auth choice is provider/account dependent. For always-on gateway hosts, API
+keys are usually the most predictable; Claude CLI reuse and existing Anthropic
+OAuth/token profiles are also supported.
+
+Example (Claude CLI):
+
+```bash
+claude auth login
+Durar models status
+```
+
+## Scanning (OpenRouter free models)
+
+`Durar models scan` inspects OpenRouter’s **free model catalog** and can
+optionally probe models for tool and image support.
+
+Key flags:
+
+- `--no-probe`: skip live probes (metadata only)
+- `--min-params <b>`: minimum parameter size (billions)
+- `--max-age-days <days>`: skip older models
+- `--provider <name>`: provider prefix filter
+- `--max-candidates <n>`: fallback list size
+- `--set-default`: set `agents.defaults.model.primary` to the first selection
+- `--set-image`: set `agents.defaults.imageModel.primary` to the first image selection
+
+Probing requires an OpenRouter API key (from auth profiles or
+`OPENROUTER_API_KEY`). Without a key, use `--no-probe` to list candidates only.
+
+Scan results are ranked by:
+
+1. Image support
+2. Tool latency
+3. Context size
+4. Parameter count
+
+Input
+
+- OpenRouter `/models` list (filter `:free`)
+- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/help/environment))
+- Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
+- Probe controls: `--timeout`, `--concurrency`
+
+When run in a TTY, you can select fallbacks interactively. In non‑interactive
+mode, pass `--yes` to accept defaults.
+
+## Models registry (`models.json`)
+
+Custom providers in `models.providers` are written into `models.json` under the
+agent directory (default `~/.Durar/agents/<agentId>/agent/models.json`). This file
+is merged by default unless `models.mode` is set to `replace`.
+
+Merge mode precedence for matching provider IDs:
+
+- Non-empty `baseUrl` already present in the agent `models.json` wins.
+- Non-empty `apiKey` in the agent `models.json` wins only when that provider is not SecretRef-managed in current config/auth-profile context.
+- SecretRef-managed provider `apiKey` values are refreshed from source markers (`ENV_VAR_NAME` for env refs, `secretref-managed` for file/exec refs) instead of persisting resolved secrets.
+- SecretRef-managed provider header values are refreshed from source markers (`secretref-env:ENV_VAR_NAME` for env refs, `secretref-managed` for file/exec refs).
+- Empty or missing agent `apiKey`/`baseUrl` fall back to config `models.providers`.
+- Other provider fields are refreshed from config and normalized catalog data.
+
+Marker persistence is source-authoritative: Durar writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values.
+This applies whenever Durar regenerates `models.json`, including command-driven paths like `Durar agent`.
+
+## Related
+
+- [Model Providers](/concepts/model-providers) — provider routing and auth
+- [Model Failover](/concepts/model-failover) — fallback chains
+- [Image Generation](/tools/image-generation) — image model configuration
+- [Configuration Reference](/gateway/configuration-reference#agent-defaults) — model config keys