@askalf/dario 6.19.1 → 6.20.0

package/dist/proxy.js

@@ -21,7 +21,7 @@ import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCo
 import { backfillIdentity } from './accounts.js';
 import { PoolSync, DEFAULT_POOL_SYNC_INTERVAL_MS } from './pool-sync.js';
 import { AccountSync, DEFAULT_ACCOUNT_SYNC_INTERVAL_MS } from './account-sync.js';
-import { Analytics, billingBucketFromClaim, costOfTokensFailClosed, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, CODEX_CLAIM, CREDITS_CLAIM } from './analytics.js';
+import { Analytics, billingBucketFromClaim, costOfTokensFailClosed, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, thinkingTokensFromUsage, CODEX_CLAIM, CREDITS_CLAIM } from './analytics.js';
 import { Ledger, resolveLedgerPath, ledgerDisabledByEnv } from './ledger.js';
 import { renderPrometheus } from './metrics.js';
 import { renderSpendDonuts, renderAnalyticsView, analyticsUiPage } from './donuts.js';
@@ -36,7 +36,8 @@ import { createTokenBucket } from './rate-limit.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI, isMiniMaxBackend, MINIMAX_MODELS } from './openai-backend.js';
 import { forwardToCodex, forwardResponsesToCodex, getCodexModelSlugs, peekCodexModelSlugs, isCodexModel, pickCodexFallback, pickClaudeTarget, CODEX_BACKEND_BASE_URL } from './codex-backend.js';
 import { formatCacheTraceLine } from './cache-trace.js';
