@mlx-node/server 0.0.0

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/** OpenAI- and Anthropic-compatible JSON error responses. */
+import type { ServerResponse } from 'node:http';
+export interface APIError {
+    type: string;
+    message: string;
+    code: string | null;
+    param: string | null;
+}
+export declare function sendError(res: ServerResponse, status: number, type: string, message: string, param?: string | null): void;
+export declare function sendBadRequest(res: ServerResponse, message: string, param?: string): void;
+export declare function sendNotFound(res: ServerResponse, message: string): void;
+export declare function sendMethodNotAllowed(res: ServerResponse, allowed: string): void;
+export declare function sendInternalError(res: ServerResponse, message: string): void;
+/**
+ * 503 with `type: 'storage_timeout'`. Emitted by the responses endpoint when
+ * an in-flight `store.store(...)` gating a `previous_response_id` continuation
+ * fails to settle within `CHAIN_WRITE_WAIT_TIMEOUT_MS` and the final `getChain`
+ * probe still misses. 503 (not 404) because the write may yet land, so the
+ * same id can be retried — a 404 would wrongly mark it permanently invalid.
+ */
+export declare function sendStorageTimeout(res: ServerResponse, message: string): void;
+/**
+ * 429 with `type: 'rate_limit_error'` and `code: 'queue_full'`. Emitted by
+ * `/v1/responses` when the per-model execution queue is already holding
+ * `maxQueueDepth` waiters behind the current dispatch. Always sets
+ * `Retry-After: 1` (string seconds) so clients back off briefly before
+ * retrying — short enough to encourage a retry, long enough to avoid
+ * busy-looping the server.
+ */
+export declare function sendRateLimit(res: ServerResponse, message: string): void;
+export declare function sendAnthropicError(res: ServerResponse, status: number, type: string, message: string): void;
+export declare function sendAnthropicBadRequest(res: ServerResponse, message: string): void;
+export declare function sendAnthropicNotFound(res: ServerResponse, message: string): void;
+export declare function sendAnthropicInternalError(res: ServerResponse, message: string): void;
+export declare function sendAnthropicMethodNotAllowed(res: ServerResponse, allowed: string): void;
+/**
+ * 429 Anthropic-shape rate-limit response. Mirror of {@link sendRateLimit}
+ * for `/v1/messages`. Body uses the `{ type: 'error', error: { type, message } }`
+ * envelope the rest of the Anthropic error helpers use; `Retry-After: 1`
+ * is set verbatim so clients can wait one second before retrying.
+ */
+export declare function sendAnthropicRateLimit(res: ServerResponse, message: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,SAAS,CACvB,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACpB,IAAI,CAWN;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEvE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAO/E;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAYxE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAG3G;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAElF;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhF;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAErF;AAED,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAGxF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAGjF"}

package/dist/errors.js

@@ -0,0 +1,84 @@
+/** OpenAI- and Anthropic-compatible JSON error responses. */
+export function sendError(res, status, type, message, param) {
+    const body = {
+        error: {
+            type,
+            message,
+            code: null,
+            param: param ?? null,
+        },
+    };
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+export function sendBadRequest(res, message, param) {
+    sendError(res, 400, 'invalid_request_error', message, param);
+}
+export function sendNotFound(res, message) {
+    sendError(res, 404, 'not_found_error', message);
+}
+export function sendMethodNotAllowed(res, allowed) {
+    res.writeHead(405, { Allow: allowed, 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+        error: { type: 'invalid_request_error', message: 'Method not allowed', code: null, param: null },
+    }));
+}
+export function sendInternalError(res, message) {
+    sendError(res, 500, 'server_error', message);
+}
+/**
+ * 503 with `type: 'storage_timeout'`. Emitted by the responses endpoint when
+ * an in-flight `store.store(...)` gating a `previous_response_id` continuation
+ * fails to settle within `CHAIN_WRITE_WAIT_TIMEOUT_MS` and the final `getChain`
+ * probe still misses. 503 (not 404) because the write may yet land, so the
+ * same id can be retried — a 404 would wrongly mark it permanently invalid.
+ */
+export function sendStorageTimeout(res, message) {
+    sendError(res, 503, 'storage_timeout', message);
+}
+/**
+ * 429 with `type: 'rate_limit_error'` and `code: 'queue_full'`. Emitted by
+ * `/v1/responses` when the per-model execution queue is already holding
+ * `maxQueueDepth` waiters behind the current dispatch. Always sets
+ * `Retry-After: 1` (string seconds) so clients back off briefly before
+ * retrying — short enough to encourage a retry, long enough to avoid
+ * busy-looping the server.
+ */
+export function sendRateLimit(res, message) {
+    res.writeHead(429, { 'Retry-After': '1', 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+        error: {
+            type: 'rate_limit_error',
+            message,
+            code: 'queue_full',
+            param: null,
+        },
+    }));
+}
+export function sendAnthropicError(res, status, type, message) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ type: 'error', error: { type, message } }));
+}
+export function sendAnthropicBadRequest(res, message) {
+    sendAnthropicError(res, 400, 'invalid_request_error', message);
+}
+export function sendAnthropicNotFound(res, message) {
+    sendAnthropicError(res, 404, 'not_found_error', message);
+}
+export function sendAnthropicInternalError(res, message) {
+    sendAnthropicError(res, 500, 'api_error', message);
+}
+export function sendAnthropicMethodNotAllowed(res, allowed) {
+    res.writeHead(405, { Allow: allowed, 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ type: 'error', error: { type: 'invalid_request_error', message: 'Method not allowed' } }));
+}
+/**
+ * 429 Anthropic-shape rate-limit response. Mirror of {@link sendRateLimit}
+ * for `/v1/messages`. Body uses the `{ type: 'error', error: { type, message } }`
+ * envelope the rest of the Anthropic error helpers use; `Retry-After: 1`
+ * is set verbatim so clients can wait one second before retrying.
+ */
+export function sendAnthropicRateLimit(res, message) {
+    res.writeHead(429, { 'Retry-After': '1', 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ type: 'error', error: { type: 'rate_limit_error', message } }));
+}

