@askalf/dario 6.16.0 → 6.17.0

package/docs/analytics.md

@@ -8,13 +8,13 @@ Every surface below is a view over those two. Nothing here collects anything new
 
 | path | what | format |
 |---|---|---|
-| `GET /analytics` | window summary + `queue` snapshot + `lifetime` ledger summary | JSON |
-| `GET /analytics/ledger` | the ledger's per-day table | JSON |
+| `GET /analytics` | window summary (with `window.perFiveMinutes`, the hour in twelve bins) + `queue` snapshot + `overage` (the halt state, for a reader who cannot open `/admin/resume`) + `lifetime` ledger summary | JSON |
+| `GET /analytics/ledger` | the ledger's per-day table, with `priced`: the same rows as USD at each day's rate | JSON |
 | `GET /analytics/stream` | live tail of request records (drives the TUI) | SSE |
 | `GET /metrics` | the same state as Prometheus text exposition | text/plain 0.0.4 |
 | `GET /analytics/donuts.svg` | spend by model / by key / by billing | SVG |
-| `GET /analytics/view` | server-rendered dashboard body | HTML fragment |
-| `GET /analytics/ui` | the dashboard shell (no data; asks for the token, loads `/view` every 60 s) | HTML page |
+| `GET /analytics/view` | the server-rendered summary (the page before 6.17; still served) | HTML fragment |
+| `GET /analytics/ui` | the dashboard (no data of its own; asks for the token, then reads the routes above, `/accounts`, `/codex` and `/health` with it and tails `/analytics/stream`) | HTML page |
 
 CLI: `dario usage` prints the ledger; `--json` dumps `/analytics`; `--card[=file]` writes the share card; `--donut[=file]` writes the three rings.
 