-import { effortForCodex } from './effort.js';
+import { effortForCodex, requestNamesEffort, withResponsesEffort } from './effort.js';
+import { thinkingToReasoningEffort } from './anthropic-responses-translate.js';
 import { MidstreamGuard, guardFor, loopbackBaseFor, chaosCutFetch, chaosCutState, CONTINUATION_HEADER, CONTINUATION_OF_HEADER, MAX_CONTINUATION_DEPTH, continuationDepth, continuationOfRequest } from './midstream.js';
 /**
  * The continuation fields for a request's analytics row, from its guard.
@@ -2646,7 +2647,7 @@ export async function startProxy(opts = {}) {
      * account, an unreadable one, or a `poolFallbackModel` that account does not
      * list all mean "not mine to serve".
      *
-     * Works for BOTH wire shapes, which is the point: forge's agents and Claude
+     * Works for BOTH wire shapes, which is the point: SDK-engine agents and Claude
      * Code speak Anthropic, and before v5.5.87 they had nowhere to fail over to
      * and simply went dark when the Claude pool filled. The substituted model is
      * announced on `x-dario-pool-fallback` exactly as the api-key path does —
@@ -2788,7 +2789,7 @@ export async function startProxy(opts = {}) {
      * versions of this logic, and v6.0.0 wired the fallback into only ONE of
      * them. The other kept returning the raw upstream 429 — and that unwired
      * site is the one reached by every non-passthrough request, i.e. everything
-     * except a literal Claude Code CLI session, forge's SDK Engine included.
+     * except a literal Claude Code CLI session, SDK-engine clients included.
      * That is what left the whole fleet unable to fail over during the live
      * outage on 2026-08-30 while `dario doctor` reported failover armed.
      *
@@ -4351,6 +4352,26 @@ export async function startProxy(opts = {}) {
             // Nothing below is allowed to depend on it: the tee only observes bytes
             // already on their way out, the comparison is never awaited by the
             // request, and every failure path resolves rather than throws.
+            // A named key's default effort (`dario keys create --effort=low`) fills in
+            // when nobody named one: no suffix on the model, no effort field in the
+            // body. --effort / DARIO_EFFORT keeps winning over it, as it does over the
+            // client, and a client that set its own effort is never overruled by a
+            // default. Why this knob is per key: a reasoning model at its default
+            // effort can spend most of its output thinking on work that did not need
+            // it, and the lane that needs the cap is one consumer, not the proxy.
+            // A Responses client names its effort in `reasoning.effort`, which the
+            // translation above turns into a model suffix, so the raw body is read too.
+            const keyDefaultEffort = requestAuth.key?.effort && !requestNamesEffort(parsedBody) && !requestNamesEffort(responsesBodyRaw)
+                ? requestAuth.key.effort : undefined;
+            // The pin outranks a key default only when it names a level. `client`
+            // means "leave the client's choice alone", and a key default exists only
+            // when the client chose nothing, so under `client` the default applies.
+            const pinnedEffort = opts.effort === 'client' && keyDefaultEffort ? undefined : opts.effort;
+            // On the Codex translated route a client's thinking budget IS its effort
+            // choice (it becomes `reasoning.effort` there), so a key default must not
+            // replace it. The proxy pin has never reached the Codex backend.
+            const codexKeyEffort = keyDefaultEffort && thinkingToReasoningEffort(parsedBody?.thinking) === undefined
+                ? keyDefaultEffort : undefined;
             const compareTarget = readCompareTarget(req.headers);
             if (compareTarget) {
                 const compareShape = isOpenAI ? 'openai' : 'anthropic';
@@ -4670,14 +4691,18 @@ export async function startProxy(opts = {}) {
                                 // outage this change exists to remove, surviving on the one shape Codex
                                 // CLI actually speaks (caught in review of #1288).
                                 if (isResponses && responsesBodyRaw) {
-                                    served = await forwardResponsesToCodex(rawRes, { ...responsesBodyRaw, model: rawModel }, codexSeat, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, codexFetch, codexOnDone, codexOnDecline, canDefer || codexPeer !== null, { queueMs, arrivedAt });
+                                    served = await forwardResponsesToCodex(
+                                    // The body as written, plus `reasoning.effort` from the model-name
+                                    // suffix or the named key's default when the client set none.
+                                    rawRes, withResponsesEffort({ ...responsesBodyRaw, model: rawModel }, effortForCodex(requestEffort ?? keyDefaultEffort)), codexSeat, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, codexFetch, codexOnDone, codexOnDecline, canDefer || codexPeer !== null, { queueMs, arrivedAt });
                                 }
                                 else {
                                     served = await forwardToCodex(req, res, body, codexSeat, corsOrigin, SECURITY_HEADERS, upstreamTimeoutMs, verbose, isOpenAI ? 'openai' : 'anthropic', codexFetch, canDefer || codexPeer !== null, codexOnDone, codexOnDecline, 
                                     // dario#1260 — the effort named by the model-name suffix stripped
-                                    // above. Undefined for every request that did not name one, which
-                                    // leaves the outbound body exactly as it was.
-                                    effortForCodex(requestEffort), codexGuard, { queueMs, arrivedAt });
+                                    // above, else the named key's default unless the client's thinking
+                                    // budget already picks one. Undefined for every request that has
+                                    // neither, which leaves the outbound body exactly as it was.
+                                    effortForCodex(requestEffort ?? codexKeyEffort), codexGuard, { queueMs, arrivedAt });
                                 }
                                 if (served || !codexPeer)
                                     break;
@@ -4978,7 +5003,7 @@ export async function startProxy(opts = {}) {
                     sanitizeMessages(client, opts.preserveOrchestrationTags);
                     const r = (isOpenAI ? openaiToAnthropic(client, target.model) : { ...client, model: target.model });
                     r.model = stripContext1mTag(typeof r.model === 'string' ? r.model : target.model);
-                    const effort = requestEffort ?? opts.effort;
+                    const effort = requestEffort ?? pinnedEffort ?? keyDefaultEffort;
                     if (effort) {
                         const oc = (r.output_config && typeof r.output_config === 'object' && !Array.isArray(r.output_config))
                             ? { ...r.output_config }
@@ -5128,7 +5153,7 @@ export async function startProxy(opts = {}) {
                                 hybridTools: opts.hybridTools ?? false,
                                 mergeTools: opts.mergeTools ?? false,
                                 noAutoDetect: opts.noAutoDetect ?? false,
-                                effort: requestEffort ?? opts.effort,
+                                effort: requestEffort ?? pinnedEffort ?? keyDefaultEffort,
                                 maxTokens: opts.maxTokens,
                                 systemPrompt: opts.systemPrompt,
                                 skipFields,
@@ -6210,6 +6235,9 @@ export async function startProxy(opts = {}) {
                 let streamCacheReadTokens = 0;
                 let streamCacheCreateTokens = 0;
                 let streamThinkingChars = 0;
+                // The billed count from message_delta's usage.output_tokens_details,
+                // when upstream sends it; the chars/4 estimate above is the fallback.
+                let streamThinkingTokens;
                 const analyticsDecoder = analytics ? new TextDecoder() : null;
                 let analyticsBuffer = '';
                 // Stream SSE chunks through
@@ -6317,6 +6345,9 @@ export async function startProxy(opts = {}) {
                                         const u = e.usage;
                                         if (u?.output_tokens)
                                             streamOutputTokens = u.output_tokens;
+                                        const billedThinking = thinkingTokensFromUsage(u);
+                                        if (billedThinking !== undefined)
+                                            streamThinkingTokens = billedThinking;
                                     }
                                     else if (e.type === 'content_block_delta') {
                                         // Mirror the non-streaming parseUsage thinking-token
@@ -6422,7 +6453,7 @@ export async function startProxy(opts = {}) {
                         model: requestModel,
                         inputTokens: streamInputTokens, outputTokens: streamOutputTokens,
                         cacheReadTokens: streamCacheReadTokens, cacheCreateTokens: streamCacheCreateTokens,
-                        thinkingTokens: Math.round(streamThinkingChars / 4),
+                        thinkingTokens: streamThinkingTokens ?? Math.round(streamThinkingChars / 4),
                         claim: claimNow(rl), util5h: rl.util5h, util7d: rl.util7d, overageUtil: rl.overageUtil,
                         latencyMs: Date.now() - startTime, status: upstream.status, isStream: true, isOpenAI, timing: timingNow(),
                         continuation: continuationOf(guard, requestDepth),

package/docs/admin-api.md

@@ -94,8 +94,9 @@ All endpoints accept the token as `authorization: Bearer <token>` or
 | `GET /admin/accounts` | — | `{ accounts: [...], count }` |
 | `DELETE /admin/accounts/<alias>` | — | `{ alias, removed }` (`404` if no such alias) |
 | `GET /admin/keys` | — | `{ keys: [...], count, path }` — every named key, hashes excluded (v6.8) |
-| `POST /admin/keys` | `{ "name": string, "seat"?: string, "models"?: string[] \| "a,b", "expires"?: "30d" \| ISO }` | `201 { key, secret }` — the secret once; `409` if the name exists |
+| `POST /admin/keys` | `{ "name": string, "seat"?: string, "models"?: string[] \| "a,b", "expires"?: "30d" \| ISO, "effort"?: "low" \| "medium" \| "high" \| "xhigh" \| "max" }` | `201 { key, secret }`, the secret shown once; `409` if the name exists |
 | `POST /admin/keys/<name>/rotate` | — | `{ key, secret }` — a new secret, the old one dead at once (`404` if unknown) |
+| `POST /admin/keys/<name>/effort` | `{ "effort": "low" \| "medium" \| "high" \| "xhigh" \| "max" \| null }` | `{ key }` (`404` if unknown); null or absent clears the default |
 | `DELETE /admin/keys/<name>` | — | `{ name, revoked }` — refused from now on, kept in the list (`404` if unknown) |
 
 The three `/admin/keys` mutations edit the same `~/.dario/keys.json` that

package/docs/configuration.md

@@ -93,9 +93,10 @@ Off by default, each one a deliberate divergence from what real CC sends.
 
 ### Per-request effort, by model name
 
-`DARIO_EFFORT` is process-wide: it applies to every caller, Claude and Codex
-alike. A client that has no way to set `output_config.effort` can instead name
-the level in the model itself, and only that request changes:
+`DARIO_EFFORT` is process-wide: it applies to every caller on the Claude path
+(it does not reach the Codex backend; a suffix or a key default does). A
+client that has no way to set `output_config.effort` can instead name the
+level in the model itself, and only that request changes:
 
 ```
 claude-opus-4-8:high      colon form
@@ -118,6 +119,12 @@ lists, so a real model id that happens to end in an effort word is routed
 exactly as written and never re-read. A `--pool-fallback` chain entry may carry
 one too, which sets the effort the failover request runs at.
 
+A named key can carry a default as well (`dario keys create <name> --effort=low`,
+`dario keys effort <name> low`). It applies when the request names no effort of
+its own: below the suffix, the operator pin and the client's own field, above
+the `high` fallback. On the Codex path it is added to the Responses body Codex
+CLI sends as well. See [keys.md](keys.md#default-effort).
+
 Effort is not free. Measured through dario on one prompt with only the level
 changing: `low` returned 1,982 output tokens in 18s, `high` 3,947 in 35s, and
 `max` 11,160 in 100s. Reasoning is billed as output, so `max` is a real cost

package/docs/drift-monitor.md

@@ -219,7 +219,7 @@ sudo npm i -g @anthropic-ai/claude-code @askalf/dario
 #    URL back into the SSH session.
 #
 #    SHARE the credential with any other CC clients that auto-refresh
-#    (e.g. a platform dario container running 24/7). Just run the standard
+#    (e.g. a dario container running 24/7). Just run the standard
 #    `dario login --manual` against /root/.claude/.credentials.json and let
 #    that long-running refresh authority keep the token fresh. The workflows
 #    read whatever's current at fire time and never attempt a refresh from
@@ -235,7 +235,7 @@ sudo npm i -g @anthropic-ai/claude-code @askalf/dario
 #
 #    Sharing with a 24/7 refresh authority (typical setup: the docker-stack
 #    dario container) fixes that. The race the isolation was protecting
-#    against is rare in practice — platform dario refreshes proactively
+#    against is rare in practice: a long-running dario refreshes proactively
 #    when the access token has ~1h life remaining, so workflow runs hit a
 #    fresh token and don't need to refresh themselves.
 dario login --manual
@@ -332,13 +332,13 @@ Workflows that exercise live `dario proxy` paths (compat-test, billing canary, f
 | `cc-billing-classifier-canary.yml` | daily 06:30 UTC | daily | 1 small haiku request |
 | `compat-test-self-hosted.yml` | per qualifying PR | per qualifying PR | ~11 small requests |
 
-**Cron scheduler reality.** GitHub Actions' free-tier cron scheduler is best-effort, not guaranteed. The class-B watcher declares `*/30 * * * *` but in practice GitHub honors it every 2-4 hours on this repo. The liveness alarm (added v4.4.2) has its threshold set to 8h (raised from 3h in v4.7.1) to absorb this skew — anything past that is signal, not scheduler noise. If you need a tighter SLA (sub-hour), self-host the runner *and* the cron driver (e.g. a cron entry on the same Hetzner box invoking `gh workflow run` directly).
+**Cron scheduler reality.** GitHub Actions' free-tier cron scheduler is best-effort, not guaranteed. The class-B watcher declares `*/30 * * * *` but in practice GitHub honors it every 2-4 hours on this repo. The liveness alarm (added v4.4.2) has its threshold set to 8h (raised from 3h in v4.7.1) to absorb this skew; anything past that is signal, not scheduler noise. If you need a tighter SLA (sub-hour), self-host the runner *and* the cron driver (e.g. a cron entry on the same host invoking `gh workflow run` directly).
 
 At steady state, this is comfortably inside Pro/Max headroom. The failure mode to watch for is **batched firing** — manually re-triggering the same workflow several times in a single hour, or PRs landing in rapid succession that each fire compat-test. We tripped this during the v4.6.x rollout: a half-dozen manual re-runs in a 2-hour window 429'd the runner credential. Pro/Max accounts have per-hour rate caps as well as per-5h / per-7d pools, and the per-hour cap is what surfaces first.
 
 If the runner credential is rate-limited and a workflow run reports 429s across the board, the right diagnosis order is: (a) check `claude --print` directly — if it 429s, the credential pool is dry, just wait an hour; (b) check the credential is still on a subscription account (`dario doctor`); (c) check workflow cadence assumptions haven't changed.
 
-The runner shares its OAuth credential with any other long-running CC client on the box (typically the platform dario container, which auto-refreshes 24/7). Sharing is intentional: a workflow that fires sparsely cannot keep its own refresh token alive — Anthropic invalidates idle refresh tokens, and `invalid_grant` then breaks every subsequent run. Letting a 24/7 refresh authority own the token rotation eliminates that failure mode at the cost of competing for the same Pro/Max headroom. With current cadence (drift-template-watch every 30 min + compat per PR + canary daily), runner-side burn on the shared account is a manageable fraction of the headroom available on a Max plan; reducing cadence further is a knob if a particular workload needs more of it.
+The runner shares its OAuth credential with any other long-running CC client on the box (typically a long-running dario container, which auto-refreshes 24/7). Sharing is intentional: a workflow that fires sparsely cannot keep its own refresh token alive: Anthropic invalidates idle refresh tokens, and `invalid_grant` then breaks every subsequent run. Letting a 24/7 refresh authority own the token rotation eliminates that failure mode at the cost of competing for the same Pro/Max headroom. With current cadence (drift-template-watch every 30 min + compat per PR + canary daily), runner-side burn on the shared account is a manageable fraction of the headroom available on a Max plan; reducing cadence further is a knob if a particular workload needs more of it.
 
 ## Why a self-hosted runner
 

package/docs/keys.md

@@ -34,12 +34,45 @@ on its next request, no restart.
 | `--expires=30d` | Refused after this, like a revoked key. `12h`, `2w`, or an ISO date. |
 | `--budget=$5/day` | A daily cap on the API-equivalent price of the key's traffic. See **Budgets**. |
 | `--budget-tokens=2M/day` | A daily cap on tokens, every bucket counted. See **Budgets**. |
+| `--effort=low` | The effort this key's requests run at when they name none themselves (no model-name suffix, no effort field). `low`, `medium`, `high`, `xhigh` or `max`. See **Default effort**. |
 
 `dario keys revoke <name>` refuses a key from now on and keeps it in the list;
 `dario keys rotate <name>` prints a new secret under the same name, seat,
 models and expiry, and the old secret stops at once; `dario keys remove
 <name>` forgets it.
 
+## Default effort
+
+`dario keys create alice --effort=low`, or `dario keys effort alice low` on an
+existing key (`--clear` to remove it), sets the effort the key's requests run
+at when they name none themselves. Resolution per request, first match wins:
+
+1. an effort suffix on the model name (`claude-opus-5-5:low`);
+2. the proxy's `--effort` / `DARIO_EFFORT` pin, when set to a level (`client`
+   is not a level: under it the key's default still fills in);
+3. the client's own effort field (`output_config.effort`, `reasoning_effort`, `reasoning.effort`);
+4. the key's default;
+5. `high`, the proxy's long-standing fallback.
+
+So a key default never overrules a client that chose, and the operator's pin
+still overrules everything, as it always has. On the Claude path the level
+goes out as `output_config.effort`.
+
+On the Codex path it goes out as `reasoning.effort`, on both routes: the
+Messages-shape request dario translates, and the Responses body Codex CLI
+sends, which dario otherwise forwards as written (the level is added to its
+`reasoning` object; `summary` and the rest stay). Two differences there. The
+proxy pin has never reached the Codex backend, so it is not in the order. And
+a Messages-shape client's `thinking.budget_tokens` is that client's choice on
+Codex (it becomes `reasoning.effort`), so it outranks the key's default the
+way the client's own field does. With none of those, the backend's own
+default applies, not `high`.
+Why the knob is per key: a reasoning model at its default effort can spend
+most of its output thinking on work that did not need it (the `Thinking:` line
+in `dario usage` shows the share per key), and the lane that needs the cap is
+usually one consumer, not the whole proxy. `dario keys list` shows an EFFORT
+column; `GET /admin/keys` and `dario keys --json` carry `effort`.
+
 ## Budgets
 
 `dario keys create alice --budget=$5/day --budget-tokens=2M/day` — or
@@ -91,7 +124,9 @@ fields (an empty body clears), audited as `key_budget`.
   to the key; the header cannot overrule a credential.
 - **`dario usage --by-key`** — the lifetime API-equivalent number split per
   consumer: named keys, header names, and the `u_…` hash of a client's user
-  id, whichever named the request.
+  id, whichever named the request. The tokens line under each key includes
+  its thinking share: how many of the key's output tokens were the model's
+  reasoning, and what they cost at the output rate.
 - **The log file** — `consumer` on every request line; `reject: "key-model"`
   on a model refusal; `event: "admin.key_create|key_rotate|key_revoke"` with
   `key: <name>` when the admin API changed something.

package/docs/pool-keys-and-analytics.md

@@ -69,8 +69,11 @@ The rolling window forgets on every restart; the **ledger** does not. Since 6.6
       Claude       $388   1,204 reqs   (Opus 5 $301 · Sonnet 5 $86.68)
       ChatGPT    $24.75     311 reqs   (gpt-5.6-terra $24.75)
     Today $48.20 · Last 7d $413 · Last 30d $413
+    Thinking: 2.1M of 3.4M output tokens (62%) · $156 of the number above
 ```
 