package/dist/handler.d.ts

@@ -0,0 +1,18 @@
+/** Composable `(req, res)` handler for node:http — usable standalone or mounted into an existing server. */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ResponseStore } from '@mlx-node/core';
+import type { ModelRegistry } from './registry.js';
+export interface HandlerOptions {
+    /** Enable CORS headers (default: true). */
+    cors?: boolean;
+    /** Response store for previous_response_id support. */
+    store?: ResponseStore | null;
+    /**
+     * Retention (seconds) stamped as `expires_at` when committing a response row.
+     * When omitted, the endpoint falls back to its own default (see `responses.ts`
+     * and `ServerConfig.responseRetentionSec`).
+     */
+    responseRetentionSec?: number;
+}
+export declare function createHandler(registry: ModelRegistry, options?: HandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAE5G,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uDAAuD;IACvD,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAgC9D"}

package/dist/handler.js

@@ -0,0 +1,35 @@
+/** Composable `(req, res)` handler for node:http — usable standalone or mounted into an existing server. */
+import { sendInternalError } from './errors.js';
+import { routeRequest } from './router.js';
+export function createHandler(registry, options) {
+    const cors = options?.cors ?? true;
+    const store = options?.store ?? null;
+    const responseRetentionSec = options?.responseRetentionSec;
+    return async (req, res) => {
+        if (cors) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, x-api-key, anthropic-version');
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+        }
+        // Returning the promise lets tests await the full lifecycle including
+        // post-`res.end()` bookkeeping (e.g. `SessionRegistry.adopt`). `http.createServer`
+        // ignores the return value, so this is transparent to production callers.
+        try {
+            await routeRequest(req, res, registry, store, responseRetentionSec);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Internal server error';
+            if (!res.headersSent) {
+                sendInternalError(res, message);
+            }
+            else {
+                res.end();
+            }
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @mlx-node/server -- OpenAI Responses + Anthropic Messages server for MLX models.
+ *
+ * Exposes loaded models via `POST /v1/responses`, `POST /v1/messages`, and
+ * `GET /v1/models`, in both streaming (SSE) and non-streaming modes.
+ */
+export { createServer } from './server.js';
+export type { ServerConfig, ServerInstance } from './server.js';
+/**
+ * Internal helpers re-exported for unit testing only. Not part of the
+ * supported public API — names may change without notice.
+ */
+export { parseEnvSeconds as __parseEnvSeconds, parseEnvPositiveInt as __parseEnvPositiveInt } from './server.js';
+export { createHandler } from './handler.js';
+export type { HandlerOptions } from './handler.js';
+export { ModelRegistry } from './registry.js';
+export type { ServableModel, ModelEntry, ModelRegistryOptions } from './registry.js';
+export { QueueFullError, SessionRegistry } from './session-registry.js';
+export type { SessionLookupResult, SessionRegistryOptions } from './session-registry.js';
+export type { ResponsesAPIRequest, ResponseObject, ResponseUsage, ResponseError, InputItem, InputMessage, InputFunctionCall, InputFunctionCallOutput, OutputItem, MessageOutputItem, ReasoningOutputItem, FunctionCallOutputItem, OutputTextPart, SummaryTextPart, ResponsesToolDefinition, ContentPart, InputTextPart, StreamEvent, } from './types.js';
+export type { AnthropicMessagesRequest, AnthropicMessagesResponse, AnthropicMessage, AnthropicContentBlock, AnthropicTextContentBlock, AnthropicImageContentBlock, AnthropicToolResultContentBlock, AnthropicToolUseContentBlock, AnthropicThinkingContentBlock, AnthropicToolDefinition, AnthropicToolChoice, AnthropicResponseContent, AnthropicResponseTextBlock, AnthropicResponseThinkingBlock, AnthropicResponseToolUseBlock, AnthropicUsage, AnthropicStreamEvent, AnthropicMessageStartEvent, AnthropicContentBlockStartEvent, AnthropicContentBlockDeltaEvent, AnthropicContentBlockStopEvent, AnthropicMessageDeltaEvent, AnthropicMessageStopEvent, AnthropicDelta, AnthropicTextDelta, AnthropicThinkingDelta, AnthropicInputJsonDelta, SystemBlock, } from './types-anthropic.js';
+export { writeSSEEvent, beginSSE, endSSE } from './streaming.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE;;;GAGG;AACH,OAAO,EAAE,eAAe,IAAI,iBAAiB,EAAE,mBAAmB,IAAI,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEjH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxE,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEzF,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,+BAA+B,EAC/B,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,EAC1B,8BAA8B,EAC9B,6BAA6B,EAC7B,cAAc,EACd,oBAAoB,EACpB,0BAA0B,EAC1B,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,EAC9B,0BAA0B,EAC1B,yBAAyB,EACzB,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @mlx-node/server -- OpenAI Responses + Anthropic Messages server for MLX models.
+ *
+ * Exposes loaded models via `POST /v1/responses`, `POST /v1/messages`, and
+ * `GET /v1/models`, in both streaming (SSE) and non-streaming modes.
+ */
+export { createServer } from './server.js';
+/**
+ * Internal helpers re-exported for unit testing only. Not part of the
+ * supported public API — names may change without notice.
+ */
+export { parseEnvSeconds as __parseEnvSeconds, parseEnvPositiveInt as __parseEnvPositiveInt } from './server.js';
+export { createHandler } from './handler.js';
+export { ModelRegistry } from './registry.js';
+export { QueueFullError, SessionRegistry } from './session-registry.js';
+export { writeSSEEvent, beginSSE, endSSE } from './streaming.js';

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

@@ -0,0 +1,9 @@
+/** Anthropic Messages API request → internal `ChatMessage[]` + `ChatConfig`. */
+import type { ChatConfig, ChatMessage } from '@mlx-node/core';
+import type { AnthropicMessagesRequest } from '../types-anthropic.js';
+export interface MappedAnthropicRequest {
+    messages: ChatMessage[];
+    config: ChatConfig;
+}
+export declare function mapAnthropicRequest(req: AnthropicMessagesRequest): MappedAnthropicRequest;
+//# sourceMappingURL=anthropic-request.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic-request.d.ts","sourceRoot":"","sources":["../../src/mappers/anthropic-request.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAE9E,OAAO,KAAK,EAGV,wBAAwB,EAIzB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC;CACpB;AAiDD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,wBAAwB,GAAG,sBAAsB,CAyMzF"}

package/dist/mappers/anthropic-request.js

@@ -0,0 +1,241 @@
+/** Anthropic Messages API request → internal `ChatMessage[]` + `ChatConfig`. */
+/**
+ * Resolve the text content of a `tool_result` block. The internal `ChatMessage`
+ * shape (NAPI-generated) has no `images` field on `role: 'tool'`, so nested
+ * images are rejected outright — any hoist-to-trailing-user workaround loses
+ * both declared order and per-tool association once downstream canonicalization
+ * reorders the tool rows. Callers must send images as a top-level image block
+ * in a separate user turn.
+ */
+function resolveToolResultContent(content) {
+    if (content == null)
+        return { text: '' };
+    if (typeof content === 'string')
+        return { text: content };
+    const parts = [];
+    for (const b of content) {
+        if (b.type === 'text') {
+            parts.push(b.text);
+        }
+        else if (b.type === 'image') {
+            throw new Error('Unsupported: nested image content in tool_result blocks is not representable in the internal ' +
+                'message model. Send the image as a top-level image block in a separate user turn, and reference ' +
+                'it from the tool_result via text.');
+        }
+        else {
+            throw new Error(`Unsupported tool_result content type: "${b.type}"`);
+        }
+    }
+    return { text: parts.join('') };
+}
+/** NAPI `ToolDefinition` requires `parameters.properties` to be a JSON string. */
+function mapTool(tool) {
+    const schema = tool.input_schema;
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: {
+                type: typeof schema['type'] === 'string' ? schema['type'] : 'object',
+                properties: JSON.stringify(schema['properties'] ?? {}),
+                required: Array.isArray(schema['required']) ? schema['required'] : undefined,
+            },
+        },
+    };
+}
+export function mapAnthropicRequest(req) {
+    const messages = [];
+    if (req.system != null) {
+        if (typeof req.system === 'string') {
+            messages.push({ role: 'system', content: req.system });
+        }
+        else {
+            const systemParts = [];
+            for (const b of req.system) {
+                if (b.type === 'text') {
+                    systemParts.push(b.text);
+                }
+                else {
+                    throw new Error(`Unsupported system block type: "${b.type}"`);
+                }
+            }
+            messages.push({ role: 'system', content: systemParts.join('') });
+        }
+    }
+    for (const msg of req.messages) {
+        const { role, content } = msg;
+        if (role === 'user') {
+            if (typeof content === 'string') {
+                messages.push({ role: 'user', content });
+            }
+            else {
+                // An Anthropic user turn may carry either pure text/image blocks,
+                // or a contiguous prefix of `tool_result` blocks optionally followed
+                // by trailing text/image blocks. Interleaving text/image BEFORE a
+                // tool_result is rejected — we cannot preserve author intent and
+                // fan-out ordering without silently reordering the caller's blocks.
+                // Caller-relative order within a tool_result prefix is preserved;
+                // `validateAndCanonicalizeHistoryToolOrder` reorders later if needed.
+                const toolResults = [];
+                const trailingText = [];
+                const trailingImages = [];
+                let seenNonToolResult = false;
+                let seenToolResult = false;
+                for (const block of content) {
+                    if (block.type === 'tool_result') {
+                        if (seenNonToolResult) {
+                            throw new Error('Unsupported: tool_result blocks must appear as a contiguous prefix of the user ' +
+                                'turn, before any text or image blocks. Interleaving a text/image block before a ' +
+                                'tool_result would require reordering the caller-supplied blocks and silently ' +
+                                'changing authorship.');
+                        }
+                        seenToolResult = true;
+                        const resolved = resolveToolResultContent(block.content);
+                        toolResults.push({
+                            toolCallId: block.tool_use_id,
+                            content: resolved.text,
+                            isError: block.is_error === true,
+                        });
+                    }
+                    else if (block.type === 'text') {
+                        seenNonToolResult = true;
+                        trailingText.push(block.text);
+                    }
+                    else if (block.type === 'image' && block.source.type === 'base64') {
+                        seenNonToolResult = true;
+                        trailingImages.push(Buffer.from(block.source.data, 'base64'));
+                    }
+                    else {
+                        throw new Error(`Unsupported content block type: "${block.type}"`);
+                    }
+                }
+                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.
+                    for (const tr of toolResults) {
+                        const encoded = tr.isError ? JSON.stringify({ is_error: true, content: tr.content }) : tr.content;
+                        messages.push({
+                            role: 'tool',
+                            content: encoded,
+                            toolCallId: tr.toolCallId,
+                        });
+                    }
+                    // Trailing suffix after a tool_result prefix: accept either
+                    // (a) text-only (concatenated) or (b) exactly one image block.
+                    // Mixing text+image or multiple images would silently reorder
+                    // content in the flat NAPI `ChatMessage` shape.
+                    const hasTrailingText = trailingText.length > 0;
+                    const hasTrailingImages = trailingImages.length > 0;
+                    if (hasTrailingText && hasTrailingImages) {
+                        throw new Error('Unsupported: mixing trailing text and image blocks after a tool_result prefix is not ' +
+                            'representable in the internal message model. The flat ChatMessage shape cannot preserve ' +
+                            'the caller-declared relative order of interleaved text and images, so any mapping would ' +
+                            'silently reorder your content. Send any commentary as part of the tool_result text, and ' +
+                            'deliver additional images in a separate follow-up user turn.');
+                    }
+                    if (hasTrailingImages && trailingImages.length > 1) {
+                        throw new Error('Unsupported: multiple trailing image blocks after a tool_result prefix are not ' +
+                            'representable in the internal message model without silently reordering the images ' +
+                            'relative to any surrounding text. Send at most one trailing image block, and deliver ' +
+                            'additional images in a separate follow-up user turn.');
+                    }
+                    if (hasTrailingText || hasTrailingImages) {
+                        const trailingMsg = { role: 'user', content: trailingText.join('') };
+                        if (hasTrailingImages) {
+                            trailingMsg.images = trailingImages;
+                        }
+                        messages.push(trailingMsg);
+                    }
+                }
+                else {
+                    // Pure text/image user turn — always emit exactly one `user` message, even if empty.
+                    const userMsg = { role: 'user', content: trailingText.join('') };
+                    if (trailingImages.length > 0) {
+                        userMsg.images = trailingImages;
+                    }
+                    messages.push(userMsg);
+                }
+            }
+        }
+        else if (role === 'assistant') {
+            if (typeof content === 'string') {
+                messages.push({ role: 'assistant', content });
+            }
+            else {
+                // Collapse into a single assistant message. The internal shape does not
+                // support text-after-tool_use ordering, so interleaved shapes are rejected.
+                let text = '';
+                let reasoningContent;
+                const toolCalls = [];
+                let seenToolUse = false;
+                for (const block of content) {
+                    if (block.type === 'text') {
+                        if (seenToolUse) {
+                            throw new Error('Text blocks after tool_use blocks are not supported in assistant messages');
+                        }
+                        text += block.text;
+                    }
+                    else if (block.type === 'thinking') {
+                        reasoningContent = (reasoningContent ?? '') + block.thinking;
+                    }
+                    else if (block.type === 'tool_use') {
+                        seenToolUse = true;
+                        toolCalls.push({
+                            id: block.id,
+                            name: block.name,
+                            arguments: JSON.stringify(block.input),
+                        });
+                    }
+                    else {
+                        throw new Error(`Unsupported assistant content block type: "${block.type}"`);
+                    }
+                }
+                const assistantMsg = { role: 'assistant', content: text };
+                if (reasoningContent != null) {
+                    assistantMsg.reasoningContent = reasoningContent;
+                }
+                if (toolCalls.length > 0) {
+                    assistantMsg.toolCalls = toolCalls;
+                }
+                messages.push(assistantMsg);
+            }
+        }
+        else {
+            throw new Error(`Unsupported message role: "${role}"`);
+        }
+    }
+    const config = {
+        reportPerformance: true,
+    };
+    if (req.max_tokens != null) {
+        config.maxNewTokens = req.max_tokens;
+    }
+    if (req.temperature != null) {
+        config.temperature = req.temperature;
+    }
+    if (req.top_p != null) {
+        config.topP = req.top_p;
+    }
+    if (req.top_k != null) {
+        config.topK = req.top_k;
+    }
+    if (req.tools && req.tools.length > 0) {
+        const toolChoice = req.tool_choice;
+        if (toolChoice?.type === 'tool' && toolChoice.name) {
+            const matched = req.tools.filter((t) => t.name === toolChoice.name);
+            if (matched.length > 0) {
+                config.tools = matched.map(mapTool);
+            }
+        }
+        else {
+            config.tools = req.tools.map(mapTool);
+        }
+    }
+    return { messages, config };
+}

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

