@askalf/dario 4.0.0 → 4.1.0

package/dist/config-file.js

@@ -71,6 +71,12 @@ export function defaultConfig() {
         systemPrompt: null,
         preserveOrchestrationTags: false,
         logFile: null,
+        overageGuard: {
+            enabled: true,
+            behavior: 'halt',
+            cooldownMs: 30 * 60 * 1000,
+            notifyOs: true,
+        },
     };
 }
 /**
@@ -320,6 +326,23 @@ function sanitize(parsed) {
     const logFile = pickStringOrNull('logFile');
     if (logFile !== undefined)
         out.logFile = logFile;
+    if (isPlainObject(parsed.overageGuard)) {
+        out.overageGuard = {};
+        if (typeof parsed.overageGuard.enabled === 'boolean') {
+            out.overageGuard.enabled = parsed.overageGuard.enabled;
+        }
+        if (parsed.overageGuard.behavior === 'halt' || parsed.overageGuard.behavior === 'warn') {
+            out.overageGuard.behavior = parsed.overageGuard.behavior;
+        }
+        if (typeof parsed.overageGuard.cooldownMs === 'number'
+            && Number.isFinite(parsed.overageGuard.cooldownMs)
+            && parsed.overageGuard.cooldownMs >= 0) {
+            out.overageGuard.cooldownMs = parsed.overageGuard.cooldownMs;
+        }
+        if (typeof parsed.overageGuard.notifyOs === 'boolean') {
+            out.overageGuard.notifyOs = parsed.overageGuard.notifyOs;
+        }
+    }
     // Silence unused-warning helper.
     void pickNumberOrNull;
     return out;

package/dist/live-fingerprint.d.ts

@@ -282,7 +282,7 @@ export declare function _resetInstalledVersionProbeForTest(): void;
  */
 export declare const SUPPORTED_CC_RANGE: {
     readonly min: "1.0.0";
-    readonly maxTested: "2.1.142";
+    readonly maxTested: "2.1.143";
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/live-fingerprint.js

@@ -777,7 +777,7 @@ export function _resetInstalledVersionProbeForTest() {
  */
 export const SUPPORTED_CC_RANGE = {
     min: '1.0.0',
-    maxTested: '2.1.142',
+    maxTested: '2.1.143',
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/notify.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Best-effort cross-platform desktop notification dispatcher.
+ *
+ * Pure Node, no new dependencies. Resolves the platform's native toast
+ * mechanism at load time, falls back to the terminal BEL character on any
+ * platform that doesn't have one (or where the native path is missing).
+ *
+ * Backends:
+ *   - macOS:   `osascript -e 'display notification "msg" with title "dario"'`
+ *   - Linux:   `notify-send "dario" "msg"` (gnome / kde / dunst / mako)
+ *   - Windows: `powershell -Command New-BurntToastNotification ...` if the
+ *              `BurntToast` module is installed; falls back to `msg.exe`,
+ *              else BEL only.
+ *
+ * BEL char (`\x07`) is the unconditional floor — works on every terminal
+ * that respects ANSI control characters, which is nearly all of them.
+ *
+ * Silent on failure: a missing `osascript`/`notify-send`/PowerShell path
+ * is the common case for non-interactive sessions, headless CI runs, and
+ * SSH-into-a-server flows. The TUI banner is the authoritative surface;
+ * OS-notify is the loud, attention-grabbing supplement.
+ *
+ * See dario#288 — overage-guard.
+ */
+/**
+ * Fire a native notification. Returns immediately — the underlying spawn
+ * is fire-and-forget. Errors (missing binary, permission denied, no
+ * graphical session) are swallowed; the caller already has the in-app
+ * surface and shouldn't depend on this firing.
+ *
+ * `title` and `message` are passed verbatim except for shell-meta escaping
+ * — single quotes and backticks are stripped so the AppleScript / shell
+ * payload can't be hijacked by a malicious upstream response.
+ */
+export declare function notify(title: string, message: string): void;
+/**
+ * Test-mode hook — returns a notifier that pushes into a captured array
+ * instead of firing real OS notifications. Used by test/notify-cross-
+ * platform.mjs to verify the dispatch path without invoking osascript.
+ */
+export declare function captureNotifier(): {
+    notify: (title: string, message: string) => void;
+    captured: Array<{
+        title: string;
+        message: string;
+        ts: number;
+    }>;
+};

package/dist/notify.js

@@ -0,0 +1,120 @@
+/**
+ * Best-effort cross-platform desktop notification dispatcher.
+ *
+ * Pure Node, no new dependencies. Resolves the platform's native toast
+ * mechanism at load time, falls back to the terminal BEL character on any
+ * platform that doesn't have one (or where the native path is missing).
+ *
+ * Backends:
+ *   - macOS:   `osascript -e 'display notification "msg" with title "dario"'`
+ *   - Linux:   `notify-send "dario" "msg"` (gnome / kde / dunst / mako)
+ *   - Windows: `powershell -Command New-BurntToastNotification ...` if the
+ *              `BurntToast` module is installed; falls back to `msg.exe`,
+ *              else BEL only.
+ *
+ * BEL char (`\x07`) is the unconditional floor — works on every terminal
+ * that respects ANSI control characters, which is nearly all of them.
+ *
+ * Silent on failure: a missing `osascript`/`notify-send`/PowerShell path
+ * is the common case for non-interactive sessions, headless CI runs, and
+ * SSH-into-a-server flows. The TUI banner is the authoritative surface;
+ * OS-notify is the loud, attention-grabbing supplement.
+ *
+ * See dario#288 — overage-guard.
+ */
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+/**
+ * Fire a native notification. Returns immediately — the underlying spawn
+ * is fire-and-forget. Errors (missing binary, permission denied, no
+ * graphical session) are swallowed; the caller already has the in-app
+ * surface and shouldn't depend on this firing.
+ *
+ * `title` and `message` are passed verbatim except for shell-meta escaping
+ * — single quotes and backticks are stripped so the AppleScript / shell
+ * payload can't be hijacked by a malicious upstream response.
+ */
+export function notify(title, message) {
+    // Always BEL first — works in every TTY, doesn't depend on a graphical
+    // session. The OS notification on top is best-effort.
+    try {
+        process.stderr.write('\x07');
+    }
+    catch {
+        // stderr write can fail under exotic conditions (closed handle,
+        // detached process); silent — we have nothing else to fall back to.
+    }
+    const safeTitle = sanitize(title);
+    const safeMessage = sanitize(message);
+    const plat = platform();
+    try {
+        if (plat === 'darwin') {
+            // AppleScript single-quote inside the script body would need
+            // escaping; sanitize() strips them so the literal substitution
+            // below stays safe. Spawned via array argv to avoid a shell
+            // entirely.
+            spawn('osascript', [
+                '-e',
+                `display notification "${safeMessage}" with title "${safeTitle}"`,
+            ], { detached: true, stdio: 'ignore' }).unref();
+        }
+        else if (plat === 'linux') {
+            spawn('notify-send', [safeTitle, safeMessage], {
+                detached: true,
+                stdio: 'ignore',
+            }).unref();
+        }
+        else if (plat === 'win32') {
+            // BurntToast is the cleanest path — single-line PowerShell, real
+            // Windows toast notification. If BurntToast isn't installed the
+            // command fails silently (stdio: ignore swallows the error
+            // output), which is the desired behavior.
+            //
+            // We don't probe-then-spawn; the cost of one failed BurntToast
+            // attempt is the same as one probe attempt, and probing makes the
+            // hot path slower for the success case.
+            const ps = `try { Import-Module BurntToast -ErrorAction Stop; New-BurntToastNotification -Text '${safeTitle}', '${safeMessage}' } catch { exit 1 }`;
+            spawn('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                ps,
+            ], { detached: true, stdio: 'ignore' }).unref();
+        }
+        // freebsd / openbsd / aix / sunos / android — BEL only. There's no
+        // single "right" native notification on these platforms.
+    }
+    catch {
+        // spawn() itself can throw on EMFILE or similar; silent.
+    }
+}
+/**
+ * Strip characters that would break the embedded shell/AppleScript
+ * payload or allow command injection. Conservative: only allow printable
+ * ASCII + common Unicode word chars + a small whitelist of punctuation.
+ *
+ * This is NOT a general-purpose sanitizer; it exists to defang text we
+ * already control (our own messages) from accidentally containing
+ * AppleScript-breaking characters like a stray double quote.
+ */
+function sanitize(s) {
+    return s
+        .replace(/[\r\n]/g, ' ') // collapse newlines
+        .replace(/[`'"$]/g, '') // strip shell metas + quotes
+        .replace(/\\/g, '/') // strip backslashes
+        .slice(0, 200); // cap length; notifications truncate anyway
+}
+/**
+ * Test-mode hook — returns a notifier that pushes into a captured array
+ * instead of firing real OS notifications. Used by test/notify-cross-
+ * platform.mjs to verify the dispatch path without invoking osascript.
+ */
+export function captureNotifier() {
+    const captured = [];
+    return {
+        notify: (title, message) => {
+            captured.push({ title, message, ts: Date.now() });
+        },
+        captured,
+    };
+}

package/dist/overage-guard.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Overage-guard — halt the proxy on the first `representative-claim: overage`
+ * response to prevent silent API-rate bleed.
+ *
+ * Subscribers should never see a single overage hit during normal
+ * operation. One means something is wrong (wire-shape drift, classifier
+ * change, account misconfig, billing-flip after a CC release) and
+ * continuing to forward requests bleeds against per-token billing.
+ *
+ * The guard subscribes to the Analytics record stream — every completed
+ * request emits a record carrying its `claim` (raw representative-claim
+ * value). When `claim === 'overage'` lands, the guard transitions to a
+ * halted state and emits a `'halt'` event. The HTTP request path checks
+ * `isHalted()` on every incoming request and returns 503 with an
+ * Anthropic-shaped error body when halted.
+ *
+ * Resume paths:
+ *   - explicit:  `dario resume` CLI → POST /admin/resume → `clear('manual')`
+ *   - automatic: cooldown expires (default 30 min) → `clear('cooldown')`
+ *   - TUI:       `r` key on Status tab → POST /admin/resume (same as CLI)
+ *
+ * Behavior:
+ *   - `halt` (default) — record halted state + return 503 on subsequent requests
+ *   - `warn` — emit events + notify only; proxy keeps forwarding (visibility-only mode)
+ *
+ * See dario#288.
+ */
+import { EventEmitter } from 'node:events';
+import type { Analytics, RequestRecord } from './analytics.js';
+export interface HaltState {
+    since: number;
+    cooldownUntil: number;
+    reason: 'overage_detected';
+    request: {
+        timestamp: number;
+        model: string;
+        account: string;
+        claim: string;
+    };
+}
+export interface OverageGuardOptions {
+    enabled: boolean;
+    behavior: 'halt' | 'warn';
+    cooldownMs: number;
+    notifyOs: boolean;
+    /**
+     * Best-effort native desktop notification dispatcher. Pass the function
+     * from `./notify.ts` here. Optional — silent failure if absent. The
+     * guard always emits the `'halt'` event for in-process subscribers
+     * (the SSE stream, the TUI) regardless of whether OS-notify fired.
+     */
+    notifier?: (title: string, message: string) => void;
+}
+export declare class OverageGuard extends EventEmitter {
+    private opts;
+    private halted;
+    private cooldownTimer;
+    private analyticsListener;
+    constructor(opts: OverageGuardOptions);
+    /**
+     * Subscribe to an Analytics instance. Every record emitted with
+     * `claim === 'overage'` triggers halt (when behavior === 'halt') or a
+     * warn-only event (when behavior === 'warn').
+     *
+     * Idempotent — calling attach() a second time replaces the listener
+     * rather than stacking; useful for tests.
+     */
+    attach(analytics: Analytics): void;
+    /**
+     * Synthesize a halt event from a record. Public for the test harness;
+     * production code reaches this via attach() + the live Analytics stream.
+     */
+    onOverageDetected(r: RequestRecord): void;
+    /**
+     * Resume the proxy. Emits a 'resume' event with the reason.
+     *
+     * No-op when not currently halted. Safe to call from any path
+     * (CLI, /admin/resume HTTP endpoint, TUI `r` key, cooldown timer).
+     */
+    clear(reason: 'manual' | 'cooldown'): void;
+    /** Current halt state, or `null` if not halted. */
+    state(): HaltState | null;
+    /** Quick boolean for the request hot-path. */
+    isHalted(): boolean;
+    /** Detach from Analytics. Used by tests and by graceful shutdown. */
+    destroy(): void;
+    /** Expose options for the /status endpoint + TUI Status tab. */
+    config(): Readonly<OverageGuardOptions>;
+}
+/**
+ * The Anthropic-shaped error body returned by halted-503 responses. The
+ * shape matches what `api.anthropic.com` emits for any 4xx so CC /
+ * Cursor / Aider / Cline surface the message verbatim to the user — no
+ * client-specific handling needed.
+ */
+export declare function buildHaltErrorBody(state: HaltState): {
+    type: 'error';
+    error: {
+        type: string;
+        message: string;
+    };
+};

package/dist/overage-guard.js

@@ -0,0 +1,189 @@
+/**
+ * Overage-guard — halt the proxy on the first `representative-claim: overage`
+ * response to prevent silent API-rate bleed.
+ *
+ * Subscribers should never see a single overage hit during normal
+ * operation. One means something is wrong (wire-shape drift, classifier
+ * change, account misconfig, billing-flip after a CC release) and
+ * continuing to forward requests bleeds against per-token billing.
+ *
+ * The guard subscribes to the Analytics record stream — every completed
+ * request emits a record carrying its `claim` (raw representative-claim
+ * value). When `claim === 'overage'` lands, the guard transitions to a
+ * halted state and emits a `'halt'` event. The HTTP request path checks
+ * `isHalted()` on every incoming request and returns 503 with an
+ * Anthropic-shaped error body when halted.
+ *
+ * Resume paths:
+ *   - explicit:  `dario resume` CLI → POST /admin/resume → `clear('manual')`
+ *   - automatic: cooldown expires (default 30 min) → `clear('cooldown')`
+ *   - TUI:       `r` key on Status tab → POST /admin/resume (same as CLI)
+ *
+ * Behavior:
+ *   - `halt` (default) — record halted state + return 503 on subsequent requests
+ *   - `warn` — emit events + notify only; proxy keeps forwarding (visibility-only mode)
+ *
+ * See dario#288.
+ */
+import { EventEmitter } from 'node:events';
+export class OverageGuard extends EventEmitter {
+    opts;
+    halted = null;
+    cooldownTimer = null;
+    analyticsListener = null;
+    constructor(opts) {
+        super();
+        // /analytics/stream + TUI tabs each register a listener; the in-proc
+        // event listeners ceiling matches the Analytics class's choice.
+        this.setMaxListeners(100);
+        this.opts = opts;
+    }
+    /**
+     * Subscribe to an Analytics instance. Every record emitted with
+     * `claim === 'overage'` triggers halt (when behavior === 'halt') or a
+     * warn-only event (when behavior === 'warn').
+     *
+     * Idempotent — calling attach() a second time replaces the listener
+     * rather than stacking; useful for tests.
+     */
+    attach(analytics) {
+        if (this.analyticsListener) {
+            analytics.off('record', this.analyticsListener);
+        }
+        if (!this.opts.enabled) {
+            // Guard fully disabled — don't even register the listener. No
+            // detection, no halt, no events.
+            this.analyticsListener = null;
+            return;
+        }
+        this.analyticsListener = (r) => {
+            if (r.claim === 'overage') {
+                this.onOverageDetected(r);
+            }
+        };
+        analytics.on('record', this.analyticsListener);
+    }
+    /**
+     * Synthesize a halt event from a record. Public for the test harness;
+     * production code reaches this via attach() + the live Analytics stream.
+     */
+    onOverageDetected(r) {
+        if (this.halted) {
+            // Already halted — don't re-fire halt events. The original halt
+            // state stays in place until cleared. A second overage hit while
+            // halted is expected (the client may not have noticed the 503
+            // yet); silent.
+            return;
+        }
+        const state = {
+            since: Date.now(),
+            cooldownUntil: Date.now() + this.opts.cooldownMs,
+            reason: 'overage_detected',
+            request: {
+                timestamp: r.timestamp,
+                model: r.model,
+                account: r.account,
+                claim: r.claim,
+            },
+        };
+        if (this.opts.behavior === 'halt') {
+            this.halted = state;
+            // Schedule auto-resume. Timer reference is held so we can cancel
+            // it on a manual resume — otherwise a manual resume followed by
+            // continued use, then the original cooldown firing, would emit a
+            // spurious second 'resume' event.
+            this.cooldownTimer = setTimeout(() => {
+                if (this.halted && this.halted.since === state.since) {
+                    this.clear('cooldown');
+                }
+            }, this.opts.cooldownMs);
+            this.cooldownTimer.unref();
+        }
+        // Always fire 'halt' (or 'warn') so SSE subscribers see the event
+        // even in warn-only mode — the TUI's job is to surface this to the
+        // user regardless of whether the proxy chose to block traffic.
+        const eventName = this.opts.behavior === 'halt' ? 'halt' : 'warn';
+        try {
+            this.emit(eventName, state);
+        }
+        catch (err) {
+            // A subscriber threw — log + swallow, don't crash on event side-effects.
+            console.error('[dario] overage-guard subscriber threw:', err.message);
+        }
+        if (this.opts.notifyOs && this.opts.notifier) {
+            try {
+                const title = this.opts.behavior === 'halt' ? 'dario halted' : 'dario warning';
+                const msg = `Request classified as 'overage' (per-token billing)${this.opts.behavior === 'halt' ? '. Proxy halted. Run `dario resume` to continue.' : ''}`;
+                this.opts.notifier(title, msg);
+            }
+            catch {
+                // Native notification failure is non-fatal. Already emitted to
+                // SSE / TUI; the user gets the in-app banner regardless.
+            }
+        }
+    }
+    /**
+     * Resume the proxy. Emits a 'resume' event with the reason.
+     *
+     * No-op when not currently halted. Safe to call from any path
+     * (CLI, /admin/resume HTTP endpoint, TUI `r` key, cooldown timer).
+     */
+    clear(reason) {
+        if (!this.halted)
+            return;
+        const wasHaltedAt = this.halted.since;
+        this.halted = null;
+        if (this.cooldownTimer) {
+            clearTimeout(this.cooldownTimer);
+            this.cooldownTimer = null;
+        }
+        try {
+            this.emit('resume', { reason, previousSince: wasHaltedAt });
+        }
+        catch (err) {
+            console.error('[dario] overage-guard resume subscriber threw:', err.message);
+        }
+    }
+    /** Current halt state, or `null` if not halted. */
+    state() {
+        return this.halted;
+    }
+    /** Quick boolean for the request hot-path. */
+    isHalted() {
+        return this.halted !== null && this.opts.behavior === 'halt';
+    }
+    /** Detach from Analytics. Used by tests and by graceful shutdown. */
+    destroy() {
+        this.removeAllListeners();
+        if (this.cooldownTimer) {
+            clearTimeout(this.cooldownTimer);
+            this.cooldownTimer = null;
+        }
+        this.halted = null;
+        this.analyticsListener = null;
+    }
+    /** Expose options for the /status endpoint + TUI Status tab. */
+    config() {
+        return this.opts;
+    }
+}
+/**
+ * The Anthropic-shaped error body returned by halted-503 responses. The
+ * shape matches what `api.anthropic.com` emits for any 4xx so CC /
+ * Cursor / Aider / Cline surface the message verbatim to the user — no
+ * client-specific handling needed.
+ */
+export function buildHaltErrorBody(state) {
+    const isoCooldown = new Date(state.cooldownUntil).toISOString();
+    return {
+        type: 'error',
+        error: {
+            type: 'dario_overage_guard',
+            message: `dario halted to prevent API-rate bleed. A request was classified ` +
+                `as 'overage' (per-token billing) instead of your subscription pool. ` +
+                `To resume: run \`dario resume\` in another terminal, or wait until ` +
+                `${isoCooldown} for the cooldown to auto-clear. ` +
+                `Details: github.com/askalf/dario/issues/288`,
+        },
+    };
+}

package/dist/proxy.d.ts

@@ -162,6 +162,20 @@ interface ProxyOptions {
      * Sourced from `--system-prompt=<value>` or DARIO_SYSTEM_PROMPT.
      */
     systemPrompt?: string;
+    /**
+     * Overage-guard — halt the proxy on the first response carrying
+     * `representative-claim: overage`. Subscribers should never see a
+     * single overage hit during normal operation; one means something
+     * is wrong (wire-shape drift, classifier change, account misconfig)
+     * and continuing to forward bleeds against per-token billing.
+     *
+     * Default: enabled, halt behavior, 30-min cooldown, OS-notify on.
+     * See dario#288.
+     */
+    overageGuardEnabled?: boolean;
+    overageGuardBehavior?: 'halt' | 'warn';
+    overageGuardCooldownMs?: number;
+    overageGuardNotifyOs?: boolean;
 }
 /**
  * One JSON-ND record per completed request. Field set kept narrow to