@askalf/dario 6.0.12 → 6.0.13

package/dist/serving-probe.d.ts

@@ -1,120 +1,35 @@
-/**
- * serving-probe.ts — the "can dario actually serve a request?" check.
- *
- * WHY THIS EXISTS (dario#905, dario#921)
- *
- * dario's existing health surfaces are both STRUCTURAL — they inspect state,
- * they never prove anything end-to-end:
- *
- *   /livez   the HTTP server is accepting connections. Always 200.
- *   /health  credentials/pool look sane: token not expired, refresh not broken,
- *            accounts not all in auth-cooldown, queue snapshot attached.
- *
- * Neither can catch the failure class that actually took a user down for ~14h
- * across four episodes (#905): dario looking perfectly healthy from the outside
- * while every real request failed. The reporter's remediation was an external
- * watchdog that sends a real inference call and restarts the service when it
- * doesn't come back — i.e. the user had to write the liveness check dario
- * should own. This module is that check, brought in-house.
- *
- * It also covers a class /health provably cannot see: an account whose token is
- * unexpired and refreshable (so `status: healthy`) but whose accountUuid has
- * drifted, so upstream 401s every request. Structural inspection says fine;
- * only a round-trip says otherwise.
- *
- * WHAT IT PROVES, AND WHAT IT DELIBERATELY DOES NOT
- *
- * The probe is a minimal `POST /v1/messages` (max_tokens 1) sent DIRECTLY to
- * api.anthropic.com with the same auth the request path uses — pool bearer, or
- * `x-api-key` in upstream-API-key mode. That proves: a token can be acquired,
- * the network path is up, and upstream accepts our credential.
- *
- * It deliberately does NOT go through dario's own proxy path:
- *   - No recursion, no self-deadlock, no port/auth assumptions.
- *   - It must not take a concurrency slot. A probe that queues behind real
- *     traffic would report "unhealthy" during a legitimate burst and hand a
- *     watchdog a reason to restart a busy-but-fine dario. Slot exhaustion is
- *     covered instead by `queue.saturatedSince` (request-queue.ts), which is
- *     free, needs no tokens, and cannot false-positive on a short burst.
- *
- * So: the probe covers the credential/network axis, the queue snapshot covers
- * the concurrency axis. Neither claims to cover the transform path.
- *
- * COST AND EXPOSURE
- *
- * A probe is a real billed request. Three guards, all load-bearing:
- *   1. OPT-IN. Only runs when a caller explicitly asks (`/health?probe=1`).
- *      A plain /health never spends a token — existing docker healthchecks and
- *      uptime monitors keep their current cost profile, which is zero.
- *   2. TRUSTED CALLERS ONLY. proxy.ts honours `?probe=1` only for callers that
- *      already pass shouldDiscloseHealthInternals. A world-readable /health
- *      behind a Cloudflare tunnel bypass must not be a button the internet can
- *      press to spend the operator's tokens.
- *   3. CACHED + SINGLE-FLIGHTED. Results are reused for `ttlMs` (default 60s)
- *      and concurrent callers share one in-flight request, so a monitor polling
- *      every second still costs at most one probe per minute.
- *
- * VERDICT SEMANTICS — why 429 is NOT a failure
- *
- * `ok` answers "would a restart or an alert help?", not "did the call return
- * 200". Rate-limited (429) and upstream-overloaded (529) are healthy states:
- * dario is working, the answer is legitimately "not right now", and a watchdog
- * that restarts on them just thrashes. That is the same lesson /livez already
- * encodes in proxy.ts — a shared-refresh-family outage once had dario restart
- * -looping for 4h+ because the healthcheck keyed on a condition a restart
- * cannot fix. Auth rejection, 5xx, network failure and timeout DO set ok=false.
- */
-/** Cheapest family, and the one doctor's own probe already uses. */
 export declare const DEFAULT_PROBE_MODEL = "claude-haiku-4-5";
 export declare const DEFAULT_PROBE_TTL_MS = 60000;
 export declare const DEFAULT_PROBE_TIMEOUT_MS = 15000;
