# Quota Router configuration

`dsh-quota-router` is a **policy plugin**. It chooses among routes that DSH already knows; it never creates providers, stores credentials, or guesses model capabilities.

Use **Settings → Quota Router** in DSH Web to edit the policy, or configure the `quota-router` namespace in DSH settings.

## Ownership boundaries

| Area | Owner | Editable in Quota Router |
| --- | --- | --- |
| Source order, task profiles, model mappings | You | Yes |
| Retry threshold, cooldown duration, ledger limit | You | Yes |
| Profile matching, forward-only fallback, cooldown algorithm | Plugin | No |
| Provider registration, credentials, model catalog | DSH Models | No |
| Model reasoning-effort support and adapter retry | DSH | No |
| Context compaction | DSH `compaction-basic` | No |

`quota_router_status` is a runtime diagnostic tool. It reports decisions, active cooldowns, and source-tier usage; it is not a provider or credential manager.

## Minimal safe configuration

```yaml
quota-router:
  enabled: true
  transientFailureThreshold: 2
  cooldownMs: 60000
  allowPaidFallback: false

  sources:
    - id: opencode-go
      provider: opencode-go
      tier: subscription
      priority: 1
      autoEligible: true
    - id: token-share
      provider: token-share
      tier: free
      priority: 2
      autoEligible: true
    - id: starchasing
      provider: starchasing
      tier: paid
      priority: 3
      autoEligible: true

  profiles:
    - id: coding
      keywords: ["写代码", "修复", "bug", "fix", "code"]
      modelBySource:
        opencode-go: mimo-v2.5
        token-share: gpt-5.6-luna
        starchasing: gpt-5.6-terra
```

`allowPaidFallback: false` is the safe default. A `paid` source may be mapped in profiles and shown in the chain preview, but it is automatically skipped until you explicitly enable paid fallback. `manual` and `emergency` sources are always skipped automatically.

## Fields

### Global policy

| Field | Default | Meaning |
| --- | --- | --- |
| `enabled` | `true` | Turns policy routing on/off. Disabled leaves DSH defaults unchanged. |
| `matchCase` | `false` | Whether profile keyword matching is case sensitive. |
| `transientFailureThreshold` | `2` | Same source-route transient failures required before cooldown/fallback. |
| `cooldownMs` | `60000` | How long a transiently failing source-route is skipped. |
| `ledgerLimit` | `200` | In-memory decision history size. |
| `allowPaidFallback` | `false` | Explicit global approval for automatically selecting `tier: paid` sources. |

### Sources

A source is a named reference to a DSH provider.

| Field | Meaning |
| --- | --- |
| `id` | Stable key used by `profiles[].modelBySource`. Do not casually rename it. |
| `provider` | A provider ID already registered in DSH Models. |
| `name` | Optional display label. |
| `tier` | Your policy label: `free`, `subscription`, `unlimited`, `quota`, `payg`, `paid`, `manual`, or `emergency`. It never changes order itself. |
| `priority` | Lower number is tried first. Keep priorities unique. |
| `enabled` | Disables the source entirely. |
| `autoEligible` | Allows automatic selection, subject to paid/manual/emergency safety rules. |

A source is healthy only when its DSH-native provider/model route has passed runtime validation and is not in cooldown. The configuration preview does not claim live health.

### Profiles

Profiles are evaluated in declaration order. The first enabled profile with any matching keyword wins.

| Field | Meaning |
| --- | --- |
| `id` | Stable task-policy identity used in the decision ledger. |
| `enabled` | Whether this profile participates in matching. |
| `keywords` | Ordered-profile substring triggers; place specific profiles before broad ones. |
| `reasoningEffort` | Optional default passed to DSH, subject to native DSH validation. |
| `modelBySource` | Source ID → model ID or `{ model, reasoningEffort }`. Missing sources simply do not enter this profile's chain. |

## What happens on a failure

- **Stable errors** (`QUOTA`, auth/credential failures, HTTP 401/403) advance immediately to the next healthy automatic candidate and ask DSH to retry the same turn.
- **Transient errors** (rate limiting, timeout, transport, HTTP 429/5xx) first use DSH's normal retry behavior. At the configured threshold, the current source-route enters cooldown and the profile advances.
- Candidates only move forward. If no automatic candidate remains, the original DSH failure remains intact.

See [strategy.md](./strategy.md) for recommended source chains and task decomposition patterns.