@mlx-node/server 0.0.0 → 0.0.8

package/dist/mappers/anthropic-request.js

@@ -1,4 +1,60 @@
 /** Anthropic Messages API request → internal `ChatMessage[]` + `ChatConfig`. */
+import { anthropicToolUseIdToInternal } from './anthropic-response.js';
+import { applyExtraBodyMtpOverrides } from './request.js';
+/**
+ * Anthropic billing/attribution header prefix. Claude Code injects a leading
+ * system block of the shape `"x-anthropic-billing-header: cc_version=...; cch=<token>;"`
+ * where the `cch=` token rotates per request. Leaving this in the prompt
+ * defeats prefix caching at BOTH the warm-slot gate (`getOrCreateWarmAny`,
+ * which compares `requestedSystem` byte-equally) AND the native
+ * token-prefix verifier inside `chatSessionStart`. We mirror vLLM's strategy
+ * (`vllm/entrypoints/anthropic/serving.py`, commit 262b76a0, 2026-03-11):
+ * stateless, per-block, prefix-only — drop entirely BEFORE tokenization, so
+ * the model never sees the rotating token AND the byte-prefix is stable.
+ *
+ * Hardcoded (not configurable) and intentionally limited to this single
+ * prefix to mirror vLLM's exact behaviour. The string-system branch is left
+ * UNFILTERED to match upstream.
+ */
+const ANTHROPIC_BILLING_HEADER_PREFIX = 'x-anthropic-billing-header';
+/**
+ * Canonicalize the Anthropic `system` field into the same string the mapper
+ * bakes into the leading `system` ChatMessage. Used by both
+ * `mapAnthropicRequest` (so the model never sees the billing header) and the
+ * `/v1/messages` warm-slot gate cache-key derivation (so the gate matches
+ * across rotating billing tokens). The two views MUST stay in sync — a
+ * single source of truth prevents drift.
+ *
+ * Asymmetry vs. `mapAnthropicRequest`: the mapper THROWS on non-text blocks
+ * (it's a request-validation gate), but this helper silently skips them.
+ * Safe because `mapAnthropicRequest` runs first as a pre-flight gate, so by
+ * the time the cache-key is computed, the request shape has already been
+ * validated.
+ */
+export function canonicalizeSystemForCacheKey(system) {
+    if (system == null)
+        return null;
+    if (typeof system === 'string')
+        return system;
+    const parts = [];
+    for (const b of system) {
+        if (b.type === 'text' && !b.text.startsWith(ANTHROPIC_BILLING_HEADER_PREFIX)) {
+            parts.push(b.text);
+        }
+    }
+    // An array whose every block is stripped (e.g. a request whose only system
+    // block is the rotating `x-anthropic-billing-header` line) is semantically
+    // equivalent to "no system" — collapse to `null` so it (a) does NOT push an
+    // empty `system` ChatMessage that the chat template wraps with two extra
+    // `<|im_start|>system\n<|im_end|>\n` tokens (perturbing the prefix vs. an
+    // absent-system request), and (b) compares byte-equal to `undefined` /
+    // missing on the warm-slot gate (`SessionRegistry.getOrCreateWarmAny`
+    // checks `entry.instructions !== requestedInstructions`, where `null !==
+    // ''` would otherwise miss the slot).
+    if (parts.length === 0)
+        return null;
+    return parts.join('');
+}
 /**
  * Resolve the text content of a `tool_result` block. The internal `ChatMessage`
  * shape (NAPI-generated) has no `images` field on `role: 'tool'`, so nested
@@ -46,23 +102,48 @@ function mapTool(tool) {
 }
 export function mapAnthropicRequest(req) {
     const messages = [];
+    // The leading system message is assembled and `unshift`ed AFTER the message
+    // loop so that any `system`-role message folded out of `req.messages` (see
+    // the `role === 'system'` branch below) is concatenated with the top-level
+    // `system` field into a single leading system prompt. We compute the
+    // top-level contribution here but defer the push.
+    let topLevelSystem = null;
     if (req.system != null) {
         if (typeof req.system === 'string') {
-            messages.push({ role: 'system', content: req.system });
+            topLevelSystem = req.system;
         }
         else {
-            const systemParts = [];
+            // Validate first — throw early on unsupported block types so the
+            // request fails fast (this is the validation gate). Stripping of
+            // the rotating billing-header prefix happens inside
+            // `canonicalizeSystemForCacheKey`, the single source of truth
+            // shared with `endpoints/messages.ts`'s `requestedSystem` cache
+            // key. Routing both call sites through the same helper means
+            // any future change to the strip semantics (prefix list,
+            // normalization, etc.) lands in exactly one place — the mapped
+            // messages and the cache-key view cannot drift.
             for (const b of req.system) {
-                if (b.type === 'text') {
-                    systemParts.push(b.text);
-                }
-                else {
+                if (b.type !== 'text') {
                     throw new Error(`Unsupported system block type: "${b.type}"`);
                 }
             }
-            messages.push({ role: 'system', content: systemParts.join('') });
+            // Helper returns `null` when every block was stripped (e.g. a
+            // request whose only system block is the rotating
+            // `x-anthropic-billing-header` line). An all-stripped array is
+            // semantically equivalent to "no system", so it contributes
+            // nothing — emitting `{ role: 'system', content: '' }` would
+            // otherwise have the chat template wrap it with two extra
+            // `<|im_start|>system\n<|im_end|>\n` tokens, perturbing the
+            // prefix vs. an absent-system request and breaking prefix
+            // caching across the two semantically-equivalent shapes.
+            topLevelSystem = canonicalizeSystemForCacheKey(req.system);
         }
     }
+    // Text folded out of any `system`-role message(s) in `req.messages`, in
+    // encounter order. Anthropic has no system role in `messages`, but Claude
+    // Code hooks inject one; its content is positionless "additional context"
+    // so we fold it into the leading system prompt regardless of position.
+    const foldedSystemParts = [];
     for (const msg of req.messages) {
         const { role, content } = msg;
         if (role === 'user') {
@@ -82,6 +163,14 @@ export function mapAnthropicRequest(req) {
                 const trailingImages = [];
                 let seenNonToolResult = false;
                 let seenToolResult = false;
+                // The flat `ChatMessage` shape cannot represent a text block that
+                // appears AFTER an image block in the same turn — the downstream
+                // Jinja serializer always places text before images. Reject that
+                // interleaving up front rather than silently reordering it and
+                // changing the caller's intent. This parallels the identical
+                // guard in `request.ts:resolveMessageContent` for the
+                // `/v1/responses` mapper.
+                let seenImage = false;
                 for (const block of content) {
                     if (block.type === 'tool_result') {
                         if (seenNonToolResult) {
@@ -92,18 +181,32 @@ export function mapAnthropicRequest(req) {
                         }
                         seenToolResult = true;
                         const resolved = resolveToolResultContent(block.content);
+                        // Anthropic clients echo back the same `toolu_<uuid>` we
+                        // emitted on the prior assistant turn. Translate it back to
+                        // the internal `call_<uuid>` shape so the native session
+                        // store's tool_call_id lookup (which sees the original
+                        // `call_*` id) still matches. Ids that lack the `toolu_`
+                        // prefix (legacy callers that already speak the internal
+                        // shape) pass through unchanged.
                         toolResults.push({
-                            toolCallId: block.tool_use_id,
+                            toolCallId: anthropicToolUseIdToInternal(block.tool_use_id),
                             content: resolved.text,
                             isError: block.is_error === true,
                         });
                     }
                     else if (block.type === 'text') {
+                        if (seenImage) {
+                            throw new Error('Unsupported: text block after an image block in the same user turn is not representable ' +
+                                'in the internal message model. The flat ChatMessage shape and the Jinja serializer both ' +
+                                'place all text before all images, so any mapping would silently reorder your content. ' +
+                                'Place all text blocks before any image blocks, or split across separate user turns.');
+                        }
                         seenNonToolResult = true;
                         trailingText.push(block.text);
                     }
                     else if (block.type === 'image' && block.source.type === 'base64') {
                         seenNonToolResult = true;
+                        seenImage = true;
                         trailingImages.push(Buffer.from(block.source.data, 'base64'));
                     }
                     else {
@@ -111,20 +214,32 @@ export function mapAnthropicRequest(req) {
                     }
                 }
                 if (seenToolResult) {
-                    // `ChatMessage` (NAPI-generated) has no `isError` field, so
-                    // Anthropic's `tool_result.is_error=true` is encoded as a JSON
-                    // envelope `{ "is_error": true, "content": <original> }`. The
-                    // envelope preserves the raw payload verbatim (unlike a text
-                    // prefix, which would corrupt JSON payloads and collide with
-                    // strings that legitimately start with the prefix). Every other
-                    // wire shape is a successful tool result.
+                    // The structured `isError` field on the internal `ChatMessage`
+                    // is the authoritative signal of tool-call failure (mirroring
+                    // the existing `toolCallId` pattern). Pass `tr.content`
+                    // through verbatim — no JSON envelope, no in-band marker — and
+                    // surface the error condition via the dedicated structured
+                    // field. The Rust-side wire-format renderers (Jinja serializer
+                    // for the cold-start path, ChatML formatter for the fallback
+                    // template) inject a short model-facing `[tool error]` cue
+                    // into the prompt when `isError === true`, but the
+                    // `ChatMessage.content` itself stays byte-for-byte equal to
+                    // the original payload so a successful tool result whose
+                    // content happens to start with the same marker text cannot
+                    // be confused with an errored one on read-back. Neither
+                    // mlx-lm nor mlx-vlm have a precedent for an in-band marker
+                    // here; the structured-field approach matches how
+                    // `toolCallId` is plumbed and survives round-tripping cleanly.
                     for (const tr of toolResults) {
-                        const encoded = tr.isError ? JSON.stringify({ is_error: true, content: tr.content }) : tr.content;
-                        messages.push({
+                        const msg = {
                             role: 'tool',
-                            content: encoded,
+                            content: tr.content,
                             toolCallId: tr.toolCallId,
-                        });
+                        };
+                        if (tr.isError) {
+                            msg.isError = true;
+                        }
+                        messages.push(msg);
                     }
                     // Trailing suffix after a tool_result prefix: accept either
                     // (a) text-only (concatenated) or (b) exactly one image block.
@@ -186,8 +301,12 @@ export function mapAnthropicRequest(req) {
                     }
                     else if (block.type === 'tool_use') {
                         seenToolUse = true;
+                        // Anthropic clients echo back the `toolu_<uuid>` we emitted
+                        // on the prior assistant turn. Translate to the internal
+                        // `call_<uuid>` shape so the native session store and the
+                        // Qwen chat template paths see a consistent id family.
                         toolCalls.push({
-                            id: block.id,
+                            id: anthropicToolUseIdToInternal(block.id),
                             name: block.name,
                             arguments: JSON.stringify(block.input),
                         });
@@ -206,10 +325,68 @@ export function mapAnthropicRequest(req) {
                 messages.push(assistantMsg);
             }
         }
+        else if (role === 'system') {
+            // `system` is not a role in the Anthropic Messages spec, but Claude
+            // Code's SessionStart hooks (e.g. superpowers) inject a
+            // `{ role: 'system' }` message carrying "additional context" into the
+            // `messages` array. Rather than rejecting the request (HTTP 400), fold
+            // its text into the leading system prompt (assembled after the loop).
+            //
+            // CONTRACT — position-agnostic hoist (deliberate): a `system`-role
+            // message is folded to the SINGLE leading system prompt regardless of
+            // where it appears in `messages`. This is intentional, not incidental:
+            //   1. The Anthropic wire format has no positional `system` role, so
+            //      any `{ role: 'system' }` here is non-spec tooling injection with
+            //      no defined positional semantics to preserve.
+            //   2. The only known producer (Claude Code SessionStart hooks) emits
+            //      positionless "additional context" — conceptually system-level,
+            //      not a turn-point instruction.
+            //   3. The internal `ChatMessage`/`primeHistory` pipeline represents
+            //      only a SINGLE leading system message; a mid-history system turn
+            //      is not representable, so hoisting is the sole non-rejecting
+            //      option. Multiple system-role messages accumulate in encounter
+            //      order (handled at assembly below).
+            if (typeof content === 'string') {
+                foldedSystemParts.push(content);
+            }
+            else {
+                let text = '';
+                for (const block of content) {
+                    if (block.type !== 'text') {
+                        throw new Error(`Unsupported content block type "${block.type}" in system-role message`);
+                    }
+                    text += block.text;
+                }
+                foldedSystemParts.push(text);
+            }
+        }
         else {
             throw new Error(`Unsupported message role: "${role}"`);
         }
     }
+    // Assemble the single leading system prompt from the top-level `system`
+    // field plus any folded `system`-role message text. Joined with `'\n\n'`
+    // between distinct contributions (a single string when there is only one),
+    // so a request with ONLY a top-level system — the overwhelmingly common
+    // case — stays byte-identical to the pre-folding behaviour.
+    //
+    // Empty folded contributions are dropped so an empty hook context message
+    // ({ role: 'system', content: '' }) neither corrupts a real top-level
+    // system prompt with a trailing `'\n\n'` separator nor synthesises a bare
+    // empty system message. The top-level `system` field itself is preserved
+    // verbatim (an explicit empty string still emits, matching prior behaviour).
+    const systemParts = [];
+    if (topLevelSystem !== null) {
+        systemParts.push(topLevelSystem);
+    }
+    for (const part of foldedSystemParts) {
+        if (part.length > 0) {
+            systemParts.push(part);
+        }
+    }
+    if (systemParts.length > 0) {
+        messages.unshift({ role: 'system', content: systemParts.join('\n\n') });
+    }
     const config = {
         reportPerformance: true,
     };
@@ -225,17 +402,38 @@ export function mapAnthropicRequest(req) {
     if (req.top_k != null) {
         config.topK = req.top_k;
     }
+    // `stop_sequences` has no `ChatConfig` field to map onto, so it rides out on
+    // the widened return instead. Normalize to drop absent/null entries, empty
+    // strings (which would match at every position and stop generation
+    // immediately), and whitespace-only entries (which would truncate normal
+    // output at the first space/newline; the real Anthropic API rejects these
+    // with a 400, so making them a no-op is the lowest-risk resolution). A
+    // downstream consumer honours the result.
+    const stopSequences = (req.stop_sequences ?? []).filter((s) => typeof s === 'string' && s.trim().length > 0);
     if (req.tools && req.tools.length > 0) {
         const toolChoice = req.tool_choice;
-        if (toolChoice?.type === 'tool' && toolChoice.name) {
+        if (toolChoice?.type === 'tool') {
+            // `{type:'tool', name:'X'}` is a HARD constraint: the model MUST call X
+            // and only X. If the caller omitted the name, or named a tool that is
+            // not in `req.tools`, falling through to the all-tools path would
+            // silently violate that contract. Reject up front so the failure mode
+            // is loud and the client gets a clear 400.
+            if (!toolChoice.name) {
+                throw new Error('tool_choice.type is "tool" but no name was provided');
+            }
             const matched = req.tools.filter((t) => t.name === toolChoice.name);
-            if (matched.length > 0) {
-                config.tools = matched.map(mapTool);
+            if (matched.length === 0) {
+                throw new Error(`tool_choice references tool "${toolChoice.name}" which is not present in the request's tools list`);
             }
+            config.tools = matched.map(mapTool);
         }
         else {
+            // `tool_choice` is undefined, `{type:'auto'}`, or `{type:'any'}` — all
+            // three semantically mean "let the model pick from any tool", so we
+            // forward the full tools array.
             config.tools = req.tools.map(mapTool);
         }
     }
-    return { messages, config };
+    applyExtraBodyMtpOverrides(config, req.extra_body);
+    return { messages, config, stopSequences };
 }

package/dist/mappers/anthropic-response.d.ts

@@ -1,14 +1,39 @@
 /** ChatResult / ChatStreamEvent → Anthropic Messages API output. */
 import type { ChatResult } from '@mlx-node/core';
