durar-ai 2026.4.4

package/docs/providers/openai.md

@@ -0,0 +1,472 @@
+---
+summary: "Use OpenAI via API keys or Codex subscription in Durar"
+read_when:
+  - You want to use OpenAI models in Durar
+  - You want Codex subscription auth instead of API keys
+title: "OpenAI"
+---
+
+# OpenAI
+
+OpenAI provides developer APIs for GPT models. Codex supports **ChatGPT sign-in** for subscription
+access or **API key** sign-in for usage-based access. Codex cloud requires ChatGPT sign-in.
+OpenAI explicitly supports subscription OAuth usage in external tools/workflows like Durar.
+
+## Default interaction style
+
+Durar can add a small OpenAI-specific prompt overlay for both `openai/*` and
+`openai-codex/*` runs. By default, the overlay keeps the assistant warm,
+collaborative, concise, direct, and a little more emotionally expressive
+without replacing the base Durar system prompt. The friendly overlay also
+permits the occasional emoji when it fits naturally, while keeping overall
+output concise.
+
+Config key:
+
+`plugins.entries.openai.config.personality`
+
+Allowed values:
+
+- `"friendly"`: default; enable the OpenAI-specific overlay.
+- `"off"`: disable the overlay and use the base Durar prompt only.
+
+Scope:
+
+- Applies to `openai/*` models.
+- Applies to `openai-codex/*` models.
+- Does not affect other providers.
+
+This behavior is on by default. Keep `"friendly"` explicitly if you want that
+to survive future local config churn:
+
+```json5
+{
+  plugins: {
+    entries: {
+      openai: {
+        config: {
+          personality: "friendly",
+        },
+      },
+    },
+  },
+}
+```
+
+### Disable the OpenAI prompt overlay
+
+If you want the unmodified base Durar prompt, set the overlay to `"off"`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      openai: {
+        config: {
+          personality: "off",
+        },
+      },
+    },
+  },
+}
+```
+
+You can also set it directly with the config CLI:
+
+```bash
+Durar config set plugins.entries.openai.config.personality off
+```
+
+## Option A: OpenAI API key (OpenAI Platform)
+
+**Best for:** direct API access and usage-based billing.
+Get your API key from the OpenAI dashboard.
+
+### CLI setup
+
+```bash
+Durar onboard --auth-choice openai-api-key
+# or non-interactive
+Durar onboard --openai-api-key "$OPENAI_API_KEY"
+```
+
+### Config snippet
+
+```json5
+{
+  env: { OPENAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
+}
+```
+
+OpenAI's current API model docs list `gpt-5.4` and `gpt-5.4-pro` for direct
+OpenAI API usage. Durar forwards both through the `openai/*` Responses path.
+Durar intentionally suppresses the stale `openai/gpt-5.3-codex-spark` row,
+because direct OpenAI API calls reject it in live traffic.
+
+Durar does **not** expose `openai/gpt-5.3-codex-spark` on the direct OpenAI
+API path. `pi-ai` still ships a built-in row for that model, but live OpenAI API
+requests currently reject it. Spark is treated as Codex-only in Durar.
+
+## Option B: OpenAI Code (Codex) subscription
+
+**Best for:** using ChatGPT/Codex subscription access instead of an API key.
+Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in.
+
+### CLI setup (Codex OAuth)
+
+```bash
+# Run Codex OAuth in the wizard
+Durar onboard --auth-choice openai-codex
+
+# Or run OAuth directly
+Durar models auth login --provider openai-codex
+```
+
+### Config snippet (Codex subscription)
+
+```json5
+{
+  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
+}
+```
+
+OpenAI's current Codex docs list `gpt-5.4` as the current Codex model. Durar
+maps that to `openai-codex/gpt-5.4` for ChatGPT/Codex OAuth usage.
+
+If onboarding reuses an existing Codex CLI login, those credentials stay
+managed by Codex CLI. On expiry, Durar re-reads the external Codex source
+first and, when the provider can refresh it, writes the refreshed credential
+back to Codex storage instead of taking ownership in a separate Durar-only
+copy.
+
+If your Codex account is entitled to Codex Spark, Durar also supports:
+
+- `openai-codex/gpt-5.3-codex-spark`
+
+Durar treats Codex Spark as Codex-only. It does not expose a direct
+`openai/gpt-5.3-codex-spark` API-key path.
+
+Durar also preserves `openai-codex/gpt-5.3-codex-spark` when `pi-ai`
+discovers it. Treat it as entitlement-dependent and experimental: Codex Spark is
+separate from GPT-5.4 `/fast`, and availability depends on the signed-in Codex /
+ChatGPT account.
+
+### Codex context window cap
+
+Durar treats the Codex model metadata and the runtime context cap as separate
+values.
+
+For `openai-codex/gpt-5.4`:
+
+- native `contextWindow`: `1050000`
+- default runtime `contextTokens` cap: `272000`
+
+That keeps model metadata truthful while preserving the smaller default runtime
+window that has better latency and quality characteristics in practice.
+
+If you want a different effective cap, set `models.providers.<provider>.models[].contextTokens`:
+
+```json5
+{
+  models: {
+    providers: {
+      "openai-codex": {
+        models: [
+          {
+            id: "gpt-5.4",
+            contextTokens: 160000,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+Use `contextWindow` only when you are declaring or overriding native model
+metadata. Use `contextTokens` when you want to limit the runtime context budget.
+
+### Transport default
+
+Durar uses `pi-ai` for model streaming. For both `openai/*` and
+`openai-codex/*`, default transport is `"auto"` (WebSocket-first, then SSE
+fallback).
+
+In `"auto"` mode, Durar also retries one early, retryable WebSocket failure
+before it falls back to SSE. Forced `"websocket"` mode still surfaces transport
+errors directly instead of hiding them behind fallback.
+
+After a connect or early-turn WebSocket failure in `"auto"` mode, Durar marks
+that session's WebSocket path as degraded for about 60 seconds and sends
+subsequent turns over SSE during the cool-down instead of thrashing between
+transports.
+
+For native OpenAI-family endpoints (`openai/*`, `openai-codex/*`, and Azure
+OpenAI Responses), Durar also attaches stable session and turn identity state
+to requests so retries, reconnects, and SSE fallback stay aligned to the same
+conversation identity. On native OpenAI-family routes this includes stable
+session/turn request identity headers plus matching transport metadata.
+
+Durar also normalizes OpenAI usage counters across transport variants before
+they reach session/status surfaces. Native OpenAI/Codex Responses traffic may
+report usage as either `input_tokens` / `output_tokens` or
+`prompt_tokens` / `completion_tokens`; Durar treats those as the same input
+and output counters for `/status`, `/usage`, and session logs. When native
+WebSocket traffic omits `total_tokens` (or reports `0`), Durar falls back to
+the normalized input + output total so session/status displays stay populated.
+
+You can set `agents.defaults.models.<provider/model>.params.transport`:
+
+- `"sse"`: force SSE
+- `"websocket"`: force WebSocket
+- `"auto"`: try WebSocket, then fall back to SSE
+
+For `openai/*` (Responses API), Durar also enables WebSocket warm-up by
+default (`openaiWsWarmup: true`) when WebSocket transport is used.
+
+Related OpenAI docs:
+
+- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
+- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "openai-codex/gpt-5.4" },
+      models: {
+        "openai-codex/gpt-5.4": {
+          params: {
+            transport: "auto",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### OpenAI WebSocket warm-up
+
+OpenAI docs describe warm-up as optional. Durar enables it by default for
+`openai/*` to reduce first-turn latency when using WebSocket transport.
+
+### Disable warm-up
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            openaiWsWarmup: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Enable warm-up explicitly
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            openaiWsWarmup: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### OpenAI and Codex priority processing
+
+OpenAI's API exposes priority processing via `service_tier=priority`. In
+Durar, set `agents.defaults.models["<provider>/<model>"].params.serviceTier`
+to pass that field through on native OpenAI/Codex Responses endpoints.
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            serviceTier: "priority",
+          },
+        },
+        "openai-codex/gpt-5.4": {
+          params: {
+            serviceTier: "priority",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Supported values are `auto`, `default`, `flex`, and `priority`.
+
+Durar forwards `params.serviceTier` to both direct `openai/*` Responses
+requests and `openai-codex/*` Codex Responses requests when those models point
+at the native OpenAI/Codex endpoints.
+
+Important behavior:
+
+- direct `openai/*` must target `api.openai.com`
+- `openai-codex/*` must target `chatgpt.com/backend-api`
+- if you route either provider through another base URL or proxy, Durar leaves `service_tier` untouched
+
+### OpenAI fast mode
+
+Durar exposes a shared fast-mode toggle for both `openai/*` and
+`openai-codex/*` sessions:
+
+- Chat/UI: `/fast status|on|off`
+- Config: `agents.defaults.models["<provider>/<model>"].params.fastMode`
+
+When fast mode is enabled, Durar maps it to OpenAI priority processing:
+
+- direct `openai/*` Responses calls to `api.openai.com` send `service_tier = "priority"`
+- `openai-codex/*` Responses calls to `chatgpt.com/backend-api` also send `service_tier = "priority"`
+- existing payload `service_tier` values are preserved
+- fast mode does not rewrite `reasoning` or `text.verbosity`
+
+Example:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            fastMode: true,
+          },
+        },
+        "openai-codex/gpt-5.4": {
+          params: {
+            fastMode: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Session overrides win over config. Clearing the session override in the Sessions UI
+returns the session to the configured default.
+
+### Native OpenAI versus OpenAI-compatible routes
+
+Durar treats direct OpenAI, Codex, and Azure OpenAI endpoints differently
+from generic OpenAI-compatible `/v1` proxies:
+
+- native `openai/*`, `openai-codex/*`, and Azure OpenAI routes keep
+  `reasoning: { effort: "none" }` intact when you explicitly disable reasoning
+- native OpenAI-family routes default tool schemas to strict mode
+- hidden Durar attribution headers (`originator`, `version`, and
+  `User-Agent`) are only attached on verified native OpenAI hosts
+  (`api.openai.com`) and native Codex hosts (`chatgpt.com/backend-api`)
+- native OpenAI/Codex routes keep OpenAI-only request shaping such as
+  `service_tier`, Responses `store`, OpenAI reasoning-compat payloads, and
+  prompt-cache hints
+- proxy-style OpenAI-compatible routes keep the looser compat behavior and do
+  not force strict tool schemas, native-only request shaping, or hidden
+  OpenAI/Codex attribution headers
+
+Azure OpenAI stays in the native-routing bucket for transport and compat
+behavior, but it does not receive the hidden OpenAI/Codex attribution headers.
+
+This preserves current native OpenAI Responses behavior without forcing older
+OpenAI-compatible shims onto third-party `/v1` backends.
+
+### OpenAI Responses server-side compaction
+
+For direct OpenAI Responses models (`openai/*` using `api: "openai-responses"` with
+`baseUrl` on `api.openai.com`), Durar now auto-enables OpenAI server-side
+compaction payload hints:
+
+- Forces `store: true` (unless model compat sets `supportsStore: false`)
+- Injects `context_management: [{ type: "compaction", compact_threshold: ... }]`
+
+By default, `compact_threshold` is `70%` of model `contextWindow` (or `80000`
+when unavailable).
+
+### Enable server-side compaction explicitly
+
+Use this when you want to force `context_management` injection on compatible
+Responses models (for example Azure OpenAI Responses):
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "azure-openai-responses/gpt-5.4": {
+          params: {
+            responsesServerCompaction: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Enable with a custom threshold
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            responsesServerCompaction: true,
+            responsesCompactThreshold: 120000,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Disable server-side compaction
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "openai/gpt-5.4": {
+          params: {
+            responsesServerCompaction: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`responsesServerCompaction` only controls `context_management` injection.
+Direct OpenAI Responses models still force `store: true` unless compat sets
+`supportsStore: false`.
+
+## Notes
+
+- Model refs always use `provider/model` (see [/concepts/models](/concepts/models)).
+- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).

package/docs/providers/opencode-go.md

@@ -0,0 +1,45 @@
+---
+summary: "Use the OpenCode Go catalog with the shared OpenCode setup"
+read_when:
+  - You want the OpenCode Go catalog
+  - You need the runtime model refs for Go-hosted models
+title: "OpenCode Go"
+---
+
+# OpenCode Go
+
+OpenCode Go is the Go catalog within [OpenCode](/providers/opencode).
+It uses the same `OPENCODE_API_KEY` as the Zen catalog, but keeps the runtime
+provider id `opencode-go` so upstream per-model routing stays correct.
+
+## Supported models
+
+- `opencode-go/kimi-k2.5`
+- `opencode-go/glm-5`
+- `opencode-go/minimax-m2.5`
+
+## CLI setup
+
+```bash
+Durar onboard --auth-choice opencode-go
+# or non-interactive
+Durar onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "YOUR_API_KEY_HERE" }, // pragma: allowlist secret
+  agents: { defaults: { model: { primary: "opencode-go/kimi-k2.5" } } },
+}
+```
+
+## Routing behavior
+
+Durar handles per-model routing automatically when the model ref uses `opencode-go/...`.
+
+## Notes
+
+- Use [OpenCode](/providers/opencode) for the shared onboarding and catalog overview.
+- Runtime refs stay explicit: `opencode/...` for Zen, `opencode-go/...` for Go.

package/docs/providers/opencode.md

@@ -0,0 +1,68 @@
+---
+summary: "Use OpenCode Zen and Go catalogs with Durar"
+read_when:
+  - You want OpenCode-hosted model access
+  - You want to pick between the Zen and Go catalogs
+title: "OpenCode"
+---
+
+# OpenCode
+
+OpenCode exposes two hosted catalogs in Durar:
+
+- `opencode/...` for the **Zen** catalog
+- `opencode-go/...` for the **Go** catalog
+
+Both catalogs use the same OpenCode API key. Durar keeps the runtime provider ids
+split so upstream per-model routing stays correct, but onboarding and docs treat them
+as one OpenCode setup.
+
+## CLI setup
+
+### Zen catalog
+
+```bash
+Durar onboard --auth-choice opencode-zen
+Durar onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
+```
+
+### Go catalog
+
+```bash
+Durar onboard --auth-choice opencode-go
+Durar onboard --opencode-go-api-key "$OPENCODE_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENCODE_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
+}
+```
+
+## Catalogs
+
+### Zen
+
+- Runtime provider: `opencode`
+- Example models: `opencode/claude-opus-4-6`, `opencode/gpt-5.4`, `opencode/gemini-3-pro`
+- Best when you want the curated OpenCode multi-model proxy
+
+### Go
+
+- Runtime provider: `opencode-go`
+- Example models: `opencode-go/kimi-k2.5`, `opencode-go/glm-5`, `opencode-go/minimax-m2.5`
+- Best when you want the OpenCode-hosted Kimi/GLM/MiniMax lineup
+
+## Notes
+
+- `OPENCODE_ZEN_API_KEY` is also supported.
+- Entering one OpenCode key during setup stores credentials for both runtime providers.
+- You sign in to OpenCode, add billing details, and copy your API key.
+- Billing and catalog availability are managed from the OpenCode dashboard.
+- Gemini-backed OpenCode refs stay on the proxy-Gemini path, so Durar keeps
+  Gemini thought-signature sanitation there without enabling native Gemini
+  replay validation or bootstrap rewrites.
+- Non-Gemini OpenCode refs keep the minimal OpenAI-compatible replay policy.

package/docs/providers/openrouter.md

@@ -0,0 +1,59 @@
+---
+summary: "Use OpenRouter's unified API to access many models in Durar"
+read_when:
+  - You want a single API key for many LLMs
+  - You want to run models via OpenRouter in Durar
+title: "OpenRouter"
+---
+
+# OpenRouter
+
+OpenRouter provides a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+## CLI setup
+
+```bash
+Durar onboard --auth-choice openrouter-api-key
+```
+
+## Config snippet
+
+```json5
+{
+  env: { OPENROUTER_API_KEY: "sk-or-..." },
+  agents: {
+    defaults: {
+      model: { primary: "openrouter/auto" },
+    },
+  },
+}
+```
+
+## Notes
+
+- Model refs are `openrouter/<provider>/<model>`.
+- Onboarding defaults to `openrouter/auto`. Switch to a concrete model later with
+  `Durar models set openrouter/<provider>/<model>`.
+- For more model/provider options, see [/concepts/model-providers](/concepts/model-providers).
+- OpenRouter uses a Bearer token with your API key under the hood.
+- On real OpenRouter requests (`https://openrouter.ai/api/v1`), Durar also
+  adds OpenRouter's documented app-attribution headers:
+  `HTTP-Referer: https://Durar.ai`, `X-OpenRouter-Title: Durar`, and
+  `X-OpenRouter-Categories: cli-agent`.
+- On verified OpenRouter routes, Anthropic model refs also keep the
+  OpenRouter-specific Anthropic `cache_control` markers that Durar uses for
+  better prompt-cache reuse on system/developer prompt blocks.
+- If you repoint the OpenRouter provider at some other proxy/base URL, Durar
+  does not inject those OpenRouter-specific headers or Anthropic cache markers.
+- OpenRouter still runs through the proxy-style OpenAI-compatible path, so
+  native OpenAI-only request shaping such as `serviceTier`, Responses `store`,
+  OpenAI reasoning-compat payloads, and prompt-cache hints is not forwarded.
+- Gemini-backed OpenRouter refs stay on the proxy-Gemini path: Durar keeps
+  Gemini thought-signature sanitation there, but does not enable native Gemini
+  replay validation or bootstrap rewrites.
+- On supported non-`auto` routes, Durar maps the selected thinking level to
+  OpenRouter proxy reasoning payloads. Unsupported model hints and
+  `openrouter/auto` skip that reasoning injection.
+- If you pass OpenRouter provider routing under model params, Durar forwards
+  it as OpenRouter routing metadata before the shared stream wrappers run.

package/docs/providers/perplexity-provider.md

@@ -0,0 +1,62 @@
+---
+title: "Perplexity (Provider)"
+summary: "Perplexity web search provider setup (API key, search modes, filtering)"
+read_when:
+  - You want to configure Perplexity as a web search provider
+  - You need the Perplexity API key or OpenRouter proxy setup
+---
+
+# Perplexity (Web Search Provider)
+
+The Perplexity plugin provides web search capabilities through the Perplexity
+Search API or Perplexity Sonar via OpenRouter.
+
+<Note>
+This page covers the Perplexity **provider** setup. For the Perplexity
+**tool** (how the agent uses it), see [Perplexity tool](/tools/perplexity-search).
+</Note>
+
+- Type: web search provider (not a model provider)
+- Auth: `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter)
+- Config path: `plugins.entries.perplexity.config.webSearch.apiKey`
+
+## Quick start
+
+1. Set the API key:
+
+```bash
+Durar configure --section web
+```
+
+Or set it directly:
+
+```bash
+Durar config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
+```
+
+2. The agent will automatically use Perplexity for web searches when configured.
+
+## Search modes
+
+The plugin auto-selects the transport based on API key prefix:
+
+| Key prefix | Transport                    | Features                                         |
+| ---------- | ---------------------------- | ------------------------------------------------ |
+| `pplx-`    | Native Perplexity Search API | Structured results, domain/language/date filters |
+| `sk-or-`   | OpenRouter (Sonar)           | AI-synthesized answers with citations            |
+
+## Native API filtering
+
+When using the native Perplexity API (`pplx-` key), searches support:
+
+- **Country**: 2-letter country code
+- **Language**: ISO 639-1 language code
+- **Date range**: day, week, month, year
+- **Domain filters**: allowlist/denylist (max 20 domains)
+- **Content budget**: `max_tokens`, `max_tokens_per_page`
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure
+`PERPLEXITY_API_KEY` is available to that process (for example, in
+`~/.Durar/.env` or via `env.shellEnv`).