-/**
- * Why the round-trip ended the way it did. Carried on both verdicts so an
- * operator reading a green probe can still tell "served" from "rate-limited".
- */
-export type ProbeReason = 'served' | 'rate-limited' | 'upstream-overloaded' | 'no-token' | 'auth-rejected' | 'upstream-error' | 'timeout' | 'network-error';
+export type ProbeReason = 'served' | 'billing-required' | 'rate-limited' | 'upstream-overloaded' | 'no-token' | 'auth-rejected' | 'upstream-error' | 'timeout' | 'network-error';
 export interface ProbeResult {
-    /** False only for conditions where dario is the problem — see module header. */
     ok: boolean;
     reason: ProbeReason;
-    /** Epoch ms the round-trip completed. */
     checkedAt: number;
-    /** Wall time of the round-trip, including token acquisition. */
     latencyMs: number;
     model: string;
-    /** Upstream HTTP status, when upstream answered at all. */
     status?: number;
-    /** Short failure detail. Never carries a token or a raw body. */
     detail?: string;
 }
 export interface ProbeDeps {
     fetchImpl?: typeof fetch;
-    /** OAuth bearer source. Ignored when upstreamApiKey is set. */
     getToken?: () => Promise<string>;
-    /** Per-token API mode — forwarded as x-api-key, mirroring request-path auth. */
     upstreamApiKey?: string;
     now?: () => number;
     model?: string;
     timeoutMs?: number;
     ttlMs?: number;
 }
-/**
- * Map an upstream HTTP status onto a verdict. Pure, so the whole policy
- * ("which statuses mean dario is broken") is testable without a network.
- */
+export declare function classifyProbeResponse(status: number, body?: string): {
+    ok: boolean;
+    reason: ProbeReason;
+    detail?: string;
+};
+/** Backward-compatible status-only classifier; body-aware callers use classifyProbeResponse. */
 export declare function classifyProbeStatus(status: number): {
     ok: boolean;
     reason: ProbeReason;
 };
-/**
- * The cached verdict, refreshing it when stale. Never throws — a health
- * surface that can 500 is worse than useless, so every failure path becomes a
- * `ok: false` verdict with a reason instead of an exception.
- *
- * Concurrent callers past the TTL share one in-flight probe; the loser of the
- * race gets the same result rather than sending a second billed request.
- */
 export declare function getServingProbe(deps?: ProbeDeps): Promise<ProbeResult>;
-/** Age of the cached verdict, for the `ageMs` field callers see. */
 export declare function probeAgeMs(result: ProbeResult, now: number): number;
 export declare function _resetServingProbeForTest(): void;

package/dist/serving-probe.js

