@askalf/dario 3.31.21 → 3.32.1

package/dist/cli.js

@@ -181,8 +181,19 @@ async function proxy() {
     const passthrough = args.includes('--passthrough') || args.includes('--thin');
     const preserveTools = args.includes('--preserve-tools') || args.includes('--keep-tools');
     const hybridTools = args.includes('--hybrid-tools') || args.includes('--context-inject');
-    if (preserveTools && hybridTools) {
-        console.error('[dario] --preserve-tools and --hybrid-tools are mutually exclusive. Pick one.');
+    const mergeTools = args.includes('--merge-tools') || args.includes('--append-tools');
+    // The three modes shape the outbound `tools` array differently;
+    // combining any two would mean two different bodies. Caught here so
+    // the operator gets a clear error instead of one flag silently
+    // winning. startProxy enforces the same mutex defensively.
+    const toolModeCount = [preserveTools, hybridTools, mergeTools].filter(Boolean).length;
+    if (toolModeCount > 1) {
+        const picked = [
+            preserveTools && '--preserve-tools',
+            hybridTools && '--hybrid-tools',
+            mergeTools && '--merge-tools',
+        ].filter(Boolean).join(', ');
+        console.error(`[dario] tool-routing flags are mutually exclusive. Pick one (got: ${picked}).`);
         process.exit(1);
     }
     // Opt-out for v3.19.3's text-tool-client auto-detection. Operators who
@@ -268,6 +279,17 @@ async function proxy() {
     // the server side, so passing through a too-high value returns a clean
     // 400 rather than silently accepting beyond-model-max.
     const maxTokens = resolveMaxTokensFlag(args, process.env['DARIO_MAX_TOKENS']);
+    // --log-file <path> — append a one-line JSON record per completed
+    // request. Useful for backgrounded proxies where stdout is unobserved.
+    // Falls back to DARIO_LOG_FILE; off by default. Path is opened with
+    // append mode so multiple proxy restarts share a rolling history.
+    const logFile = parseLogFileFlag(args) ?? process.env['DARIO_LOG_FILE'] ?? undefined;
+    // --passthrough-betas=name1,name2 — operator-pinned beta allow-list.
+    // Names listed here are always forwarded to Anthropic regardless of
+    // CC's captured set or the client's own beta header; bypasses the
+    // billable-filter. Empty values are dropped. Falls back to
+    // DARIO_PASSTHROUGH_BETAS env var.
+    const passthroughBetas = parsePassthroughBetasFlag(args, process.env['DARIO_PASSTHROUGH_BETAS']);
     // Non-loopback bind without DARIO_API_KEY turns dario into an open
     // OAuth-subscription relay for anyone on the reachable network. Refuse
     // to start rather than rely on the operator to read the startup banner.
@@ -287,7 +309,56 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort, maxTokens });
+    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort, maxTokens, logFile, passthroughBetas });
+}
+/**
+ * Parse `--passthrough-betas=<csv>` (or the env-var fallback) into a
+ * deduped, trimmed list. The CLI flag wins over the env var when both
+ * are set — that's the convention every other dario flag uses.
+ *
+ * Edge cases:
+ *   - `--passthrough-betas=`  (explicit empty) → returns []. The
+ *     operator typed an empty value; this is the documented "clear the
+ *     env-default, run with no pinned betas" override.
+ *   - flag missing entirely → falls back to envVar.
+ *   - empty entries / whitespace-only entries / duplicates are dropped.
+ */
+export function parsePassthroughBetasFlag(args, envVar) {
+    const eqArg = args.find((a) => a.startsWith('--passthrough-betas='));
+    // When the flag is present at all (even with an empty value), it owns
+    // the result. Only fall back to the env var when the flag is absent.
+    const raw = eqArg !== undefined ? eqArg.slice('--passthrough-betas='.length) : envVar;
+    if (!raw)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const piece of raw.split(',')) {
+        const trimmed = piece.trim();
+        if (trimmed.length > 0 && !seen.has(trimmed)) {
+            seen.add(trimmed);
+            out.push(trimmed);
+        }
+    }
+    return out;
+}
+/**
+ * Parse `--log-file=<path>` or `--log-file <path>`. Returns the path
+ * string when present, undefined otherwise. An empty path (e.g.
+ * `--log-file=`) is treated as unset so the env-var fallback can apply.
+ */
+function parseLogFileFlag(args) {
+    const eqArg = args.find(a => a.startsWith('--log-file='));
+    if (eqArg) {
+        const value = eqArg.slice('--log-file='.length);
+        return value.length > 0 ? value : undefined;
+    }
+    const idx = args.indexOf('--log-file');
+    if (idx >= 0 && idx + 1 < args.length) {
+        const value = args[idx + 1];
+        if (value && !value.startsWith('-'))
+            return value;
+    }
+    return undefined;
 }
 /**
  * Parse `--max-tokens=<N|client>` + `DARIO_MAX_TOKENS` env (dario#88).
@@ -671,11 +742,30 @@ async function help() {
                              DARIO_API_KEY — with redacted previews and
                              a targeted diagnosis (dario#97 class). Use
                              --timeout-ms=N to adjust the 30s default.
+    dario doctor --bun-bootstrap
+                             One-shot Bun installer. Closes the gap
+                             between "doctor warned about Node-only TLS
+                             fingerprint" and "Bun on PATH" without
+                             copy-pasting a curl-to-shell line. Skips
+                             when Bun is already installed. Pure
+                             delegation to the official installer at
+                             bun.com — dario does not vendor or pin a
+                             Bun version.
     dario config             Print the effective configuration (port,
                              host, DARIO_API_KEY state, OAuth status,
                              pool, backends, paths) with credentials
                              redacted. Safe to paste into bug reports.
                              --json for structured output.
+    dario usage              Burn-rate summary of the running proxy's
+                             traffic (last 60 min): requests, token
+                             totals, subscription % vs. extra-usage,
+                             per-account rotation if pool mode is on.
+                             Hits /analytics on the local proxy. Works
+                             only when proxy is running; for a one-off
+                             rate-limit snapshot from Anthropic, see
+                             \`dario doctor --usage\`. --port=N to target
+                             a non-default port; --json for the raw
+                             /analytics payload.
     dario upgrade            npm install -g @askalf/dario@latest with a
                              pre-flight current-vs-latest check.
 
@@ -691,6 +781,14 @@ async function help() {
                              Loses subscription routing; use for custom agents
     --hybrid-tools           Remap to CC tools, inject sessionId/requestId/etc.
                              Keeps subscription routing for custom agents
+    --merge-tools            Send CC's canonical tools first, append the
+                             client's custom tools after (deduped by name).
+                             Model can call either; tool calls flow back
+                             unchanged. EXPERIMENTAL — Anthropic's billing
+                             classifier may flip routing on the appended
+                             tail. Validate with --verbose on the first
+                             1-2 requests. Mutually exclusive with
+                             --preserve-tools and --hybrid-tools.
     --no-auto-detect         Disable Cline/Kilo/Roo auto-preserve-tools
                              (v3.19.3 behavior). Keeps CC fingerprint
                              intact even when a text-tool client is
@@ -801,6 +899,20 @@ async function help() {
     --verbose, -v            Log all requests
     --verbose=2, -vv         Also dump redacted request bodies
                              (env: DARIO_LOG_BODIES=1)
+    --log-file=PATH          Append one JSON-ND record per completed
+                             request to PATH. Useful for backgrounded
+                             proxies where stdout is unobserved (where
+                             --verbose can't help). Secrets scrubbed,
+                             no request bodies. Env: DARIO_LOG_FILE.
+    --passthrough-betas=CSV  Beta flags to ALWAYS forward upstream
+                             regardless of CC's captured set or the
+                             client's anthropic-beta header. Bypasses
+                             the billable-beta filter. Per-account
+                             rejection cache still applies (so a flag
+                             upstream 400's gets dropped, not retried
+                             forever). Use when you know a beta works
+                             on your account but isn't in the captured
+                             template. Env: DARIO_PASSTHROUGH_BETAS.
 
   Quick start:
     dario login              # auto-detects Claude Code credentials
@@ -982,6 +1094,53 @@ async function doctor() {
     const usage = args.includes('--usage');
     const asJson = args.includes('--json');
     const authCheck = args.includes('--auth-check');
+    const bunBoot = args.includes('--bun-bootstrap');
+    if (bunBoot) {
+        // One-shot Bun installer. Closes the gap between "doctor warned
+        // about Node-only TLS fingerprint" and "Bun is on PATH" without
+        // making the user copy-paste a curl line from the README.
+        // Probe first so we don't reinstall on a Bun-already-present host.
+        const { probeBunVersion, bunBootstrap } = await import('./runtime-fingerprint.js');
+        console.log('');
+        console.log('  dario — Bun bootstrap');
+        console.log('  ─────────────────────');
+        console.log('');
+        const existing = probeBunVersion();
+        if (existing) {
+            console.log(`  Bun v${existing} already on PATH — nothing to install.`);
+            console.log('  If dario is still running on Node, the auto-relaunch was bypassed (DARIO_NO_BUN set,');
+            console.log('  or invoked through a wrapper that strips it). Re-run \`dario proxy\` directly.');
+            console.log('');
+            return;
+        }
+        console.log('  Bun is not on PATH. Running the official upstream installer:');
+        console.log('');
+        const result = await bunBootstrap();
+        console.log('');
+        if (result.exitCode === 0) {
+            // Probe again — installer may write into a directory that the
+            // current shell doesn't have on PATH yet (typical: ~/.bun/bin
+            // appended to a profile that hasn't reloaded). We can't fix that
+            // for the running shell; just call it out so the user knows what
+            // to do next.
+            const after = probeBunVersion();
+            if (after) {
+                console.log(`  Bun v${after} installed. Re-run \`dario proxy\` to auto-relaunch under it.`);
+            }
+            else {
+                console.log('  Installer reported success, but \`bun --version\` still fails from this shell.');
+                console.log('  Open a new terminal (or source the profile the installer touched), then re-run');
+                console.log('  \`dario doctor\` to confirm.');
+            }
+            console.log('');
+            return;
+        }
+        console.error(`  Installer exited with code ${result.exitCode}.`);
+        console.error(`  Manual fallback: ${result.runner}`);
+        console.error('  Or visit https://bun.com for platform-specific instructions.');
+        console.error('');
+        process.exit(result.exitCode);
+    }
     if (authCheck) {
         console.log('');
         console.log('  dario — Auth Check');
@@ -1133,6 +1292,112 @@ async function upgrade() {
     console.log('  Upgrade complete. Run `dario --version` to confirm.');
     console.log('');
 }
+/**
+ * `dario usage` — focused burn-rate summary of the running proxy's
+ * traffic. Hits `/analytics` on the local proxy (default port 3456,
+ * overridable with --port=N or DARIO_USAGE_PORT) and prints a
+ * human-readable digest: requests in the last hour, token totals,
+ * subscription % vs. extra-usage, per-account rotation if pool mode
+ * is active.
+ *
+ * When the proxy isn't running on the expected port, prints a hint
+ * pointing at `dario doctor --usage` (which fires a Haiku rate-limit
+ * probe directly to Anthropic — different purpose, but the closest
+ * substitute when there's no live proxy traffic to summarize).
+ *
+ * --json mode emits the raw /analytics payload for machine consumption
+ * (CI dashboards, status bars, the MCP `usage` tool that wraps this).
+ */
+async function usage() {
+    const portArg = args.find(a => a.startsWith('--port='));
+    const port = portArg
+        ? parseInt(portArg.split('=')[1], 10)
+        : process.env['DARIO_USAGE_PORT']
+            ? parseInt(process.env['DARIO_USAGE_PORT'], 10)
+            : 3456;
+    const asJson = args.includes('--json');
+    const url = `http://127.0.0.1:${port}/analytics`;
+    let payload = null;
+    let connectError = null;
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+        if (!res.ok) {
+            connectError = `proxy responded ${res.status}`;
+        }
+        else {
+            payload = await res.json();
+        }
+    }
+    catch (err) {
+        connectError = err instanceof Error ? err.message : String(err);
+    }
+    if (asJson) {
+        if (payload) {
+            process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+            return;
+        }
+        process.stdout.write(JSON.stringify({ error: 'proxy not reachable', port, detail: connectError }, null, 2) + '\n');
+        process.exit(1);
+    }
+    console.log('');
+    console.log('  dario — Usage');
+    console.log('  ─────────────');
+    console.log('');
+    if (!payload) {
+        console.log(`  Proxy not reachable on http://127.0.0.1:${port} (${connectError ?? 'no response'}).`);
+        console.log('  `dario usage` summarizes traffic from a running proxy (live history).');
+        console.log('  For a one-off rate-limit snapshot from Anthropic, run:');
+        console.log('');
+        console.log('    dario doctor --usage');
+        console.log('');
+        console.log('  Costs ~1 subscription request; works without a running proxy.');
+        console.log('');
+        process.exit(1);
+    }
+    // Pool mode response shape:
+    //   { window: { minutes, requests, ...stats }, allTime: {...},
+    //     perAccount, perModel, utilization, predictions }
+    // Single-account mode response shape:
+    //   { mode: 'single-account', note: '...' }
+    if (payload.mode === 'single-account') {
+        console.log('  Mode:    single-account');
+        console.log('');
+        console.log(`  ${payload.note}`);
+        console.log('');
+        console.log('  For a live snapshot of your subscription rate limit, run:');
+        console.log('    dario doctor --usage');
+        console.log('');
+        return;
+    }
+    const win = payload.window;
+    const allTime = payload.allTime;
+    const perAccount = payload.perAccount;
+    console.log('  Mode:    pool');
+    console.log(`  Window:  last ${win?.minutes ?? 60} minutes`);
+    console.log('');
+    console.log(`  Requests:        ${win?.requests ?? 0}` + (allTime ? `  (all-time: ${allTime.requests ?? 0})` : ''));
+    if (win && win.requests > 0) {
+        console.log(`  Input tokens:    ${(win.totalInputTokens ?? 0).toLocaleString()}`);
+        console.log(`  Output tokens:   ${(win.totalOutputTokens ?? 0).toLocaleString()}`);
+        console.log(`  Avg latency:     ${win.avgLatencyMs ?? 0} ms`);
+        if ((win.errorRate ?? 0) > 0) {
+            console.log(`  Error rate:      ${((win.errorRate ?? 0) * 100).toFixed(1)}%`);
+        }
+        console.log(`  Subscription %:  ${win.subscriptionPercent ?? 0}%`);
+        if ((win.estimatedCost ?? 0) > 0) {
+            console.log(`  Est. cost:       $${(win.estimatedCost ?? 0).toFixed(4)} (would-be API cost)`);
+        }
+    }
+    if (perAccount && Object.keys(perAccount).length > 0) {
+        console.log('');
+        console.log('  Per-account:');
+        const aliasWidth = Math.max(...Object.keys(perAccount).map((a) => a.length));
+        for (const [alias, stats] of Object.entries(perAccount)) {
+            console.log(`    ${alias.padEnd(aliasWidth)}  ${stats.requests} req${stats.requests === 1 ? '' : 's'}  (${stats.subscriptionPercent}% subscription)`);
+        }
+    }
+    console.log('');
+}
 // Main
 const commands = {
     login,
@@ -1148,6 +1413,7 @@ const commands = {
     doctor,
     config,
     upgrade,
+    usage,
     help,
     version,
     '--help': help,

package/dist/doctor.js

@@ -210,6 +210,38 @@ export async function runChecks(opts = {}) {
     catch (err) {
         checks.push({ status: 'fail', label: 'Template', detail: `load failed: ${err.message}` });
     }
+    // ---- Per-request overhead surfacing.
+    // The CC system prompt + tool definitions are injected into every
+    // non-passthrough request and dominate the input-token cost on small
+    // turns. Anthropic caches them after the first hit (cache_creation
+    // tokens on call 1, then cache_read on subsequent calls within the
+    // 5-min/1-hr TTL), but non-CC users routing heavy tooling get
+    // surprised by the first-request charge. Surface the size up front
+    // so they can plan.
+    //
+    // No token estimate — char counts and tool count are factual; the
+    // tokenizer ratio varies enough between prose and tool-schema JSON
+    // (compressible structural keys) that any single divisor is
+    // misleading. Operators who want the exact number can read it off
+    // their first request's `cache_creation_input_tokens` once the proxy
+    // is warm. `--usage` adds the live snapshot for those who want it.
+    try {
+        const promptChars = CC_TEMPLATE.system_prompt?.length ?? 0;
+        const toolCount = (CC_TEMPLATE.tools ?? []).length;
+        const toolChars = JSON.stringify(CC_TEMPLATE.tools ?? []).length;
+        if (promptChars > 0 || toolCount > 0) {
+            checks.push({
+                status: 'info',
+                label: 'Overhead',
+                detail: `${promptChars.toLocaleString()} chars system prompt + ${toolCount} tool defs ` +
+                    `(${toolChars.toLocaleString()} chars JSON-serialized) injected per non-passthrough ` +
+                    `request. Cached after first hit; read-cost only on subsequent calls within ` +
+                    `the 5-min/1-hr TTL. Exact token count surfaces as cache_creation_input_tokens ` +
+                    `on the first response (or run \`dario doctor --usage\`).`,
+            });
+        }
+    }
+    catch { /* don't let overhead reporting break the doctor */ }
     // ---- Template drift
     try {
         const drift = detectDrift(CC_TEMPLATE);
@@ -429,6 +461,43 @@ export async function runChecks(opts = {}) {
                     (expired > 0 ? `, ${expired} expired` : '') +
                     (aliases.length < 2 ? ' (pool activates at 2+)' : ''),
             });
+            // Next-account-in-rotation surfacing. The proxy's per-request
+            // selector picks by max headroom (with 7d_<family> per-model
+            // bucket considered when a request's model family is known);
+            // doctor doesn't know the next request's model so it reports
+            // the family-agnostic pick. That's still the right preview for
+            // operators wondering "if I send a request right now, which
+            // account gets it?" — it matches `pool.select()` with no family
+            // hint, the same call the proxy uses when no model is parsed
+            // yet (e.g. on misshapen requests). Bypassed when only one
+            // account is loaded since "rotation" doesn't apply.
+            if (aliases.length >= 2) {
+                try {
+                    const { AccountPool } = await import('./pool.js');
+                    const pool = new AccountPool();
+                    for (const acc of loaded) {
+                        pool.add(acc.alias, {
+                            accessToken: acc.accessToken,
+                            refreshToken: acc.refreshToken,
+                            expiresAt: acc.expiresAt,
+                            deviceId: acc.deviceId,
+                            accountUuid: acc.accountUuid,
+                        });
+                    }
+                    const next = pool.select();
+                    const ps = pool.status();
+                    checks.push({
+                        status: 'info',
+                        label: 'Pool routing',
+                        detail: next
+                            ? `next: ${next.alias}  (max-headroom select; ${ps.healthy}/${ps.accounts} healthy)`
+                            : `no eligible account — all rejected or near-expiry (${ps.exhausted}/${ps.accounts} exhausted)`,
+                    });
+                }
+                catch (err) {
+                    checks.push({ status: 'warn', label: 'Pool routing', detail: `check failed: ${err.message}` });
+                }
+            }
         }
     }
     catch (err) {

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.121";
+    readonly maxTested: "2.1.122";
 };
 /**
  * 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.121',
+    maxTested: '2.1.122',
 };
 /**
  * Compare two dotted-numeric version strings. Returns negative if `a<b`,

package/dist/mcp/tools.d.ts

@@ -22,6 +22,32 @@ import type { McpTool } from './protocol.js';
  * tests can substitute pure synthetic data to avoid touching network /
  * filesystem / OAuth state.
  */
+/**
+ * Shape returned by the `usage` data source. Mirrors the public subset
+ * of /analytics — keeps the MCP tool decoupled from internal Analytics
+ * record fields. Single-account mode returns `{ mode: 'single-account' }`
+ * with no stats since Analytics only collects in pool mode.
+ */
+export interface UsageSummary {
+    mode: 'pool' | 'single-account';
+    reachable: boolean;
+    port?: number;
+    detail?: string;
+    window?: {
+        minutes: number;
+        requests: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        avgLatencyMs: number;
+        errorRate: number;
+        subscriptionPercent: number;
+        estimatedCost: number;
+    };
+    perAccount?: Record<string, {
+        requests: number;
+        subscriptionPercent: number;
+    }>;
+}
 export interface ToolDataSources {
     doctor: () => Promise<Array<{
         status: string;
@@ -58,6 +84,8 @@ export interface ToolDataSources {
         templateSource: string;
         templateSchema: number | null;
     }>;
+    /** Burn-rate / consumption summary; see UsageSummary for the shape. */
+    usage: () => Promise<UsageSummary>;
     darioVersion: () => string;
 }
 export declare function buildToolRegistry(data: ToolDataSources): McpTool[];

package/dist/mcp/tools.js

@@ -131,6 +131,56 @@ export function buildToolRegistry(data) {
                 return textResult(lines.join('\n'));
             },
         },
+        {
+            name: 'usage',
+            description: 'Burn-rate summary of the running dario proxy\'s traffic over the last 60 minutes: requests, token totals, subscription % vs. extra-usage, per-account rotation if pool mode is on. Read-only — fetches /analytics from the local proxy. Returns a compact text summary; pair with the `dario usage --json` CLI for the full /analytics payload.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const u = await data.usage();
+                if (!u.reachable) {
+                    const lines = [];
+                    lines.push(`Proxy not reachable on port ${u.port ?? 3456}.`);
+                    if (u.detail)
+                        lines.push(`Detail: ${u.detail}`);
+                    lines.push('');
+                    lines.push('`usage` summarizes traffic from a running proxy. Start `dario proxy`, then re-call.');
+                    lines.push('For a one-off rate-limit snapshot, run `dario doctor --usage` (~1 subscription request).');
+                    return textResult(lines.join('\n'), true);
+                }
+                if (u.mode === 'single-account') {
+                    return textResult([
+                        'Mode: single-account',
+                        '',
+                        'Analytics history is collected only in pool mode (2+ accounts in ~/.dario/accounts/).',
+                        'For a one-off rate-limit snapshot from Anthropic, run `dario doctor --usage`.',
+                    ].join('\n'));
+                }
+                const lines = [];
+                const w = u.window;
+                lines.push('Mode:    pool');
+                lines.push(`Window:  last ${w?.minutes ?? 60} minutes`);
+                lines.push(`Requests:        ${w?.requests ?? 0}`);
+                if (w && w.requests > 0) {
+                    lines.push(`Input tokens:    ${w.totalInputTokens.toLocaleString()}`);
+                    lines.push(`Output tokens:   ${w.totalOutputTokens.toLocaleString()}`);
+                    lines.push(`Avg latency:     ${w.avgLatencyMs} ms`);
+                    if (w.errorRate > 0)
+                        lines.push(`Error rate:      ${(w.errorRate * 100).toFixed(1)}%`);
+                    lines.push(`Subscription %:  ${w.subscriptionPercent}%`);
+                    if (w.estimatedCost > 0)
+                        lines.push(`Est. cost:       $${w.estimatedCost.toFixed(4)} (would-be API cost)`);
+                }
+                if (u.perAccount && Object.keys(u.perAccount).length > 0) {
+                    lines.push('');
+                    lines.push('Per-account:');
+                    const aliasWidth = Math.max(...Object.keys(u.perAccount).map((a) => a.length));
+                    for (const [alias, stats] of Object.entries(u.perAccount)) {
+                        lines.push(`  ${alias.padEnd(aliasWidth)}  ${stats.requests} req${stats.requests === 1 ? '' : 's'}  (${stats.subscriptionPercent}% subscription)`);
+                    }
+                }
+                return textResult(lines.join('\n'));
+            },
+        },
     ];
 }
 /**
@@ -187,9 +237,63 @@ export async function buildDefaultToolRegistry() {
                 templateSchema: tmpl._schemaVersion ?? null,
             };
         },
+        usage: async () => fetchUsage(),
         darioVersion: () => pkgVersion,
     });
 }
+/**
+ * Fetch the local proxy's `/analytics` endpoint and shape it into the
+ * MCP-tool surface. Port resolution mirrors `dario usage`:
+ * DARIO_USAGE_PORT, then DARIO_PORT (proxy's own default-port env), then
+ * 3456. 3-second timeout — we don't block the MCP client on a slow
+ * proxy.
+ *
+ * Failure modes are returned as `{ reachable: false, detail }` rather
+ * than thrown, so the tool handler can present a helpful message
+ * instead of a generic protocol error.
+ */
+async function fetchUsage() {
+    const port = process.env.DARIO_USAGE_PORT
+        ? parseInt(process.env.DARIO_USAGE_PORT, 10)
+        : process.env.DARIO_PORT
+            ? parseInt(process.env.DARIO_PORT, 10)
+            : 3456;
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/analytics`, { signal: AbortSignal.timeout(3000) });
+        if (!res.ok) {
+            return { mode: 'pool', reachable: false, port, detail: `HTTP ${res.status}` };
+        }
+        const body = await res.json();
+        if (body.mode === 'single-account') {
+            return { mode: 'single-account', reachable: true, port };
+        }
+        const w = body.window;
+        return {
+            mode: 'pool',
+            reachable: true,
+            port,
+            window: {
+                minutes: w?.minutes ?? 60,
+                requests: w?.requests ?? 0,
+                totalInputTokens: w?.totalInputTokens ?? 0,
+                totalOutputTokens: w?.totalOutputTokens ?? 0,
+                avgLatencyMs: w?.avgLatencyMs ?? 0,
+                errorRate: w?.errorRate ?? 0,
+                subscriptionPercent: w?.subscriptionPercent ?? 0,
+                estimatedCost: w?.estimatedCost ?? 0,
+            },
+            perAccount: body.perAccount,
+        };
+    }
+    catch (err) {
+        return {
+            mode: 'pool',
+            reachable: false,
+            port,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 async function readDarioVersion() {
     try {
         const { readFileSync } = await import('node:fs');