@askalf/dario 3.30.8 → 3.30.10

package/README.md

@@ -443,12 +443,102 @@ const msg = await client.messages.create({
 
 ### OpenAI-compatible tools (Cursor, Continue, Aider, LiteLLM, …)
 
+Any tool that accepts an OpenAI-compatible base URL + API key works with dario. The universal env-var setup:
+
 ```bash
 export OPENAI_BASE_URL=http://localhost:3456/v1
 export OPENAI_API_KEY=dario
 ```
 
-Any tool that accepts an OpenAI base URL works. Use Claude model names (`claude-opus-4-7`, `opus`, `sonnet`, `haiku`) for the Claude backend, or GPT-family names for the configured OpenAI-compat backend.
+Use Claude model names (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`, or shortcuts `opus` / `sonnet` / `haiku`) for the Claude subscription backend, or GPT-family / Llama / any-other-model names for your configured OpenAI-compat backends.
+
+Some tools use env vars (above works as-is); others want settings-UI entries:
+
+#### Cursor
+
+1. **Cmd/Ctrl + ,** to open Settings → **Models**
+2. Under the **OpenAI API Key** section:
+   - Check **Override OpenAI Base URL**: `http://localhost:3456/v1`
+   - API key: `dario`
+3. Under the **Model Names** section (or the Add Model button):
+   - Add `claude-sonnet-4-6`
+   - Add `claude-opus-4-7` (premium)
+   - Add `claude-haiku-4-5` (cheap)
+4. Select one of the new models in the chat input's model picker.
+
+Cursor now routes those model names through dario → your Claude Max / Pro subscription. `gpt-*` and `o*` model names still route through Cursor's default OpenAI path — dario doesn't interfere with non-Claude traffic unless you point Cursor's base URL at it exclusively.
+
+#### Continue.dev
+
+In `~/.continue/config.yaml` (or the Continue settings UI, which edits the same file):
+
+```yaml
+models:
+  - name: Claude Sonnet (dario)
+    provider: anthropic
+    model: claude-sonnet-4-6
+    apiBase: http://localhost:3456
+    apiKey: dario
+  - name: Claude Opus (dario)
+    provider: anthropic
+    model: claude-opus-4-7
+    apiBase: http://localhost:3456
+    apiKey: dario
+```
+
+`provider: anthropic` + `apiBase: http://localhost:3456` points Continue's Anthropic SDK path at dario instead of `api.anthropic.com`. dario runs the full Claude Code wire replay on the outbound path.
+
+#### Aider
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario
+aider --model sonnet
+```
+
+Aider's Anthropic path honors `ANTHROPIC_BASE_URL` directly. `--model opus`, `--model haiku`, or any explicit `claude-*` model name works.
+
+#### Cline / Roo Code / Kilo Code
+
+Cline and its forks use a UI-based "API Provider" dropdown. Pick **Anthropic** as the provider and fill in:
+
+- **API Key**: `dario`
+- **Anthropic Base URL**: `http://localhost:3456`
+- **Model**: `claude-sonnet-4-6` / `claude-opus-4-7` / `claude-haiku-4-5`
+
+Cline's tool-invocation protocol is XML-based (`<execute_command>`, `<write_to_file>`, etc.), not Anthropic's tool-use format. Dario auto-detects Cline-family clients via system-prompt fingerprint and flips into preserve-tools mode automatically — Cline's own tool schema passes through to Anthropic, your commands route back to Cline's parser. No flag required. Override: `--no-auto-detect` if you'd rather force the CC fingerprint and deal with the parser mismatch yourself (see [Agent compatibility](#agent-compatibility)).
+
+#### Zed
+
+Zed's Anthropic provider config (`~/.config/zed/settings.json` or Cmd/Ctrl+,):
+
+```json
+{
+  "language_models": {
+    "anthropic": {
+      "api_url": "http://localhost:3456",
+      "version": "2023-06-01"
+    }
+  }
+}
+```
+
+Set the `ANTHROPIC_API_KEY` env var to `dario` before launching Zed. Model picker then shows Claude models routed through your subscription.
+
+#### OpenHands
+
+```bash
+export LLM_BASE_URL=http://localhost:3456
+export LLM_API_KEY=dario
+export LLM_MODEL=anthropic/claude-sonnet-4-6
+python -m openhands.core.main -t "task description"
+```
+
+Prefix the model with `anthropic/` so LiteLLM (OpenHands' inner routing layer) knows to hit the Anthropic path, which dario is now fronting.
+
+#### Everything else
+
+If your tool isn't listed, check whether it reads `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` from the environment. Most do. For tools that don't, look in their settings for "Base URL" / "API URL" / "Endpoint" / "OpenAI-compatible endpoint" — all of those map to dario's `http://localhost:3456` (Anthropic-protocol) or `http://localhost:3456/v1` (OpenAI-protocol). If the tool only accepts `https://`, you'll need a loopback TLS shim (out of scope here — open an issue if you need one for a specific tool).
 
 ### curl
 

package/dist/cc-template.d.ts

@@ -170,6 +170,20 @@ export interface RequestContext {
  * Replaces the entire request structure — tools, fields, ordering — with
  * what real CC sends. Only the conversation content is preserved.
  */
+/** Valid values for the `--effort` flag. `'client'` passes through the client's own `output_config.effort` (falling back to `'high'` if the client didn't send one). dario#87. */
+export type EffortValue = 'low' | 'medium' | 'high' | 'xhigh' | 'client';
+export declare const VALID_EFFORT_VALUES: ReadonlyArray<EffortValue>;
+/**
+ * Resolve the outbound `output_config.effort` value.
+ *
+ *   undefined / 'high' → 'high' (current default, matches CC 2.1.116 wire value)
+ *   'low' / 'medium' / 'xhigh' → pin to that value
+ *   'client' → extract from `clientBody.output_config.effort`; fall back
+ *              to 'high' if the client didn't send one or sent a non-string
+ *
+ * Exported for tests.
+ */
+export declare function resolveEffort(flag: EffortValue | undefined, clientBody: Record<string, unknown>): string;
 export declare function buildCCRequest(clientBody: Record<string, unknown>, billingTag: string, cacheControl: {
     type: 'ephemeral';
 }, identity: {
@@ -180,6 +194,7 @@ export declare function buildCCRequest(clientBody: Record<string, unknown>, bill
     preserveTools?: boolean;
     hybridTools?: boolean;
     noAutoDetect?: boolean;
+    effort?: EffortValue;
 }): {
     body: Record<string, unknown>;
     toolMap: Map<string, ToolMapping>;

package/dist/cc-template.js

@@ -708,11 +708,29 @@ const TOOL_MAP = {
     },
     exit_worktree: { ccTool: 'ExitWorktree' },
 };
+export const VALID_EFFORT_VALUES = ['low', 'medium', 'high', 'xhigh', 'client'];
 /**
- * Build a CC-template request from a client request.
- * Replaces the entire request structure — tools, fields, ordering — with
- * what real CC sends. Only the conversation content is preserved.
+ * Resolve the outbound `output_config.effort` value.
+ *
+ *   undefined / 'high' → 'high' (current default, matches CC 2.1.116 wire value)
+ *   'low' / 'medium' / 'xhigh' → pin to that value
+ *   'client' → extract from `clientBody.output_config.effort`; fall back
+ *              to 'high' if the client didn't send one or sent a non-string
+ *
+ * Exported for tests.
  */
+export function resolveEffort(flag, clientBody) {
+    if (flag === undefined)
+        return 'high';
+    if (flag === 'client') {
+        const clientOC = clientBody.output_config;
+        const clientEffort = clientOC?.effort;
+        if (typeof clientEffort === 'string' && clientEffort.length > 0)
+            return clientEffort;
+        return 'high';
+    }
+    return flag;
+}
 export function buildCCRequest(clientBody, billingTag, cacheControl, identity, opts = {}) {
     const model = clientBody.model || 'claude-sonnet-4-6';
     const isHaiku = model.toLowerCase().includes('haiku');
@@ -979,7 +997,11 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
     if (!isHaiku) {
         ccRequest.thinking = { type: 'adaptive' };
         ccRequest.context_management = { edits: [{ type: 'clear_thinking_20251015', keep: 'all' }] };
-        ccRequest.output_config = { effort: 'high' };
+        // output_config.effort default is `'high'` (matches CC 2.1.116's wire
+        // value). `--effort` flag overrides; `'client'` passes through whatever
+        // the client sent (or falls back to `'high'` if the client didn't
+        // include an output_config). See dario#87.
+        ccRequest.output_config = { effort: resolveEffort(opts.effort, clientBody) };
     }
     ccRequest.stream = stream;
     // Replay the captured top-level key order. The hardcoded build order above

package/dist/cli.d.ts

@@ -9,6 +9,21 @@
  *   dario refresh   — Force token refresh
  *   dario logout    — Remove saved credentials
  */
+import { type EffortValue } from './cc-template.js';
+/**
+ * Parse the `--effort` flag + `DARIO_EFFORT` env. Validates against the
+ * allowed set; unrecognised values cause a non-zero exit with the list of
+ * valid choices (same philosophy as other strict parsers in this CLI).
+ * Flag value wins over env. Exported for tests. dario#87.
+ */
+export declare function resolveEffortFlag(args: string[], env: string | undefined): EffortValue | undefined;
+/**
+ * Parse a positive-integer env var. Returns undefined on unset, empty,
+ * non-numeric, or non-positive values so the caller's default applies.
+ * Sibling of parsePositiveIntFlag; exported for tests + used by the
+ * dario#80 queue env mirrors.
+ */
+export declare function parsePositiveIntEnv(value: string | undefined): number | undefined;
 /**
  * Parse a boolean env var. Accepts "1", "true", "yes", "on" (case-insensitive)
  * as truthy; everything else (including unset) is undefined/false. Exported

package/dist/cli.js

@@ -37,6 +37,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { startAutoOAuthFlow, startManualOAuthFlow, detectHeadlessEnvironment, getStatus, refreshTokens, loadCredentials } from './oauth.js';
 import { startProxy, sanitizeError } from './proxy.js';
+import { VALID_EFFORT_VALUES } from './cc-template.js';
 import { listAccountAliases, loadAllAccounts, addAccountViaOAuth, removeAccount } from './accounts.js';
 import { listBackends, saveBackend, removeBackend } from './openai-backend.js';
 const args = process.argv.slice(2);
@@ -250,6 +251,26 @@ async function proxy() {
     const strictTemplate = args.includes('--strict-template')
         || parseBooleanEnv(process.env['DARIO_STRICT_TEMPLATE'])
         || undefined;
+    // --max-concurrent=N / --max-queued=N / --queue-timeout=MS — bounded
+    // request queue knobs (dario#80). Defaults preserve v3.30.x-and-earlier
+    // behaviour for typical single-user workloads; tune up for high-fan-out
+    // agent setups that otherwise hit dario-level 429s before upstream.
+    const maxConcurrent = parsePositiveIntFlag('--max-concurrent=')
+        ?? parsePositiveIntEnv(process.env['DARIO_MAX_CONCURRENT']);
+    const maxQueued = parsePositiveIntFlag('--max-queued=')
+        ?? parsePositiveIntEnv(process.env['DARIO_MAX_QUEUED']);
+    const queueTimeoutMs = parsePositiveIntFlag('--queue-timeout=')
+        ?? parsePositiveIntEnv(process.env['DARIO_QUEUE_TIMEOUT_MS']);
+    // --effort=low|medium|high|xhigh|client — override the outbound
+    // output_config.effort (dario#87). Default (unset) pins 'high' to match
+    // CC 2.1.116's wire value. 'client' passes through whatever the client
+    // sent, falling back to 'high' if the client didn't include one.
+    //
+    // Risk: setting effort to a non-CC-default value may cause Anthropic's
+    // classifier to flip requests to 'overage' billing. Users opting in
+    // should watch the `representative-claim` response header via -v logs
+    // and revert to default if subscription billing breaks.
+    const effort = resolveEffortFlag(args, process.env['DARIO_EFFORT']);
     // Non-loopback bind without DARIO_API_KEY turns dario into an open
     // OAuth-subscription relay for anyone on the reachable network. Refuse
     // to start rather than rely on the operator to read the startup banner.
@@ -269,7 +290,39 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate });
+    await startProxy({ port, host, verbose, verboseBodies, model, passthrough, preserveTools, hybridTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, effort });
+}
+/**
+ * Parse the `--effort` flag + `DARIO_EFFORT` env. Validates against the
+ * allowed set; unrecognised values cause a non-zero exit with the list of
+ * valid choices (same philosophy as other strict parsers in this CLI).
+ * Flag value wins over env. Exported for tests. dario#87.
+ */
+export function resolveEffortFlag(args, env) {
+    const withValue = args.find(a => a.startsWith('--effort='));
+    const raw = withValue ? withValue.slice('--effort='.length) : env;
+    if (raw === undefined || raw === '')
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (VALID_EFFORT_VALUES.includes(normalized)) {
+        return normalized;
+    }
+    console.error(`[dario] Invalid --effort value: ${JSON.stringify(raw)}. Must be one of: ${VALID_EFFORT_VALUES.join(', ')}.`);
+    process.exit(1);
+}
+/**
+ * Parse a positive-integer env var. Returns undefined on unset, empty,
+ * non-numeric, or non-positive values so the caller's default applies.
+ * Sibling of parsePositiveIntFlag; exported for tests + used by the
+ * dario#80 queue env mirrors.
+ */
+export function parsePositiveIntEnv(value) {
+    if (value === undefined || value === '')
+        return undefined;
+    const n = Number.parseInt(value.trim(), 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return n;
 }
 /**
  * Parse a boolean env var. Accepts "1", "true", "yes", "on" (case-insensitive)
@@ -648,6 +701,27 @@ async function help() {
                              as --strict-tls: make the unsafe state
                              require intent. Env: DARIO_STRICT_TEMPLATE=1.
                              (v3.30.8, dario#77)
+    --max-concurrent=N       Max in-flight requests (default: 10).
+                             Env: DARIO_MAX_CONCURRENT. (dario#80)
+    --max-queued=N           Max requests buffered waiting for a
+                             concurrency slot before dario returns
+                             429 "queue-full" (default: 128).
+                             Env: DARIO_MAX_QUEUED. (dario#80)
+    --queue-timeout=MS       Max ms a queued request waits before
+                             dario returns 504 "queue-timeout"
+                             (default: 60000).
+                             Env: DARIO_QUEUE_TIMEOUT_MS. (dario#80)
+    --effort=<low|medium|high|xhigh|client>
+                             Override the outbound output_config.effort
+                             on non-haiku requests. Default (unset)
+                             pins 'high' — matches CC 2.1.116's wire
+                             value. 'client' passes through what the
+                             client sent (falls back to 'high' if none).
+                             WARNING: non-'high' values may cause
+                             Anthropic's classifier to flip requests
+                             to 'overage' billing; watch -v logs for
+                             representative-claim changes.
+                             Env: DARIO_EFFORT. (dario#87)
     --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

@@ -1,4 +1,5 @@
 import { type IncomingMessage } from 'node:http';
+import { type EffortValue } from './cc-template.js';
 export declare function parseProviderPrefix(model: string): {
     provider: 'openai' | 'claude';
     model: string;
@@ -65,6 +66,20 @@ interface ProxyOptions {
      * --strict-tls. dario#77.
      */
     strictTemplate?: boolean;
+    /** Max concurrent in-flight requests. Default 10. dario#80. */
+    maxConcurrent?: number;
+    /** Max requests buffered waiting for a concurrency slot. Default 128. dario#80. */
+    maxQueued?: number;
+    /** Max ms a queued request waits before it times out with 504. Default 60000. dario#80. */
+    queueTimeoutMs?: number;
+    /**
+     * Override the outbound `output_config.effort` value on non-haiku
+     * requests. Default (undefined) pins `'high'`, matching CC 2.1.116's
+     * wire value. `'client'` passes through whatever the client sent (or
+     * falls back to `'high'` if the client didn't include an output_config).
+     * dario#87.
+     */
+    effort?: EffortValue;
 }
 export declare function sanitizeError(err: unknown): string;
 /**

package/dist/proxy.js

@@ -12,12 +12,12 @@ import { AccountPool, computeStickyKey, parseRateLimits } from './pool.js';
 import { Analytics, billingBucketFromClaim } from './analytics.js';
 import { loadAllAccounts, loadAccount, refreshAccountToken } from './accounts.js';
 import { getOpenAIBackend, isOpenAIModel, forwardToOpenAI } from './openai-backend.js';
+import { RequestQueue, QueueFullError, QueueTimeoutError, DEFAULT_MAX_CONCURRENT, DEFAULT_MAX_QUEUED, DEFAULT_QUEUE_TIMEOUT_MS } from './request-queue.js';
 const ANTHROPIC_API = 'https://api.anthropic.com';
 const DEFAULT_PORT = 3456;
 const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB — generous for large prompts, prevents abuse
 const UPSTREAM_TIMEOUT_MS = 300_000; // 5 min — matches Anthropic SDK default
 const BODY_READ_TIMEOUT_MS = 30_000; // 30s — prevents slow-loris on body reads
-const MAX_CONCURRENT = 10; // Max concurrent upstream requests
 const DEFAULT_HOST = '127.0.0.1';
 // A host is "loopback" if it's one of the well-known localhost literals.
 // Used to decide whether to warn at startup about binding to a reachable
@@ -28,28 +28,8 @@ function isLoopbackHost(host) {
         return true;
     return host.startsWith('127.');
 }
-// Simple semaphore for concurrency control
-class Semaphore {
-    max;
-    queue = [];
-    active = 0;
-    constructor(max) {
-        this.max = max;
-    }
-    async acquire() {
-        if (this.active < this.max) {
-            this.active++;
-            return;
-        }
-        return new Promise(resolve => { this.queue.push(() => { this.active++; resolve(); }); });
-    }
-    release() {
-        this.active--;
-        const next = this.queue.shift();
-        if (next)
-            next();
-    }
-}
+// Concurrency control: see src/request-queue.ts for the bounded queue
+// (replaced the v3.30.x-and-earlier simple unbounded semaphore in dario#80).
 // Billing tag hash seed — matches Claude Code's value
 const BILLING_SEED = '59cf53e54c78';
 // Compute per-request build tag:
@@ -572,7 +552,11 @@ export async function startProxy(opts = {}) {
         }
     }
     let requestCount = 0;
-    const semaphore = new Semaphore(MAX_CONCURRENT);
+    const queue = new RequestQueue({
+        maxConcurrent: opts.maxConcurrent ?? DEFAULT_MAX_CONCURRENT,
+        maxQueued: opts.maxQueued ?? DEFAULT_MAX_QUEUED,
+        queueTimeoutMs: opts.queueTimeoutMs ?? DEFAULT_QUEUE_TIMEOUT_MS,
+    });
     // Cache context-1m beta availability. Set false once per account (or process
     // in single-account mode) after the first "long context" rejection, so we
     // skip sending context-1m on every subsequent request instead of paying the
@@ -771,8 +755,38 @@ export async function startProxy(opts = {}) {
             res.end(ERR_METHOD);
             return;
         }
-        // Proxy to Anthropic (with concurrency control)
-        await semaphore.acquire();
+        // Proxy to Anthropic (with concurrency control). The bounded queue
+        // replaces the v3.30.x-and-earlier unbounded semaphore — dario#80. A
+        // queue-full condition returns an explicit 429 with a `"queue-full"`
+        // marker in the body; a queue-timeout returns 504 with `"queue-timeout"`.
+        try {
+            await queue.acquire();
+        }
+        catch (err) {
+            if (err instanceof QueueFullError) {
+                res.writeHead(429, JSON_HEADERS);
+                res.end(JSON.stringify({
+                    type: 'error',
+                    error: {
+                        type: 'rate_limit_error',
+                        message: `dario queue full — ${queue.maxConcurrent} concurrent + ${queue.maxQueued} queued already in flight. Tune --max-concurrent / --max-queued, or reduce client-side concurrency. (dario#80)`,
+                    },
+                }));
+                return;
+            }
+            if (err instanceof QueueTimeoutError) {
+                res.writeHead(504, JSON_HEADERS);
+                res.end(JSON.stringify({
+                    type: 'error',
+                    error: {
+                        type: 'timeout_error',
+                        message: `dario queue timeout — request waited longer than ${queue.queueTimeoutMs}ms for a concurrency slot. Tune --queue-timeout, or reduce client-side concurrency. (dario#80)`,
+                    },
+                }));
+                return;
+            }
+            throw err;
+        }
         // Hoisted so the finally block can clean up whatever was set.
         let upstreamTimeout = null;
         let onClientClose = null;
@@ -964,6 +978,7 @@ export async function startProxy(opts = {}) {
                             preserveTools: opts.preserveTools ?? false,
                             hybridTools: opts.hybridTools ?? false,
                             noAutoDetect: opts.noAutoDetect ?? false,
+                            effort: opts.effort,
                         });
                         // Log the auto-preserve-tools switch once per text-tool
                         // client family. Skip when the operator already opted into
@@ -1617,7 +1632,7 @@ export async function startProxy(opts = {}) {
                 clearTimeout(upstreamTimeout);
             if (onClientClose !== null)
                 req.off('close', onClientClose);
-            semaphore.release();
+            queue.release();
         }
     });
     server.on('error', (err) => {

package/dist/request-queue.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bounded request queue — replaces the simple in-process semaphore so that
+ * overload conditions are visible and tunable instead of silently queuing
+ * unbounded or rejecting with generic 429s before upstream had a chance.
+ *
+ * Three knobs:
+ *   - maxConcurrent : in-flight requests allowed at once (default 10)
+ *   - maxQueued     : buffered requests waiting for a concurrency slot
+ *                     (default 128); beyond this, the queue is "full" and
+ *                     admission is rejected with a clear 429 body.
+ *   - queueTimeoutMs: how long a queued request waits before it 504s with
+ *                     a "queue-timeout" reason (default 60_000).
+ *
+ * Behaviour:
+ *   - active < maxConcurrent → admit immediately
+ *   - else, queued < maxQueued → enqueue
+ *   - else → reject with `queue-full`
+ *   - queued > queueTimeoutMs → reject with `queue-timeout`
+ *
+ * The decision logic is split out as a pure `decideAdmit(state)` function so
+ * tests can exercise all three branches without side effects or timers.
+ *
+ * dario#80 (Gemini review push-back).
+ */
+export interface QueueState {
+    active: number;
+    queued: number;
+    maxConcurrent: number;
+    maxQueued: number;
+}
+export type AdmitDecision = {
+    action: 'admit';
+} | {
+    action: 'enqueue';
+} | {
+    action: 'reject';
+    reason: 'queue-full';
+};
+/** Pure admission decision — no side effects, no clock dep. */
+export declare function decideAdmit(state: QueueState): AdmitDecision;
+/** Pure timeout check — separated so tests can pass an explicit clock. */
+export declare function isQueueEntryExpired(enqueuedAt: number, now: number, timeoutMs: number): boolean;
+export declare class QueueFullError extends Error {
+    constructor();
+}
+export declare class QueueTimeoutError extends Error {
+    constructor();
+}
+export interface RequestQueueOptions {
+    maxConcurrent?: number;
+    maxQueued?: number;
+    queueTimeoutMs?: number;
+}
+export declare const DEFAULT_MAX_CONCURRENT = 10;
+export declare const DEFAULT_MAX_QUEUED = 128;
+export declare const DEFAULT_QUEUE_TIMEOUT_MS = 60000;
+export declare class RequestQueue {
+    readonly maxConcurrent: number;
+    readonly maxQueued: number;
+    readonly queueTimeoutMs: number;
+    private active;
+    private queue;
+    constructor(opts?: RequestQueueOptions);
+    /**
+     * Acquire a concurrency slot. Resolves when admitted; throws
+     * `QueueFullError` when the queue is at its `maxQueued` cap, throws
+     * `QueueTimeoutError` when a queued request waited longer than
+     * `queueTimeoutMs`.
+     */
+    acquire(): Promise<void>;
+    /** Release a slot. The next queued entry (if any) is admitted in FIFO order. */
+    release(): void;
+    /** Snapshot of queue state — exposed for /analytics + tests. */
+    snapshot(): QueueState;
+}

package/dist/request-queue.js

@@ -0,0 +1,108 @@
+/**
+ * Bounded request queue — replaces the simple in-process semaphore so that
+ * overload conditions are visible and tunable instead of silently queuing
+ * unbounded or rejecting with generic 429s before upstream had a chance.
+ *
+ * Three knobs:
+ *   - maxConcurrent : in-flight requests allowed at once (default 10)
+ *   - maxQueued     : buffered requests waiting for a concurrency slot
+ *                     (default 128); beyond this, the queue is "full" and
+ *                     admission is rejected with a clear 429 body.
+ *   - queueTimeoutMs: how long a queued request waits before it 504s with
+ *                     a "queue-timeout" reason (default 60_000).
+ *
+ * Behaviour:
+ *   - active < maxConcurrent → admit immediately
+ *   - else, queued < maxQueued → enqueue
+ *   - else → reject with `queue-full`
+ *   - queued > queueTimeoutMs → reject with `queue-timeout`
+ *
+ * The decision logic is split out as a pure `decideAdmit(state)` function so
+ * tests can exercise all three branches without side effects or timers.
+ *
+ * dario#80 (Gemini review push-back).
+ */
+/** Pure admission decision — no side effects, no clock dep. */
+export function decideAdmit(state) {
+    if (state.active < state.maxConcurrent)
+        return { action: 'admit' };
+    if (state.queued < state.maxQueued)
+        return { action: 'enqueue' };
+    return { action: 'reject', reason: 'queue-full' };
+}
+/** Pure timeout check — separated so tests can pass an explicit clock. */
+export function isQueueEntryExpired(enqueuedAt, now, timeoutMs) {
+    return (now - enqueuedAt) > timeoutMs;
+}
+export class QueueFullError extends Error {
+    constructor() { super('queue-full'); this.name = 'QueueFullError'; }
+}
+export class QueueTimeoutError extends Error {
+    constructor() { super('queue-timeout'); this.name = 'QueueTimeoutError'; }
+}
+export const DEFAULT_MAX_CONCURRENT = 10;
+export const DEFAULT_MAX_QUEUED = 128;
+export const DEFAULT_QUEUE_TIMEOUT_MS = 60_000;
+export class RequestQueue {
+    maxConcurrent;
+    maxQueued;
+    queueTimeoutMs;
+    active = 0;
+    queue = [];
+    constructor(opts = {}) {
+        this.maxConcurrent = opts.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+        this.maxQueued = opts.maxQueued ?? DEFAULT_MAX_QUEUED;
+        this.queueTimeoutMs = opts.queueTimeoutMs ?? DEFAULT_QUEUE_TIMEOUT_MS;
+    }
+    /**
+     * Acquire a concurrency slot. Resolves when admitted; throws
+     * `QueueFullError` when the queue is at its `maxQueued` cap, throws
+     * `QueueTimeoutError` when a queued request waited longer than
+     * `queueTimeoutMs`.
+     */
+    async acquire() {
+        const decision = decideAdmit(this.snapshot());
+        if (decision.action === 'admit') {
+            this.active++;
+            return;
+        }
+        if (decision.action === 'reject') {
+            throw new QueueFullError();
+        }
+        return new Promise((resolve, reject) => {
+            const enqueuedAt = Date.now();
+            const timeoutHandle = setTimeout(() => {
+                const idx = this.queue.indexOf(entry);
+                if (idx >= 0) {
+                    this.queue.splice(idx, 1);
+                    reject(new QueueTimeoutError());
+                }
+            }, this.queueTimeoutMs);
+            // Keep the timer from pinning the event loop open on shutdown. A queued
+            // request waiting for a slot shouldn't by itself keep the process alive.
+            timeoutHandle.unref?.();
+            const entry = { resolve, reject, enqueuedAt, timeoutHandle };
+            this.queue.push(entry);
+        });
+    }
+    /** Release a slot. The next queued entry (if any) is admitted in FIFO order. */
+    release() {
+        if (this.active > 0)
+            this.active--;
+        const next = this.queue.shift();
+        if (next) {
+            clearTimeout(next.timeoutHandle);
+            this.active++;
+            next.resolve();
+        }
+    }
+    /** Snapshot of queue state — exposed for /analytics + tests. */
+    snapshot() {
+        return {
+            active: this.active,
+            queued: this.queue.length,
+            maxConcurrent: this.maxConcurrent,
+            maxQueued: this.maxQueued,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.30.8",
+  "version": "3.30.10",
   "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/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/cc-authorize-probe-classifier.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 && node test/sanitize-messages.mjs && node test/platform-tools.mjs && node test/strict-template-flags.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/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/cc-authorize-probe-classifier.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 && node test/sanitize-messages.mjs && node test/platform-tools.mjs && node test/strict-template-flags.mjs && node test/request-queue.mjs && node test/effort-flag.mjs",
     "audit": "npm audit --production --audit-level=high",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",