@@ -1,73 +1,11 @@
 /**
  * serving-probe.ts — the "can dario actually serve a request?" check.
- *
- * WHY THIS EXISTS (dario#905, dario#921)
- *
- * dario's existing health surfaces are both STRUCTURAL — they inspect state,
- * they never prove anything end-to-end:
- *
- *   /livez   the HTTP server is accepting connections. Always 200.
- *   /health  credentials/pool look sane: token not expired, refresh not broken,
- *            accounts not all in auth-cooldown, queue snapshot attached.
- *
- * Neither can catch the failure class that actually took a user down for ~14h
- * across four episodes (#905): dario looking perfectly healthy from the outside
- * while every real request failed. The reporter's remediation was an external
- * watchdog that sends a real inference call and restarts the service when it
- * doesn't come back — i.e. the user had to write the liveness check dario
- * should own. This module is that check, brought in-house.
- *
- * It also covers a class /health provably cannot see: an account whose token is
- * unexpired and refreshable (so `status: healthy`) but whose accountUuid has
- * drifted, so upstream 401s every request. Structural inspection says fine;
- * only a round-trip says otherwise.
- *
- * WHAT IT PROVES, AND WHAT IT DELIBERATELY DOES NOT
- *
- * The probe is a minimal `POST /v1/messages` (max_tokens 1) sent DIRECTLY to
- * api.anthropic.com with the same auth the request path uses — pool bearer, or
- * `x-api-key` in upstream-API-key mode. That proves: a token can be acquired,
- * the network path is up, and upstream accepts our credential.
- *
- * It deliberately does NOT go through dario's own proxy path:
- *   - No recursion, no self-deadlock, no port/auth assumptions.
- *   - It must not take a concurrency slot. A probe that queues behind real
- *     traffic would report "unhealthy" during a legitimate burst and hand a
- *     watchdog a reason to restart a busy-but-fine dario. Slot exhaustion is
- *     covered instead by `queue.saturatedSince` (request-queue.ts), which is
- *     free, needs no tokens, and cannot false-positive on a short burst.
- *
- * So: the probe covers the credential/network axis, the queue snapshot covers
- * the concurrency axis. Neither claims to cover the transform path.
- *
- * COST AND EXPOSURE
- *
- * A probe is a real billed request. Three guards, all load-bearing:
- *   1. OPT-IN. Only runs when a caller explicitly asks (`/health?probe=1`).
- *      A plain /health never spends a token — existing docker healthchecks and
- *      uptime monitors keep their current cost profile, which is zero.
- *   2. TRUSTED CALLERS ONLY. proxy.ts honours `?probe=1` only for callers that
- *      already pass shouldDiscloseHealthInternals. A world-readable /health
- *      behind a Cloudflare tunnel bypass must not be a button the internet can
- *      press to spend the operator's tokens.
- *   3. CACHED + SINGLE-FLIGHTED. Results are reused for `ttlMs` (default 60s)
- *      and concurrent callers share one in-flight request, so a monitor polling
- *      every second still costs at most one probe per minute.
- *
- * VERDICT SEMANTICS — why 429 is NOT a failure
- *
- * `ok` answers "would a restart or an alert help?", not "did the call return
- * 200". Rate-limited (429) and upstream-overloaded (529) are healthy states:
- * dario is working, the answer is legitimately "not right now", and a watchdog
- * that restarts on them just thrashes. That is the same lesson /livez already
- * encodes in proxy.ts — a shared-refresh-family outage once had dario restart
- * -looping for 4h+ because the healthcheck keyed on a condition a restart
- * cannot fix. Auth rejection, 5xx, network failure and timeout DO set ok=false.
+ * Opt-in, trusted-callers-only, cached and single-flighted.
  */
+import { classifyUpstreamRejection, rejectionRemediation } from './upstream-rejection.js';
 const ANTHROPIC_MESSAGES = 'https://api.anthropic.com/v1/messages';
 const ANTHROPIC_VERSION = '2023-06-01';
 const OAUTH_BETA = 'oauth-2025-04-20';
-/** Cheapest family, and the one doctor's own probe already uses. */
 export const DEFAULT_PROBE_MODEL = 'claude-haiku-4-5';
 export const DEFAULT_PROBE_TTL_MS = 60_000;
 export const DEFAULT_PROBE_TIMEOUT_MS = 15_000;
@@ -77,23 +15,31 @@ function envInt(name, dflt) {
     const v = Number(process.env[name]);
     return Number.isFinite(v) && v > 0 ? v : dflt;
 }