@@ -24,7 +24,7 @@ By default the proxy binds loopback and these paths need no credential. With `DA
 
 `--analytics-token=<secret>` (or `DARIO_ANALYTICS_TOKEN`) adds a **read-only** credential accepted on exactly the paths in the table above, on `GET` only. It is refused on `/v1/*`, `/accounts`, `/status`, `/admin/*`, and any non-GET. That is the point: a Grafana box or a browser tab can hold the numbers without holding request rights. The root key keeps working on the analytics paths too. On an unkeyed proxy the token gates nothing, and the proxy says so at startup.
 
-`/analytics/ui` itself is served without a credential because it contains no data. It stores the token you type in `sessionStorage` and sends it as a bearer on every fetch of `/analytics/view`.
+`/analytics/ui` itself is served without a credential because it contains no data. It stores the token you type in `sessionStorage` and sends it as a bearer on every read. With the analytics token it shows spend, routing, the live feed and the ledger; the seats panel needs an API key, because `/accounts` and `/codex` refuse the read-only token, and the keys panel needs the admin API (`DARIO_ADMIN=1`, the admin token). The page loads nothing from outside the proxy, follows the system theme (with a toggle), has a table view behind every chart, and opened from disk (`dist/analytics-ui.html`) it runs on sample data.
 
 ## `/metrics` families
 
@@ -35,19 +35,21 @@ Names ending in `_total` are counters; everything else is a gauge. Labels are es
 | `dario_info` | `version` | always 1 |
 | `dario_requests_total`, `dario_tokens_total{kind}`, `dario_estimated_cost_usd_total`, `dario_error_rate` | `kind` ∈ input, output, cache_read, cache_create, thinking | since start |
 | `dario_window_requests`, `_avg_latency_ms`, `_error_rate`, `_cached_prompt_percent`, `_estimated_cost_usd` | `window_minutes` | rolling window |
-| `dario_window_billing_requests` | `bucket` ∈ subscription, subscription_fallback, extra_usage, api, unknown | claims folded by `billingBucketFromClaim` |
+| `dario_window_billing_requests` | `bucket` ∈ subscription, subscription_fallback, extra_usage, api, credits, unknown | claims folded by `billingBucketFromClaim` |
 | `dario_account_requests_total`, `dario_account_estimated_cost_usd`, `dario_account_utilization{window}` | `account`, `window` ∈ 5h, 7d | last rate-limit headers per seat |
 | `dario_model_requests_total`, `dario_model_estimated_cost_usd` | `model` | since start |
 | `dario_consumer_requests_total`, `dario_consumer_estimated_cost_usd` | `consumer` (named key or `x-dario-consumer`) | since start |
-| `dario_queue_active`, `_queued`, `_max_concurrent`, `_max_queued`, `_stalled`, `_max_wait_ms`, `_consumers_active` | — | request queue |
+| `dario_queue_active`, `_queued`, `_max_concurrent`, `_max_queued`, `_stalled`, `_max_wait_ms`, `_consumers_active` | (none) | request queue |
 | `dario_request_latency_ms{quantile}` + `_sum`, `_count` | `quantile` ∈ 0.5, 0.9, 0.99 | nearest-rank over the most recent 1,000 records |
 | `dario_queue_wait_ms`, `dario_pacing_wait_ms`, `dario_upstream_ttfb_ms`, `dario_upstream_latency_ms`, `dario_overhead_ms` — each `{quantile}` + `_sum`, `_count` | `quantile` ∈ 0.5, 0.9, 0.99 | the timing split (below), nearest-rank over the recent records that carry one |
 | `dario_window_avg_upstream_ttfb_ms`, `_avg_upstream_latency_ms`, `_avg_overhead_ms`, `_avg_queue_wait_ms`, `_avg_pacing_wait_ms` | `window_minutes` | the split averaged over the rolling window; omitted until a request has carried one |
-| `dario_predicted_exhaustion_minutes` (omitted when unknown), `dario_burn_tokens_per_minute`, `dario_burn_cost_usd_per_minute` | — | window predictions |
+| `dario_predicted_exhaustion_minutes` (omitted when unknown), `dario_burn_tokens_per_minute`, `dario_burn_total_tokens_per_minute`, `dario_burn_cost_usd_per_minute` | (none) | window predictions |
 | `dario_ledger_requests_total`, `_api_equivalent_usd`, `_metered_usd`, `_recent_api_equivalent_usd{window}`, `_model_api_equivalent_usd{model,provider}`, `_model_requests_total{model,provider}`, `_consumer_api_equivalent_usd{consumer}` | `window` ∈ today, 7d, 30d | ledger (absent when the ledger is off) |
 
 `dario_request_latency_ms` is the number dario has always kept: dispatch to response end, as the client saw it. Since 6.9 every request also carries the split below, so the one figure can be read as its parts.
 
+The two token burn gauges differ in scope: `dario_burn_tokens_per_minute` is input and output only, cache reads and writes are not in it, while `dario_burn_total_tokens_per_minute` counts every kind. On a cached prompt the second is many times the first. `/analytics` carries the same pair as `predictions.tokenBurnRate` and `predictions.totalTokenBurnRate`.
+
 ## The timing split
 
 A request's wall-clock time through dario is five stamps (`src/timing.ts`), all in milliseconds, all on dario's clock:

package/docs/api-equivalent-spend.md

@@ -36,7 +36,10 @@ Two columns per row:
 - **metered** — billed per token anyway: an API key upstream (`api`) or
   Anthropic's paid overage (`overage` → `extra_usage`). That money was spent.
   It is reported on its own line ("Paid per token on top") and never counted
-  as saved.
+  as saved. The credits rung of the failover chain (`credits:<model>`) lands
+  in this column too: those credits were spent. The ledger keeps the two
+  columns only; the rolling window and the dashboard tell credits, API key
+  and extra usage apart.
 
 A mid-stream continuation (6.1) is two upstream requests and records as two
 rows, one per provider, each with the tokens that leg actually consumed.
@@ -124,7 +127,11 @@ by the anonymous traffic.
 ```
 
 `GET /analytics/ledger` is the file itself: `{ path, version, since, updated,
-days: { "YYYY-MM-DD": { "<model>": { covered: {…}, metered: {…} } } } }`.
+days: { "YYYY-MM-DD": { "<model>": { covered: {…}, metered: {…} } } } }`, plus
+`priced`, the same rows as money: `{ days: { "YYYY-MM-DD": { "<model>": {
+covered: 1.23, metered: 0.04 } } }, consumers: {…} }`, each bucket priced at
+that day's rate by the function the summary uses, so a reader charting the
+table (the dashboard, a script) needs no price list of its own.
 
 ## Pricing on the ChatGPT leg
 

package/docs/faq.md

@@ -30,6 +30,11 @@ Two questions to verify at any time — and the exact check to run the day a rev
 
 No config change is needed on the user side, split or no split — same install, same `localhost:3456`, same `ANTHROPIC_BASE_URL=http://localhost:3456` env var.
 
+**Max plans now include monthly API credits. Do I still need dario?**
+Since October 2026 a Max 5x plan includes $100 of Claude API credits a month and Max 20x includes $200 ([Monthly API credits for Max and Team plans](https://support.claude.com/en/articles/17154008)). They are spent through a Console API key on the Claude API and the Agent SDK, not in Claude Code, they expire at the end of each billing cycle, and when they are gone API requests stop. Your seat's own five-hour and weekly windows are a different bucket, and Anthropic's note on the change says third-party apps may still use them ([the October 7 update](https://support.claude.com/en/articles/15036540)). dario is how every tool draws on the seat first, so the credits are not the only thing between you and a meter. Run `dario usage` for a week: the API-equivalent figure is what your seat absorbed, and the comparison with $100 or $200 is yours to make.
+
+The credits can be the last rung of the failover chain. Put the Console key in `DARIO_CREDITS_API_KEY` and name the rung in the chain, `--pool-fallback=credits:claude-sonnet-5`: when every seat is parked, the request goes to the Claude API on that key as a plain API request, both wire shapes, the response says `x-dario-pool-fallback: credits:claude-sonnet-5`, `/analytics` and the dashboard show it under its own bucket, `credits`, and the ledger counts it as metered, so the receipt stays honest ([failover](./two-plans.md#failover-between-subscriptions)). A metered openai-compat backend can be a rung the same way, shown under API key. Neither is on until you name it.
+
 **Do I need Claude Code installed?**
 Recommended for the Claude backend, not strictly required. With CC installed, `dario login` picks up your credentials automatically, and the live template extractor reads your CC binary on every startup so the template stays current. Without CC, dario runs its own OAuth flow and falls back to the bundled template snapshot (scrubbed of host context at bake time as of v3.21). Drift detection warns you if your installed CC doesn't match the captured template, so upgrade windows don't silently ship stale templates.
 

package/docs/multi-account-pool.md

@@ -204,7 +204,7 @@ Where it shows: `GET /analytics` gains `perConsumer` (requests, tokens, cache sh
 
 **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.
+Every request carries a `billingBucket` field (`subscription` / `subscription_fallback` / `extra_usage` / `api` / `credits` / `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/pool-keys-and-analytics.md

@@ -73,6 +73,8 @@ The rolling window forgets on every restart; the **ledger** does not. Since 6.6
 
 Only served requests count. Traffic that was metered anyway — an API key upstream, or Anthropic's paid `extra_usage` overage — is kept in its own column and reported as spent, not saved. `dario usage --card` writes the headline as a 640×320 SVG you can drop in a README or a post, and `--donut` writes the same number as three rings — by model, by key, subscription vs metered; `--no-ledger` / `DARIO_LEDGER=0` turns the file off, `DARIO_LEDGER_PATH` moves it, and `GET /analytics/ledger` is the per-day table behind the number. Details: [api-equivalent-spend.md](api-equivalent-spend.md).
 
+A request served on a Max plan's API credits (the `credits:<model>` rung of the failover chain, key in `DARIO_CREDITS_API_KEY`, [failover](two-plans.md#failover-between-subscriptions)) is counted as spent the same way in the ledger; `/analytics`, `/metrics` and the dashboard show it under its own bucket, `credits`.
+
 **Scrape it, or open it.** `GET /metrics` is the same state as Prometheus text exposition — window, seats, models, consumers, queue, latency quantiles, burn rates, ledger — so Grafana reads dario like anything else. Since 6.9 every request also carries its **timing split**: queue wait, governor sleep, the provider's time to first byte, the provider's total, and what is left — dario's own overhead — as `x-dario-*-ms` response headers on the request itself, as `window.timing` on `/analytics`, and as five more `/metrics` families, so "was that Anthropic or the proxy?" is a `curl -i` away ([details](analytics.md#the-timing-split)). `GET /analytics/ui` is a self-contained dashboard page with the headline, the rings and the tables, refreshing every minute. Both sit behind the same gate as `/analytics`; `--analytics-token` (env `DARIO_ANALYTICS_TOKEN`) adds a **read-only** credential accepted on those paths and nowhere else, so a scraper or a browser can hold the numbers without holding request rights. Families and the gate: [analytics.md](analytics.md).
 
 ---

package/docs/two-plans.md

@@ -44,6 +44,8 @@ That is a **chain**, read left to right; each provider takes the first entry it
 
 A single-entry chain is one-way and means what it always meant, so an existing config is unaffected. Failover is opt-in: without `--pool-fallback`, a drained pool still returns its honest 429/503. Only a **429 or 5xx** fails over; a 400 surfaces, because a bad request that fails over just reproduces itself on the other provider and buries the real cause. A 429 also cools that provider for a bounded interval, its `retry-after` if it sent one and 60 s otherwise, never longer than 15 min, and an entry that already declined is not asked again within the same request. When every entry is cooling, the request ends on one honest `429` with a `retry-after` instead of a retry storm. The Claude entry has to be a model the pool can actually serve, checked positively against the live catalog, so a typo can't trade a recoverable 429 for an unrecoverable 404.
 
+An entry written `credits:<model>` is a rung on the API credits a Max plan includes ($100 a month on Max 5x, $200 on Max 20x, spent through a Console key). It is opt-in twice: the entry has to be in the chain, and the key has to be in `DARIO_CREDITS_API_KEY` (env only, never a flag, so it never lands in argv). When every seat is drained or cooling and no subscription rung can serve, the request goes to `api.anthropic.com` on the Messages path as a plain API request: the client's own body with the model swapped, `x-api-key`, no Claude Code template and no OAuth beta. Both wire shapes work, since the Claude path already translates OpenAI-shape requests. The response says `x-dario-pool-fallback: credits:<model>`. The rolling window, `/metrics` and the dashboard file the request under its own billing bucket, `credits`, next to extra usage and API key; the persistent ledger counts it in its metered total, as spent, the way it counts an API key. The overage guard does not halt on it: a rung you configured is not a surprise bill. A subscription rung always goes first; between the credits rung and an openai-compat backend, the chain's own left-to-right order decides. Tier maps take it too (`opus:credits:claude-opus-5`). Without the key the entry is inert, the startup line says so and `dario doctor` says so in its Failover line.
+
 The chain also covers a stream that dies **mid-answer**. Until 6.1 that was the one failure nothing could catch: bytes were on the wire, so the socket reset, the in-band `overloaded_error`, the codex `response.failed` all ended the stream where they happened, with no `message_stop`, and the client threw away every word it already had. Now dario finishes the same stream — on the same model first, a fresh request through its own front door; on the other subscription when that delivers nothing or dies too. The resume picks up inside the still-open content block, a comment marks each seam (`: dario continuation claude-opus-5 (same model) after 1240 chars`), and the client sees one message. The model is asked to repeat the last few words verbatim and dario trims the repeat, so the join is rendered by a model and cut by a parser, never guessed. Text only — a cut inside a tool call ends as it always did. On by default, `--no-midstream-continue` turns it off; without a chain the second hop is simply not there. [How it works](midstream-continuation.md).
 
 `dario doctor` tells you which of these you are actually in:

package/docs/who-its-for.md

@@ -1,10 +1,10 @@
 # Who it's for
 
-**Best fit:** developers juggling multiple LLM tools and per-tool API keys · Claude Pro/Max subscribers who want their plan usable everywhere, not just in Claude Code · ChatGPT Plus/Pro subscribers who want their plan in OpenAI-compatible harnesses · teams running local or hosted OpenAI-compat servers who want one stable local endpoint · Agent SDK users who want subscription routing with zero code change · power users wanting multi-account pooling with 429 failover.
+**Best fit:** developers juggling multiple LLM tools and per-tool API keys · Claude Pro/Max subscribers who want their plan usable everywhere, not just in Claude Code · ChatGPT Plus/Pro subscribers who want their plan in OpenAI-compatible harnesses · teams running local or hosted OpenAI-compat servers who want one stable local endpoint · Agent SDK users who want subscription routing with zero code change · power users wanting multi-account pooling with 429 failover · anyone who wants one number for what their plans absorbed across every tool.
 
 **Not a fit:** you need vendor-managed production SLAs (use the provider APIs) · you want a hosted multi-tenant team platform with dashboards and SSO (dario is a single-owner local proxy) · you want a chat UI (use claude.ai).
 
-**How it compares.** Only one of these routes a consumer subscription; the others route API keys, and that is the whole split.
+**How it compares.** Only one of these routes a consumer subscription and prices every request against the API rate card; the others route API keys, and that is the whole split.
 
 | Tool | What it is | When it wins |
 |---|---|---|

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@askalf/dario",
-  "version": "6.16.0",
-  "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.",
+  "version": "6.17.0",
+  "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, opt-in failover when one hits its limit, and a ledger of what each plan absorbed.",
   "type": "module",
   "bin": {
     "dario": "./dist/cli.js"
@@ -22,7 +22,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc && cp src/cc-template-data.json dist/",
+    "build": "tsc && cp src/cc-template-data.json src/analytics-ui.html dist/",
     "test": "node --test test/all.test.mjs",
     "test:serial": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/tool-schema-contract.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/pool-sticky.mjs && node test/live-fingerprint.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/subagent.mjs && node test/mcp-protocol.mjs && node test/mcp-tools.mjs && node test/mcp-e2e.mjs && node test/session-rotation.mjs && node test/drift-detection.mjs && node test/cc-authorize-probe-classifier.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/doctor-identity-drift.mjs && node test/doctor-oauth-pool.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/durable-token-persist.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs && node test/context-bleed.mjs && node test/passthrough-header-forwarding.mjs && node test/capture-provenance.mjs && node test/sanitize-messages.mjs && node test/platform-tools.mjs && node test/strict-template-flags.mjs && node test/request-queue.mjs && node test/effort-flag.mjs && node test/template-invariants.mjs",
     "audit": "npm audit --production --audit-level=high",
@@ -71,7 +71,11 @@
     "ollama",
     "groq",
     "cli",
-    "developer-tools"
+    "developer-tools",
+    "usage-ledger",
+    "dashboard",
+    "api-credits",
+    "rate-limits"
   ],
   "author": "askalf (https://github.com/askalf)",
   "license": "MIT",