@askalf/dario 6.0.27 → 6.0.28

package/dist/cli.js

@@ -1049,6 +1049,75 @@ async function accounts() {
         }
         return;
     }
+    if (sub === 'check') {
+        // Read-only, in-place seat probe: one tiny request per model, pinned to
+        // the seat (x-dario-account, admin-token gated), through the RUNNING proxy.
+        // Nothing is copied and nothing is restarted; the upstream status is the
+        // verdict, because a pinned request never fails over.
+        const alias = args[2];
+        if (!alias) {
+            console.error('');
+            console.error('  Usage: dario accounts check <alias> [--models=a,b,c] [--port=N]');
+            console.error('');
+            process.exit(1);
+        }
+        const modelsArg = args.find(a => a.startsWith('--models='));
+        const models = (modelsArg ? modelsArg.slice('--models='.length) : 'claude-haiku-4-5,claude-sonnet-5,claude-opus-5')
+            .split(',').map(m => m.trim()).filter(Boolean);
+        const { loadConfig } = await import('./config-file.js');
+        const fileCfg = loadConfig().config;
+        const portArg = args.find(a => a.startsWith('--port='));
+        const port = (portArg ? parseInt(portArg.split('=')[1], 10) : undefined)
+            ?? (process.env['DARIO_PORT'] ? parseInt(process.env['DARIO_PORT'], 10) : undefined)
+            ?? fileCfg.port ?? 3456;
+        const apiKey = process.env['DARIO_API_KEY'];
+        const adminToken = process.env['DARIO_ADMIN_TOKEN'] || apiKey;
+        if (!adminToken) {
+            console.error('[dario] accounts check needs DARIO_ADMIN_TOKEN (or DARIO_API_KEY) in the environment, and the proxy running with DARIO_ADMIN=1.');
+            process.exit(1);
+        }
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-dario-account': alias,
+            'x-dario-admin-token': adminToken,
+        };
+        if (apiKey)
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        console.log('');
+        console.log(`  dario — seat check: ${alias} via http://127.0.0.1:${port} (pinned, no failover)`);
+        console.log('');
+        let failed = 0;
+        for (const model of models) {
+            let line;
+            try {
+                const resp = await fetch(`http://127.0.0.1:${port}/v1/messages`, {
+                    method: 'POST', headers,
+                    body: JSON.stringify({ model, max_tokens: 8, messages: [{ role: 'user', content: 'Reply with the single word PONG.' }] }),
+                });
+                const text = await resp.text();
+                let detail = '';
+                try {
+                    const j = JSON.parse(text);
+                    detail = resp.ok ? (j.model ?? '') : `${j.error?.type ?? ''} ${(j.error?.message ?? '').slice(0, 120)}`.trim();
+                }
+                catch {
+                    detail = text.slice(0, 120);
+                }
+                if (!resp.ok)
+                    failed++;
+                line = `    ${model.padEnd(24)} HTTP ${resp.status}  ${detail}`;
+            }
+            catch (err) {
+                failed++;
+                line = `    ${model.padEnd(24)} FAIL  ${err.message}`;
+            }
+            console.log(line);
+        }
+        console.log('');
+        console.log(failed === 0 ? `  seat "${alias}" serves every model listed.` : `  ${failed}/${models.length} failed on seat "${alias}" — a 401 means its credential or identity, a 429 its window; neither was masked by a peer or the Codex leg.`);
+        console.log('');
+        process.exit(failed === 0 ? 0 : 1);
+    }
     if (sub === 'remove' || sub === 'rm') {
         const alias = args[2];
         if (!alias) {
@@ -1068,7 +1137,7 @@ async function accounts() {
         return;
     }
     console.error(`[dario] Unknown accounts subcommand: ${sub}`);
-    console.error('Usage: dario accounts [list|add <alias>|remove <alias>]');
+    console.error('Usage: dario accounts [list|add <alias>|check <alias>|remove <alias>]');
     process.exit(1);
 }
 /**

package/dist/proxy.js

@@ -17,6 +17,7 @@ import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLA
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
 import { grantAge, grantThresholds, worstGrantLevel, describeGrantAge } from './refresh-grant.js';
+import { resolveSeatPin, SEAT_PIN_HEADER, SEAT_PIN_TOKEN_HEADER } from './seat-pin.js';
 import { loadAllAccounts, loadAccount, saveAccount, refreshAccountToken, resyncLoginFromCredentialsIfStale, ensureLoginCredentialsInPool, mirrorLoginToCredentials } from './accounts.js';
 import { handleAdminRequest } from './admin-api.js';
 import { createTokenBucket } from './rate-limit.js';
@@ -2606,6 +2607,41 @@ export async function startProxy(opts = {}) {
                     ? { type: 'error', error: { type: 'authentication_error', message }, account: err.alias }
                     : { error: message, account: err.alias }));
             };
+            // Seat pin (seat-pin.ts): `x-dario-account: <alias>` + `x-dario-admin-token`
+            // routes this one request to that seat with no headroom selection, no
+            // sticky rebinding and no failover of any kind — the upstream answer is
+            // the seat's answer. Refused (not ignored) without the admin API, so a
+            // probe can never silently turn into a normal request.
+            const seatPin = resolveSeatPin(req.headers, { adminEnabled, adminTokenBuf });
+            if (seatPin.kind === 'disabled' || seatPin.kind === 'unauthorized') {
+                res.writeHead(403, JSON_HEADERS);
+                res.end(JSON.stringify({ type: 'error', error: { type: 'permission_error', message: seatPin.kind === 'disabled'
+                            ? `${SEAT_PIN_HEADER} needs the admin API: DARIO_ADMIN=1 with DARIO_ADMIN_TOKEN set`
+                            : `${SEAT_PIN_HEADER} needs a valid ${SEAT_PIN_TOKEN_HEADER}` } }));
+                return;
+            }
+            if (seatPin.kind === 'invalid-alias') {
+                res.writeHead(400, JSON_HEADERS);
+                res.end(JSON.stringify({ type: 'error', error: { type: 'invalid_request_error', message: `${SEAT_PIN_HEADER}: invalid alias` } }));
+                return;
+            }
+            // Upstream API-key mode bypasses the pool entirely (x-api-key, no
+            // bearer), so a pin cannot be honoured there — and "honoured by the
+            // key" would be the silent-wrong-seat outcome this feature exists to
+            // prevent. Refuse it, before the alias is even looked up.
+            if (seatPin.kind === 'pinned' && upstreamApiKey) {
+                res.writeHead(409, JSON_HEADERS);
+                res.end(JSON.stringify({ type: 'error', error: { type: 'invalid_request_error', message: `${SEAT_PIN_HEADER} cannot be honoured: the proxy is in upstream API-key mode (ANTHROPIC_UPSTREAM_API_KEY), which bypasses the account pool` } }));
+                return;
+            }
+            const pinnedAccount = seatPin.kind === 'pinned' ? (pool.get(seatPin.alias) ?? null) : null;
+            if (seatPin.kind === 'pinned' && !pinnedAccount) {
+                res.writeHead(404, JSON_HEADERS);
+                res.end(JSON.stringify({ type: 'error', error: { type: 'not_found_error', message: `${SEAT_PIN_HEADER}: no pool account "${seatPin.alias}"` } }));
+                return;
+            }
+            if (pinnedAccount && verbose)
+                console.log(`[dario] seat pin → ${pinnedAccount.alias} (no failover)`);
             const selectPoolAccount = () => {
                 if (upstreamApiKey) {
                     // Per-token API-key mode: no OAuth, no pool selection. `poolAccount`
@@ -2615,6 +2651,11 @@ export async function startProxy(opts = {}) {
                 }
                 // Pool is the one credential model (v5.0): a plain `dario login` is a
                 // pool of one, so every OAuth request selects from the pool.
+                if (pinnedAccount) {
+                    poolAccount = pinnedAccount;
+                    accessToken = pinnedAccount.accessToken;
+                    return true;
+                }
                 poolAccount = pool.select();
                 if (!poolAccount) {
                     // Pool-exhausted fallback: when armed, the pool HAS accounts (all
@@ -2893,6 +2934,18 @@ export async function startProxy(opts = {}) {
                         poolFallbackModel: requestPoolFallbackModel,
                         poolSize: pool.size,
                     });
+                    // A pin names a Claude POOL seat, so it is only meaningful for a request
+                    // this proxy would dispatch through that pool. Provider routing happens
+                    // here, BEFORE selectPoolAccount(), so a pinned request naming a Codex or
+                    // OpenAI-backend model would otherwise be answered by that leg and report
+                    // the wrong thing healthy — the same silent-wrong-leg outcome as the
+                    // api-key case above. Refuse it instead.
+                    if (pinnedAccount && decision.provider !== 'claude') {
+                        requestCount++;
+                        res.writeHead(409, JSON_HEADERS);
+                        res.end(JSON.stringify({ type: 'error', error: { type: 'invalid_request_error', message: `${SEAT_PIN_HEADER} names a Claude pool seat, but this request routes to ${decision.provider}; drop the header or ask for a Claude model` } }));
+                        return;
+                    }
                     if (rawModel && codexUnavailable && decision.provider === 'codex') {
                         requestCount++;
                         writeCodexCredentialsUnavailable(codexUnavailable, isOpenAI ? 'openai' : 'anthropic');
@@ -3035,7 +3088,7 @@ export async function startProxy(opts = {}) {
             if (!upstreamApiKey && !poolAccount) {
                 attemptedProviders.add('claude');
             }
-            if (!upstreamApiKey && !poolAccount && await tryCodexPoolFallback(req, res, body, selectPoolFallbackForBody(body), isOpenAI ? 'openai' : 'anthropic', 'pool exhausted', attemptedProviders)) {
+            if (!upstreamApiKey && !poolAccount && !pinnedAccount && await tryCodexPoolFallback(req, res, body, selectPoolFallbackForBody(body), isOpenAI ? 'openai' : 'anthropic', 'pool exhausted', attemptedProviders)) {
                 return;
             }
             // `isOpenAI` is REQUIRED here and was not, before v6.0.0 — the selector's
@@ -3173,7 +3226,7 @@ export async function startProxy(opts = {}) {
                         // that already has the Anthropic prompt cache warmed for it.
                         // Rotating off mid-session costs cache-create on every turn.
                         stickyKey = computeStickyKey(userMsg);
-                        if (stickyKey) {
+                        if (stickyKey && !pinnedAccount) {
                             const preferred = pool.selectSticky(stickyKey, modelFamily(requestModel));
                             if (preferred && preferred.alias !== poolAccount?.alias) {
                                 poolAccount = preferred;
@@ -3540,6 +3593,11 @@ export async function startProxy(opts = {}) {
             const triedAliases = new Set();
             if (poolAccount)
                 triedAliases.add(poolAccount.alias);
+            // A pinned request has no peers: every other seat counts as already
+            // tried, so the 401/429 sites below find nobody to fail over to.
+            if (pinnedAccount)
+                for (const a of pool.all())
+                    triedAliases.add(a.alias);
             let upstream;
             let peekedBody = null;
             // Inside-request 429 failover loop (v3.8.0). On a 429, pool mode tries
@@ -3869,7 +3927,7 @@ export async function startProxy(opts = {}) {
                         // sent one, so the following request does not re-walk the chain.
                         attemptedProviders.add('claude');
                         providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
-                        if (await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders)) {
+                        if (!pinnedAccount && await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders)) {
                             return;
                         }
                         if (allProvidersCooled(['codex', 'claude'], providerCooldowns)) {
@@ -3994,7 +4052,7 @@ export async function startProxy(opts = {}) {
                     // Same bookkeeping as the other mid-flight site — see there.
                     attemptedProviders.add('claude');
                     providerCooldowns.note('claude', parseRetryAfterMs(upstream.headers.get('retry-after')));
-                    if (await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders)) {
+                    if (!pinnedAccount && await attemptPoolFallbackOn429(req, res, body, isOpenAI, attemptedProviders)) {
                         return;
                     }
                     if (allProvidersCooled(['codex', 'claude'], providerCooldowns)) {

package/dist/seat-pin.d.ts

@@ -0,0 +1,20 @@
+import type { IncomingHttpHeaders } from 'node:http';
+export declare const SEAT_PIN_HEADER = "x-dario-account";
+export declare const SEAT_PIN_TOKEN_HEADER = "x-dario-admin-token";
+export type SeatPin = {
+    kind: 'none';
+} | {
+    kind: 'disabled';
+} | {
+    kind: 'unauthorized';
+} | {
+    kind: 'invalid-alias';
+    alias: string;
+} | {
+    kind: 'pinned';
+    alias: string;
+};
+export declare function resolveSeatPin(headers: IncomingHttpHeaders, opts: {
+    adminEnabled: boolean;
+    adminTokenBuf: Buffer | null;
+}): SeatPin;

package/dist/seat-pin.js

@@ -0,0 +1,44 @@
+/**
+ * Seat pin — route one request to one named pool account, with no failover.
+ *
+ * The read-only probe primitive behind `dario accounts check <alias>`: "does
+ * this seat serve this model right now?" cannot be answered by a normal
+ * request, because the pool picks the seat by headroom and fails over on
+ * 401/429 (to a peer, then to the Codex leg). A pinned request does none of
+ * that: it goes to the named seat and the upstream status comes back as-is.
+ *
+ * Gated on the admin API — `DARIO_ADMIN=1` plus a distinct `DARIO_ADMIN_TOKEN`
+ * sent in `x-dario-admin-token` — because choosing the seat is an admin act
+ * (it bypasses headroom routing and can burn one seat's window on purpose).
+ * The proxy's own API key still applies to the request as usual. With the
+ * admin API off the header is refused, not ignored: a probe that silently
+ * became a normal request would report the wrong seat as healthy.
+ */
+import { timingSafeEqual } from 'node:crypto';
+export const SEAT_PIN_HEADER = 'x-dario-account';
+export const SEAT_PIN_TOKEN_HEADER = 'x-dario-admin-token';
+/** Same charset as accounts.ts safeAliasPath — anything else is not a seat. */
+const ALIAS_RE = /^[A-Za-z0-9][A-Za-z0-9_\-.]{0,63}$/;
+function first(v) {
+    if (Array.isArray(v))
+        return v[0];
+    return v;
+}
+export function resolveSeatPin(headers, opts) {
+    const raw = first(headers[SEAT_PIN_HEADER]);
+    if (raw === undefined)
+        return { kind: 'none' };
+    const alias = raw.trim();
+    if (!opts.adminEnabled || !opts.adminTokenBuf)
+        return { kind: 'disabled' };
+    const provided = first(headers[SEAT_PIN_TOKEN_HEADER]);
+    if (!provided)
+        return { kind: 'unauthorized' };
+    const providedBuf = Buffer.from(provided);
+    if (providedBuf.length !== opts.adminTokenBuf.length || !timingSafeEqual(providedBuf, opts.adminTokenBuf)) {
+        return { kind: 'unauthorized' };
+    }
+    if (!ALIAS_RE.test(alias))
+        return { kind: 'invalid-alias', alias };
+    return { kind: 'pinned', alias };
+}

package/docs/admin-api.md

@@ -102,6 +102,20 @@ representative `claim` (e.g. `five_hour`), routing `status`,
 equivalent of the proxy-key-gated `GET /accounts` pool view; a headless
 operator needs only the admin token to watch headroom.
 
+## Pinning a request to one seat
+
+`x-dario-account: <alias>` on `POST /v1/messages` (or `/v1/chat/completions`) routes that one request to the named pool account with **no failover**: no headroom selection, no sticky rebinding, no peer retry on 401/429, no Codex leg. The upstream status comes back as-is. It is the primitive behind `dario accounts check <alias>` — the answer to "does this seat serve Sonnet right now?" without copying a credential anywhere or restarting anything.
+
+The header is gated on the admin API: the request must also carry `x-dario-admin-token: <DARIO_ADMIN_TOKEN>` (the proxy API key still applies as usual). With the admin API off, or the token missing or wrong, the request is refused with 403 rather than served unpinned — a probe that silently became a normal request would call the wrong seat healthy. An unknown alias is 404; a malformed one is 400. In upstream API-key mode (`ANTHROPIC_UPSTREAM_API_KEY`) the pool is bypassed entirely, so a pin is refused with 409 rather than quietly served by the key. A request that routes to another provider (a Codex-named model, or an OpenAI backend) is refused with 409 for the same reason: the pin names a Claude pool seat, and answering from another leg would report the wrong thing healthy.
+
+```bash
+curl -s http://localhost:3456/v1/messages \
+  -H "authorization: Bearer $DARIO_API_KEY" \
+  -H "x-dario-account: spare" -H "x-dario-admin-token: $DARIO_ADMIN_TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{"model":"claude-sonnet-5","max_tokens":8,"messages":[{"role":"user","content":"PONG"}]}'
+```
+
 ## Bulk re-auth, in one round-trip
 
 For a pool with several accounts, the round-trip of "notice one's broken,

package/docs/commands.md

@@ -15,6 +15,7 @@ This page is the per-flag reference. For environment variables grouped by task
 | `dario status` | Show Claude backend OAuth token health and expiry |
 | `dario refresh` | Force an immediate Claude token refresh |
 | `dario logout` | Delete stored Claude credentials |
+| `dario accounts check <alias> [--models=a,b]` | Read-only, in-place seat probe: one tiny request per model, pinned to that seat through the running proxy (`x-dario-account` + `x-dario-admin-token`, needs `DARIO_ADMIN=1`). A pinned request never fails over, so the upstream status is the seat's own answer. |
 | `dario accounts list` / `add <alias>` / `remove <alias>` | Multi-account pool management. `add <alias>` on a fresh pool auto back-fills your existing `dario login` credentials as `login`, so your first `add` trips the 2+ pool threshold on its own — see [Multi-account pool mode](./multi-account-pool.md). |
 | `dario backend list` / `add <name> --key=<key> [--base-url=<url>]` / `remove <name>` | OpenAI-compat backend management |
 | `dario subagent install` / `remove` / `status` | CC sub-agent lifecycle. See [sub-agent hook](./sub-agent.md). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.0.27",
+  "version": "6.0.28",
   "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.",
   "type": "module",
   "bin": {