@mlx-node/server 0.0.7 → 0.0.9

package/dist/host/logger.js

@@ -0,0 +1,376 @@
+/**
+ * Request/response logger for `mlx launch claude --verbose`.
+ *
+ * Each HTTP turn is written as one line of newline-delimited JSON to
+ * `requests.ndjson`. Streaming responses capture every chunk written
+ * to the socket so SSE events land verbatim — enough to audit cache
+ * hits (`x-session-cache` header), tool-call round-trips, and the
+ * model's token-level output post-hoc.
+ *
+ * `session.log` is the human-readable companion: one line per request
+ * arrival and completion, for `tail -f` during a live session.
+ */
+import { Buffer } from 'node:buffer';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Headers whose value is a credential and must never reach the log file.
+ *
+ * The log lands in `~/.mlx-node/logs/<timestamp>/requests.ndjson`, which users
+ * paste into bug reports, and every client of a protected host presents a live
+ * secret on every turn: the per-launch token `mlx launch claude` generates, or
+ * `MLX_SERVER_AUTH_TOKEN` — or, before the launcher stopped handing it down,
+ * the user's own `sk-ant-…` key.
+ */
+const REDACTED_REQUEST_HEADERS = ['authorization', 'x-api-key', 'proxy-authorization', 'cookie'];
+/**
+ * Copy `headers`, replacing credential values with a marker.
+ *
+ * The KEY is kept: "a token was presented and it was wrong" and "no token was
+ * presented at all" are different bugs, and a log that drops the header cannot
+ * tell them apart. Node lower-cases incoming header names, so the comparison
+ * needs no folding.
+ */
+function redactRequestHeaders(headers) {
+    let copy = null;
+    for (const name of REDACTED_REQUEST_HEADERS) {
+        if (headers[name] === undefined)
+            continue;
+        copy ??= { ...headers };
+        copy[name] = '[redacted]';
+    }
+    return copy ?? headers;
+}
+function parseJsonObject(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed != null && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function asUsage(value) {
+    return value != null && typeof value === 'object' ? value : undefined;
+}
+function fmtMs(ms) {
+    return typeof ms === 'number' && Number.isFinite(ms) ? `${Math.round(ms)}ms` : undefined;
+}
+function fmtRate(rate) {
+    return typeof rate === 'number' && Number.isFinite(rate) ? `${rate.toFixed(2)}/s` : undefined;
+}
+function addMs(left, right) {
+    return typeof left === 'number' && Number.isFinite(left) && typeof right === 'number' && Number.isFinite(right)
+        ? left + right
+        : undefined;
+}
+function extractUsageSummary(resBody) {
+    let model;
+    let usage;
+    let stop;
+    const trimmed = resBody.trimStart();
+    if (trimmed.startsWith('{')) {
+        const json = parseJsonObject(trimmed);
+        if (json) {
+            const response = json.response != null && typeof json.response === 'object' ? json.response : json;
+            model = typeof response.model === 'string' ? response.model : undefined;
+            usage = asUsage(response.usage);
+            stop = typeof response.stop_reason === 'string' ? response.stop_reason : undefined;
+            return { model, usage, stop };
+        }
+    }
+    for (const line of resBody.split('\n')) {
+        if (!line.startsWith('data: '))
+            continue;
+        const payload = line.slice(6);
+        if (payload === '[DONE]')
+            continue;
+        const event = parseJsonObject(payload);
+        if (!event)
+            continue;
+        if (event.type === 'message_start' && event.message != null && typeof event.message === 'object') {
+            const message = event.message;
+            if (typeof message.model === 'string')
+                model = message.model;
+        }
+        if (event.type === 'message_delta') {
+            usage = asUsage(event.usage) ?? usage;
+            const delta = event.delta != null && typeof event.delta === 'object' ? event.delta : null;
+            if (typeof delta?.stop_reason === 'string')
+                stop = delta.stop_reason;
+        }
+        if ((event.type === 'response.completed' || event.type === 'response.failed') &&
+            event.response != null &&
+            typeof event.response === 'object') {
+            const response = event.response;
+            if (typeof response.model === 'string')
+                model = response.model;
+            usage = asUsage(response.usage) ?? usage;
+            if (typeof response.status === 'string')
+                stop = response.status;
+        }
+    }
+    return { model, usage, stop };
+}
+function buildTimingSummary(reqBody, resBody) {
+    const request = parseJsonObject(reqBody);
+    const response = extractUsageSummary(resBody);
+    const model = typeof request?.model === 'string' ? request.model : response.model;
+    const usage = response.usage;
+    if (!usage && !model)
+        return '';
+    const parts = [];
+    if (model)
+        parts.push(`model=${model}`);
+    if (usage) {
+        const cachedTokens = usage.cache_read_input_tokens ?? usage.cached_prefix_tokens ?? usage.input_tokens_details?.cached_tokens;
+        const tokenParts = [
+            typeof usage.input_tokens === 'number' ? `in=${usage.input_tokens}` : undefined,
+            typeof cachedTokens === 'number' ? `cache=${cachedTokens}` : undefined,
+            typeof usage.prefill_input_tokens === 'number' ? `prefill=${usage.prefill_input_tokens}` : undefined,
+            typeof usage.output_tokens === 'number' ? `out=${usage.output_tokens}` : undefined,
+        ].filter((part) => part != null);
+        if (tokenParts.length > 0)
+            parts.push(`tok(${tokenParts.join(' ')})`);
+        const totalFirstTokenMs = usage.server_total_time_to_first_token_ms ?? addMs(usage.server_pre_inference_ms, usage.time_to_first_token_ms);
+        const timingParts = [
+            fmtMs(totalFirstTokenMs) ? `ttfb=${fmtMs(totalFirstTokenMs)}` : undefined,
+            fmtMs(usage.time_to_first_token_ms) ? `ttft=${fmtMs(usage.time_to_first_token_ms)}` : undefined,
+            fmtRate(usage.prefill_tokens_per_second) ? `prefill=${fmtRate(usage.prefill_tokens_per_second)}` : undefined,
+            fmtRate(usage.decode_tokens_per_second) ? `decode=${fmtRate(usage.decode_tokens_per_second)}` : undefined,
+            fmtMs(usage.server_inference_elapsed_ms) ? `infer=${fmtMs(usage.server_inference_elapsed_ms)}` : undefined,
+        ].filter((part) => part != null);
+        if (timingParts.length > 0)
+            parts.push(`perf(${timingParts.join(' ')})`);
+        const serverParts = [
+            fmtMs(usage.server_model_resolve_ms) ? `resolve=${fmtMs(usage.server_model_resolve_ms)}` : undefined,
+            fmtMs(usage.server_load_wait_ms) ? `load_wait=${fmtMs(usage.server_load_wait_ms)}` : undefined,
+            typeof usage.server_load_owner === 'boolean' ? `load_owner=${usage.server_load_owner}` : undefined,
+            fmtMs(usage.server_queue_ms) ? `queue=${fmtMs(usage.server_queue_ms)}` : undefined,
+            fmtMs(usage.server_pre_inference_ms) ? `pre=${fmtMs(usage.server_pre_inference_ms)}` : undefined,
+        ].filter((part) => part != null);
+        if (serverParts.length > 0)
+            parts.push(`server(${serverParts.join(' ')})`);
+        const tuningParts = [
+            typeof usage.server_paged_prefill_chunk_size === 'number'
+                ? `prefill_chunk=${usage.server_paged_prefill_chunk_size}`
+                : undefined,
+            typeof usage.server_paged_prefill_eval_interval === 'number'
+                ? `prefill_eval=${usage.server_paged_prefill_eval_interval}`
+                : undefined,
+            typeof usage.server_paged_decode_cache_clear_interval === 'number'
+                ? `decode_clear=${usage.server_paged_decode_cache_clear_interval}`
+                : undefined,
+        ].filter((part) => part != null);
+        if (tuningParts.length > 0)
+            parts.push(`tune(${tuningParts.join(' ')})`);
+    }
+    if (response.stop)
+        parts.push(`stop=${response.stop}`);
+    return parts.length > 0 ? ` ${parts.join(' ')}` : '';
+}
+function buildRequestBodySummary(reqBody) {
+    const request = parseJsonObject(reqBody);
+    if (!request)
+        return '';
+    const parts = [];
+    if (typeof request.model === 'string')
+        parts.push(`model=${request.model}`);
+    if (typeof request.max_tokens === 'number')
+        parts.push(`max_tokens=${request.max_tokens}`);
+    if (typeof request.stream === 'boolean')
+        parts.push(`stream=${request.stream}`);
+    if (Array.isArray(request.messages))
+        parts.push(`messages=${request.messages.length}`);
+    if (Array.isArray(request.tools))
+        parts.push(`tools=${request.tools.length}`);
+    if (typeof request.system === 'string') {
+        parts.push(`system=string`);
+    }
+    else if (Array.isArray(request.system)) {
+        parts.push(`system=blocks:${request.system.length}`);
+    }
+    return parts.length > 0 ? ` ${parts.join(' ')}` : '';
+}
+/**
+ * Attach request/response capture to `server`. Call `close()` AFTER
+ * `server.close()` resolves: the completion listeners below fire when a
+ * response finishes, so ending the streams first drops the tail of every
+ * request still in flight.
+ */
+export function attachLogger(server, logDir) {
+    mkdirSync(logDir, { recursive: true });
+    const reqLog = createWriteStream(join(logDir, 'requests.ndjson'), { flags: 'a' });
+    const pretty = createWriteStream(join(logDir, 'session.log'), { flags: 'a' });
+    // A write that lands after `end()` reports `ERR_STREAM_WRITE_AFTER_END`
+    // asynchronously, as an `error` event — the `try`/`catch` around each
+    // `write()` below cannot see it. With no listener that event is fatal, so
+    // a request completing during shutdown would take the process down instead
+    // of finishing the graceful close. Ordering close correctly is what keeps
+    // the record intact; these listeners are what keep a lost log line from
+    // being lethal when the ordering cannot help — the forced-close path emits
+    // `res.on('close')` a tick after `server.close()` has already resolved.
+    const discardStreamError = () => { };
+    reqLog.on('error', discardStreamError);
+    pretty.on('error', discardStreamError);
+    const writePretty = (line) => {
+        try {
+            pretty.write(`${new Date().toISOString()} ${line}\n`);
+        }
+        catch {
+            /* never let logging failure break serving */
+        }
+    };
+    writePretty(`[logging] writing to ${logDir}`);
+    writePretty(`[logging]   requests.ndjson  — one JSON line per HTTP turn (full body in/out, SSE chunks)`);
+    writePretty(`[logging]   session.log      — human-readable chronological trace`);
+    if (process.env.MLX_INFERENCE_TRACE_FILE) {
+        writePretty(`[logging]   inference trace — ${process.env.MLX_INFERENCE_TRACE_FILE}`);
+    }
+    // Node's http.Server multicasts request events — our listener fires
+    // alongside the createServer handler. Dedupe in case the same
+    // request ever re-enters (paranoia; it shouldn't).
+    const seen = new WeakSet();
+    // Prepend so our listener runs BEFORE the main handler. This is
+    // what lets the write/end wrappers land before any synchronous
+    // response path writes — a sync handler (easy to hit in tests)
+    // would otherwise miss the wrap entirely.
+    server.prependListener('request', (req, res) => {
+        if (seen.has(req))
+            return;
+        seen.add(req);
+        const start = Date.now();
+        const rid = `${start.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        writePretty(`[req ${rid}] ${req.method ?? '?'} ${req.url ?? '?'}`);
+        let reqBody = '';
+        req.on('data', (chunk) => {
+            reqBody += chunk.toString('utf8');
+        });
+        // Wrap res.write / res.end to capture streamed chunks (SSE + regular).
+        // Preserve original method semantics — we only observe, never transform.
+        const chunks = [];
+        const origWrite = res.write.bind(res);
+        const origEnd = res.end.bind(res);
+        // biome-ignore lint/suspicious/noExplicitAny: capture wrapper
+        res.write = (chunk, ...rest) => {
+            if (chunk != null) {
+                try {
+                    chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            return origWrite(chunk, ...rest);
+        };
+        // biome-ignore lint/suspicious/noExplicitAny: capture wrapper
+        res.end = (chunk, ...rest) => {
+            if (chunk != null) {
+                try {
+                    chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            return origEnd(chunk, ...rest);
+        };
+        // Write the NDJSON entry when BOTH the request body has been fully
+        // consumed (`req.on('end')`) AND the response has fully flushed
+        // (`res.on('finish')`). Necessary because a synchronous handler can
+        // call `res.end()` before our `req.on('data')` listener has seen
+        // any chunks — the stream was set flowing on `.on('data', ...)`
+        // but the chunks deliver in a later tick.
+        let reqDone = false;
+        let resDone = false;
+        let emitted = false;
+        let requestBodyLogged = false;
+        const logRequestBody = (phase) => {
+            if (requestBodyLogged)
+                return;
+            requestBodyLogged = true;
+            writePretty(`[req ${rid}] request_body_${phase} ${Buffer.byteLength(reqBody, 'utf8')}B${buildRequestBodySummary(reqBody)}`);
+        };
+        const tryEmit = () => {
+            if (emitted || !reqDone || !resDone)
+                return;
+            emitted = true;
+            const resBody = chunks.join('');
+            const entry = {
+                rid,
+                t: new Date(start).toISOString(),
+                method: req.method,
+                path: req.url,
+                reqHeaders: redactRequestHeaders(req.headers),
+                reqBody: reqBody || null,
+                status: res.statusCode,
+                resHeaders: res.getHeaders(),
+                resBody,
+                elapsedMs: Date.now() - start,
+            };
+            try {
+                reqLog.write(`${JSON.stringify(entry)}\n`);
+            }
+            catch {
+                /* never block the response */
+            }
+            const timingSummary = buildTimingSummary(reqBody, resBody);
+            writePretty(`[req ${rid}] ${res.statusCode} ${req.method ?? '?'} ${req.url ?? '?'} ${entry.elapsedMs}ms ${resBody.length}B${timingSummary}`);
+        };
+        req.on('end', () => {
+            reqDone = true;
+            logRequestBody('end');
+            tryEmit();
+        });
+        req.on('close', () => {
+            // Client may drop the body mid-flight; emit whatever we have.
+            reqDone = true;
+            logRequestBody('close');
+            tryEmit();
+        });
+        res.on('finish', () => {
+            resDone = true;
+            tryEmit();
+        });
+        res.on('close', () => {
+            if (!res.writableEnded) {
+                writePretty(`[req ${rid}] aborted (client close) after ${Date.now() - start}ms`);
+            }
+            // Abort path: treat as done so we still emit what we captured.
+            resDone = true;
+            tryEmit();
+        });
+    });
+    let closed = false;
+    return {
+        logDir,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await Promise.all([
+                new Promise((resolve) => reqLog.end(resolve)),
+                new Promise((resolve) => pretty.end(resolve)),
+            ]);
+        },
+    };
+}
+/**
+ * Resolve the log directory for a verbose launch.
+ *
+ * Order: explicit `--log-dir` > `MLX_LOG_DIR` env > a fresh timestamped
+ * directory under `<mlxNodeHome>/logs/`. The timestamped default gives
+ * each launch its own dir so concurrent / sequential runs don't
+ * interleave into one file.
+ */
+export function resolveLogDir(explicit, mlxNodeHome) {
+    if (explicit)
+        return explicit;
+    const envDir = process.env.MLX_LOG_DIR;
+    if (envDir)
+        return envDir;
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return join(mlxNodeHome, 'logs', stamp);
+}

package/dist/host/net.d.ts

@@ -0,0 +1,65 @@
+/** Bind-address and port helpers shared by every inference host front-end. */
+/**
+ * Wrap a bare IPv6 literal in `[...]` so it is safe inside a URL authority.
+ *
+ * Any host carrying a `:` that is not already bracketed is an IPv6 literal
+ * (`::1`, `2001:db8::1`, or a scoped `fe80::1%en0`); an unbracketed one makes
+ * the trailing `:<port>` ambiguous and `new URL()` reject it. IPv4/hostnames
+ * (no `:`) and already-bracketed literals pass through unchanged. A scoped
+ * literal is bracketed too: `new URL` still rejects the `%`, but the printed
+ * string stays well-formed rather than crashing the caller.
+ *
+ * `@mlx-node/dashboard` carries its own copy for its own bind logic; this one
+ * is the inference host's, so the two can diverge without coupling.
+ */
+export declare function bracketHost(host: string): string;
+/**
+ * Convert the one bracketed bind form the host security policy accepts into
+ * the bare literal Node's `server.listen()` requires.
+ *
+ * Brackets belong to URL authorities, not socket bind addresses: passing
+ * `[::1]` to Node performs a DNS lookup and fails with `ENOTFOUND`. This is
+ * deliberately exact rather than a general bracket stripper. In particular,
+ * `[::]` and bracketed routable IPv6 text must not be turned into working
+ * wildcard/network binds by a helper intended only to repair loopback.
+ */
+export declare function normalizeLoopbackBindHost(host: string): string;
+/**
+ * Build the URL a client should connect to for a `(host, port)` bind.
+ *
+ * A wildcard bind has no connectable literal host, so advertise the matching
+ * loopback instead: `::` binds IPv6 → `[::1]`, `0.0.0.0`/`''` bind IPv4 →
+ * `127.0.0.1`. A concrete host is advertised as-is with any IPv6 literal
+ * bracketed.
+ */
+export declare function hostUrl(host: string, port: number): string;
+/**
+ * Does this BIND address keep the socket unreachable from another machine?
+ *
+ * Distinct from the desktop supervisor's `isLoopbackHttpUrl`, which classifies
+ * a URL a client would connect TO. This one classifies the string handed to
+ * `server.listen(port, host)`, where the failure modes are different: the
+ * wildcards (`0.0.0.0`, `::`, `''`) are not routable addresses at all yet bind
+ * every interface, and `hostUrl` deliberately ADVERTISES them as loopback — so
+ * a check written against the advertised URL would call a wildcard bind safe.
+ *
+ * Loopback: the whole `127.0.0.0/8` block, `::1` (bracketed or not), and
+ * `localhost`. Anything else — a LAN address, a wildcard, a hostname that
+ * resolves off-box — is treated as reachable, because a predicate that has to
+ * resolve DNS to answer would either block startup or guess.
+ */
+export declare function isLoopbackBindHost(host: string): boolean;
+/**
+ * Ask the kernel for a free port by binding to port 0, reading the assigned
+ * port, and closing immediately.
+ *
+ * Racy in theory (another process could grab the port between the close and
+ * the real listen), but acceptable for a developer-local host. Callers that
+ * cannot tolerate the race should pass `port: 0` straight through to
+ * `createServer` and read the bound port back off the socket instead — the
+ * inference host does exactly that when no port is requested at all; this
+ * helper exists for the case where the port must be known BEFORE the server
+ * starts (e.g. baking `ANTHROPIC_BASE_URL` into a child's env).
+ */
+export declare function pickFreePort(): Promise<number>;
+//# sourceMappingURL=net.d.ts.map

package/dist/host/net.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../../src/host/net.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAI9E;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAepD"}

package/dist/host/net.js

@@ -0,0 +1,97 @@
+/** Bind-address and port helpers shared by every inference host front-end. */
+import { createServer as netCreateServer } from 'node:net';
+/**
+ * Wrap a bare IPv6 literal in `[...]` so it is safe inside a URL authority.
+ *
+ * Any host carrying a `:` that is not already bracketed is an IPv6 literal
+ * (`::1`, `2001:db8::1`, or a scoped `fe80::1%en0`); an unbracketed one makes
+ * the trailing `:<port>` ambiguous and `new URL()` reject it. IPv4/hostnames
+ * (no `:`) and already-bracketed literals pass through unchanged. A scoped
+ * literal is bracketed too: `new URL` still rejects the `%`, but the printed
+ * string stays well-formed rather than crashing the caller.
+ *
+ * `@mlx-node/dashboard` carries its own copy for its own bind logic; this one
+ * is the inference host's, so the two can diverge without coupling.
+ */
+export function bracketHost(host) {
+    return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+/**
+ * Convert the one bracketed bind form the host security policy accepts into
+ * the bare literal Node's `server.listen()` requires.
+ *
+ * Brackets belong to URL authorities, not socket bind addresses: passing
+ * `[::1]` to Node performs a DNS lookup and fails with `ENOTFOUND`. This is
+ * deliberately exact rather than a general bracket stripper. In particular,
+ * `[::]` and bracketed routable IPv6 text must not be turned into working
+ * wildcard/network binds by a helper intended only to repair loopback.
+ */
+export function normalizeLoopbackBindHost(host) {
+    return host === '[::1]' ? '::1' : host;
+}
+/**
+ * Build the URL a client should connect to for a `(host, port)` bind.
+ *
+ * A wildcard bind has no connectable literal host, so advertise the matching
+ * loopback instead: `::` binds IPv6 → `[::1]`, `0.0.0.0`/`''` bind IPv4 →
+ * `127.0.0.1`. A concrete host is advertised as-is with any IPv6 literal
+ * bracketed.
+ */
+export function hostUrl(host, port) {
+    const wildcard = host === '0.0.0.0' || host === '::' || host === '';
+    const displayHost = wildcard ? (host === '::' ? '[::1]' : '127.0.0.1') : bracketHost(host);
+    return `http://${displayHost}:${port}`;
+}
+/**
+ * Does this BIND address keep the socket unreachable from another machine?
+ *
+ * Distinct from the desktop supervisor's `isLoopbackHttpUrl`, which classifies
+ * a URL a client would connect TO. This one classifies the string handed to
+ * `server.listen(port, host)`, where the failure modes are different: the
+ * wildcards (`0.0.0.0`, `::`, `''`) are not routable addresses at all yet bind
+ * every interface, and `hostUrl` deliberately ADVERTISES them as loopback — so
+ * a check written against the advertised URL would call a wildcard bind safe.
+ *
+ * Loopback: the whole `127.0.0.0/8` block, `::1` (bracketed or not), and
+ * `localhost`. Anything else — a LAN address, a wildcard, a hostname that
+ * resolves off-box — is treated as reachable, because a predicate that has to
+ * resolve DNS to answer would either block startup or guess.
+ */
+export function isLoopbackBindHost(host) {
+    if (host === 'localhost' || host === '::1' || host === '[::1]')
+        return true;
+    // `::ffff:127.0.0.1` is the IPv4-mapped form Node accepts on a dual-stack
+    // socket; it binds the same loopback interface.
+    if (/^::ffff:127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/i.test(host))
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+/**
+ * Ask the kernel for a free port by binding to port 0, reading the assigned
+ * port, and closing immediately.
+ *
+ * Racy in theory (another process could grab the port between the close and
+ * the real listen), but acceptable for a developer-local host. Callers that
+ * cannot tolerate the race should pass `port: 0` straight through to
+ * `createServer` and read the bound port back off the socket instead — the
+ * inference host does exactly that when no port is requested at all; this
+ * helper exists for the case where the port must be known BEFORE the server
+ * starts (e.g. baking `ANTHROPIC_BASE_URL` into a child's env).
+ */
+export async function pickFreePort() {
+    return await new Promise((resolve, reject) => {
+        const probe = netCreateServer();
+        probe.unref();
+        probe.once('error', reject);
+        probe.listen(0, '127.0.0.1', () => {
+            const addr = probe.address();
+            if (addr && typeof addr === 'object') {
+                const port = addr.port;
+                probe.close(() => resolve(port));
+            }
+            else {
+                probe.close(() => reject(new Error('could not determine free port')));
+            }
+        });
+    });
+}

package/dist/host/paths.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared `$HOME/.mlx-node` layout helpers. Drives `mlx download model`
+ * (output destination), every inference host (`mlx serve`, `mlx launch
+ * claude`, the desktop sidecar) as the model discovery root, and the
+ * default log root.
+ *
+ * Published as its own `@mlx-node/server/host/paths` subpath, and it must
+ * stay a dependency-free leaf. `@mlx-node/server/host` value-imports
+ * `@mlx-node/lm`, which dlopens the native addon at module scope; commands
+ * that only need to know where models live — `mlx download model` above all,
+ * the one you run BEFORE you have anything to run — must not pay for that,
+ * and on a headless box the dlopen is a liability rather than a cost.
+ */
+/** Absolute path to `$HOME/.mlx-node`. Used for `config.json` lookup and as the default parent of `models/`. */
+export declare function resolveMlxNodeHome(): string;
+/**
+ * Resolve the directory where downloaded models live.
+ *
+ * Resolution order:
+ *   1. `explicit` arg (non-empty)
+ *   2. `MLX_MODELS_DIR` env var
+ *   3. `modelsDir` field in `$HOME/.mlx-node/config.json`
+ *   4. `$HOME/.mlx-node/models`
+ *
+ * Creates the chosen directory (recursive) before returning.
+ */
+export declare function resolveModelsDir(explicit?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/host/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/host/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,gHAAgH;AAChH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAiB1D"}

package/dist/host/paths.js

@@ -0,0 +1,71 @@
+/**
+ * Shared `$HOME/.mlx-node` layout helpers. Drives `mlx download model`
+ * (output destination), every inference host (`mlx serve`, `mlx launch
+ * claude`, the desktop sidecar) as the model discovery root, and the
+ * default log root.
+ *
+ * Published as its own `@mlx-node/server/host/paths` subpath, and it must
+ * stay a dependency-free leaf. `@mlx-node/server/host` value-imports
+ * `@mlx-node/lm`, which dlopens the native addon at module scope; commands
+ * that only need to know where models live — `mlx download model` above all,
+ * the one you run BEFORE you have anything to run — must not pay for that,
+ * and on a headless box the dlopen is a liability rather than a cost.
+ */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/** Absolute path to `$HOME/.mlx-node`. Used for `config.json` lookup and as the default parent of `models/`. */
+export function resolveMlxNodeHome() {
+    return join(homedir(), '.mlx-node');
+}
+/**
+ * Resolve the directory where downloaded models live.
+ *
+ * Resolution order:
+ *   1. `explicit` arg (non-empty)
+ *   2. `MLX_MODELS_DIR` env var
+ *   3. `modelsDir` field in `$HOME/.mlx-node/config.json`
+ *   4. `$HOME/.mlx-node/models`
+ *
+ * Creates the chosen directory (recursive) before returning.
+ */
+export function resolveModelsDir(explicit) {
+    if (explicit && explicit.length > 0) {
+        return ensureDir(resolve(explicit));
+    }
+    const envDir = process.env.MLX_MODELS_DIR;
+    if (envDir && envDir.length > 0) {
+        return ensureDir(resolve(envDir));
+    }
+    const configPath = join(resolveMlxNodeHome(), 'config.json');
+    const fromConfig = readModelsDirFromConfig(configPath);
+    if (fromConfig) {
+        return ensureDir(resolve(fromConfig));
+    }
+    return ensureDir(join(resolveMlxNodeHome(), 'models'));
+}
+function readModelsDirFromConfig(configPath) {
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf-8');
+    }
+    catch {
+        // Missing / unreadable file: fall through to default.
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.modelsDir === 'string' && parsed.modelsDir.length > 0) {
+            return parsed.modelsDir;
+        }
+        return undefined;
+    }
+    catch {
+        console.warn(`[mlx] warning: malformed JSON in ${configPath}; falling back to default models dir`);
+        return undefined;
+    }
+}
+function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+    return path;
+}

package/dist/host/swap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Single-resident lazy-load policy for an inference host.
+ *
+ * The host discovers every local model up-front but loads at most one into
+ * the `ModelRegistry` at a time. Switching models (e.g. via Claude Code's
+ * `/model` picker, or the desktop app's model menu) unregisters the previous
+ * instance, letting GC + native destructors reclaim memory, before loading
+ * the new one.
+ */
+import type { LoadableModel } from '@mlx-node/lm';
+import type { PublicModelEntry } from '../handler.js';
+import type { ModelRegistry } from '../registry.js';
+import type { DiscoveredModel } from './discover.js';
+export interface SwapController {
+    resolveModel: (name: string) => Promise<void>;
+    listModels: () => PublicModelEntry[];
+}
+/**
+ * Build the `resolveModel` + `listModels` callbacks for the handler.
+ *
+ * `loadModelFn` is injected so tests can stub it without touching native code.
+ * The controller serializes every `resolveModel` invocation on a single
+ * promise chain so two concurrent requests for different-but-currently-
+ * unloaded models cannot race on the native compiled-path globals.
+ */
+export declare function makeSwapController(discovered: DiscoveredModel[], registry: ModelRegistry, loadModelFn: (path: string) => Promise<LoadableModel>, defaultName?: string): SwapController;
+//# sourceMappingURL=swap.d.ts.map

package/dist/host/swap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swap.d.ts","sourceRoot":"","sources":["../../src/host/swap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAuB,MAAM,cAAc,CAAC;AAEvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,UAAU,EAAE,MAAM,gBAAgB,EAAE,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,EAAE,EAC7B,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,EACrD,WAAW,CAAC,EAAE,MAAM,GACnB,cAAc,CAqKhB"}