@askalf/dario 6.0.32 → 6.0.34

package/docs/admin-api.md

@@ -95,12 +95,24 @@ All endpoints accept the token as `authorization: Bearer <token>` or
 | `DELETE /admin/accounts/<alias>` | — | `{ alias, removed }` (`404` if no such alias) |
 
 `GET /admin/accounts` is the monitoring surface: each entry carries the
-persisted metadata (`alias`, `scopes`, `expires_in_ms`) **plus live pool
-status whenever pool mode is active** — `util5h` / `util7d` utilization,
-representative `claim` (e.g. `five_hour`), routing `status`,
-`request_count`, and `consecutive_auth_failures`. It's the admin-token-gated
-equivalent of the proxy-key-gated `GET /accounts` pool view; a headless
-operator needs only the admin token to watch headroom.
+persisted metadata (`alias`, `scopes`, `expires_in_ms`, the grant-age fields)
+**plus live pool status whenever pool mode is active** — `util5h` / `util7d`
+utilization with `last_observed_at` / `util_age_ms` (how old that reading is;
+it does not tick while a seat is parked), `reset_at` / `reset_in_ms` (when
+the window it was measured against rolls — for a `rejected` seat, when the
+rejection lifts), representative `claim` (e.g. `five_hour`), routing
+`status`, `request_count` (requests served), `rejected_count` /
+`last_rejected_at` (429s answered — a 429 serves nothing, so it is not a
+request), `organization_id` (the organization the token belongs to, learned
+from its responses and written to the record with its next refresh), `shares_window_with` (aliases whose last
+reading names the same live window — one subscription under several aliases,
+see [One subscription under two aliases](./multi-account-pool.md#one-subscription-under-two-aliases)),
+and `consecutive_auth_failures`. What each `status` means and what
+to do about it: [Reading a seat's `status`](./multi-account-pool.md#reading-a-seats-status).
+It's the admin-token-gated equivalent of the proxy-key-gated `GET /accounts`
+pool view; a headless operator needs only the admin token to watch headroom.
+Completing a login for an alias that is already in the pool re-grants it: the
+seat starts fresh — no carried-over rejection, cool-down or identity.
 
 ## Pinning a request to one seat
 

package/docs/configuration.md

@@ -41,6 +41,16 @@ Halts the proxy when an upstream response reports `representative-claim: overage
 | `DARIO_MAX_CONCURRENT` | `--max-concurrent=N` | `10` | in-flight ceiling |
 | `DARIO_MAX_QUEUED` | `--max-queued=N` | `128` | buffered waiting for a slot; over this, dario returns 429 `queue-full` |
 | `DARIO_QUEUE_TIMEOUT_MS` | `--queue-timeout=MS` | `60000` | a queued request waiting longer gets 504 `queue-timeout` |
+| `DARIO_MAX_CONCURRENT_PER_CONSUMER` | `--max-concurrent-per-consumer=N` | `0` (off) | in-flight ceiling per consumer, keyed by the `x-dario-consumer` request header; a consumer at the cap waits in the queue while everyone else keeps flowing. See [Consumers](./multi-account-pool.md#consumers-who-a-request-is-for) |
+
+## Multi-instance
+
+| Variable | Flag | Default | Notes |
+|---|---|---|---|
+| `DARIO_REFRESH_LOCK_URL` | — | unset | refresh-lock service; unset = single-instance behaviour. See [multi-instance.md](./multi-instance.md) |
+| `DARIO_REFRESH_LOCK_TOKEN` | — | unset | bearer for the lock service |
+| `DARIO_POOL_SHARED_STATE` | `--pool-shared-state` | off | share rate-limit readings and sticky bindings with the other instances through the lock service; fails open |
+| `DARIO_POOL_SHARED_STATE_INTERVAL_MS` | `--pool-shared-state-interval=MS` | `2000` | how often to pull peers' readings |
 
 ## Template fidelity
 

package/docs/integrations/openclaw-walkthrough.md

@@ -8,7 +8,7 @@ This is opinionated. There are several ways to wire OpenClaw to dario; this is t
 
 - OpenClaw running locally, talking to dario at `localhost:3456`
 - All Claude API calls routed through your Pro / Max subscription via the Claude Code wire shape
-- OpenClaw's tool schema (`exec`, `process`, `web_search`, `web_fetch`, `browser`, `message`) auto-translated to CC's canonical set on the outbound path and rebuilt back on the inbound path — **no flag required**
+- OpenClaw's tool schema (`exec`, `process`, `web_search`, `web_fetch`, `browser`) auto-translated to CC's canonical set on the outbound path and rebuilt back on the inbound path — **no flag required**; a tool outside the map (`message`, for one) rides a fallback slot
 - Your `openclaw.inbound_meta.v1` namespace stripped at the proxy boundary so Anthropic's billing classifier doesn't flip you to extra-usage
 - `dario doctor --usage` showing the OpenClaw traffic in your 5-hour bucket with `claim=five_hour (subscription)`
 
@@ -134,7 +134,7 @@ Watch the dario terminal — you should see one log line per request, looking li
 ...
 ```
 
-If you see `→ 200` lines and OpenClaw is making progress, you're good. dario's `client: 'unknown-non-cc'` structural fallback is silently auto-translating OpenClaw's `exec` / `process` / `web_search` / `web_fetch` / `browser` / `message` tools to CC's canonical set on the outbound path and rebuilding the OpenClaw shape on the inbound path — no flag, no config.
+If you see `→ 200` lines and OpenClaw is making progress, you're good. dario's `client: 'unknown-non-cc'` structural fallback is silently auto-translating OpenClaw's `exec` / `process` / `web_search` / `web_fetch` / `browser` tools to CC's canonical set (anything outside the map, `message` included, rides a fallback slot) on the outbound path and rebuilding the OpenClaw shape on the inbound path — no flag, no config.
 
 ## Verifying subscription billing (the important part)
 

package/docs/multi-account-pool.md

@@ -91,6 +91,45 @@ curl http://localhost:3456/accounts     # per-account utilization, claim, sticky
 curl http://localhost:3456/analytics    # per-account / per-model stats, burn rate, exhaustion predictions
 ```
 
+## Reading a seat's `status`
+
+`GET /accounts` (and the admin API's `GET /admin/accounts`, in snake_case) report one `status` per seat. It is the routing verdict, and every value comes with the fields that explain it.
+
+| `status` | What it means | What to do |
+|---|---|---|
+| `allowed` | The seat's last response was a 200 with headroom. `util5h` / `util7d` are that response's reading — a ratio against 1.0, so `0.42` is 42% — `lastObservedAt` / `utilAgeMs` say how old it is, `resetAt` / `resetInMs` when its representative window rolls. | Nothing. |
+| `rejected` | The seat's last response was a 429: the organization behind its token is over the window named by `claim` (`five_hour`, `seven_day`, …). `util5h: 1.04` is 104% of the five-hour window, not 1%. `rejectedCount` / `lastRejectedAt` say the seat was tried — a 429 serves nothing, so `requestCount` does not move — and `resetInMs` says how long it stays parked. Requests route around it; it returns on its own when the window rolls. | Nothing — the window clears itself. If the reading surprises you (your usage page for that account says 0%), the token belongs to a different organization than the page you are looking at, or to the same organization as another seat: the reading is Anthropic's own, taken on that token. `dario accounts check <alias>` asks the seat directly. |
+| `unknown` | No current observation: a seat that has served nothing yet, or a rejection whose window has rolled (`resetInMs: 0`) and that nothing has measured since. | Nothing; the next request measures it. |
+| `auth-cooldown` | Upstream answered 401/403 or `invalid_grant`. `consecutiveAuthFailures` tells a blip (1) from a dead refresh token (a streak); the cool-down doubles with the streak, from 1 minute to 30. | A streak means re-grant the seat — `dario accounts remove` + `add`, or the admin login flow under the same alias. A new grant starts the seat fresh: no carried-over cool-down, rejection or identity. See [Refresh-token grant age](#refresh-token-grant-age) for the 28-day wall behind most streaks. |
+
+The proxy logs every parking as it happens, once per window: `rate limited (429) on account "spare": 5h 104%, 7d 25%, claim five_hour, resets in 37m — parked until the window rolls`. The re-probes the all-exhausted fallback makes of an already-parked seat are logged only under `-v`.
+
+`dario accounts list --live` prints the same view from the running proxy — status with its countdown, the reading and its age, requests served and 429s answered, the organization, shared windows, grant age — where the plain `dario accounts list` only knows what is on disk.
+
+## One subscription under two aliases
+
+A pool of six is only six windows if the six tokens belong to six subscriptions. Two aliases granted from the same account — or from two accounts on one organization that share a plan — share one five-hour and one seven-day window, and the pool counts that window twice: both seats look like headroom, the busier one fills the window for both, and the other 429s on its first request with the same reading (the #1244 report).
+
+Two facts make this visible:
+
+- **`organizationId`** — the `anthropic-organization-id` every response carries, learned the first time a seat serves and written to its record with the seat's next token refresh. It is what to compare with the organization behind the usage page you are looking at: a reading that surprises you is usually a token on a different organization.
+- **`sharesWindowWith`** — the other aliases whose last reading names the same live window (same representative claim, same reset second). Two independent windows all but never share a reset second; two readings of one window always do. This is the fact that matters for headroom, and it is deliberately not derived from the organization: seats on one organization can still have their own windows.
+
+Both are on `GET /accounts` (`distinctWindows` at the top counts the windows the pool really has), on `GET /admin/accounts` as `organization_id` / `shares_window_with`, in `dario accounts list --live`, and in `dario doctor` (the `Organizations` row, from the ids on the records — so up to one refresh behind the running proxy). The proxy also says it once, when the second reading arrives: `seats "twin" and "busy" report the same five_hour window (resets 2026-09-07T13:12:00.000Z) — one subscription under two aliases; the pool has 2 distinct windows across 3 seats`.
+
+What to do about it: nothing is broken — the pool routes on real headroom either way, and the duplicate seat simply parks on the first 429 until the window rolls. If the second alias was meant to be a second subscription, re-grant it while signed in to the right account.
+
+## Consumers: who a request is for
+
+A pool shared by a team serves several people through one `DARIO_API_KEY`, and until now nothing said whose traffic went where. A request can now name its consumer, and dario attributes and, optionally, paces by it:
+
+- **`x-dario-consumer: <name>`** — one printable token, up to 64 characters, no spaces. Set it per user in whatever fronts dario (LiteLLM's per-key headers, a reverse proxy, the client itself). This is the name the per-consumer cap keys on.
+- **Without the header**, attribution falls back to a hash of the body's user id: the Anthropic `metadata.user_id` (Claude Code sends `user_<hash>_account_<uuid>_session_<uuid>`; the session part is dropped, so one person is one key across sessions) or the OpenAI `user` field. The key is `u_` plus twelve hex characters — no account id or raw user id becomes an analytics key. The fallback is attribution only: the body is parsed after the concurrency slot is taken, so only the header can pace.
+
+Where it shows: `GET /analytics` gains `perConsumer` (requests, tokens, cache share, estimated cost, the seats the consumer landed on, last model) next to `perAccount`; every request log line and the `-v` usage line carry `consumer`; the TUI's Hits tab shows it on the selected request.
+
+**Fairness.** `--max-concurrent-per-consumer=N` (`DARIO_MAX_CONCURRENT_PER_CONSUMER`) caps in-flight requests per named consumer. A consumer at the cap waits in the queue while slots are free for everyone else; when a slot frees, the first waiter whose consumer is under its cap is admitted, so one heavy user's backlog never holds up another user's next turn. Requests that name no consumer are never capped. Off by default — the plain `--max-concurrent` ceiling still applies to everyone together.
+
 Every request carries a `billingBucket` field (`subscription` / `subscription_fallback` / `extra_usage` / `api` / `unknown`) so you can see which bucket each request billed against and a `subscriptionPercent` headline number tells you at a glance whether dario is actually routing through your subscription or silently falling to API overage.
 
 ## Refresh-token grant age

package/docs/multi-instance.md

@@ -1,6 +1,6 @@
 # Running more than one dario against the same accounts
 
-Short answer: **you can share credentials safely between instances, but dario is not HA.** Those are different claims, and the difference matters before you scale a Deployment to 2.
+Short answer: **you can share credentials safely between instances, and with shared pool state on they also share what they know about the seats.** dario is still not a consensus system; the difference matters before you scale a Deployment to 2.
 
 This page covers what actually breaks with two instances, which part is solved, how to turn the fix on, and how to prove it works on your own infrastructure.
 
@@ -20,18 +20,22 @@ Two instances holding the same account both notice the token is near expiry, and
 
 A plain mutex does not fix this. The loser waits, acquires the lock, and then refreshes with a token that is *already* stale — it just loses more slowly. The fix is that the loser **adopts the winner's fresh credentials** instead of attempting its own. That is what dario's refresh lock does.
 
-### 2. Rate-limit accounting — **not solved**
+### 2. Rate-limit accounting — **solved with shared state**
 
 `pool.ts` keeps `accounts: Map<string, PoolAccount>` in process memory, and updates it only from rate-limit headers on responses *that instance* saw.
 
-Two instances sharing an account each believe it has full headroom. Both route to it. Neither can see what the other is spending, so the pool overshoots the real 5-hour and 7-day windows and starts getting rejections it did not predict. Adding instances makes this worse, not better.
+Two instances sharing an account each believe it has full headroom. Both route to it. Neither can see what the other is spending, so the pool overshoots the real 5-hour and 7-day windows and starts getting rejections it did not predict — and each instance eats its own 429 to learn what the other already knew.
 
-### 3. Session stickiness — **not solved**
+With `--pool-shared-state` every instance reports each reading it takes to the lock service and pulls the others' every two seconds, adopting any reading newer than its own. A 429 taken on one instance parks the seat on all of them within a pull; the listings say whose reading a seat carries (`readingFrom`), and `rejectedCount` stays each instance's own. The accounting is eventually consistent — a pull interval behind, never ahead — which is what makes it approximate rather than wrong.
+
+### 3. Session stickiness — **solved with shared state**
 
 `computeStickyKey()` hashes the first user message and pins that conversation to one account, so its prompt cache stays warm. The binding lives in process memory.
 
 With two instances behind one Service, the same conversation can land on either, and get a different account each time. The prefix is re-cached per account, so you pay cache writes instead of reads. See [`docs/multi-account-pool.md`](./multi-account-pool.md) for why that costs real money.
 
+With `--pool-shared-state` a binding made on one instance is published, and an instance that sees a conversation it holds no binding for asks the service before choosing — so the second turn of a conversation that started on the other replica reads the cache the first turn wrote. Failover rebindings are published the same way.
+
 ---
 
 ## So what should you actually run?
@@ -40,8 +44,8 @@ With two instances behind one Service, the same conversation can land on either,
 |---|---|
 | Zero-downtime restarts / rolling deploys | Two instances **with the refresh lock**. Brief overlap is fine; the credential race is the only thing that corrupts state, and the lock covers it. |
 | More throughput from more accounts | **One instance, more accounts in the pool.** The pool is the horizontal-scaling mechanism; a second instance is not. |
-| Survive a node failure | Two instances with the lock, and accept that rate-limit accounting is approximate while both are live. |
-| Precise rate-limit accounting | One instance. There is no shared-state mode today. |
+| Survive a node failure | Two instances with the lock and shared pool state; accounting is a pull interval behind while both are live. |
+| Precise rate-limit accounting | One instance. Shared state is eventually consistent (a pull interval behind), not exact. |
 
 dario starts in well under a second, so for most people a single replica with a sensible `restartPolicy` is the honest answer — which is roughly where [#993](https://github.com/askalf/dario/issues/993) landed too.
 
@@ -90,6 +94,23 @@ The lock is resilience layered on top of dario's job, not a new dependency dario
 
 ---
 
+## Turning shared pool state on
+
+Same service, same two variables, one more switch on every instance:
+
+```
+DARIO_REFRESH_LOCK_URL=http://<lock-host>:8080
+DARIO_REFRESH_LOCK_TOKEN=<shared secret>
+DARIO_POOL_SHARED_STATE=1            # or: dario proxy --pool-shared-state
+DARIO_POOL_SHARED_STATE_INTERVAL_MS=2000   # optional; how often to pull peers' readings
+```
+
+Both reference backends serve the three extra endpoints (`/pool/seat/<alias>`, `/pool/seats`, `/pool/sticky/<key>/{bind,get}`); redeploy the one you run. What crosses the wire is rate-limit snapshots, aliases and hashed sticky keys — no token, no message content.
+
+The proxy says what it is doing at startup (`Pool shared state: on (instance …, via …, pulling peers every 2000ms; fails open)`), `GET /accounts` carries a `sharedState` block (instance id, last pull, readings adopted and reported, bindings pushed and adopted, errors), and each seat says whose reading it holds in `readingFrom`. A seat parked on a peer's 429 is logged on every instance: `seat "busy" parked by peer <id>'s reading: 5h 104%, 7d 25%, claim five_hour, resets in 37m`.
+
+It fails open like the lock: an unreachable service is one log line per outage and each instance carries on with its own state until the service answers again.
+
 ## Proving it works on your own setup
 
 Do not take the above on trust. `test/integration/dual-instance-race.mjs` runs the real scenario: **two genuinely separate `node` processes**, each with its own isolated `~/.dario`, sharing nothing but the lock service, both racing to refresh the same account at the same instant.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@askalf/dario",
-  "version": "6.0.32",
-  "description": "Use your Claude Pro/Max subscription in any tool — Cursor, Cline, Aider, the Agent SDK, your scripts — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint.",
+  "version": "6.0.34",
+  "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, with automatic failover when one hits its limit.",
   "type": "module",
   "bin": {
     "dario": "./dist/cli.js"
@@ -41,28 +41,34 @@
     "cch:calibrate": "node scripts/cch-calibrate.mjs",
     "fix:pkg": "node -e \"const fs=require('fs');fs.writeFileSync('package.json',JSON.stringify(JSON.parse(fs.readFileSync('package.json','utf-8')),null,2)+'\\n')\"",
     "audit:tui": "node tools/tui-audit/audit.mjs",
-    "readme:assets": "node scripts/readme/hero.mjs && node scripts/readme/terminal.mjs && node scripts/readme/tui.mjs",
+    "readme:assets": "node scripts/readme/terminal.mjs && node scripts/readme/tui.mjs",
     "check:readme": "node scripts/check-readme-line-count.mjs && node scripts/check-readme-links.mjs"
   },
   "keywords": [
     "llm",
     "llm-router",
+    "llm-proxy",
     "multi-provider",
     "openai-compat",
     "openai",
-    "openrouter",
-    "groq",
-    "litellm",
-    "ollama",
+    "chatgpt",
+    "codex",
     "claude",
     "anthropic",
-    "oauth",
-    "proxy",
-    "api",
-    "subscription",
+    "claude-code",
     "claude-max",
     "claude-pro",
-    "ai",
+    "subscription",
+    "oauth",
+    "proxy",
+    "cursor",
+    "cline",
+    "aider",
+    "agent-sdk",
+    "openrouter",
+    "litellm",
+    "ollama",
+    "groq",
     "cli",
     "developer-tools"
   ],