-/**
- * Map an upstream HTTP status onto a verdict. Pure, so the whole policy
- * ("which statuses mean dario is broken") is testable without a network.
- */
-export function classifyProbeStatus(status) {
+export function classifyProbeResponse(status, body = '') {
     if (status >= 200 && status < 300)
         return { ok: true, reason: 'served' };
-    // Serving fine, just throttled — restarting cannot help, so do not fail.
-    if (status === 429)
-        return { ok: true, reason: 'rate-limited' };
+    // 429/529 are TRANSIENT: the seat is servable, the window is just closed.
+    // They stay ok:true (reason still reported) so a watchdog does not restart on
+    // an ordinary overage window — see test/health-verdict.mjs. Only states that
+    // do NOT self-clear (billing, credential, upstream-error) are ok:false.
     if (status === 529)
-        return { ok: true, reason: 'upstream-overloaded' };
-    // The credential is being rejected even though local state looks valid.
-    // This is the accountUuid-drift signature /health structurally cannot see.
-    if (status === 401 || status === 403)
-        return { ok: false, reason: 'auth-rejected' };
-    return { ok: false, reason: 'upstream-error' };
+        return { ok: true, reason: 'upstream-overloaded', detail: 'Upstream is overloaded; retry later.' };
+    const rejection = classifyUpstreamRejection(status, body);
+    if (rejection.class === 'billing') {
+        return { ok: false, reason: 'billing-required', detail: rejectionRemediation(rejection) };
+    }
+    if (rejection.class === 'rate_limit') {
+        return { ok: true, reason: 'rate-limited', detail: rejectionRemediation(rejection) };
+    }
+    if (rejection.class === 'credential') {
+        return { ok: false, reason: 'auth-rejected', detail: rejectionRemediation(rejection) };
+    }
+    return { ok: false, reason: 'upstream-error', detail: rejectionRemediation(rejection) };
+}
+/** Backward-compatible status-only classifier; body-aware callers use classifyProbeResponse. */
+export function classifyProbeStatus(status) {
+    const { ok, reason } = classifyProbeResponse(status);
+    return { ok, reason };
 }
 async function runProbe(deps) {
     const f = deps.fetchImpl ?? fetch;
@@ -101,17 +47,10 @@ async function runProbe(deps) {
     const model = deps.model ?? process.env.DARIO_PROBE_MODEL ?? DEFAULT_PROBE_MODEL;
     const timeoutMs = deps.timeoutMs ?? envInt('DARIO_PROBE_TIMEOUT_MS', DEFAULT_PROBE_TIMEOUT_MS);
     const startedAt = now();
-    // Arm the deadline BEFORE token acquisition so a wedged refresh is bounded
-    // too, not just the fetch — the same trap model-catalog.ts hit in #642: a
-    // getToken() that never settles would leave `inflight` non-null forever and
-    // permanently wedge every future probe on a stale cached verdict.
     const ctl = new AbortController();
     const timer = setTimeout(() => ctl.abort(), timeoutMs);
     const finish = (r) => ({
-        ...r,
-        model,
-        checkedAt: now(),
-        latencyMs: now() - startedAt,
+        ...r, model, checkedAt: now(), latencyMs: now() - startedAt,
     });
     try {
         const headers = {
@@ -128,17 +67,15 @@ async function runProbe(deps) {
             try {
                 token = await Promise.race([
                     deps.getToken(),
-                    new Promise((_, rej) => {
-                        ctl.signal.addEventListener('abort', () => rej(new Error('token acquisition timed out')), { once: true });
+                    new Promise((_, reject) => {
+                        ctl.signal.addEventListener('abort', () => reject(new Error('token acquisition timed out')), { once: true });
                     }),
                 ]);
             }
             catch (err) {
-                // An empty pool lands here — the message already says so (pool.ts /
-                // catalogDeps phrase it for the operator), so surface it verbatim.
                 return finish({ ok: false, reason: 'no-token', detail: errText(err) });
             }
-            headers['authorization'] = `Bearer ${token}`;
+            headers.authorization = `Bearer ${token}`;
             headers['anthropic-beta'] = OAUTH_BETA;
         }
         const res = await f(ANTHROPIC_MESSAGES, {
@@ -147,12 +84,8 @@ async function runProbe(deps) {
             body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] }),
             signal: ctl.signal,
         });
-        // Drain so the socket is released back to the agent pool. The body is
-        // never inspected: a 200 is the whole signal, and the content could carry
-        // model output we have no reason to log.
-        await res.text().catch(() => '');
-        const verdict = classifyProbeStatus(res.status);
-        return finish({ ...verdict, status: res.status });
+        const body = await res.text().catch(() => '');
+        return finish({ ...classifyProbeResponse(res.status, body), status: res.status });
     }
     catch (err) {
         const aborted = ctl.signal.aborted || err?.name === 'AbortError';
@@ -169,14 +102,6 @@ async function runProbe(deps) {
 function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }
-/**
- * The cached verdict, refreshing it when stale. Never throws — a health
- * surface that can 500 is worse than useless, so every failure path becomes a
- * `ok: false` verdict with a reason instead of an exception.
- *
- * Concurrent callers past the TTL share one in-flight probe; the loser of the
- * race gets the same result rather than sending a second billed request.
- */
 export async function getServingProbe(deps = {}) {
     const now = (deps.now ?? Date.now)();
     const ttl = deps.ttlMs ?? envInt('DARIO_PROBE_TTL_MS', DEFAULT_PROBE_TTL_MS);
@@ -185,16 +110,13 @@ export async function getServingProbe(deps = {}) {
     if (inflight !== null)
         return inflight;
     inflight = runProbe(deps)
-        .then((r) => {
-        cache = r;
-        return r;
+        .then((result) => {
+        cache = result;
+        return result;
     })
-        .finally(() => {
-        inflight = null;
-    });
+        .finally(() => { inflight = null; });
     return inflight;
 }
-/** Age of the cached verdict, for the `ageMs` field callers see. */
 export function probeAgeMs(result, now) {
     return Math.max(0, now - result.checkedAt);
 }

package/dist/upstream-rejection.d.ts

@@ -1,9 +1,13 @@
-export type UpstreamRejectionClass = 'billing' | 'rate_limit' | 'other';
+export type UpstreamRejectionClass = 'billing' | 'rate_limit' | 'credential' | 'other';
 export interface UpstreamRejection {
     class: UpstreamRejectionClass;
-    marker: 'billing_required' | 'rate_limited' | 'upstream_rejected';
+    marker: 'billing_required' | 'rate_limited' | 'credential_rejected' | 'upstream_rejected';
 }
 /** Classify subscription entitlement failures separately from temporary quota exhaustion. */
 export declare function classifyUpstreamRejection(status: number, body: string): UpstreamRejection;
+/** Operator action paired with the failure class. Never suggest credential churn for billing. */
+export declare function rejectionRemediation(rejection: UpstreamRejection): string;
+/** Stable reason string for health, doctor, and workflow consumers. */
+export declare function rejectionReason(rejection: UpstreamRejection): string;
 /** Bounded diagnostic text; callers must apply their standard secret redactor first. */
 export declare function diagnosticSnippet(body: string, maxLength?: number): string;

package/dist/upstream-rejection.js

@@ -10,8 +10,34 @@ export function classifyUpstreamRejection(status, body) {
         return { class: 'billing', marker: 'billing_required' };
     if (status === 429)
         return { class: 'rate_limit', marker: 'rate_limited' };
+    if (status === 401 || normalized.includes('authentication_error') || normalized.includes('invalid_grant')) {
+        return { class: 'credential', marker: 'credential_rejected' };
+    }
     return { class: 'other', marker: 'upstream_rejected' };
 }
+/** Operator action paired with the failure class. Never suggest credential churn for billing. */
+export function rejectionRemediation(rejection) {
+    switch (rejection.class) {
+        case 'billing':
+            return 'The subscription or payment method needs operator attention. Restarting, re-transplanting credentials, logging in again, or removing the pool account will not help.';
+        case 'rate_limit':
+            return 'The quota window self-clears; wait for the upstream reset window, then retry.';
+        case 'credential':
+            return 'The credential was rejected; follow the OAuth re-authentication runbook.';
+        default:
+            return 'Upstream rejected the request for an unclassified reason; inspect the bounded diagnostic before changing credentials.';
+    }
+}
+/** Stable reason string for health, doctor, and workflow consumers. */
+export function rejectionReason(rejection) {
+    if (rejection.class === 'billing')
+        return 'billing-required';
+    if (rejection.class === 'rate_limit')
+        return 'rate-limited';
+    if (rejection.class === 'credential')
+        return 'auth-rejected';
+    return 'upstream-rejected';
+}
 /** Bounded diagnostic text; callers must apply their standard secret redactor first. */
 export function diagnosticSnippet(body, maxLength = 500) {
     return body.replace(/\s+/g, ' ').trim().slice(0, maxLength);

package/package.json

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