@askalf/dario 3.8.0 → 3.9.0

package/README.md

@@ -245,7 +245,8 @@ curl http://localhost:3456/analytics    # per-account / per-model stats, burn ra
 | Flag / env | Description | Default |
 |---|---|---|
 | `--passthrough` / `--thin` | Thin proxy for the Claude backend — OAuth swap only, no template injection | off |
-| `--preserve-tools` / `--keep-tools` | Keep client tool schemas instead of remapping to CC tools (Claude backend) | off |
+| `--preserve-tools` / `--keep-tools` | Keep client tool schemas instead of remapping to CC's `Bash/Read/Grep/Glob/WebSearch/WebFetch`. Required for clients whose tools have fields CC doesn't (`sessionId`, custom ids, etc.) — see [Custom tool schemas](#custom-tool-schemas). Trade-off: drops the CC request fingerprint. | off |
+| `--hybrid-tools` / `--context-inject` | Remap to CC tools **and** inject request-context values (`sessionId`, `requestId`, `channelId`, `userId`, `timestamp`) into client-declared fields CC's schema doesn't carry. Preserves the CC fingerprint while keeping custom schemas functional — see [Hybrid tool mode](#hybrid-tool-mode). Mutually exclusive with `--preserve-tools`. | off |
 | `--model=<name>` | Force a model (`opus`, `sonnet`, `haiku`, or full ID). Applies to the Claude backend. | passthrough |
 | `--port=<n>` | Port to listen on | `3456` |
 | `--host=<addr>` / `DARIO_HOST` | Bind address. Use `0.0.0.0` for LAN, or a specific IP (e.g. a Tailscale interface). When non-loopback, also set `DARIO_API_KEY`. | `127.0.0.1` |
@@ -347,6 +348,50 @@ curl http://localhost:3456/v1/chat/completions \
 
 All supported. Claude backend: full Anthropic SSE format plus OpenAI-SSE translation for tool_use streaming. OpenAI-compat backend: streaming body forwarded byte-for-byte.
 
+### 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.
+
+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, anything — 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.
+
+Fix: run dario with `--preserve-tools` (or `--keep-tools`). That skips the CC tool remap entirely, passes your client's tool definitions through to the model unchanged, and lets the model populate every field your schema expects.
+
+```bash
+dario proxy --preserve-tools
+```
+
+The cost: requests no longer look like CC on the wire, so the CC subscription fingerprint is gone. On a Max/Pro plan, that means the request may be counted against your API usage rather than your subscription quota. If you're on API-key billing already, `--preserve-tools` is free; if you're using dario specifically to route against a subscription, the [hybrid tool mode](#hybrid-tool-mode) below is the compromise that keeps both.
+
+The openai-compat backend (OpenRouter, OpenAI, Groq, local LiteLLM, etc.) is unaffected — it forwards tool definitions byte-for-byte and doesn't need this flag.
+
+### Hybrid tool mode
+
+For the very common case where the "missing" fields on your client's tool are **request context** — `sessionId`, `requestId`, `channelId`, `userId`, `timestamp` — dario can remap to CC tools *and* inject those values on the reverse path. The fingerprint stays intact, the model still sees only CC's tools (so subscription billing still routes), and your validator still sees the fields it requires because dario fills them from request headers on the way back.
+
+```bash
+dario proxy --hybrid-tools
+```
+
+**How it works.** On each request, dario builds a `RequestContext` from headers (`x-session-id`, `x-request-id`, `x-channel-id`, `x-user-id`) plus its own generated ids and the current timestamp. After `translateBack` produces the client-shaped tool call on the response path, any field declared on the client's tool schema whose name matches a known context field (`sessionId`/`session_id`, `requestId`/`request_id`, `channelId`/`channel_id`, `userId`/`user_id`, `timestamp`/`created_at`/`createdAt`) and isn't already populated gets filled from the context. Fields the model genuinely populated via `translateBack` are never overwritten.
+
+**When to use which flag.**
+
+| Your situation | Flag | Why |
+|---|---|---|
+| 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. |
+
+**Limitations of hybrid mode.**
+
+- Top-level fields only. If your custom field is nested (e.g. `meta: {sessionId: ...}`), v1 doesn't reach into the nested object. Tracked in [#33](https://github.com/askalf/dario/issues/33).
+- The field-to-context mapping is a fixed list. If you need arbitrary fields (e.g. an internal `tenant_id`) pulled from headers, file an issue and we'll extend the map.
+- No type coercion beyond string. If your schema requires a numeric `sessionId`, dario sends the string it got from headers — override at your client level or use `--preserve-tools`.
+
+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.
+
 ### Library mode
 
 ```typescript
@@ -530,6 +575,8 @@ npm run dev   # runs with tsx, no build step
 | [@GodsBoy](https://github.com/GodsBoy) | Proxy authentication, token redaction, error sanitization ([#2](https://github.com/askalf/dario/pull/2)) |
 | [@belangertrading](https://github.com/belangertrading) | Billing classification investigation ([#4](https://github.com/askalf/dario/issues/4)), cache_control fingerprinting ([#6](https://github.com/askalf/dario/issues/6)), billing reclassification root cause ([#7](https://github.com/askalf/dario/issues/7)), OAuth client_id discovery ([#12](https://github.com/askalf/dario/issues/12)), multi-agent session-level billing analysis ([#23](https://github.com/askalf/dario/issues/23)) |
 | [@nathan-widjaja](https://github.com/nathan-widjaja) | README positioning rewrite structure ([#21](https://github.com/askalf/dario/issues/21)) |
+| [@iNicholasBE](https://github.com/iNicholasBE) | macOS keychain credential detection ([#30](https://github.com/askalf/dario/pull/30)) |
+| [@boeingchoco](https://github.com/boeingchoco) | Reverse-direction tool parameter translation ([#29](https://github.com/askalf/dario/issues/29)), SSE event-group framing regression catch (v3.7.1), provider-comparison diagnostic that surfaced the `--preserve-tools` discoverability gap (v3.8.1), and the motivating case for hybrid tool mode ([#33](https://github.com/askalf/dario/issues/33), v3.9.0) |
 
 ---
 

package/dist/cc-template.d.ts

@@ -37,6 +37,25 @@ export interface ToolMapping {
     ccTool: string;
     translateArgs?: (args: Record<string, unknown>) => Record<string, unknown>;
     translateBack?: (args: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Top-level field names the client's original tool schema declared.
+     * Populated only in hybrid mode (`hybridTools: true`) so the reverse
+     * path can inject request-context values (sessionId, requestId, …)
+     * into fields CC's schema doesn't carry. Unset in default mode.
+     */
+    clientFields?: string[];
+}
+/**
+ * Request context extracted once per incoming request. Source for
+ * hybrid-mode field injection — fields declared on the client's tool
+ * but not on CC's get filled from here on the reverse path.
+ */
+export interface RequestContext {
+    sessionId: string;
+    requestId: string;
+    channelId?: string;
+    userId?: string;
+    timestamp: string;
 }
 /**
  * Build a CC-template request from a client request.
@@ -52,6 +71,7 @@ export declare function buildCCRequest(clientBody: Record<string, unknown>, bill
     sessionId: string;
 }, opts?: {
     preserveTools?: boolean;
+    hybridTools?: boolean;
 }): {
     body: Record<string, unknown>;
     toolMap: Map<string, ToolMapping>;
@@ -64,7 +84,7 @@ export declare function buildCCRequest(clientBody: Record<string, unknown>, bill
  * body isn't valid JSON (e.g. an error response, a partial chunk),
  * returns it unchanged.
  */
-export declare function reverseMapResponse(responseBody: string, toolMap: Map<string, ToolMapping>): string;
+export declare function reverseMapResponse(responseBody: string, toolMap: Map<string, ToolMapping>, ctx?: RequestContext): string;
 /**
  * Streaming reverse-mapper for SSE responses.
  *
@@ -111,4 +131,4 @@ export interface StreamingReverseMapper {
     feed(chunk: Uint8Array): Uint8Array;
     end(): Uint8Array;
 }
-export declare function createStreamingReverseMapper(toolMap: Map<string, ToolMapping>): StreamingReverseMapper;
+export declare function createStreamingReverseMapper(toolMap: Map<string, ToolMapping>, ctx?: RequestContext): StreamingReverseMapper;

package/dist/cc-template.js

@@ -39,6 +39,49 @@ export function scrubFrameworkIdentifiers(text) {
     }
     return result;
 }
+/**
+ * Map from client-declared field name (lowercase) to the RequestContext
+ * key that supplies its value. A field declared on the client's tool
+ * whose name matches one of these gets auto-filled in hybrid mode.
+ *
+ * Case-insensitive match on the client's declared field name. Both
+ * snake_case and camelCase variants map to the same source.
+ */
+const CONTEXT_FIELD_SOURCES = {
+    sessionid: 'sessionId',
+    session_id: 'sessionId',
+    requestid: 'requestId',
+    request_id: 'requestId',
+    channelid: 'channelId',
+    channel_id: 'channelId',
+    userid: 'userId',
+    user_id: 'userId',
+    timestamp: 'timestamp',
+    createdat: 'timestamp',
+    created_at: 'timestamp',
+};
+/**
+ * Fill in fields declared on the client's tool schema that are still
+ * absent from the translated input, drawing values from the request
+ * context. Only runs when a mapping has `clientFields` populated
+ * (hybrid mode) and an input object is present. Fields already set
+ * by `translateBack` are never overwritten.
+ */
+function injectContextFields(input, clientFields, ctx) {
+    if (!clientFields || !ctx)
+        return input;
+    for (const field of clientFields) {
+        if (field in input && input[field] !== undefined && input[field] !== null && input[field] !== '')
+            continue;
+        const sourceKey = CONTEXT_FIELD_SOURCES[field.toLowerCase()];
+        if (!sourceKey)
+            continue;
+        const value = ctx[sourceKey];
+        if (value !== undefined)
+            input[field] = value;
+    }
+    return input;
+}
 const TOOL_MAP = {
     // Direct maps
     bash: {
@@ -233,7 +276,18 @@ export function buildCCRequest(clientBody, billingTag, cache1h, identity, opts =
             const name = (tool.name || '').toLowerCase();
             const mapping = TOOL_MAP[name];
             if (mapping) {
-                activeToolMap.set(tool.name, mapping);
+                // In hybrid mode, clone the shared mapping and attach the
+                // client-declared top-level field names from input_schema.
+                // The reverse path uses these to inject request-context values
+                // into fields CC's schema doesn't carry.
+                if (opts.hybridTools) {
+                    const schema = tool.input_schema;
+                    const fields = schema?.properties ? Object.keys(schema.properties) : [];
+                    activeToolMap.set(tool.name, { ...mapping, clientFields: fields });
+                }
+                else {
+                    activeToolMap.set(tool.name, mapping);
+                }
                 claimedCC.add(mapping.ccTool);
             }
         }
@@ -435,7 +489,7 @@ function buildReverseLookup(toolMap) {
  * leaving the input shape in CC's parameter names which the client's
  * own validator would reject.
  */
-function rewriteToolUseBlock(block, reverseMap) {
+function rewriteToolUseBlock(block, reverseMap, ctx) {
     const ccName = block.name;
     if (typeof ccName !== 'string')
         return;
@@ -453,6 +507,13 @@ function rewriteToolUseBlock(block, reverseMap) {
             // the same broken input it would have seen pre-v3.7.0.
         }
     }
+    // Hybrid mode: inject request-context values into any client-declared
+    // fields still missing after translateBack. No-op unless the mapping
+    // was built with `clientFields` populated (hybridTools: true) and a
+    // context was passed in.
+    if (entry.mapping.clientFields && block.input && typeof block.input === 'object') {
+        injectContextFields(block.input, entry.mapping.clientFields, ctx);
+    }
 }
 /**
  * Reverse-map CC tool calls in a non-streaming response back to the
@@ -461,7 +522,7 @@ function rewriteToolUseBlock(block, reverseMap) {
  * body isn't valid JSON (e.g. an error response, a partial chunk),
  * returns it unchanged.
  */
-export function reverseMapResponse(responseBody, toolMap) {
+export function reverseMapResponse(responseBody, toolMap, ctx) {
     if (toolMap.size === 0)
         return responseBody;
     const reverseMap = buildReverseLookup(toolMap);
@@ -477,12 +538,12 @@ export function reverseMapResponse(responseBody, toolMap) {
         return responseBody;
     for (const block of content) {
         if (block && typeof block === 'object' && block.type === 'tool_use') {
-            rewriteToolUseBlock(block, reverseMap);
+            rewriteToolUseBlock(block, reverseMap, ctx);
         }
     }
     return JSON.stringify(parsed);
 }
-export function createStreamingReverseMapper(toolMap) {
+export function createStreamingReverseMapper(toolMap, ctx) {
     const noop = {
         feed: (chunk) => chunk,
         end: () => new Uint8Array(0),
@@ -490,11 +551,13 @@ export function createStreamingReverseMapper(toolMap) {
     if (toolMap.size === 0)
         return noop;
     const reverseMap = buildReverseLookup(toolMap);
-    // If no mapping needs translation, fall back to identity behavior
-    // so we don't pay the SSE-parsing cost on every chunk.
+    // If no mapping needs translation OR context injection, fall back to
+    // identity behavior so we don't pay the SSE-parsing cost on every chunk.
+    // Hybrid mode with clientFields always needs the streaming path so the
+    // injection can run at content_block_stop.
     let anyNeedsTranslation = false;
     for (const { mapping } of reverseMap.values()) {
-        if (mapping.translateBack) {
+        if (mapping.translateBack || (mapping.clientFields && mapping.clientFields.length > 0)) {
             anyNeedsTranslation = true;
             break;
         }
@@ -568,7 +631,9 @@ export function createStreamingReverseMapper(toolMap) {
             const block = event.content_block;
             if (block && block.type === 'tool_use' && typeof block.name === 'string') {
                 const entry = reverseMap.get(block.name);
-                if (entry && entry.mapping.translateBack && idx >= 0) {
+                const needsBuffering = entry && idx >= 0 && (entry.mapping.translateBack ||
+                    (entry.mapping.clientFields && entry.mapping.clientFields.length > 0));
+                if (entry && needsBuffering) {
                     // Stash the block so we can flush a translated version at
                     // content_block_stop. Emit a rewritten start event now so
                     // the client sees its own tool name immediately.
@@ -619,6 +684,9 @@ export function createStreamingReverseMapper(toolMap) {
                 translatedInput = buf.mapping.translateBack
                     ? buf.mapping.translateBack(parsedInput)
                     : parsedInput;
+                if (buf.mapping.clientFields && buf.mapping.clientFields.length > 0) {
+                    injectContextFields(translatedInput, buf.mapping.clientFields, ctx);
+                }
             }
             catch {
                 parseOk = false;

package/dist/cli.js

@@ -140,9 +140,14 @@ async function proxy() {
     const verbose = args.includes('--verbose') || args.includes('-v');
     const passthrough = args.includes('--passthrough') || args.includes('--thin');
     const preserveTools = args.includes('--preserve-tools') || args.includes('--keep-tools');
+    const hybridTools = args.includes('--hybrid-tools') || args.includes('--context-inject');
+    if (preserveTools && hybridTools) {
+        console.error('[dario] --preserve-tools and --hybrid-tools are mutually exclusive. Pick one.');
+        process.exit(1);
+    }
     const modelArg = args.find(a => a.startsWith('--model='));
     const model = modelArg ? modelArg.split('=')[1] : undefined;
-    await startProxy({ port, host, verbose, model, passthrough, preserveTools });
+    await startProxy({ port, host, verbose, model, passthrough, preserveTools, hybridTools });
 }
 async function accounts() {
     const sub = args[1];
@@ -369,6 +374,10 @@ async function help() {
                              Default: passthrough (client decides)
     --passthrough, --thin    Thin proxy — OAuth swap only, no injection
     --preserve-tools         Keep client tool schemas (for agents with custom tools)
+    --hybrid-tools           Remap to CC tools AND inject request-context fields
+                             (sessionId, requestId, channelId, userId, timestamp)
+                             declared on the client's tool schema but missing
+                             from CC's. Preserves CC fingerprint. See #33.
     --port=PORT              Port to listen on (default: 3456)
     --host=ADDRESS           Address to bind to (default: 127.0.0.1)
                              Use 0.0.0.0 to accept connections from other machines.

package/dist/proxy.d.ts

@@ -5,6 +5,7 @@ interface ProxyOptions {
     model?: string;
     passthrough?: boolean;
     preserveTools?: boolean;
+    hybridTools?: boolean;
 }
 export declare function sanitizeError(err: unknown): string;
 export declare function startProxy(opts?: ProxyOptions): Promise<void>;

package/dist/proxy.js

@@ -626,6 +626,20 @@ export async function startProxy(opts = {}) {
             let finalBody = body.length > 0 ? body : undefined;
             let ccToolMap = null;
             let requestModel = '';
+            // 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
+            // carry. Undefined when hybridTools is off — the reverse path then
+            // skips injection entirely.
+            const reqCtx = opts.hybridTools ? {
+                sessionId: req.headers['x-session-id']
+                    ?? req.headers['x-client-session-id']
+                    ?? SESSION_ID,
+                requestId: req.headers['x-request-id'] ?? randomUUID(),
+                channelId: req.headers['x-channel-id'],
+                userId: req.headers['x-user-id'],
+                timestamp: new Date().toISOString(),
+            } : undefined;
             if (body.length > 0) {
                 try {
                     const parsed = JSON.parse(body.toString());
@@ -649,7 +663,10 @@ export async function startProxy(opts = {}) {
                         const bodyIdentity = poolAccount
                             ? poolAccount.identity
                             : { deviceId: identity.deviceId, accountUuid: identity.accountUuid, sessionId: SESSION_ID };
-                        const { body: ccBody, toolMap } = buildCCRequest(r, billingTag, CACHE_1H, bodyIdentity, { preserveTools: opts.preserveTools ?? false });
+                        const { body: ccBody, toolMap } = buildCCRequest(r, billingTag, CACHE_1H, bodyIdentity, {
+                            preserveTools: opts.preserveTools ?? false,
+                            hybridTools: opts.hybridTools ?? false,
+                        });
                         // Store tool map for response reverse-mapping
                         ccToolMap = toolMap;
                         // Replace request body entirely with CC template
@@ -944,7 +961,7 @@ export async function startProxy(opts = {}) {
                 // path; the non-streaming reverseMapResponse covers buffered
                 // responses below.
                 const streamMapper = ccToolMap && !isOpenAI
-                    ? createStreamingReverseMapper(ccToolMap)
+                    ? createStreamingReverseMapper(ccToolMap, reqCtx)
                     : null;
                 try {
                     let buffer = '';
@@ -1039,7 +1056,7 @@ export async function startProxy(opts = {}) {
                 let responseBody = await upstream.text();
                 // Reverse tool name mapping so client sees original names
                 if (ccToolMap)
-                    responseBody = reverseMapResponse(responseBody, ccToolMap);
+                    responseBody = reverseMapResponse(responseBody, ccToolMap, reqCtx);
                 if (isOpenAI && upstream.status >= 200 && upstream.status < 300) {
                     try {
                         const parsed = JSON.parse(responseBody);

package/package.json

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