+The `Thinking:` line is the share of output tokens that were the model's reasoning, read from the usage block upstream returns on Claude traffic, and what that reasoning would have cost at each model's output rate. It is the first number to look at when a bill surprises you: a reasoning model at its default effort can spend most of its output thinking on work that did not need it, and `output_config.effort` (or a `:low` model-name suffix, see [configuration](configuration.md#per-request-effort-by-model-name)) is a cheaper fix than a smaller model. `dario usage --by-key` shows the share per key, so the lane that is thinking the most is one line away.
+
 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`.

package/docs/system-prompt.md

@@ -13,6 +13,8 @@ The empirical basis for this feature lives in [`docs/research/system-prompt-clas
 | `aggressive` | Partial + remove the prompt-level RLHF restatements (`IMPORTANT: Assist with authorized security testing…`, `IMPORTANT: You must NEVER generate or guess URLs…`) and the `# Executing actions with care` section. | <3% above partial |
 | `<file path>` | Replace the slot entirely with the contents of a file you control. The escape hatch for users running well-defined agent workflows with their own system prompt. | depends on your prompt |
 
+What `partial` finds to strip depends on the prompt Claude Code sends for the model. The Sonnet 5 prompt has the `# Tone and style` and `# Text output` sections and the Doing-tasks bullets. The Fable prompt has a one-line rule about code comments, which `partial` swaps for a "be thorough" instruction. The base prompt (Claude Code 2.1.316) and the Opus 5 prompt carry none of these, so `partial` sends them unchanged and only `aggressive` changes them.
+
 ## Aggressive vs partial — what's the actual difference?
 
 Aggressive is provided for completeness, not because it does meaningful work. The added removals are *prompt-level restatements* of refusal categories — reminders the prompt makes about RLHF behavior that's already trained into the model's weights. Removing the reminder doesn't remove the trained behavior. We measured this: 9 trials (3 prompts × 3 strip levels), aggressive vs partial added <3% practical change on benign tasks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.19.1",
+  "version": "6.20.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": {