@askalf/dario 3.26.0 → 3.28.0

package/dist/cli.js

@@ -220,7 +220,16 @@ async function proxy() {
     // read-to-completion pattern. Costs tokens (the response is fully
     // generated even if nobody reads it), so it's opt-in.
     const drainOnClose = args.includes('--drain-on-close') || undefined;
-    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose });
+    // --session-* knobs (v3.28, direction #1). Control the single-account
+    // session-id lifecycle: idle threshold, jitter on that threshold, hard
+    // max-age, and whether to give each upstream client its own session.
+    // All defaults preserve v3.27 behaviour exactly. Logic lives in
+    // src/session-rotation.ts; these flags just feed resolveSessionRotationConfig.
+    const sessionIdleRotateMs = parsePositiveIntFlag('--session-idle-rotate=');
+    const sessionRotateJitterMs = parsePositiveIntFlag('--session-rotate-jitter=');
+    const sessionMaxAgeMs = parsePositiveIntFlag('--session-max-age=');
+    const sessionPerClient = args.includes('--session-per-client') || undefined;
+    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient });
 }
 function parsePositiveIntFlag(prefix) {
     const found = args.find(a => a.startsWith(prefix));
@@ -461,6 +470,14 @@ async function help() {
                              operations to a named sub-agent (v3.26)
     dario subagent remove    Remove the registered sub-agent file
     dario subagent status    Show whether the sub-agent is installed
+    dario mcp                Run dario as an MCP (Model Context Protocol)
+                             server on stdio. Exposes read-only tools
+                             (doctor, status, accounts_list, backends_list,
+                             subagent_status, fingerprint_info) so MCP
+                             clients (Claude Desktop, IDEs, etc.) can
+                             inspect dario's state. No destructive ops
+                             are exposed — mutations still require the
+                             CLI. (v3.27)
     dario doctor             Print a health report: dario / Node / CC /
                              template / drift / OAuth / pool / backends
 
@@ -505,6 +522,26 @@ async function help() {
                              is fully generated even if nobody reads
                              it) for fingerprint fidelity. Bounded by
                              the 5-minute upstream timeout. (v3.25)
+    --session-idle-rotate=MS Idle ms before the single-account session
+                             id rotates (default: 900000 = 15 min).
+                             Real CC rotates once per conversation, not
+                             per call; the default matches its observed
+                             cadence. Pool mode is unaffected. (v3.28)
+    --session-rotate-jitter=MS
+                             Max additional uniform-random jitter (ms)
+                             added to the idle threshold, sampled once
+                             per session at creation. Default: 0 (off).
+                             Hides the exact threshold from long-run
+                             rotation statistics. (v3.28)
+    --session-max-age=MS     Hard cap on a session id's lifetime
+                             regardless of activity. Default: off. Set
+                             for always-on pipelines where an idle
+                             window would never trigger. (v3.28)
+    --session-per-client     Give each upstream client (keyed by
+                             x-session-id / x-client-session-id
+                             header) its own rotated session id.
+                             Default: off (single session across all
+                             clients, v3.27 behaviour). (v3.28)
     --port=PORT              Port to listen on (default: 3456)
     --host=ADDRESS           Address to bind to (default: 127.0.0.1)
                              Use 0.0.0.0 for LAN; see README for DARIO_API_KEY
@@ -647,6 +684,45 @@ async function subagent() {
     console.error('');
     process.exit(1);
 }
+async function mcp() {
+    // MCP-over-stdio: protocol frames on stdout ONLY. Any stray console.log
+    // from downstream modules (doctor / oauth / accounts helpers) would
+    // corrupt the frame stream, so redirect them to stderr defensively for
+    // the lifetime of the server. Restored in the finally block for tests /
+    // embedders that re-use the process after `dario mcp`.
+    const origLog = console.log;
+    const origInfo = console.info;
+    console.log = (...a) => console.error(...a);
+    console.info = (...a) => console.error(...a);
+    try {
+        const [{ buildDefaultToolRegistry }, { runMcpServer }] = await Promise.all([
+            import('./mcp/tools.js'),
+            import('./mcp/server.js'),
+        ]);
+        const { readFile } = await import('node:fs/promises');
+        const { fileURLToPath } = await import('node:url');
+        const here = join(fileURLToPath(import.meta.url), '..', '..');
+        let pkgVersion = 'unknown';
+        try {
+            const pkg = JSON.parse(await readFile(join(here, 'package.json'), 'utf-8'));
+            if (typeof pkg.version === 'string')
+                pkgVersion = pkg.version;
+        }
+        catch {
+            // package.json missing or malformed — fall back to 'unknown' but let
+            // the server keep running so tool responses are still usable.
+        }
+        const tools = await buildDefaultToolRegistry();
+        await runMcpServer({
+            tools,
+            server: { name: 'dario', version: pkgVersion },
+        });
+    }
+    finally {
+        console.log = origLog;
+        console.info = origInfo;
+    }
+}
 async function doctor() {
     const { runChecks, formatChecks, exitCodeFor } = await import('./doctor.js');
     console.log('');
@@ -686,6 +762,7 @@ const commands = {
     backend,
     shim,
     subagent,
+    mcp,
     doctor,
     help,
     version,

package/dist/mcp/protocol.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimal MCP (Model Context Protocol) implementation — JSON-RPC 2.0 + the
+ * subset of methods dario needs to expose as an MCP server (direction #4,
+ * v3.27). Zero-runtime-deps policy means we don't pull in
+ * `@modelcontextprotocol/sdk`; the protocol surface we need is small enough
+ * to hand-roll correctly.
+ *
+ * MCP over stdio uses newline-delimited JSON — each line on stdin is one
+ * complete JSON-RPC message; each line on stdout is one complete response
+ * or notification. That's what `parseLine` and `encodeMessage` handle.
+ *
+ * We implement three methods from the MCP spec:
+ *   initialize           — handshake, server replies with capabilities.
+ *   tools/list           — enumerate exposed tools + their JSON schemas.
+ *   tools/call           — invoke a named tool with structured arguments.
+ *
+ * Plus the standard JSON-RPC error shapes. Notifications (no-`id` messages)
+ * are accepted and, for the only one we care about (`notifications/initialized`),
+ * acknowledged silently.
+ *
+ * Kept pure on purpose so the tests can exercise every branch without any
+ * stdio — `handleMessage` takes a raw JSON-RPC payload and a tool registry
+ * and returns either a response string or null (for notifications).
+ */
+/** MCP spec revisions ship with different wire quirks; pin the one we test against. */
+export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
+/** JSON-RPC 2.0 error codes (https://www.jsonrpc.org/specification). */
+export declare const JSONRPC_ERRORS: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification;
+/** Shape of an MCP tool's content block — we only emit text content. */
+export interface McpToolContent {
+    type: 'text';
+    text: string;
+}
+export interface McpToolResult {
+    content: McpToolContent[];
+    /** If a tool ran but the operation itself failed (e.g. upstream error), set isError: true. */
+    isError?: boolean;
+}
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<McpToolResult>;
+}
+/** Server identity the client sees on `initialize`. */
+export interface ServerInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Parse one newline-delimited JSON line into a JSON-RPC message.
+ * Returns `{ ok: true, msg }` on success or `{ ok: false, error }` so the
+ * caller can emit the canonical -32700 parse-error response. Blank lines
+ * are reported as ok=false with no error — they're legal stdio framing
+ * noise, not protocol violations.
+ */
+export declare function parseLine(line: string): {
+    ok: true;
+    msg: JsonRpcMessage;
+} | {
+    ok: false;
+    error: string | null;
+};
+/**
+ * Shape a successful response. `id` is echoed from the request.
+ */
+export declare function successResponse(id: string | number, result: unknown): JsonRpcResponse;
+/**
+ * Shape an error response with a JSON-RPC error code + message. When the
+ * originating message was unparseable (no id extractable), pass `null`.
+ */
+export declare function errorResponse(id: string | number | null, code: number, message: string, data?: unknown): JsonRpcResponse;
+/** Encode a response as a newline-terminated string ready for stdout. */
+export declare function encodeMessage(msg: JsonRpcResponse): string;
+/**
+ * Core request-dispatch routine. Pure: given a parsed message + a tool
+ * registry + server identity, returns the JSON-RPC response (or null for
+ * a notification that expects no reply).
+ */
+export declare function handleMessage(msg: JsonRpcMessage, tools: McpTool[], server: ServerInfo): Promise<JsonRpcResponse | null>;

package/dist/mcp/protocol.js

@@ -0,0 +1,135 @@
+/**
+ * Minimal MCP (Model Context Protocol) implementation — JSON-RPC 2.0 + the
+ * subset of methods dario needs to expose as an MCP server (direction #4,
+ * v3.27). Zero-runtime-deps policy means we don't pull in
+ * `@modelcontextprotocol/sdk`; the protocol surface we need is small enough
+ * to hand-roll correctly.
+ *
+ * MCP over stdio uses newline-delimited JSON — each line on stdin is one
+ * complete JSON-RPC message; each line on stdout is one complete response
+ * or notification. That's what `parseLine` and `encodeMessage` handle.
+ *
+ * We implement three methods from the MCP spec:
+ *   initialize           — handshake, server replies with capabilities.
+ *   tools/list           — enumerate exposed tools + their JSON schemas.
+ *   tools/call           — invoke a named tool with structured arguments.
+ *
+ * Plus the standard JSON-RPC error shapes. Notifications (no-`id` messages)
+ * are accepted and, for the only one we care about (`notifications/initialized`),
+ * acknowledged silently.
+ *
+ * Kept pure on purpose so the tests can exercise every branch without any
+ * stdio — `handleMessage` takes a raw JSON-RPC payload and a tool registry
+ * and returns either a response string or null (for notifications).
+ */
+/** MCP spec revisions ship with different wire quirks; pin the one we test against. */
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+/** JSON-RPC 2.0 error codes (https://www.jsonrpc.org/specification). */
+export const JSONRPC_ERRORS = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};
+/**
+ * Parse one newline-delimited JSON line into a JSON-RPC message.
+ * Returns `{ ok: true, msg }` on success or `{ ok: false, error }` so the
+ * caller can emit the canonical -32700 parse-error response. Blank lines
+ * are reported as ok=false with no error — they're legal stdio framing
+ * noise, not protocol violations.
+ */
+export function parseLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+        return { ok: false, error: null };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return { ok: false, error: 'top-level not an object' };
+    const obj = parsed;
+    if (obj.jsonrpc !== '2.0')
+        return { ok: false, error: 'missing or wrong jsonrpc version' };
+    if (typeof obj.method !== 'string')
+        return { ok: false, error: 'method must be a string' };
+    return { ok: true, msg: obj };
+}
+/**
+ * Shape a successful response. `id` is echoed from the request.
+ */
+export function successResponse(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+/**
+ * Shape an error response with a JSON-RPC error code + message. When the
+ * originating message was unparseable (no id extractable), pass `null`.
+ */
+export function errorResponse(id, code, message, data) {
+    const err = { code, message };
+    if (data !== undefined)
+        err.data = data;
+    return { jsonrpc: '2.0', id, error: err };
+}
+/** Encode a response as a newline-terminated string ready for stdout. */
+export function encodeMessage(msg) {
+    return JSON.stringify(msg) + '\n';
+}
+/**
+ * Core request-dispatch routine. Pure: given a parsed message + a tool
+ * registry + server identity, returns the JSON-RPC response (or null for
+ * a notification that expects no reply).
+ */
+export async function handleMessage(msg, tools, server) {
+    const isNotification = !('id' in msg) || msg.id === undefined;
+    const id = isNotification ? null : msg.id;
+    // Notifications — no response expected. Only handle the ones we care about;
+    // silently ignore others (per JSON-RPC spec).
+    if (isNotification) {
+        return null;
+    }
+    const reqId = id;
+    switch (msg.method) {
+        case 'initialize':
+            return successResponse(reqId, {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: server,
+            });
+        case 'tools/list':
+            return successResponse(reqId, {
+                tools: tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                })),
+            });
+        case 'tools/call': {
+            const params = (msg.params ?? {});
+            if (typeof params.name !== 'string') {
+                return errorResponse(reqId, JSONRPC_ERRORS.INVALID_PARAMS, 'tools/call requires string `name`');
+            }
+            const tool = tools.find((t) => t.name === params.name);
+            if (!tool) {
+                return errorResponse(reqId, JSONRPC_ERRORS.METHOD_NOT_FOUND, `unknown tool: ${params.name}`);
+            }
+            const argsVal = params.arguments;
+            const args = (argsVal && typeof argsVal === 'object' && !Array.isArray(argsVal))
+                ? argsVal
+                : {};
+            try {
+                const result = await tool.handler(args);
+                return successResponse(reqId, result);
+            }
+            catch (err) {
+                return errorResponse(reqId, JSONRPC_ERRORS.INTERNAL_ERROR, `tool handler threw: ${err.message}`);
+            }
+        }
+        default:
+            return errorResponse(reqId, JSONRPC_ERRORS.METHOD_NOT_FOUND, `unknown method: ${msg.method}`);
+    }
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP server runtime — bridges newline-delimited JSON-RPC on stdio to the
+ * pure `handleMessage` dispatcher in `./protocol.ts`. Everything stateful
+ * (stream I/O, serialization, logging) lives here; the protocol module
+ * stays pure so its tests don't need fake streams.
+ *
+ * Why serial: for await (const line of rl) processes one line at a time
+ * and we await the handler before reading the next. MCP clients tolerate
+ * both ordered and out-of-order responses, but ordered keeps the stdio
+ * frame sequence deterministic, avoids interleaving partial writes, and
+ * — the boring reason — matches what the tests can easily assert on.
+ *
+ * Why `runMcpServer` takes injectable streams: makes the event loop
+ * testable end-to-end with a PassThrough pair, no child process needed.
+ */
+import { type McpTool, type ServerInfo } from './protocol.js';
+export interface RunServerOptions {
+    tools: McpTool[];
+    server: ServerInfo;
+    /** Stream of newline-delimited JSON-RPC messages. Defaults to `process.stdin`. */
+    stdin?: NodeJS.ReadableStream;
+    /** Sink for newline-delimited JSON-RPC responses. Defaults to `process.stdout`. */
+    stdout?: NodeJS.WritableStream;
+    /** Diagnostic channel. Defaults to `process.stderr`. */
+    stderr?: NodeJS.WritableStream;
+    /** Hook fired when a handler throws unexpectedly — primarily for tests. */
+    onError?: (err: unknown, line: string) => void;
+}
+export declare function runMcpServer(opts: RunServerOptions): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,63 @@
+/**
+ * MCP server runtime — bridges newline-delimited JSON-RPC on stdio to the
+ * pure `handleMessage` dispatcher in `./protocol.ts`. Everything stateful
+ * (stream I/O, serialization, logging) lives here; the protocol module
+ * stays pure so its tests don't need fake streams.
+ *
+ * Why serial: for await (const line of rl) processes one line at a time
+ * and we await the handler before reading the next. MCP clients tolerate
+ * both ordered and out-of-order responses, but ordered keeps the stdio
+ * frame sequence deterministic, avoids interleaving partial writes, and
+ * — the boring reason — matches what the tests can easily assert on.
+ *
+ * Why `runMcpServer` takes injectable streams: makes the event loop
+ * testable end-to-end with a PassThrough pair, no child process needed.
+ */
+import { createInterface } from 'node:readline';
+import { handleMessage, parseLine, errorResponse, encodeMessage, JSONRPC_ERRORS, } from './protocol.js';
+/**
+ * Back-pressure-aware line write. Using the callback form of
+ * `stream.write` means we wait for the chunk to drain before proceeding —
+ * on a slow stdout consumer that prevents us from buffering unboundedly.
+ */
+function writeLine(stream, chunk) {
+    return new Promise((resolve, reject) => {
+        stream.write(chunk, (err) => (err ? reject(err) : resolve()));
+    });
+}
+export async function runMcpServer(opts) {
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stdout;
+    const stderr = opts.stderr ?? process.stderr;
+    const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+    for await (const line of rl) {
+        const parsed = parseLine(line);
+        if (!parsed.ok) {
+            // Blank lines are legal framing noise, not errors — skip silently.
+            if (parsed.error === null)
+                continue;
+            await writeLine(stdout, encodeMessage(errorResponse(null, JSONRPC_ERRORS.PARSE_ERROR, `parse error: ${parsed.error}`)));
+            continue;
+        }
+        try {
+            const response = await handleMessage(parsed.msg, opts.tools, opts.server);
+            if (response !== null) {
+                await writeLine(stdout, encodeMessage(response));
+            }
+        }
+        catch (err) {
+            // `handleMessage` already wraps tool-handler errors into -32603 responses;
+            // anything reaching here is a bug in the dispatcher itself. Still, don't
+            // let it crash the server — emit a synthetic error response and log.
+            const message = err?.message ?? 'internal error';
+            const id = 'id' in parsed.msg && parsed.msg.id !== undefined
+                ? parsed.msg.id
+                : null;
+            if (opts.onError)
+                opts.onError(err, line);
+            else
+                stderr.write(`[dario mcp] unhandled: ${message}\n`);
+            await writeLine(stdout, encodeMessage(errorResponse(id, JSONRPC_ERRORS.INTERNAL_ERROR, message)));
+        }
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,69 @@
+/**
+ * MCP tool registry for the dario MCP server (v3.27, direction #4).
+ *
+ * Each tool wraps an existing dario subsystem that's already covered by
+ * its own tests, so these wrappers stay thin — fetch data, format it as
+ * text content, return. All tools are read-only. Destructive operations
+ * (login/logout, accounts add/remove, backend add/remove, proxy start)
+ * are deliberately NOT exposed: an MCP client shouldn't be able to
+ * mutate the user's dario state just by being connected, same boundary
+ * as the sub-agent prompt (v3.26).
+ *
+ * `buildToolRegistry` is a factory so tests can inject fake backends for
+ * each dario subsystem. In production, `buildDefaultToolRegistry` wires
+ * up the real dynamic imports — the imports live inside the factory so
+ * `src/mcp/protocol.ts` stays a pure module, decoupled from any of
+ * dario's heavier code paths.
+ */
+import type { McpTool } from './protocol.js';
+/**
+ * Injectable data sources for the tool handlers. Production wiring in
+ * `buildDefaultToolRegistry` fills these in with the real dario imports;
+ * tests can substitute pure synthetic data to avoid touching network /
+ * filesystem / OAuth state.
+ */
+export interface ToolDataSources {
+    doctor: () => Promise<Array<{
+        status: string;
+        label: string;
+        detail: string;
+    }>>;
+    status: () => Promise<{
+        authenticated: boolean;
+        status: string;
+        expiresIn?: string;
+        canRefresh?: boolean;
+    }>;
+    accounts: () => Promise<Array<{
+        alias: string;
+        expiresAt: number;
+    }>>;
+    backends: () => Promise<Array<{
+        name: string;
+        baseUrl: string;
+        model?: string;
+    }>>;
+    subagent: () => Promise<{
+        installed: boolean;
+        path: string;
+        fileVersion: string | null;
+        current: boolean;
+        agentsDirExists: boolean;
+    }>;
+    fingerprint: () => Promise<{
+        runtime: string;
+        runtimeVersion: string;
+        status: string;
+        detail: string;
+        templateSource: string;
+        templateSchema: number | null;
+    }>;
+    darioVersion: () => string;
+}
+export declare function buildToolRegistry(data: ToolDataSources): McpTool[];
+/**
+ * Default production wiring — imports dario's real subsystems. Kept out
+ * of `buildToolRegistry` so the registry factory stays pure over its
+ * data sources (and the unit tests don't pay for dynamic imports).
+ */
+export declare function buildDefaultToolRegistry(): Promise<McpTool[]>;

package/dist/mcp/tools.js

@@ -0,0 +1,205 @@
+/**
+ * MCP tool registry for the dario MCP server (v3.27, direction #4).
+ *
+ * Each tool wraps an existing dario subsystem that's already covered by
+ * its own tests, so these wrappers stay thin — fetch data, format it as
+ * text content, return. All tools are read-only. Destructive operations
+ * (login/logout, accounts add/remove, backend add/remove, proxy start)
+ * are deliberately NOT exposed: an MCP client shouldn't be able to
+ * mutate the user's dario state just by being connected, same boundary
+ * as the sub-agent prompt (v3.26).
+ *
+ * `buildToolRegistry` is a factory so tests can inject fake backends for
+ * each dario subsystem. In production, `buildDefaultToolRegistry` wires
+ * up the real dynamic imports — the imports live inside the factory so
+ * `src/mcp/protocol.ts` stays a pure module, decoupled from any of
+ * dario's heavier code paths.
+ */
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: 'text', text }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+export function buildToolRegistry(data) {
+    const emptyObjectSchema = { type: 'object', properties: {}, required: [] };
+    return [
+        {
+            name: 'doctor',
+            description: 'Run dario\'s health-report checks and return the formatted output. Covers: dario version, Node, platform, runtime TLS fingerprint, CC binary + compat, template source + drift, OAuth state, account pool, backends, CC sub-agent install. No side effects.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const checks = await data.doctor();
+                if (checks.length === 0)
+                    return textResult('No checks produced output.');
+                const labelWidth = checks.reduce((n, c) => Math.max(n, c.label.length), 0);
+                const prefix = {
+                    ok: '[ OK ]', warn: '[WARN]', fail: '[FAIL]', info: '[INFO]',
+                };
+                const lines = checks.map((c) => `${prefix[c.status] ?? '[????]'}  ${c.label.padEnd(labelWidth)}  ${c.detail}`);
+                const failed = checks.filter((c) => c.status === 'fail').length;
+                const warned = checks.filter((c) => c.status === 'warn').length;
+                const summary = `\n\nSummary: ${checks.length} checks — ${failed} fail, ${warned} warn`;
+                return textResult(lines.join('\n') + summary);
+            },
+        },
+        {
+            name: 'status',
+            description: 'Report the dario OAuth authentication status: whether credentials are present, valid, and when they expire. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const s = await data.status();
+                if (!s.authenticated) {
+                    const detail = s.status === 'none'
+                        ? 'No credentials — run `dario login`.'
+                        : s.status === 'expired' && s.canRefresh
+                            ? 'Credentials expired but refreshable — run `dario refresh` or `dario proxy`.'
+                            : `Not authenticated (status: ${s.status}).`;
+                    return textResult(`Authenticated: no\n${detail}`);
+                }
+                return textResult(`Authenticated: yes\nStatus: ${s.status}\nExpires in: ${s.expiresIn ?? 'unknown'}`);
+            },
+        },
+        {
+            name: 'accounts_list',
+            description: 'List the accounts configured in dario\'s multi-account pool (~/.dario/accounts/). Returns alias + token expiry per account. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const accounts = await data.accounts();
+                if (accounts.length === 0) {
+                    return textResult('No pool accounts configured. dario runs in single-account mode from ~/.dario/credentials.json.');
+                }
+                const now = Date.now();
+                const lines = accounts.map((a) => {
+                    const msLeft = Math.max(0, a.expiresAt - now);
+                    const hours = Math.floor(msLeft / 3600000);
+                    const mins = Math.floor((msLeft % 3600000) / 60000);
+                    const expiry = msLeft > 0 ? `${hours}h ${mins}m` : 'expired';
+                    return `  ${a.alias.padEnd(20)} token expires in ${expiry}`;
+                });
+                const note = accounts.length < 2
+                    ? '\n\nPool mode activates at 2+ accounts — currently single-account.'
+                    : '';
+                return textResult(`${accounts.length} account${accounts.length === 1 ? '' : 's'}:\n${lines.join('\n')}${note}`);
+            },
+        },
+        {
+            name: 'backends_list',
+            description: 'List configured OpenAI-compat backends (OpenAI, OpenRouter, Groq, LiteLLM, Ollama, etc.). Read-only — does not expose API keys.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const backends = await data.backends();
+                if (backends.length === 0) {
+                    return textResult('No OpenAI-compat backends configured. Claude subscription is the only route.');
+                }
+                const lines = backends.map((b) => `  ${b.name.padEnd(20)} ${b.baseUrl}${b.model ? `  (default model: ${b.model})` : ''}`);
+                return textResult(`${backends.length} backend${backends.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
+            },
+        },
+        {
+            name: 'subagent_status',
+            description: 'Report whether the dario CC sub-agent (~/.claude/agents/dario.md) is installed and whether it matches the running dario version. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const s = await data.subagent();
+                const lines = [];
+                lines.push(`Path: ${s.path}`);
+                lines.push(`~/.claude/agents exists: ${s.agentsDirExists ? 'yes' : 'no'}`);
+                lines.push(`Installed: ${s.installed ? `yes (v${s.fileVersion ?? 'unknown'})` : 'no'}`);
+                if (s.installed && !s.current) {
+                    lines.push('Note: file version does not match running dario — run `dario subagent install` to refresh.');
+                }
+                if (!s.installed && s.agentsDirExists) {
+                    lines.push('Install with: `dario subagent install`.');
+                }
+                return textResult(lines.join('\n'));
+            },
+        },
+        {
+            name: 'fingerprint_info',
+            description: 'Report dario\'s runtime / TLS fingerprint state: whether the proxy is running under Bun (matches CC\'s TLS stack) or Node (diverges), which template source is active (live-captured vs bundled), and the template schema version. Read-only.',
+            inputSchema: emptyObjectSchema,
+            handler: async () => {
+                const f = await data.fingerprint();
+                const lines = [];
+                lines.push(`Runtime:         ${f.runtime} ${f.runtimeVersion}`);
+                lines.push(`TLS status:      ${f.status}`);
+                lines.push(`TLS detail:      ${f.detail}`);
+                lines.push(`Template source: ${f.templateSource}`);
+                lines.push(`Template schema: v${f.templateSchema ?? '?'}`);
+                lines.push(`dario version:   ${data.darioVersion()}`);
+                return textResult(lines.join('\n'));
+            },
+        },
+    ];
+}
+/**
+ * Default production wiring — imports dario's real subsystems. Kept out
+ * of `buildToolRegistry` so the registry factory stays pure over its
+ * data sources (and the unit tests don't pay for dynamic imports).
+ */
+export async function buildDefaultToolRegistry() {
+    const [doctorMod, oauthMod, accountsMod, backendMod, subagentMod, runtimeMod, templateMod, pkgVersion] = await Promise.all([
+        import('../doctor.js'),
+        import('../oauth.js'),
+        import('../accounts.js'),
+        import('../openai-backend.js'),
+        import('../subagent.js'),
+        import('../runtime-fingerprint.js'),
+        import('../cc-template.js'),
+        readDarioVersion(),
+    ]);
+    return buildToolRegistry({
+        doctor: async () => {
+            const checks = await doctorMod.runChecks();
+            return checks.map((c) => ({
+                status: c.status,
+                label: c.label,
+                detail: c.detail,
+            }));
+        },
+        status: async () => oauthMod.getStatus(),
+        accounts: async () => {
+            const loaded = await accountsMod.loadAllAccounts();
+            return loaded.map((a) => ({
+                alias: a.alias,
+                expiresAt: a.expiresAt,
+            }));
+        },
+        backends: async () => {
+            const backends = await backendMod.listBackends();
+            return backends.map((b) => ({
+                name: b.name,
+                baseUrl: b.baseUrl,
+                model: b.model,
+            }));
+        },
+        subagent: async () => subagentMod.loadSubagentStatus(),
+        fingerprint: async () => {
+            const rt = runtimeMod.detectRuntimeFingerprint();
+            const tmpl = templateMod.CC_TEMPLATE;
+            return {
+                runtime: rt.runtime,
+                runtimeVersion: rt.runtimeVersion,
+                status: rt.status,
+                detail: rt.detail,
+                templateSource: tmpl._source ?? 'unknown',
+                templateSchema: tmpl._schemaVersion ?? null,
+            };
+        },
+        darioVersion: () => pkgVersion,
+    });
+}
+async function readDarioVersion() {
+    try {
+        const { readFileSync } = await import('node:fs');
+        const { fileURLToPath } = await import('node:url');
+        const { dirname, join } = await import('node:path');
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/proxy.d.ts

@@ -16,6 +16,10 @@ interface ProxyOptions {
     pacingMinMs?: number;
     pacingJitterMs?: number;
     drainOnClose?: boolean;
+    sessionIdleRotateMs?: number;
+    sessionRotateJitterMs?: number;
+    sessionMaxAgeMs?: number;
+    sessionPerClient?: boolean;
 }
 export declare function sanitizeError(err: unknown): string;
 export declare function startProxy(opts?: ProxyOptions): Promise<void>;

package/dist/proxy.js

@@ -97,11 +97,17 @@ function extractFirstUserMessage(body) {
 //
 //   v3.19 keeps the id stable through a conversation window and rotates
 //   only after an idle gap long enough to credibly indicate a new
-//   conversation (SESSION_IDLE_ROTATE_MS). Pool mode still uses the
-//   per-account identity.sessionId (stable across the account's lifetime).
+//   conversation. Pool mode still uses the per-account identity.sessionId
+//   (stable across the account's lifetime).
+//
+//   v3.28 generalises the single hardcoded 15-min window into a tunable
+//   registry (see src/session-rotation.ts) with optional jitter, max-age,
+//   and per-client keying. SESSION_ID below is kept only as a mirror of
+//   the default single-account session so out-of-band consumers (presence
+//   ping, diagnostic logs) can read the most recent id without going
+//   through the registry. It's refreshed after every dispatch-path call
+//   that assigns a new id.
 let SESSION_ID = randomUUID();
-let SESSION_LAST_USED = 0;
-const SESSION_IDLE_ROTATE_MS = 15 * 60 * 1000;
 const OS_NAME = platform === 'win32' ? 'Windows' : platform === 'darwin' ? 'MacOS' : 'Linux';
 // Claude Code device identity — required for Max plan billing classification.
 // Without metadata.user_id, Anthropic classifies requests as third-party and
@@ -593,6 +599,22 @@ export async function startProxy(opts = {}) {
     if (verbose) {
         console.log(`[dario] drain-on-close: ${drainOnClose ? 'enabled' : 'disabled'}`);
     }
+    // Session-ID lifecycle (v3.28, direction #1). Replaces the v3.27 hardcoded
+    // 15-minute idle window with a tunable registry: idle threshold, jitter on
+    // that threshold, optional hard max-age, and optional per-client keying.
+    // Defaults preserve v3.27 behavior exactly. See src/session-rotation.ts.
+    const { SessionRegistry, resolveSessionRotationConfig } = await import('./session-rotation.js');
+    const sessionCfg = resolveSessionRotationConfig({
+        idleRotateMs: opts.sessionIdleRotateMs,
+        jitterMs: opts.sessionRotateJitterMs,
+        maxAgeMs: opts.sessionMaxAgeMs,
+        perClient: opts.sessionPerClient,
+    });
+    const sessionRegistry = new SessionRegistry(sessionCfg, () => randomUUID());
+    if (verbose) {
+        const maxAge = sessionCfg.maxAgeMs !== undefined ? `${sessionCfg.maxAgeMs}ms` : 'off';
+        console.log(`[dario] session: idle=${sessionCfg.idleRotateMs}ms jitter=${sessionCfg.jitterMs}ms maxAge=${maxAge} perClient=${sessionCfg.perClient}`);
+    }
     // Optional proxy authentication — pre-encode key buffer for performance
     const apiKey = process.env.DARIO_API_KEY;
     const apiKeyBuf = apiKey ? Buffer.from(apiKey) : null;
@@ -958,6 +980,9 @@ export async function startProxy(opts = {}) {
             // selection toward one we already paid cache cost on — passthrough
             // users aren't doing template replay anyway).
             let stickyKey = null;
+            // Outbound session id resolved once — either inside the template build
+            // (so body metadata matches) or below for passthrough (no body build).
+            let preBodySessionId;
             // Request context for hybrid-mode field injection (#33). Built once
             // per request from incoming headers so the reverse mapper can fill
             // client-declared fields like `sessionId` that CC's schema doesn't
@@ -1010,9 +1035,28 @@ export async function startProxy(opts = {}) {
                                 }
                             }
                         }
+                        // Resolve the outbound session id before the body build so the
+                        // metadata.session_id in the CC body and the x-claude-code-session-id
+                        // header both use the same value. v3.27 consulted SESSION_ID twice
+                        // with rotation between the reads, so on rotation events body and
+                        // header disagreed — harmless for plain operation but a fingerprint
+                        // in its own right.
+                        if (poolAccount) {
+                            preBodySessionId = poolAccount.identity.sessionId;
+                        }
+                        else {
+                            const clientKey = req.headers['x-session-id']
+                                ?? req.headers['x-client-session-id'];
+                            const assigned = sessionRegistry.getOrCreate(clientKey, Date.now());
+                            preBodySessionId = assigned.sessionId;
+                            SESSION_ID = assigned.sessionId;
+                            if (verbose && assigned.rotated && assigned.reason !== 'rotate-new') {
+                                console.log(`[dario] #${requestCount} session: rotate (${assigned.reason})`);
+                            }
+                        }
                         const bodyIdentity = poolAccount
                             ? poolAccount.identity