@@ -0,0 +1,14 @@
+/** ChatResult / ChatStreamEvent → Anthropic Messages API output. */
+import type { ChatResult } from '@mlx-node/core';
+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;
+/** 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 buildMessageStop(): AnthropicMessageStopEvent;
+//# sourceMappingURL=anthropic-response.d.ts.map

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

@@ -0,0 +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"}

package/dist/mappers/anthropic-response.js

@@ -0,0 +1,112 @@
+/** ChatResult / ChatStreamEvent → Anthropic Messages API output. */
+import { genId } from './response.js';
+function parseArguments(args) {
+    if (typeof args === 'string') {
+        return JSON.parse(args);
+    }
+    return args;
+}
+export function mapStopReason(finishReason, hasToolCalls) {
+    if (finishReason === 'length') {
+        return 'max_tokens';
+    }
+    if (hasToolCalls) {
+        return 'tool_use';
+    }
+    return 'end_turn';
+}
+export function buildAnthropicContent(result) {
+    const content = [];
+    if (result.thinking) {
+        content.push({ type: 'thinking', thinking: result.thinking });
+    }
+    const okToolCalls = result.toolCalls.filter((t) => t.status === 'ok');
+    // 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 });
+    }
+    for (const tc of okToolCalls) {
+        content.push({
+            type: 'tool_use',
+            id: 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');
+    const hasToolCalls = okToolCalls.length > 0;
+    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,
+        },
+    };
+}
+// Streaming helpers
+/** Embedded message has empty content and zero output_tokens at start. */
+export function buildMessageStartEvent(req, messageId, inputTokens) {
+    return {
+        type: 'message_start',
+        message: {
+            id: messageId,
+            type: 'message',
+            role: 'assistant',
+            model: req.model,
+            content: [],
+            stop_reason: null,
+            stop_sequence: null,
+            usage: {
+                input_tokens: inputTokens,
+                output_tokens: 0,
+            },
+        },
+    };
+}
+export function buildContentBlockStart(index, block) {
+    return {
+        type: 'content_block_start',
+        index,
+        content_block: block,
+    };
+}
+export function buildContentBlockDelta(index, delta) {
+    return {
+        type: 'content_block_delta',
+        index,
+        delta,
+    };
+}
+export function buildContentBlockStop(index) {
+    return {
+        type: 'content_block_stop',
+        index,
+    };
+}
+export function buildMessageDelta(stopReason, outputTokens, inputTokens) {
+    return {
+        type: 'message_delta',
+        delta: {
+            stop_reason: stopReason,
+            stop_sequence: null,
+        },
+        usage: {
+            ...(inputTokens != null ? { input_tokens: inputTokens } : {}),
+            output_tokens: outputTokens,
+        },
+    };
+}
+export function buildMessageStop() {
+    return {
+        type: 'message_stop',
+    };
+}

