@askalf/dario 3.15.0 → 3.16.0

package/README.md

@@ -124,7 +124,7 @@ OAuth-backed Claude Max / Pro, billed against your plan instead of the API. Acti
 **What it does:**
 
 - Every request is replaced with a Claude Code template before it goes upstream — 25 tool definitions, ~25KB system prompt, exact CC field order, exact beta headers, exact metadata structure. Only the conversation content is preserved. Anthropic's classifier sees what looks like a Claude Code session because, from the wire up, it *is* one — and that's what keeps your usage on subscription billing instead of Extra Usage.
-- **Live fingerprint extraction** (v3.11.0). Dario spawns your installed `claude` binary against a loopback MITM endpoint on startup, captures its outbound request, and extracts the live template (system prompt, tools, user-agent, beta flags, and as of v3.13.0 the exact header insertion order). Eliminates the "Anthropic ships a new CC, dario is stale for 48 hours" window. Cached at `~/.dario/cc-template.live.json` with a 24h TTL. Falls back to the bundled snapshot if CC isn't installed.
+- **Live fingerprint extraction** (v3.11.0). Dario spawns your installed `claude` binary against a loopback MITM endpoint on startup, captures its outbound request, and extracts the live template (system prompt, tools, user-agent, beta flags, and as of v3.13.0 the exact header insertion order — replayed on the wire by the shim since v3.13.0 and by the proxy since v3.16.0). Eliminates the "Anthropic ships a new CC, dario is stale for 48 hours" window. Cached at `~/.dario/cc-template.live.json` with a 24h TTL. Falls back to the bundled snapshot if CC isn't installed.
 - **Billing tag** reconstructed using CC's own algorithm: `x-anthropic-billing-header: cc_version=<version>.<build_tag>; cc_entrypoint=cli; cch=<5-char-hex>;` where `build_tag = SHA-256(seed + chars[4,7,20] of user message + version).slice(0,3)`.
 - **OAuth config auto-detection** from the installed CC binary. When Anthropic rotates `client_id`, authorize URL, or scopes, dario picks up the new values on the next run without needing a release.
 - **Multi-account pool mode** — see below. Automatic when 2+ accounts are configured.