+import { type PerformanceMetricsForUsage, type ServerTimingForUsage } from '../timing.js';
 import type { AnthropicContentBlockDeltaEvent, AnthropicContentBlockStartEvent, AnthropicContentBlockStopEvent, AnthropicDelta, AnthropicMessageDeltaEvent, AnthropicMessageStartEvent, AnthropicMessageStopEvent, AnthropicMessagesRequest, AnthropicMessagesResponse, AnthropicResponseContent } from '../types-anthropic.js';
-export declare function mapStopReason(finishReason: string, hasToolCalls: boolean): 'end_turn' | 'max_tokens' | 'tool_use';
-export declare function buildAnthropicContent(result: ChatResult): AnthropicResponseContent[];
-export declare function buildAnthropicResponse(result: ChatResult, req: AnthropicMessagesRequest, messageId: string): AnthropicMessagesResponse;
+/**
+ * Translate a native tool-call id (minted as `call_<uuid>` by the Rust
+ * parser, which keeps the OpenAI Responses convention) to the Anthropic
+ * Messages wire convention (`toolu_<uuid>`). The uuid body is preserved
+ * verbatim so the inverse `anthropicToolUseIdToInternal` round-trips
+ * losslessly when clients echo the id back via `tool_result.tool_use_id`.
+ *
+ * Defensive: ids that do not have the expected `call_` prefix (e.g. a
+ * legacy caller, an in-process driver constructing its own id, or a
+ * future variant) pass through unchanged so this function never
+ * synthesizes a wrong id.
+ */
+export declare function internalToolCallIdToAnthropic(id: string): string;
+/**
+ * Inverse of `internalToolCallIdToAnthropic`: translate an incoming
+ * Anthropic `tool_use_id` (`toolu_<uuid>`) back to the internal `call_*`
+ * shape so historical assistant turns and the tool_call_id lookup in
+ * the native session store keep matching. Ids without the expected
+ * `toolu_` prefix pass through unchanged for the same defensive reason
+ * (some legacy callers send raw `call_*` directly).
+ */
+export declare function anthropicToolUseIdToInternal(id: string): string;
+export declare function mapStopReason(finishReason: string, hasToolCalls: boolean, matchedStopSequence?: string | null): 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+export declare function containsToolCallMarkup(rawText: string): boolean;
+export declare function recoverSuppressedToolCallText(rawText: string): string;
+export declare function buildAnthropicContent(result: ChatResult, allowToolUse?: boolean, stopMatched?: boolean): AnthropicResponseContent[];
+export declare function buildAnthropicResponse(result: ChatResult, req: AnthropicMessagesRequest, messageId: string, performance?: PerformanceMetricsForUsage, allowToolUse?: boolean, serverTiming?: ServerTimingForUsage, matchedStopSequence?: string | null): AnthropicMessagesResponse;
 /** Embedded message has empty content and zero output_tokens at start. */
 export declare function buildMessageStartEvent(req: AnthropicMessagesRequest, messageId: string, inputTokens: number): AnthropicMessageStartEvent;
 export declare function buildContentBlockStart(index: number, block: AnthropicResponseContent): AnthropicContentBlockStartEvent;
 export declare function buildContentBlockDelta(index: number, delta: AnthropicDelta): AnthropicContentBlockDeltaEvent;
 export declare function buildContentBlockStop(index: number): AnthropicContentBlockStopEvent;
