@askalf/dario 3.27.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));
@@ -513,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

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.27.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/mcp-protocol.mjs && node test/mcp-tools.mjs && node test/mcp-e2e.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",