-                            : { deviceId: identity.deviceId, accountUuid: identity.accountUuid, sessionId: SESSION_ID };
+                            : { deviceId: identity.deviceId, accountUuid: identity.accountUuid, sessionId: preBodySessionId };
                         const { body: ccBody, toolMap, detectedClient } = buildCCRequest(r, billingTag, CACHE_1H, bodyIdentity, {
                             preserveTools: opts.preserveTools ?? false,
                             hybridTools: opts.hybridTools ?? false,
@@ -1102,18 +1146,30 @@ export async function startProxy(opts = {}) {
             }
             lastRequestTime = Date.now();
             // Session ID: pool mode uses the per-account identity.sessionId (stable
-            // per account). Single-account mode keeps SESSION_ID stable through
-            // active conversations and rotates only after an idle gap that looks
-            // like a new conversation — matches CC's observed cadence (see note
-            // at SESSION_ID declaration).
-            if (!poolAccount) {
-                const nowTs = Date.now();
-                if (SESSION_LAST_USED === 0 || nowTs - SESSION_LAST_USED > SESSION_IDLE_ROTATE_MS) {
-                    SESSION_ID = randomUUID();
+            // per account). Single-account mode delegates to the session registry
+            // (src/session-rotation.ts) which applies the configured idle / jitter /
+            // max-age / per-client policy. Resolution happens earlier, at body-build
+            // time, so the CC body's metadata.session_id and the outbound
+            // x-claude-code-session-id header always agree. preBodySessionId holds
+            // the template-build value; in passthrough mode (no template build)
+            // the registry is consulted here instead.
+            let outboundSessionId;
+            if (poolAccount) {
+                outboundSessionId = poolAccount.identity.sessionId;
+            }
+            else if (preBodySessionId !== undefined) {
+                outboundSessionId = preBodySessionId;
+            }
+            else {
+                const clientKey = req.headers['x-session-id']
+                    ?? req.headers['x-client-session-id'];
+                const assigned = sessionRegistry.getOrCreate(clientKey, Date.now());
+                outboundSessionId = assigned.sessionId;
+                SESSION_ID = assigned.sessionId;
+                if (verbose && assigned.rotated && assigned.reason !== 'rotate-new') {
+                    console.log(`[dario] #${requestCount} session: rotate (${assigned.reason})`);
                 }
-                SESSION_LAST_USED = nowTs;
             }
-            const outboundSessionId = poolAccount ? poolAccount.identity.sessionId : SESSION_ID;
             const headers = {
                 ...staticHeaders,
                 'Authorization': `Bearer ${accessToken}`,

package/dist/session-rotation.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Session-ID lifecycle (v3.28, direction #1 — interactive-side rotation).
+ *
+ * Every outbound request to Anthropic carries a session identifier in the
+ * CC request body's metadata. Real Claude Code holds that id stable through
+ * a conversation and mints a new one when the user returns after an idle
+ * gap — roughly "one id per conversation", not per HTTP call. A proxy that
+ * rotates per-request looks synthetic; one that never rotates looks equally
+ * synthetic over long sessions. v3.19 tightened the per-request leak into a
+ * single hardcoded 15-minute idle window; this module generalises that into
+ * a registry so operators can tune the behaviour and so the multi-client
+ * case (dario fanning multiple UIs through one proxy) stops sharing one id.
+ *
+ * Three independent knobs:
+ *
+ *   idleRotateMs — the v3.19 behaviour: rotate after this many ms of no
+ *                  traffic on a given session. Default 15 min preserves
+ *                  v3.27 exactly when the other knobs stay at defaults.
+ *
+ *   jitterMs     — the observable idle threshold for a given session is
+ *                  idleRotateMs + U(0, jitterMs), sampled once at session
+ *                  creation. A zero-jitter proxy rotates at exactly the
+ *                  same interval every time; adding jitter means the floor
+ *                  can't be inferred from long-run rotation cadence.
+ *
+ *   maxAgeMs     — hard cap on a session's total lifetime regardless of
+ *                  activity. Optional (undefined disables). A chatty
+ *                  always-on pipeline would otherwise keep one session id
+ *                  alive for days; real CC conversations don't.
+ *
+ *   perClient    — when true, the registry keys sessions by the caller's
+ *                  `x-session-id` / `x-client-session-id` header so two
+ *                  upstream UIs talking to one dario don't collapse onto
+ *                  a single session id. Default false preserves v3.27
+ *                  single-account semantics.
+ *
+ * Pure logic (decideSessionRotation) is separated from the stateful cache
+ * (SessionRegistry) so tests can walk every decision branch without Maps,
+ * timers, or UUID sources. The proxy injects a `() => string` id factory
+ * (randomUUID) and `() => number` rng so both are swappable in tests.
+ *
+ * Pool mode is unaffected — each account carries a stable identity.sessionId
+ * for its lifetime, and the caller doesn't consult this registry. This
+ * module only governs the single-account SESSION_ID slot.
+ */
+export interface SessionRotationConfig {
+    /** Idle threshold in ms: if no traffic for this long, the session rotates on the next request. */
+    idleRotateMs: number;
+    /** Max additional uniform-random ms added to the idle threshold at session creation. Pass 0 to disable. */
+    jitterMs: number;
+    /** Optional hard cap on session lifetime in ms. Undefined = no cap. */
+    maxAgeMs?: number;
+    /** When true, key sessions by client header so multiple upstreams get distinct ids. Default false. */
+    perClient: boolean;
+}
+export interface SessionEntry {
+    /** The session id sent to Anthropic in the outbound body. */
+    upstreamSessionId: string;
+    /** Wall-clock creation time (ms since epoch). */
+    createdAt: number;
+    /** Wall-clock time of last outbound use (ms since epoch). */
+    lastUsedAt: number;
+    /** Jitter offset sampled once at creation; added to cfg.idleRotateMs to get this session's effective idle threshold. */
+    idleJitterOffsetMs: number;
+}
+export type RotationDecision = 'keep' | 'rotate-new' | 'rotate-idle' | 'rotate-age';
+/**
+ * Pure decision: should the given entry be rotated at `now`?
+ *
+ * Returns 'rotate-new' when no entry exists yet (first use for this key).
+ * Returns 'rotate-idle' when traffic has been silent for longer than this
+ * entry's sampled threshold. Returns 'rotate-age' when the entry's
+ * absolute lifetime exceeds cfg.maxAgeMs (when set). Otherwise 'keep'.
+ *
+ * Idle is checked before age so an idle-but-young session rotates on a
+ * fresh conversation boundary rather than churning mid-conversation at
+ * exactly its max-age. Negative config values are clamped to 0 (lenient:
+ * a typoed flag should behave like "rotate eagerly", not crash startup).
+ */
+export declare function decideSessionRotation(entry: SessionEntry | undefined, now: number, cfg: SessionRotationConfig): RotationDecision;
+/** Result of SessionRegistry.getOrCreate — both the id to send and why it was chosen. */
+export interface RegistryResult {
+    sessionId: string;
+    rotated: boolean;
+    reason: RotationDecision;
+}
+/**
+ * Per-client session cache with rotation + LRU eviction.
+ *
+ * Not concurrency-safe — the proxy's dispatch loop is single-threaded
+ * JavaScript and call sites are serialized by the event loop. The
+ * registry is intentionally a plain Map, not a TTL cache, because
+ * rotation timing is part of the observable behaviour we're modelling
+ * and a background sweeper would add a separate dimension (WHEN entries
+ * disappear) that doesn't exist in a real CC client.
+ *
+ * maxEntries defaults to 1024 — more than enough for any reasonable
+ * fan-out while capping memory growth against a pathological client
+ * that sends a fresh session header on every request.
+ */
+export declare class SessionRegistry {
+    private readonly cfg;
+    private readonly newId;
+    private readonly rng;
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(cfg: SessionRotationConfig, newId: () => string, rng?: () => number, maxEntries?: number);
+    /**
+     * Resolve the outbound session id for a given client key at time `now`.
+     *
+     * `clientKey` is the caller-side session header when cfg.perClient is
+     * true, and ignored (replaced with 'default') when perClient is false.
+     * Callers pass the raw header value and let the registry decide —
+     * otherwise flipping perClient at runtime would require threading
+     * the decision to every call site.
+     *
+     * Updates lastUsedAt on the entry (whether kept or freshly minted),
+     * and nudges the entry to the end of the insertion-order map so
+     * eviction under maxEntries pressure is LRU.
+     */
+    getOrCreate(clientKey: string | undefined, now: number): RegistryResult;
+    /**
+     * Read the current id for a client key without touching lastUsedAt.
+     *
+     * Used by out-of-band consumers (e.g. presence pings) that want to
+     * reflect the most recently assigned session id but must not count
+     * as activity for rotation purposes. Returns undefined if no entry.
+     */
+    peek(clientKey: string | undefined): string | undefined;
+    size(): number;
+    clear(): void;
+    private evictIfOverCap;
+}
+/**
+ * Resolve a SessionRotationConfig from explicit options, env vars, and defaults.
+ *
+ * Precedence (highest first):
+ *   1. Explicit argument (typically from CLI flag)
+ *   2. DARIO_SESSION_IDLE_ROTATE_MS / DARIO_SESSION_JITTER_MS /
+ *      DARIO_SESSION_MAX_AGE_MS / DARIO_SESSION_PER_CLIENT env vars
+ *   3. Defaults: idleRotateMs=15min, jitterMs=0, maxAgeMs=undefined,
+ *      perClient=false — exactly matches the hardcoded v3.27 behaviour.
+ *
+ * Invalid numeric strings fall through to the next source. For perClient,
+ * '1' / 'true' / 'yes' (case-insensitive) enable; anything else stays at
+ * the explicit or default value.
+ */
+export declare function resolveSessionRotationConfig(explicit?: {
+    idleRotateMs?: number;
+    jitterMs?: number;
+    maxAgeMs?: number;
+    perClient?: boolean;
+}, env?: NodeJS.ProcessEnv): SessionRotationConfig;

package/dist/session-rotation.js

@@ -0,0 +1,214 @@
+/**
+ * Session-ID lifecycle (v3.28, direction #1 — interactive-side rotation).
+ *
+ * Every outbound request to Anthropic carries a session identifier in the
+ * CC request body's metadata. Real Claude Code holds that id stable through
+ * a conversation and mints a new one when the user returns after an idle
+ * gap — roughly "one id per conversation", not per HTTP call. A proxy that
+ * rotates per-request looks synthetic; one that never rotates looks equally
+ * synthetic over long sessions. v3.19 tightened the per-request leak into a
+ * single hardcoded 15-minute idle window; this module generalises that into
+ * a registry so operators can tune the behaviour and so the multi-client
+ * case (dario fanning multiple UIs through one proxy) stops sharing one id.
+ *
+ * Three independent knobs:
+ *
+ *   idleRotateMs — the v3.19 behaviour: rotate after this many ms of no
+ *                  traffic on a given session. Default 15 min preserves
+ *                  v3.27 exactly when the other knobs stay at defaults.
+ *
+ *   jitterMs     — the observable idle threshold for a given session is
+ *                  idleRotateMs + U(0, jitterMs), sampled once at session
+ *                  creation. A zero-jitter proxy rotates at exactly the
+ *                  same interval every time; adding jitter means the floor
+ *                  can't be inferred from long-run rotation cadence.
+ *
+ *   maxAgeMs     — hard cap on a session's total lifetime regardless of
+ *                  activity. Optional (undefined disables). A chatty
+ *                  always-on pipeline would otherwise keep one session id
+ *                  alive for days; real CC conversations don't.
+ *
+ *   perClient    — when true, the registry keys sessions by the caller's
+ *                  `x-session-id` / `x-client-session-id` header so two
+ *                  upstream UIs talking to one dario don't collapse onto
+ *                  a single session id. Default false preserves v3.27
+ *                  single-account semantics.
+ *
+ * Pure logic (decideSessionRotation) is separated from the stateful cache
+ * (SessionRegistry) so tests can walk every decision branch without Maps,
+ * timers, or UUID sources. The proxy injects a `() => string` id factory
+ * (randomUUID) and `() => number` rng so both are swappable in tests.
+ *
+ * Pool mode is unaffected — each account carries a stable identity.sessionId
+ * for its lifetime, and the caller doesn't consult this registry. This
+ * module only governs the single-account SESSION_ID slot.
+ */
+/**
+ * Pure decision: should the given entry be rotated at `now`?
+ *
+ * Returns 'rotate-new' when no entry exists yet (first use for this key).
+ * Returns 'rotate-idle' when traffic has been silent for longer than this
+ * entry's sampled threshold. Returns 'rotate-age' when the entry's
+ * absolute lifetime exceeds cfg.maxAgeMs (when set). Otherwise 'keep'.
+ *
+ * Idle is checked before age so an idle-but-young session rotates on a
+ * fresh conversation boundary rather than churning mid-conversation at
+ * exactly its max-age. Negative config values are clamped to 0 (lenient:
+ * a typoed flag should behave like "rotate eagerly", not crash startup).
+ */
+export function decideSessionRotation(entry, now, cfg) {
+    if (!entry)
+        return 'rotate-new';
+    const idleBase = Math.max(0, cfg.idleRotateMs);
+    const idleThreshold = idleBase + Math.max(0, entry.idleJitterOffsetMs);
+    if (now - entry.lastUsedAt > idleThreshold)
+        return 'rotate-idle';
+    if (cfg.maxAgeMs !== undefined && cfg.maxAgeMs > 0 && now - entry.createdAt > cfg.maxAgeMs) {
+        return 'rotate-age';
+    }
+    return 'keep';
+}
+/**
+ * Per-client session cache with rotation + LRU eviction.
+ *
+ * Not concurrency-safe — the proxy's dispatch loop is single-threaded
+ * JavaScript and call sites are serialized by the event loop. The
+ * registry is intentionally a plain Map, not a TTL cache, because
+ * rotation timing is part of the observable behaviour we're modelling
+ * and a background sweeper would add a separate dimension (WHEN entries
+ * disappear) that doesn't exist in a real CC client.
+ *
+ * maxEntries defaults to 1024 — more than enough for any reasonable
+ * fan-out while capping memory growth against a pathological client
+ * that sends a fresh session header on every request.
+ */
+export class SessionRegistry {
+    cfg;
+    newId;
+    rng;
+    maxEntries;
+    entries = new Map();
+    constructor(cfg, newId, rng = Math.random, maxEntries = 1024) {
+        this.cfg = cfg;
+        this.newId = newId;
+        this.rng = rng;
+        this.maxEntries = maxEntries;
+    }
+    /**
+     * Resolve the outbound session id for a given client key at time `now`.
+     *
+     * `clientKey` is the caller-side session header when cfg.perClient is
+     * true, and ignored (replaced with 'default') when perClient is false.
+     * Callers pass the raw header value and let the registry decide —
+     * otherwise flipping perClient at runtime would require threading
+     * the decision to every call site.
+     *
+     * Updates lastUsedAt on the entry (whether kept or freshly minted),
+     * and nudges the entry to the end of the insertion-order map so
+     * eviction under maxEntries pressure is LRU.
+     */
+    getOrCreate(clientKey, now) {
+        const key = this.cfg.perClient ? (clientKey && clientKey.length > 0 ? clientKey : 'default') : 'default';
+        const existing = this.entries.get(key);
+        const decision = decideSessionRotation(existing, now, this.cfg);
+        if (decision === 'keep' && existing) {
+            existing.lastUsedAt = now;
+            // Re-insert to refresh LRU position.
+            this.entries.delete(key);
+            this.entries.set(key, existing);
+            return { sessionId: existing.upstreamSessionId, rotated: false, reason: 'keep' };
+        }
+        const jitterOffset = this.cfg.jitterMs > 0 ? Math.floor(this.rng() * this.cfg.jitterMs) : 0;
+        const entry = {
+            upstreamSessionId: this.newId(),
+            createdAt: now,
+            lastUsedAt: now,
+            idleJitterOffsetMs: jitterOffset,
+        };
+        this.entries.set(key, entry);
+        this.evictIfOverCap();
+        return { sessionId: entry.upstreamSessionId, rotated: true, reason: decision };
+    }
+    /**
+     * Read the current id for a client key without touching lastUsedAt.
+     *
+     * Used by out-of-band consumers (e.g. presence pings) that want to
+     * reflect the most recently assigned session id but must not count
+     * as activity for rotation purposes. Returns undefined if no entry.
+     */
+    peek(clientKey) {
+        const key = this.cfg.perClient ? (clientKey && clientKey.length > 0 ? clientKey : 'default') : 'default';
+        return this.entries.get(key)?.upstreamSessionId;
+    }
+    size() {
+        return this.entries.size;
+    }
+    clear() {
+        this.entries.clear();
+    }
+    evictIfOverCap() {
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+}
+/**
+ * Resolve a SessionRotationConfig from explicit options, env vars, and defaults.
+ *
+ * Precedence (highest first):
+ *   1. Explicit argument (typically from CLI flag)
+ *   2. DARIO_SESSION_IDLE_ROTATE_MS / DARIO_SESSION_JITTER_MS /
+ *      DARIO_SESSION_MAX_AGE_MS / DARIO_SESSION_PER_CLIENT env vars
+ *   3. Defaults: idleRotateMs=15min, jitterMs=0, maxAgeMs=undefined,
+ *      perClient=false — exactly matches the hardcoded v3.27 behaviour.
+ *
+ * Invalid numeric strings fall through to the next source. For perClient,
+ * '1' / 'true' / 'yes' (case-insensitive) enable; anything else stays at
+ * the explicit or default value.
+ */
+export function resolveSessionRotationConfig(explicit = {}, env = process.env) {
+    const idleRotateMs = pickNonNegativeInt(explicit.idleRotateMs, env.DARIO_SESSION_IDLE_ROTATE_MS) ?? 15 * 60 * 1000;
+    const jitterMs = pickNonNegativeInt(explicit.jitterMs, env.DARIO_SESSION_JITTER_MS) ?? 0;
+    const maxAgeMs = pickPositiveInt(explicit.maxAgeMs, env.DARIO_SESSION_MAX_AGE_MS);
+    const perClient = pickBool(explicit.perClient, env.DARIO_SESSION_PER_CLIENT) ?? false;
+    return { idleRotateMs, jitterMs, maxAgeMs, perClient };
+}
+function pickNonNegativeInt(...candidates) {
+    for (const c of candidates) {
+        if (c === undefined || c === null || c === '')
+            continue;
+        const n = typeof c === 'number' ? c : parseInt(c, 10);
+        if (Number.isFinite(n) && n >= 0)
+            return Math.floor(n);
+    }
+    return undefined;
+}
+function pickPositiveInt(...candidates) {
+    for (const c of candidates) {
+        if (c === undefined || c === null || c === '')
+            continue;
+        const n = typeof c === 'number' ? c : parseInt(c, 10);
+        if (Number.isFinite(n) && n > 0)
+            return Math.floor(n);
+    }
+    return undefined;
+}
+function pickBool(...candidates) {
+    for (const c of candidates) {
+        if (c === undefined || c === null)
+            continue;
+        if (typeof c === 'boolean')
+            return c;
+        const s = c.trim().toLowerCase();
+        if (s === '')
+            continue;
+        if (s === '1' || s === 'true' || s === 'yes' || s === 'on')
+            return true;
+        if (s === '0' || s === 'false' || s === 'no' || s === 'off')
+            return false;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "description": "A local LLM router. One endpoint, every provider — Claude subscriptions, OpenAI, OpenRouter, Groq, local LiteLLM, any OpenAI-compat endpoint — your tools don't need to change.",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "build": "tsc && cp src/cc-template-data.json dist/ && node -e \"require('fs').mkdirSync('dist/shim',{recursive:true})\" && cp src/shim/runtime.cjs dist/shim/",
-    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/tool-schema-contract.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/pool-sticky.mjs && node test/sealed-pool.mjs && node test/live-fingerprint.mjs && node test/shim-runtime.mjs && node test/shim-e2e.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/subagent.mjs && node test/drift-detection.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs",
+    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.mjs && node test/tool-schema-contract.mjs && node test/scrub-paths.mjs && node test/provider-prefix.mjs && node test/analytics-recording.mjs && node test/analytics-billing-bucket.mjs && node test/failover-429.mjs && node test/pool-sticky.mjs && node test/sealed-pool.mjs && node test/live-fingerprint.mjs && node test/shim-runtime.mjs && node test/shim-e2e.mjs && node test/proxy-header-order.mjs && node test/proxy-body-order.mjs && node test/runtime-fingerprint.mjs && node test/pacing.mjs && node test/stream-drain.mjs && node test/subagent.mjs && node test/mcp-protocol.mjs && node test/mcp-tools.mjs && node test/mcp-e2e.mjs && node test/session-rotation.mjs && node test/drift-detection.mjs && node test/compat-range.mjs && node test/doctor-formatter.mjs && node test/atomic-write.mjs && node test/account-refresh-singleflight.mjs && node test/streaming-edge-cases.mjs && node test/client-detection.mjs && node test/manual-oauth-flow.mjs && node test/scrub-template.mjs",
     "audit": "npm audit --production --audit-level=high",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",