-export declare function buildMessageDelta(stopReason: string, outputTokens: number, inputTokens?: number): AnthropicMessageDeltaEvent;
+export declare function buildMessageDelta(stopReason: string, outputTokens: number, inputTokens?: number, cachedTokens?: number, performance?: PerformanceMetricsForUsage, serverTiming?: ServerTimingForUsage, stopSequence?: string | null): AnthropicMessageDeltaEvent;
 export declare function buildMessageStop(): AnthropicMessageStopEvent;
 //# sourceMappingURL=anthropic-response.d.ts.map

package/dist/mappers/anthropic-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic-response.d.ts","sourceRoot":"","sources":["../../src/mappers/anthropic-response.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EACV,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,EAC9B,cAAc,EACd,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAU/B,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAQjH;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,wBAAwB,EAAE,CAwBpF;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,wBAAwB,EAC7B,SAAS,EAAE,MAAM,GAChB,yBAAyB,CAiB3B;AAID,0EAA0E;AAC1E,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,wBAAwB,EAC7B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,0BAA0B,CAiB5B;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,wBAAwB,GAC9B,+BAA+B,CAMjC;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,+BAA+B,CAM5G;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,8BAA8B,CAKnF;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,0BAA0B,CAY5B;AAED,wBAAgB,gBAAgB,IAAI,yBAAyB,CAI5D"}
+{"version":3,"file":"anthropic-response.d.ts","sourceRoot":"","sources":["../../src/mappers/anthropic-response.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,EAA8B,KAAK,0BAA0B,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACtH,OAAO,KAAK,EACV,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,EAC9B,cAAc,EACd,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAU/B;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,OAAO,EACrB,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAClC,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,UAAU,CAW1D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO/D;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,UAAU,EAClB,YAAY,UAAO,EACnB,WAAW,UAAQ,GAClB,wBAAwB,EAAE,CA0C5B;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,wBAAwB,EAC7B,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,0BAA0B,EACxC,YAAY,UAAO,EACnB,YAAY,CAAC,EAAE,oBAAoB,EACnC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAClC,yBAAyB,CAyD3B;AAID,0EAA0E;AAC1E,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,wBAAwB,EAC7B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,0BAA0B,CAiB5B;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,wBAAwB,GAC9B,+BAA+B,CAMjC;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,+BAA+B,CAM5G;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,8BAA8B,CAKnF;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,0BAA0B,EACxC,YAAY,CAAC,EAAE,oBAAoB,EACnC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3B,0BAA0B,CAgC5B;AAED,wBAAgB,gBAAgB,IAAI,yBAAyB,CAI5D"}

package/dist/mappers/anthropic-response.js

@@ -1,4 +1,5 @@
 /** ChatResult / ChatStreamEvent → Anthropic Messages API output. */
+import { mergeTimingUsageExtensions } from '../timing.js';
 import { genId } from './response.js';
 function parseArguments(args) {
     if (typeof args === 'string') {
@@ -6,7 +7,36 @@ function parseArguments(args) {
     }
     return args;
 }
-export function mapStopReason(finishReason, hasToolCalls) {
+/**
+ * Translate a native tool-call id (minted as `call_<uuid>` by the Rust
+ * parser, which keeps the OpenAI Responses convention) to the Anthropic
+ * Messages wire convention (`toolu_<uuid>`). The uuid body is preserved
+ * verbatim so the inverse `anthropicToolUseIdToInternal` round-trips
+ * losslessly when clients echo the id back via `tool_result.tool_use_id`.
+ *
+ * Defensive: ids that do not have the expected `call_` prefix (e.g. a
+ * legacy caller, an in-process driver constructing its own id, or a
+ * future variant) pass through unchanged so this function never
+ * synthesizes a wrong id.
+ */
+export function internalToolCallIdToAnthropic(id) {
+    return id.startsWith('call_') ? `toolu_${id.slice('call_'.length)}` : id;
+}
+/**
+ * Inverse of `internalToolCallIdToAnthropic`: translate an incoming
+ * Anthropic `tool_use_id` (`toolu_<uuid>`) back to the internal `call_*`
+ * shape so historical assistant turns and the tool_call_id lookup in
+ * the native session store keep matching. Ids without the expected
+ * `toolu_` prefix pass through unchanged for the same defensive reason
+ * (some legacy callers send raw `call_*` directly).
+ */
+export function anthropicToolUseIdToInternal(id) {
+    return id.startsWith('toolu_') ? `call_${id.slice('toolu_'.length)}` : id;
+}
+export function mapStopReason(finishReason, hasToolCalls, matchedStopSequence) {
+    if (matchedStopSequence) {
+        return 'stop_sequence';
+    }
     if (finishReason === 'length') {
         return 'max_tokens';
     }
@@ -15,41 +45,112 @@ export function mapStopReason(finishReason, hasToolCalls) {
     }
     return 'end_turn';
 }
-export function buildAnthropicContent(result) {
+export function containsToolCallMarkup(rawText) {
+    return (rawText.includes('<tool_call') ||
+        rawText.includes('</tool_call') ||
+        rawText.includes('<|tool_call') ||
+        rawText.includes('<tool_call|>'));
+}
+export function recoverSuppressedToolCallText(rawText) {
+    return rawText
+        .replace(/<\|channel>[\s\S]*?(?:<channel\|>|$)/g, '')
+        .replace(/<channel\|>/g, '')
+        .replace(/<\|tool_call>[\s\S]*?(?:<tool_call\|>|$)/g, '')
+        .replace(/<tool_call>[\s\S]*?(?:<\/tool_call>|$)/g, '')
+        .replace(/<\|tool_response>[\s\S]*?(?:<tool_response\|>|$)/g, '')
+        .replace(/<\|tool>[\s\S]*?(?:<tool\|>|$)/g, '')
+        .replace(/<\|turn>[^\n]*(?:\n|$)/g, '')
+        .replace(/<turn\|>/g, '');
+}
+export function buildAnthropicContent(result, allowToolUse = true, stopMatched = false) {
     const content = [];
     if (result.thinking) {
         content.push({ type: 'thinking', thinking: result.thinking });
     }
-    const okToolCalls = result.toolCalls.filter((t) => t.status === 'ok');
+    const parsedToolCalls = result.toolCalls.filter((t) => t.status === 'ok');
+    // A matched stop sequence halts generation at its position, so any tool call
+    // whose tag would have followed the stop boundary is dropped and the
+    // truncated visible text (`result.text`, already cut at the stop) is emitted
+    // verbatim — the suppressed-markup recovery is skipped because it would
+    // re-introduce text that lived after the stop.
+    const okToolCalls = stopMatched || !allowToolUse ? [] : parsedToolCalls;
+    const text = !stopMatched &&
+        !allowToolUse &&
+        result.text.length === 0 &&
+        parsedToolCalls.length > 0 &&
+        containsToolCallMarkup(result.rawText)
+        ? recoverSuppressedToolCallText(result.rawText)
+        : result.text;
     // Emit a text block unless tool calls exist and there is no text.
-    if (result.text || okToolCalls.length === 0) {
-        content.push({ type: 'text', text: result.text });
+    if (text || okToolCalls.length === 0) {
+        content.push({ type: 'text', text });
     }
     for (const tc of okToolCalls) {
+        // Translate native `call_<uuid>` to Anthropic `toolu_<uuid>` at the
+        // wire boundary. The fallback `genId('toolu_')` covers the case where
+        // the native parser did not mint an id (an in-process driver or a
+        // legacy bridge — present-day Rust paths always populate it).
         content.push({
             type: 'tool_use',
-            id: tc.id ?? genId('toolu_'),
+            id: tc.id != null ? internalToolCallIdToAnthropic(tc.id) : genId('toolu_'),
             name: tc.name,
             input: parseArguments(tc.arguments),
         });
     }
     return content;
 }
-export function buildAnthropicResponse(result, req, messageId) {
-    const okToolCalls = result.toolCalls.filter((t) => t.status === 'ok');
+export function buildAnthropicResponse(result, req, messageId, performance, allowToolUse = true, serverTiming, matchedStopSequence) {
+    // A matched stop sequence takes precedence over tool_use: suppress the tool
+    // calls so `stop_reason: 'stop_sequence'` is never emitted alongside a
+    // tool_use block whose tag followed the stop boundary.
+    const stopMatched = Boolean(matchedStopSequence);
+    const okToolCalls = allowToolUse && !stopMatched ? result.toolCalls.filter((t) => t.status === 'ok') : [];
     const hasToolCalls = okToolCalls.length > 0;
+    // Cache accounting (Anthropic Messages API spec):
+    //   * On a cache HIT (`cachedTokens > 0`) the wire MUST emit
+    //     `cache_read_input_tokens: cachedTokens` and reduce
+    //     `input_tokens` to the unsuffixed remainder
+    //     `promptTokens - cachedTokens` — Claude Code (and other
+    //     Anthropic-compatible UIs) read this directly for cost /
+    //     billing display, and a wire that left `input_tokens` at the
+    //     full prompt count would silently double-bill the cached
+    //     prefix.
+    //   * On a cache MISS (`cachedTokens === 0`) the cache fields are
+    //     OMITTED — they are optional in the spec and other
+    //     Anthropic-compatible servers elide them on misses.
+    //   * `cache_creation_input_tokens` stays unset: this server's KV
+    //     reuse is implicit (no `cache_control` breakpoints), so a
+    //     client that did not request explicit caching should never
+    //     see a non-zero creation count.
+    const cachedTokens = result.cachedTokens;
+    const usage = cachedTokens > 0
+        ? {
+            input_tokens: result.promptTokens - cachedTokens,
+            output_tokens: result.numTokens,
+            cache_read_input_tokens: cachedTokens,
+        }
+        : {
+            input_tokens: result.promptTokens,
+            output_tokens: result.numTokens,
+        };
+    // Server-extension perf fields. Same gating pattern as
+    // `cache_read_input_tokens`: only land on the wire when the native
+    // dispatch produced a finite, positive value — `undefined` /
+    // `NaN` / `0` is elided so the launcher's verbose log can read
+    // absence as "not plumbed" instead of treating zero as a real
+    // measurement. Cache-context fields make the prefill rate explicit:
+    // on cached-prefix turns the denominator is the uncached suffix, not
+    // the full logical prompt.
+    mergeTimingUsageExtensions(usage, performance, result.promptTokens, result.numTokens, cachedTokens, serverTiming);
     return {
         id: messageId,
         type: 'message',
         role: 'assistant',
         model: req.model,
-        content: buildAnthropicContent(result),
-        stop_reason: mapStopReason(result.finishReason, hasToolCalls),
-        stop_sequence: null,
-        usage: {
-            input_tokens: result.promptTokens,
-            output_tokens: result.numTokens,
-        },
+        content: buildAnthropicContent(result, allowToolUse, stopMatched),
+        stop_reason: mapStopReason(result.finishReason, hasToolCalls, matchedStopSequence),
+        stop_sequence: matchedStopSequence ?? null,
+        usage,
     };
 }
 // Streaming helpers
@@ -92,17 +193,38 @@ export function buildContentBlockStop(index) {
         index,
     };
 }
-export function buildMessageDelta(stopReason, outputTokens, inputTokens) {
+export function buildMessageDelta(stopReason, outputTokens, inputTokens, cachedTokens, performance, serverTiming, stopSequence) {
+    // Streaming `message_delta` mirrors the non-streaming response's
+    // cache accounting: when `cachedTokens > 0` we emit
+    // `cache_read_input_tokens: cachedTokens` AND subtract that count
+    // from `input_tokens`. On a cache miss (or when `cachedTokens` is
+    // omitted by an in-process driver / mock) the cache fields stay
+    // off the wire. See the matching block on `buildAnthropicResponse`
+    // and the field-level docstrings on `AnthropicUsage`.
+    const usage = {
+        output_tokens: outputTokens,
+    };
+    if (cachedTokens != null && cachedTokens > 0) {
+        if (inputTokens != null) {
+            usage.input_tokens = inputTokens - cachedTokens;
+        }
+        usage.cache_read_input_tokens = cachedTokens;
+    }
+    else if (inputTokens != null) {
+        usage.input_tokens = inputTokens;
+    }
+    // Server-extension perf fields — same gating pattern as the
+    // cache-field block above. See `buildAnthropicResponse` for the
+    // matching non-streaming branch and the docstring on
+    // `AnthropicUsage` for the wire-format rationale.
+    mergeTimingUsageExtensions(usage, performance, inputTokens, outputTokens, cachedTokens, serverTiming);
     return {
         type: 'message_delta',
         delta: {
             stop_reason: stopReason,
-            stop_sequence: null,
-        },
-        usage: {
-            ...(inputTokens != null ? { input_tokens: inputTokens } : {}),
-            output_tokens: outputTokens,
+            stop_sequence: stopSequence ?? null,
         },
+        usage,
     };
 }
 export function buildMessageStop() {