package/dist/mappers/request.d.ts

@@ -0,0 +1,18 @@
+/** OpenAI Responses API request → internal `ChatMessage[]` + `ChatConfig`. */
+import type { ChatConfig, ChatMessage } from '@mlx-node/core';
+import type { ResponsesAPIRequest } from '../types.js';
+export interface MappedRequest {
+    messages: ChatMessage[];
+    config: ChatConfig;
+}
+export declare function mapRequest(req: ResponsesAPIRequest, priorMessages?: ChatMessage[]): MappedRequest;
+/**
+ * Reconstruct `ChatMessage[]` from a stored response chain. Each record
+ * stores `inputJson` (messages sent) and `outputJson` (output items); we
+ * interleave them.
+ */
+export declare function reconstructMessagesFromChain(chain: {
+    inputJson: string;
+    outputJson: string;
+}[]): ChatMessage[];
+//# sourceMappingURL=request.d.ts.map

package/dist/mappers/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/mappers/request.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAkB,MAAM,gBAAgB,CAAC;AAE9E,OAAO,KAAK,EAAe,mBAAmB,EAA2B,MAAM,aAAa,CAAC;AAqC7F,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,mBAAmB,EAAE,aAAa,CAAC,EAAE,WAAW,EAAE,GAAG,aAAa,CA4GjG;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,WAAW,EAAE,CAoE9G"}