@@ -248,7 +248,7 @@ Under the hood: `dario shim` spawns the child with `NODE_OPTIONS=--require <dari
 - **Runtime detection** — `detectRuntime()` checks `globalThis.Bun` / `globalThis.Deno` / `process.versions.node` and logs a warning for non-Node runtimes. Canary for the day Anthropic ships a Bun-compiled CC.
 - **Template mtime-based auto-reload** — long-running child processes pick up mid-session fingerprint refreshes from dario's live capture without restart.
 - **Strict defensive `rewriteBody`** — the previous logic accepted `length >= 1` on the system array and invented `[1]`/`[2]` blocks out of thin air. Now requires exactly `length === 3` with all-text blocks; any mismatch passes through unchanged. Passthrough on an unknown shape is safer than blind replacement.
-- **`rewriteHeaders` honors captured header order** — the live fingerprint capture now records the exact order CC emits headers on the wire, and the shim replays that order on every outbound request. Header sequence alone is a fingerprint vector; v3.13.0 removes it.
+- **`rewriteHeaders` honors captured header order** — the live fingerprint capture now records the exact order CC emits headers on the wire, and the shim replays that order on every outbound request. Header sequence alone is a fingerprint vector; v3.13.0 removes it from the shim, and v3.16.0 closes the same gap on the proxy via the shared `orderHeadersForOutbound` helper so both transports produce an identical wire shape.
 - **`checkVersionDrift`** — logs when the child's UA `cc_version` differs from the template's, so stale-cache windows during CC upgrades are visible in debug output.
 
 **When to use shim mode:**
@@ -410,11 +410,29 @@ Recognized prefixes:
 
 The prefix gets stripped before the request goes upstream — the backend only sees the bare model name. Unrecognized prefixes are ignored, so ollama-style `llama3:8b` passes through untouched. `dario proxy --model=openai:gpt-4o` applies the prefix to every request server-wide.
 
+### Agent compatibility
+
+As of **v3.15.0**, dario's built-in `TOOL_MAP` has **71 entries** covering the tool schemas of every major coding agent. If you're running one of these, no flag is required on the Claude backend — tool calls translate to CC's native `Bash/Read/Write/Edit/Glob/Grep/WebSearch/WebFetch` on the outbound path (so the subscription fingerprint stays intact) and rebuild to your agent's exact expected shape on the inbound path (so your validator is happy).
+
+| Agent | Covered tool names (subset) |
+|---|---|
+| Claude Code | default — CC's own tools |
+| Cline / Roo Code | `execute_command`, `write_to_file`, `replace_in_file`, `apply_diff`, `list_files`, `search_files`, `read_file` |
+| Cursor | `run_terminal_cmd`, `edit_file`, `search_replace`, `codebase_search`, `grep_search`, `file_search`, `list_dir`, `read_file` (`target_file`) |
+| Windsurf | `run_command`, `view_file`, `write_to_file`, `replace_file_content`, `find_by_name`, `grep_search`, `list_dir`, `search_web`, `read_url_content` |
+| Continue.dev | `builtin_run_terminal_command`, `builtin_read_file`, `builtin_create_new_file`, `builtin_edit_existing_file`, `builtin_file_glob_search`, `builtin_grep_search`, `builtin_ls` |
+| GitHub Copilot | `run_in_terminal`, `insert_edit_into_file`, `semantic_search`, `codebase_search`, `list_dir`, `fetch_webpage` |
+| OpenHands | `execute_bash`, `str_replace_editor` |
+| OpenClaw | `exec`, `process`, `web_search`, `web_fetch`, `browser`, `message` |
+| Hermes | `terminal`, `patch`, `web_extract`, `clarify` |
+
+If your agent's tool names aren't in this list, you've got two escape hatches below: **`--preserve-tools`** (forward your schema verbatim, lose the CC fingerprint) or **`--hybrid-tools`** (keep the fingerprint, fill request-context fields from headers). Open an issue with your agent's tool schema and we'll add a pre-mapping entry.
+
 ### Custom tool schemas
 
-By default, on the Claude backend, dario replaces your client's tool definitions with the real Claude Code tools (`Bash`, `Read`, `Grep`, `Glob`, `WebSearch`, `WebFetch`) and translates parameters back and forth. That's how dario looks like CC on the wire, which is what lets your request bill against your Claude subscription instead of API pricing.
+By default, on the Claude backend, dario replaces your client's tool definitions with the real Claude Code tools (`Bash`, `Read`, `Write`, `Edit`, `Grep`, `Glob`, `WebSearch`, `WebFetch`) and translates parameters back and forth. That's how dario looks like CC on the wire, which is what lets your request bill against your Claude subscription instead of API pricing. For the agents listed in [Agent compatibility](#agent-compatibility) above, the translation is pre-mapped and runs automatically — nothing to configure.
 
-The trade-off: if your client's tools carry fields CC's schema doesn't have — a `sessionId`, a custom request id, a channel-bound context token — those fields don't survive the round trip. The model only ever sees `Bash({command})`, responds with `Bash({command})`, and dario's reverse map rebuilds your tool call without the fields the model never saw. Your validator then rejects the call for a missing required field.
+The trade-off shows up when you're running something that *isn't* in the pre-mapped list and whose tools carry fields CC's schema doesn't have — a `sessionId`, a custom request id, a channel-bound context token, a `confidence` score the model is supposed to emit. Those fields don't survive the round trip. The model only ever sees `Bash({command})`, responds with `Bash({command})`, and dario's reverse map rebuilds your tool call without the fields the model never saw. Your validator then rejects the call for a missing required field.
 
 Symptom: your tool calls come back looking stripped-down, or your runtime complains about a required field being absent *only when routed through dario's Claude backend*, while the same tools work fine against a direct API key or the OpenAI-compat backend.
 
@@ -442,9 +460,10 @@ dario proxy --hybrid-tools
 
 | Your situation | Flag | Why |
 |---|---|---|
+| Your agent is listed in [Agent compatibility](#agent-compatibility) | *(neither)* | Pre-mapped in `TOOL_MAP`; the default path already handles it. |
 | Your custom fields are request context (session/request/channel/user ids, timestamps) | `--hybrid-tools` | Keeps the CC fingerprint *and* your validator is satisfied. |
 | Your custom fields need the model's reasoning (e.g. `confidence`, `reasoning_trace`, `tool_selection_rationale`) | `--preserve-tools` | The model has to see the real schema to populate these. Accept the fingerprint loss. |
-| Your client's tools are already a subset of CC's `Bash/Read/Grep/Glob/WebSearch/WebFetch` | *(neither)* | Default mode works as-is. |
+| Your client's tools are already a subset of CC's `Bash/Read/Write/Edit/Grep/Glob/WebSearch/WebFetch` | *(neither)* | Default mode works as-is. |
 
 Hybrid mode was built to resolve [#29](https://github.com/askalf/dario/issues/29) cleanly for OpenClaw-style agents whose `process` tool declares `sessionId`, after the full provider-comparison diagnostic from [@boeingchoco](https://github.com/boeingchoco) made clear that the problem wasn't fixable in the translation layer alone.
 

package/dist/cc-template.d.ts

@@ -17,6 +17,34 @@ export declare const CC_TOOL_DEFINITIONS: {
 export declare const CC_SYSTEM_PROMPT: string;
 /** CC's agent identity string. */
 export declare const CC_AGENT_IDENTITY: string;
+/**
+ * Apply the live template's captured header_order to an outbound header
+ * record. Returns a HeadersInit in one of two forms:
+ *
+ * - If the template has no header_order (bundled-only install, or capture
+ *   didn't record rawHeaders), returns the input record unchanged.
+ * - If header_order is present, returns an array of [name, value] pairs
+ *   in the captured order. `fetch()` serializes pairs to the wire in
+ *   array order; a plain Record or Headers instance doesn't preserve
+ *   order in the same way (Headers iteration is spec-sorted alphabetically,
+ *   and while modern V8 iterates own-property keys in insertion order,
+ *   nothing in the fetch contract guarantees that order reaches the HTTP
+ *   layer untouched — the array form is the one variant where wire order
+ *   is part of the spec).
+ *
+ * Caller-supplied headers that don't appear in the captured order are
+ * appended at the tail in their original insertion order so host-set
+ * headers (content-type, content-length) aren't silently dropped. Names
+ * in the captured order are emitted in the template's exact case; names
+ * only in the caller's map keep the caller's case.
+ *
+ * Matches `rewriteHeaders` in `src/shim/runtime.cjs` — the shim and the
+ * proxy are two transports that need to produce the same wire shape.
+ *
+ * @param headers outbound headers the proxy built
+ * @param overrideHeaderOrder test-only override; production callers pass nothing
+ */
+export declare function orderHeadersForOutbound(headers: Record<string, string>, overrideHeaderOrder?: string[] | undefined): Record<string, string> | Array<[string, string]>;
 export declare function scrubFrameworkIdentifiers(text: string): string;
 /**
  * Client tool name → CC tool mapping with parameter translation.

package/dist/cc-template.js

@@ -16,6 +16,65 @@ export const CC_TOOL_DEFINITIONS = TEMPLATE.tools;
 export const CC_SYSTEM_PROMPT = TEMPLATE.system_prompt;
 /** CC's agent identity string. */
 export const CC_AGENT_IDENTITY = TEMPLATE.agent_identity;
+/**
+ * Apply the live template's captured header_order to an outbound header
+ * record. Returns a HeadersInit in one of two forms:
+ *
+ * - If the template has no header_order (bundled-only install, or capture
+ *   didn't record rawHeaders), returns the input record unchanged.
+ * - If header_order is present, returns an array of [name, value] pairs
+ *   in the captured order. `fetch()` serializes pairs to the wire in
+ *   array order; a plain Record or Headers instance doesn't preserve
+ *   order in the same way (Headers iteration is spec-sorted alphabetically,
+ *   and while modern V8 iterates own-property keys in insertion order,
+ *   nothing in the fetch contract guarantees that order reaches the HTTP
+ *   layer untouched — the array form is the one variant where wire order
+ *   is part of the spec).
+ *
+ * Caller-supplied headers that don't appear in the captured order are
+ * appended at the tail in their original insertion order so host-set
+ * headers (content-type, content-length) aren't silently dropped. Names
+ * in the captured order are emitted in the template's exact case; names
+ * only in the caller's map keep the caller's case.
+ *
+ * Matches `rewriteHeaders` in `src/shim/runtime.cjs` — the shim and the
+ * proxy are two transports that need to produce the same wire shape.
+ *
+ * @param headers outbound headers the proxy built
+ * @param overrideHeaderOrder test-only override; production callers pass nothing
+ */
+export function orderHeadersForOutbound(headers, overrideHeaderOrder) {
+    const order = overrideHeaderOrder !== undefined ? overrideHeaderOrder : TEMPLATE.header_order;
+    if (!Array.isArray(order) || order.length === 0) {
+        return headers;
+    }
+    const lowerToValue = new Map();
+    const lowerToOriginalKey = new Map();
+    for (const [k, v] of Object.entries(headers)) {
+        const lk = k.toLowerCase();
+        lowerToValue.set(lk, v);
+        lowerToOriginalKey.set(lk, k);
+    }
+    const ordered = [];
+    const seen = new Set();
+    for (const name of order) {
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            continue;
+        const value = lowerToValue.get(key);
+        if (value !== undefined) {
+            ordered.push([name, value]);
+            seen.add(key);
+        }
+    }
+    for (const [k, v] of Object.entries(headers)) {
+        const lk = k.toLowerCase();
+        if (!seen.has(lk)) {
+            ordered.push([k, v]);
+        }
+    }
+    return ordered;
+}
 // Framework identifiers that would flag non-CC usage. Stripped from the system
 // prompt and from message content text blocks before the request goes upstream.
 const FRAMEWORK_PATTERNS = [

package/dist/proxy.js

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { arch, platform } from 'node:process';
 import { getAccessToken, getStatus } from './oauth.js';
-import { buildCCRequest, reverseMapResponse, createStreamingReverseMapper } from './cc-template.js';
+import { buildCCRequest, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound } from './cc-template.js';
 import { AccountPool, computeStickyKey, parseRateLimits } from './pool.js';
 import { Analytics, billingBucketFromClaim } from './analytics.js';
 import { loadAllAccounts, loadAccount, refreshAccountToken } from './accounts.js';
@@ -1000,9 +1000,14 @@ export async function startProxy(opts = {}) {
             // the next-best account before surfacing the error to the client.
             // Bounded to pool.size iterations; breaks immediately on any non-429.
             dispatchLoop: while (true) {
+                // Reorder outbound headers to match CC's captured header sequence
+                // when the live template recorded one. No-op on bundled-only installs.
+                // Skipped in passthrough mode — passthrough means "don't shape the
+                // request to look like CC," and reordering is a form of shaping.
+                const outboundHeaders = passthrough ? headers : orderHeadersForOutbound(headers);
                 upstream = await fetch(targetBase, {
                     method: req.method ?? 'POST',
-                    headers,
+                    headers: outboundHeaders,
                     body: finalBody ? new Uint8Array(finalBody) : undefined,
                     signal: upstreamAbort.signal,
                 });
@@ -1043,7 +1048,7 @@ export async function startProxy(opts = {}) {
                         const retryHeaders = { ...headers, 'anthropic-beta': reducedBeta };
                         const retry = await fetch(targetBase, {
                             method: req.method ?? 'POST',
-                            headers: retryHeaders,
+                            headers: passthrough ? retryHeaders : orderHeadersForOutbound(retryHeaders),
                             body: finalBody ? new Uint8Array(finalBody) : undefined,
                             signal: upstreamAbort.signal,
                         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "3.15.0",
+  "version": "3.16.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/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",
+    "test": "node test/issue-29-tool-translation.mjs && node test/hybrid-tools.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",
     "audit": "npm audit --production --audit-level=high",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",