durar-ai 2026.4.4

package/docs/providers/anthropic.md

@@ -0,0 +1,402 @@
+---
+summary: "Use Anthropic Claude via API keys or Claude CLI in Durar"
+read_when:
+  - You want to use Anthropic models in Durar
+  - You want to reuse Claude CLI subscription auth on the gateway host
+title: "Anthropic"
+---
+
+# Anthropic (Claude)
+
+Anthropic builds the **Claude** model family and provides access via an API.
+In Durar, new Anthropic setup should use an API key or the local Claude CLI
+backend. Existing legacy Anthropic token profiles are still honored at runtime
+if they are already configured.
+
+<Warning>
+Anthropic's public Claude Code docs explicitly document non-interactive CLI
+usage such as `claude -p`. Based on those docs, we believe local,
+user-managed Claude Code CLI fallback is likely allowed.
+
+Separately, Anthropic notified Durar users on **April 4, 2026 at 12:00 PM
+PT / 8:00 PM BST** that **Durar counts as a third-party harness**. Their
+stated policy is that Durar-driven Claude-login traffic no longer uses the
+included Claude subscription pool and instead requires **Extra Usage**
+(pay-as-you-go, billed separately from the subscription).
+
+That policy distinction is about **Durar-driven Claude CLI reuse**, not
+about running `claude` directly in your own terminal. That said, Anthropic's
+third-party harness policy still leaves enough ambiguity around
+subscription-backed use in external products that we do not recommend this
+path for production.
+
+Anthropic's current public docs:
+
+- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
+- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview)
+
+- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
+- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
+
+If you want the clearest billing path, use an Anthropic API key instead.
+Durar also supports other subscription-style options, including [OpenAI
+Codex](/providers/openai), [Qwen Cloud Coding Plan](/providers/qwen),
+[MiniMax Coding Plan](/providers/minimax), and [Z.AI / GLM Coding
+Plan](/providers/glm).
+</Warning>
+
+## Option A: Anthropic API key
+
+**Best for:** standard API access and usage-based billing.
+Create your API key in the Anthropic Console.
+
+### CLI setup
+
+```bash
+Durar onboard
+# choose: Anthropic API key
+
+# or non-interactive
+Durar onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+### Claude CLI config snippet
+
+```json5
+{
+  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Thinking defaults (Claude 4.6)
+
+- Anthropic Claude 4.6 models default to `adaptive` thinking in Durar when no explicit thinking level is set.
+- You can override per-message (`/think:<level>`) or in model params:
+  `agents.defaults.models["anthropic/<model>"].params.thinking`.
+- Related Anthropic docs:
+  - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
+  - [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
+
+## Fast mode (Anthropic API)
+
+Durar's shared `/fast` toggle also supports direct public Anthropic traffic, including API-key and OAuth-authenticated requests sent to `api.anthropic.com`.
+
+- `/fast on` maps to `service_tier: "auto"`
+- `/fast off` maps to `service_tier: "standard_only"`
+- Config default:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-sonnet-4-6": {
+          params: { fastMode: true },
+        },
+      },
+    },
+  },
+}
+```
+
+Important limits:
+
+- Durar only injects Anthropic service tiers for direct `api.anthropic.com` requests. If you route `anthropic/*` through a proxy or gateway, `/fast` leaves `service_tier` untouched.
+- Explicit Anthropic `serviceTier` or `service_tier` model params override the `/fast` default when both are set.
+- Anthropic reports the effective tier on the response under `usage.service_tier`. On accounts without Priority Tier capacity, `service_tier: "auto"` may still resolve to `standard`.
+
+## Prompt caching (Anthropic API)
+
+Durar supports Anthropic's prompt caching feature. This is **API-only**; legacy Anthropic token auth does not honor cache settings.
+
+### Configuration
+
+Use the `cacheRetention` parameter in your model config:
+
+| Value   | Cache Duration | Description              |
+| ------- | -------------- | ------------------------ |
+| `none`  | No caching     | Disable prompt caching   |
+| `short` | 5 minutes      | Default for API Key auth |
+| `long`  | 1 hour         | Extended cache           |
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { cacheRetention: "long" },
+        },
+      },
+    },
+  },
+}
+```
+
+### Defaults
+
+When using Anthropic API Key authentication, Durar automatically applies `cacheRetention: "short"` (5-minute cache) for all Anthropic models. You can override this by explicitly setting `cacheRetention` in your config.
+
+### Per-agent cacheRetention overrides
+
+Use model-level params as your baseline, then override specific agents via `agents.list[].params`.
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "anthropic/claude-opus-4-6" },
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { cacheRetention: "long" }, // baseline for most agents
+        },
+      },
+    },
+    list: [
+      { id: "research", default: true },
+      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
+    ],
+  },
+}
+```
+
+Config merge order for cache-related params:
+
+1. `agents.defaults.models["provider/model"].params`
+2. `agents.list[].params` (matching `id`, overrides by key)
+
+This lets one agent keep a long-lived cache while another agent on the same model disables caching to avoid write costs on bursty/low-reuse traffic.
+
+### Bedrock Claude notes
+
+- Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured.
+- Non-Anthropic Bedrock models are forced to `cacheRetention: "none"` at runtime.
+- Anthropic API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock model refs when no explicit value is set.
+
+## 1M context window (Anthropic beta)
+
+Anthropic's 1M context window is beta-gated. In Durar, enable it per model
+with `params.context1m: true` for supported Opus/Sonnet models.
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-6": {
+          params: { context1m: true },
+        },
+      },
+    },
+  },
+}
+```
+
+Durar maps this to `anthropic-beta: context-1m-2025-08-07` on Anthropic
+requests.
+
+This only activates when `params.context1m` is explicitly set to `true` for
+that model.
+
+Requirement: Anthropic must allow long-context usage on that credential
+(typically API key billing, or Durar's Claude-login path / legacy token auth
+with Extra Usage enabled). Otherwise Anthropic returns:
+`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
+
+Note: Anthropic currently rejects `context-1m-*` beta requests when using
+legacy Anthropic token auth (`sk-ant-oat-*`). If you configure
+`context1m: true` with that legacy auth mode, Durar logs a warning and
+falls back to the standard context window by skipping the context1m beta
+header while keeping the required OAuth betas.
+
+## Option B: Claude CLI as the message provider
+
+**Best for:** a single-user gateway host that already has Claude CLI installed
+and signed in, as a local fallback rather than the recommended production path.
+
+Billing note: We believe Claude Code CLI fallback is likely allowed for local,
+user-managed automation based on Anthropic's public CLI docs. That said,
+Anthropic's third-party harness policy creates enough ambiguity around
+subscription-backed use in external products that we do not recommend it for
+production. Anthropic also told Durar users that **Durar-driven** Claude
+CLI usage is treated as third-party harness traffic and, as of **April 4, 2026
+at 12:00 PM PT / 8:00 PM BST**, requires **Extra Usage** instead of the
+included Claude subscription limits.
+
+This path uses the local `claude` binary for model inference instead of calling
+the Anthropic API directly. Durar treats it as a **CLI backend provider**
+with model refs like:
+
+- `claude-cli/claude-sonnet-4-6`
+- `claude-cli/claude-opus-4-6`
+
+How it works:
+
+1. Durar launches `claude -p --output-format stream-json --include-partial-messages ...`
+   on the **gateway host** and sends the prompt over stdin.
+2. The first turn sends `--session-id <uuid>`.
+3. Follow-up turns reuse the stored Claude session via `--resume <sessionId>`.
+4. Your chat messages still go through the normal Durar message pipeline, but
+   the actual model reply is produced by Claude CLI.
+
+### Requirements
+
+- Claude CLI installed on the gateway host and available on PATH, or configured
+  with an absolute command path.
+- Claude CLI already authenticated on that same host:
+
+```bash
+claude auth status
+```
+
+- Durar auto-loads the bundled Anthropic plugin at gateway startup when your
+  config explicitly references `claude-cli/...` or `claude-cli` backend config.
+
+### Config snippet
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "claude-cli/claude-sonnet-4-6",
+      },
+      models: {
+        "claude-cli/claude-sonnet-4-6": {},
+      },
+      sandbox: { mode: "off" },
+    },
+  },
+}
+```
+
+If the `claude` binary is not on the gateway host PATH:
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude",
+        },
+      },
+    },
+  },
+}
+```
+
+### What you get
+
+- Claude subscription auth reused from the local CLI (read at runtime, not persisted)
+- Normal Durar message/session routing
+- Claude CLI session continuity across turns (invalidated on auth changes)
+- Gateway tools exposed to Claude CLI via loopback MCP bridge
+- JSONL streaming with live partial-message progress
+
+### Migrate from Anthropic auth to Claude CLI
+
+If you currently use `anthropic/...` with a legacy token profile or API key and want to
+switch the same gateway host to Claude CLI, Durar supports that as a normal
+provider-auth migration path.
+
+Prerequisites:
+
+- Claude CLI installed on the **same gateway host** that runs Durar
+- Claude CLI already signed in there: `claude auth login`
+
+Then run:
+
+```bash
+Durar models auth login --provider anthropic --method cli --set-default
+```
+
+Or in onboarding:
+
+```bash
+Durar onboard --auth-choice anthropic-cli
+```
+
+Interactive `Durar onboard` and `Durar configure` now prefer **Anthropic
+Claude CLI** first and **Anthropic API key** second.
+
+What this does:
+
+- verifies Claude CLI is already signed in on the gateway host
+- switches the default model to `claude-cli/...`
+- rewrites Anthropic default-model fallbacks like `anthropic/claude-opus-4-6`
+  to `claude-cli/claude-opus-4-6`
+- adds matching `claude-cli/...` entries to `agents.defaults.models`
+
+Quick verification:
+
+```bash
+Durar models status
+```
+
+You should see the resolved primary model under `claude-cli/...`.
+
+What it does **not** do:
+
+- delete your existing Anthropic auth profiles
+- remove every old `anthropic/...` config reference outside the main default
+  model/allowlist path
+
+That makes rollback simple: change the default model back to `anthropic/...` if
+you need to.
+
+### Important limits
+
+- This is **not** the Anthropic API provider. It is the local CLI runtime.
+- Durar does not inject tool calls directly. Claude CLI receives gateway
+  tools through a loopback MCP bridge (`bundleMcp: true`, the default).
+- Claude CLI streams replies via JSONL (`stream-json` with
+  `--include-partial-messages`). Prompts are sent over stdin, not argv.
+- Auth is read at runtime from live Claude CLI credentials and is not persisted
+  to Durar profiles. Keychain prompts are suppressed in non-interactive
+  contexts.
+- Session reuse is tracked via `cliSessionBinding` metadata. When Claude CLI
+  login state changes (relogin, token rotation), stored sessions are
+  invalidated and a fresh session starts.
+- Best fit for a personal gateway host, not shared multi-user billing setups.
+
+More details: [/gateway/cli-backends](/gateway/cli-backends)
+
+## Notes
+
+- Anthropic's public Claude Code docs still document direct CLI usage such as
+  `claude -p`. We believe local, user-managed fallback is likely allowed, but
+  Anthropic's separate notice to Durar users says the **Durar**
+  Claude-login path is third-party harness usage and requires **Extra Usage**
+  (pay-as-you-go billed separately from the subscription). For production, we
+  recommend Anthropic API keys instead.
+- Anthropic setup-token is available again in Durar as a legacy/manual path. Anthropic's Durar-specific billing notice still applies, so use it with the expectation that Anthropic requires **Extra Usage** for this path.
+- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).
+
+## Troubleshooting
+
+**401 errors / token suddenly invalid**
+
+- Legacy Anthropic token auth can expire or be revoked.
+- For new setup, migrate to an Anthropic API key or the local Claude CLI path on the gateway host.
+
+**No API key found for provider "anthropic"**
+
+- Auth is **per agent**. New agents don’t inherit the main agent’s keys.
+- Re-run onboarding for that agent, or configure an API key on the gateway
+  host, then verify with `Durar models status`.
+
+**No credentials found for profile `anthropic:default`**
+
+- Run `Durar models status` to see which auth profile is active.
+- Re-run onboarding, or configure an API key or Claude CLI for that profile path.
+
+**No available auth profile (all in cooldown/unavailable)**
+
+- Check `Durar models status --json` for `auth.unusableProfiles`.
+- Anthropic rate-limit cooldowns can be model-scoped, so a sibling Anthropic
+  model may still be usable even when the current one is cooling down.
+- Add another Anthropic profile or wait for cooldown.
+
+More: [/gateway/troubleshooting](/gateway/troubleshooting) and [/help/faq](/help/faq).

package/docs/providers/bedrock-mantle.md

@@ -0,0 +1,91 @@
+---
+summary: "Use Amazon Bedrock Mantle (OpenAI-compatible) models with Durar"
+read_when:
+  - You want to use Bedrock Mantle hosted OSS models with Durar
+  - You need the Mantle OpenAI-compatible endpoint for GPT-OSS, Qwen, Kimi, or GLM
+title: "Amazon Bedrock Mantle"
+---
+
+# Amazon Bedrock Mantle
+
+Durar includes a bundled **Amazon Bedrock Mantle** provider that connects to
+the Mantle OpenAI-compatible endpoint. Mantle hosts open-source and
+third-party models (GPT-OSS, Qwen, Kimi, GLM, and similar) through a standard
+`/v1/chat/completions` surface backed by Bedrock infrastructure.
+
+## What Durar supports
+
+- Provider: `amazon-bedrock-mantle`
+- API: `openai-completions` (OpenAI-compatible)
+- Auth: bearer token via `AWS_BEARER_TOKEN_BEDROCK`
+- Region: `AWS_REGION` or `AWS_DEFAULT_REGION` (default: `us-east-1`)
+
+## Automatic model discovery
+
+When `AWS_BEARER_TOKEN_BEDROCK` is set, Durar automatically discovers
+available Mantle models by querying the region's `/v1/models` endpoint.
+Discovery results are cached for 1 hour.
+
+Supported regions: `us-east-1`, `us-east-2`, `us-west-2`, `ap-northeast-1`,
+`ap-south-1`, `ap-southeast-3`, `eu-central-1`, `eu-west-1`, `eu-west-2`,
+`eu-south-1`, `eu-north-1`, `sa-east-1`.
+
+## Onboarding
+
+1. Set the bearer token on the **gateway host**:
+
+```bash
+export AWS_BEARER_TOKEN_BEDROCK="..."
+# Optional (defaults to us-east-1):
+export AWS_REGION="us-west-2"
+```
+
+2. Verify models are discovered:
+
+```bash
+Durar models list
+```
+
+Discovered models appear under the `amazon-bedrock-mantle` provider. No
+additional config is required unless you want to override defaults.
+
+## Manual configuration
+
+If you prefer explicit config instead of auto-discovery:
+
+```json5
+{
+  models: {
+    providers: {
+      "amazon-bedrock-mantle": {
+        baseUrl: "https://bedrock-mantle.us-east-1.api.aws/v1",
+        api: "openai-completions",
+        auth: "api-key",
+        apiKey: "env:AWS_BEARER_TOKEN_BEDROCK",
+        models: [
+          {
+            id: "gpt-oss-120b",
+            name: "GPT-OSS 120B",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 32000,
+            maxTokens: 4096,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Mantle requires a bearer token today. Plain IAM credentials (instance roles,
+  SSO, access keys) are not sufficient without a token.
+- The bearer token is the same `AWS_BEARER_TOKEN_BEDROCK` used by the standard
+  [Amazon Bedrock](/providers/bedrock) provider.
+- Reasoning support is inferred from model IDs containing patterns like
+  `thinking`, `reasoner`, or `gpt-oss-120b`.
+- If the Mantle endpoint is unavailable or returns no models, the provider is
+  silently skipped.