@mlx-node/agent 0.0.7

package/dist/provider/events.js

@@ -0,0 +1,307 @@
+/**
+ * `TurnEmitter` — maps one native `ChatStreamEvent` turn onto pi's
+ * `AssistantMessageEvent` protocol.
+ *
+ * Correctness contract (spike-proven):
+ *   - pi's agent loop takes the final message from `stream.result()` and
+ *     reads `stopReason` off THAT message — the `done` event's `reason`
+ *     field is discarded. Both are still emitted protocol-correct.
+ *   - Aborted native streams end with NO final event, so the caller must
+ *     invoke {@link TurnEmitter.onAborted} to synthesize the terminal
+ *     AssistantMessage (stopReason 'aborted', accumulated deltas intact).
+ *   - Every method is throw-safe: the pi StreamFn contract does not allow
+ *     the emitter to throw, so internal failures route to {@link onError}.
+ */
+import { coerceErrorMessage } from './error-coercion.js';
+import { ReasoningTagBuffer } from './reasoning-tag-buffer.js';
+import { ToolCallTagBuffer } from './tool-call-buffer.js';
+/**
+ * All-zero usage. Shared with the stream adapter's TurnEmitter-independent
+ * failsafe terminal, so it must stay trivially non-throwing.
+ */
+export function emptyUsage() {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    };
+}
+/**
+ * pi auto-compaction thresholds on `usage.totalTokens` vs
+ * `model.contextWindow`, so these numbers are load-bearing:
+ * input excludes the cache-served prefix, totalTokens is the full
+ * prompt + completion. All costs are 0 for local inference.
+ */
+function usageFromFinal(final) {
+    const cachedTokens = final.cachedTokens ?? 0;
+    return {
+        input: Math.max(0, final.promptTokens - cachedTokens),
+        output: final.numTokens,
+        cacheRead: cachedTokens,
+        cacheWrite: 0,
+        reasoning: final.reasoningTokens,
+        totalTokens: final.promptTokens + final.numTokens,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    };
+}
+/**
+ * Native `ToolCallResult` → pi `ToolCall`.
+ *
+ * Non-ok results (invalid_json / missing_name / parse_error) become a
+ * deliberately-invalid pi ToolCall so pi's own tool validation fails it
+ * and feeds an error tool result back to the model — pi owns that retry
+ * loop (spike-proven).
+ */
+function toPiToolCall(call) {
+    if (call.status === 'ok') {
+        const args = typeof call.arguments === 'object' && call.arguments !== null ? call.arguments : {};
+        return { type: 'toolCall', id: call.id, name: call.name, arguments: args };
+    }
+    return {
+        type: 'toolCall',
+        id: call.id,
+        name: call.name || 'malformed_tool_call',
+        arguments: { raw: call.rawContent, error: call.error },
+    };
+}
+export class TurnEmitter {
+    onPerformance;
+    stream;
+    partial;
+    textBuffer = new ToolCallTagBuffer();
+    thinkingBuffer = new ReasoningTagBuffer();
+    /**
+     * Leading whitespace-only text parked before any text block exists, so
+     * a `"\n\n"` emitted right before `<tool_call>` markup never ratifies a
+     * whitespace-only text content block (mirrors the server endpoints).
+     * Joined onto the first non-whitespace text; dropped at terminal time.
+     */
+    pendingLeadingWhitespace = '';
+    openBlock = null;
+    finished = false;
+    constructor(stream, model, onPerformance, thinkingEnabled) {
+        this.onPerformance = onPerformance;
+        this.stream = stream;
+        this.partial = {
+            role: 'assistant',
+            content: [],
+            api: model.api,
+            provider: model.provider,
+            model: model.id,
+            usage: emptyUsage(),
+            stopReason: 'stop',
+            timestamp: Date.now(),
+        };
+        // Pi persists provider messages as JSON without a provider-specific
+        // metadata bag. Keep this small enumerable provenance field on the
+        // assistant object so a later full-history replay can distinguish a
+        // disabled-thinking empty channel from an enabled-thinking turn that
+        // simply emitted no reasoning. Unknown fields survive Pi's session
+        // JSONL round-trip and are ignored by other providers.
+        if (thinkingEnabled !== undefined) {
+            this.partial.mlxThinkingEnabled = thinkingEnabled;
+        }
+        stream.push({ type: 'start', partial: this.partial });
+    }
+    onDelta(delta) {
+        if (this.finished)
+            return;
+        try {
+            if (delta.isReasoning === true) {
+                this.appendThinking(this.thinkingBuffer.push(delta.text));
+            }
+            else {
+                // A reasoning suffix that only resembled a partial protocol tag is
+                // ordinary text. Release it before opening the visible-text block.
+                this.appendThinking(this.thinkingBuffer.flush());
+                // Text routes through the tag buffer: partial structural markup
+                // (`<tool_call>` etc.) must never leak into pi-visible text.
+                const { safeText, tagFound, cleanPrefix } = this.textBuffer.push(delta.text);
+                if (tagFound) {
+                    this.appendVisibleText(cleanPrefix);
+                }
+                else if (safeText) {
+                    this.appendVisibleText(safeText);
+                }
+            }
+        }
+        catch (err) {
+            this.onError(err);
+        }
+    }
+    onFinal(final) {
+        if (this.finished)
+            return;
+        try {
+            this.partial.usage = usageFromFinal(final);
+            if (final.finishReason === 'error') {
+                this.finishWithError('error', 'model reported finishReason=error');
+                return;
+            }
+            // Release held-back suffixes from both structural-tag buffers, then
+            // close the open block.
+            this.appendThinking(this.thinkingBuffer.flush());
+            this.appendVisibleText(this.textBuffer.flush());
+            this.closeOpenBlock();
+            let sawOkToolCall = false;
+            for (const call of final.toolCalls) {
+                if (call.status === 'ok')
+                    sawOkToolCall = true;
+                const toolCall = toPiToolCall(call);
+                this.partial.content.push(toolCall);
+                const contentIndex = this.partial.content.length - 1;
+                this.stream.push({ type: 'toolcall_start', contentIndex, partial: this.partial });
+                this.stream.push({
+                    type: 'toolcall_delta',
+                    contentIndex,
+                    delta: JSON.stringify(toolCall.arguments),
+                    partial: this.partial,
+                });
+                this.stream.push({ type: 'toolcall_end', contentIndex, toolCall, partial: this.partial });
+            }
+            const reason = sawOkToolCall ? 'toolUse' : final.finishReason === 'length' ? 'length' : 'stop';
+            this.partial.stopReason = reason;
+            if (final.performance !== undefined && this.onPerformance !== undefined) {
+                try {
+                    this.onPerformance(this.partial, final.performance);
+                }
+                catch {
+                    // Footer telemetry is best-effort and must never break inference.
+                }
+            }
+            this.finished = true;
+            this.stream.push({ type: 'done', reason, message: this.partial });
+            this.stream.end();
+        }
+        catch (err) {
+            this.onError(err);
+        }
+    }
+    /**
+     * Synthesize the terminal message for an aborted native stream (which
+     * ends with no final event). Mirrors pi's provider abort pattern:
+     * `{type:'error', reason:'aborted', error: <partial message>}` with all
+     * accumulated text/thinking preserved on the message.
+     */
+    onAborted() {
+        if (this.finished)
+            return;
+        this.finishWithError('aborted', 'Request was aborted');
+    }
+    /**
+     * Terminal for internal/adapter failures. `err` is untrusted: coercion
+     * is fully guarded (shared `coerceErrorMessage`), so even a revoked
+     * Proxy or a poisoned `message` getter cannot throw out of here.
+     */
+    onError(err) {
+        if (this.finished)
+            return;
+        this.finishWithError('error', coerceErrorMessage(err));
+    }
+    /**
+     * Shared terminal path for every non-`done` ending (abort, native
+     * finishReason=error, internal failure). Recovers any held-back buffer
+     * residue and closes the open text/thinking block BEFORE emitting the
+     * terminal event — a stream must never end `text_start/text_delta/error`
+     * with no `text_end` (pi's reference providers balance all blocks
+     * before terminals).
+     */
+    finishWithError(reason, message) {
+        this.finished = true;
+        try {
+            try {
+                this.appendThinking(this.thinkingBuffer.flush());
+                this.appendVisibleText(this.textBuffer.flush());
+            }
+            catch {
+                // Preserving buffered residue is best-effort; the block close and
+                // terminal event below must still go out.
+            }
+            this.closeOpenBlock();
+            this.partial.stopReason = reason;
+            this.partial.errorMessage = message;
+            this.stream.push({ type: 'error', reason, error: this.partial });
+            this.stream.end();
+        }
+        catch {
+            // The StreamFn contract forbids throwing; a push/end failure here
+            // has no further recovery surface.
+        }
+    }
+    appendThinking(text) {
+        if (!text)
+            return;
+        let block = this.openBlock;
+        if (block?.type !== 'thinking') {
+            this.closeOpenBlock();
+            block = { type: 'thinking', thinking: '' };
+            this.partial.content.push(block);
+            this.openBlock = block;
+            this.stream.push({ type: 'thinking_start', contentIndex: this.blockIndex(), partial: this.partial });
+        }
+        block.thinking += text;
+        this.stream.push({
+            type: 'thinking_delta',
+            contentIndex: this.blockIndex(),
+            delta: text,
+            partial: this.partial,
+        });
+    }
+    appendVisibleText(text) {
+        if (this.openBlock?.type === 'text') {
+            if (!text)
+                return;
+            this.openBlock.text += text;
+            this.stream.push({ type: 'text_delta', contentIndex: this.blockIndex(), delta: text, partial: this.partial });
+            return;
+        }
+        // No text block open yet: whitespace-only text stays parked so it can
+        // front real text later or be dropped silently at tag/terminal time.
+        const combined = this.pendingLeadingWhitespace + text;
+        if (combined.trim().length === 0) {
+            this.pendingLeadingWhitespace = combined;
+            return;
+        }
+        this.pendingLeadingWhitespace = '';
+        this.closeOpenBlock();
+        const block = { type: 'text', text: '' };
+        this.partial.content.push(block);
+        this.openBlock = block;
+        this.stream.push({ type: 'text_start', contentIndex: this.blockIndex(), partial: this.partial });
+        block.text += combined;
+        this.stream.push({
+            type: 'text_delta',
+            contentIndex: this.blockIndex(),
+            delta: combined,
+            partial: this.partial,
+        });
+    }
+    closeOpenBlock() {
+        const block = this.openBlock;
+        if (!block)
+            return;
+        this.openBlock = null;
+        if (block.type === 'text') {
+            this.stream.push({
+                type: 'text_end',
+                contentIndex: this.partial.content.indexOf(block),
+                content: block.text,
+                partial: this.partial,
+            });
+        }
+        else {
+            this.stream.push({
+                type: 'thinking_end',
+                contentIndex: this.partial.content.indexOf(block),
+                content: block.thinking,
+                partial: this.partial,
+            });
+        }
+    }
+    blockIndex() {
+        return this.partial.content.length - 1;
+    }
+}

package/dist/provider/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `createMlxProviderExtension` — the pi inline extension that registers
+ * the in-process `mlx` provider.
+ *
+ * Task 8's `runAgent` passes the returned extension into pi's `main()`
+ * via `extensionFactories`; pi calls the factory during extension load,
+ * and `registerProvider` makes every discovered local model resolvable
+ * as `mlx/<dir-name>` with no /login (the literal apiKey marks the
+ * models available).
+ *
+ * Import discipline (load-bearing): pi is import-order sensitive to its
+ * config env vars, so this module — which the CLI imports BEFORE those
+ * env vars are set — must not runtime-import `@earendil-works/pi-coding-agent`
+ * at module top level. Only type-only pi imports appear here; the
+ * `ExtensionAPI` value arrives as the factory argument.
+ */
+import type { InlineExtension } from '@earendil-works/pi-coding-agent';
+import { MlxModelHost } from './model-host.js';
+import type { MlxModelInfo } from './models.js';
+/**
+ * Build the `mlx-provider` inline extension serving `models`. The host
+ * (one per process — it owns the single GPU-resident model) is created
+ * eagerly so repeated factory invocations can never spawn a second
+ * host, but stays lazy about weights: nothing loads until the first
+ * `streamSimple` call.
+ */
+export declare function createMlxProviderExtension(models: MlxModelInfo[], host?: MlxModelHost): InlineExtension;
+//# sourceMappingURL=index.d.ts.map

package/dist/provider/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,eAAe,CAqCvG"}

package/dist/provider/index.js

@@ -0,0 +1,64 @@
+/**
+ * `createMlxProviderExtension` — the pi inline extension that registers
+ * the in-process `mlx` provider.
+ *
+ * Task 8's `runAgent` passes the returned extension into pi's `main()`
+ * via `extensionFactories`; pi calls the factory during extension load,
+ * and `registerProvider` makes every discovered local model resolvable
+ * as `mlx/<dir-name>` with no /login (the literal apiKey marks the
+ * models available).
+ *
+ * Import discipline (load-bearing): pi is import-order sensitive to its
+ * config env vars, so this module — which the CLI imports BEFORE those
+ * env vars are set — must not runtime-import `@earendil-works/pi-coding-agent`
+ * at module top level. Only type-only pi imports appear here; the
+ * `ExtensionAPI` value arrives as the factory argument.
+ */
+import { MlxModelHost } from './model-host.js';
+import { PerformanceStatus } from './performance-status.js';
+import { makeMlxStreamSimple } from './stream-adapter.js';
+/**
+ * Build the `mlx-provider` inline extension serving `models`. The host
+ * (one per process — it owns the single GPU-resident model) is created
+ * eagerly so repeated factory invocations can never spawn a second
+ * host, but stays lazy about weights: nothing loads until the first
+ * `streamSimple` call.
+ */
+export function createMlxProviderExtension(models, host) {
+    const resolvedHost = host ?? new MlxModelHost(models.map((m) => m.discovered));
+    const performanceStatus = new PerformanceStatus();
+    // This closure outlives Pi runtime replacement. Pi creates a replacement
+    // runtime for /new and /resume and reruns inline extension factories; each
+    // new factory's session_start updates the root while child sessions keep
+    // using this registered stream.
+    let rootCacheOwnerId;
+    const streamSimple = makeMlxStreamSimple(resolvedHost, performanceStatus.record, () => rootCacheOwnerId);
+    return {
+        name: 'mlx-provider',
+        factory: (pi) => {
+            pi.registerProvider('mlx', {
+                api: 'mlx',
+                baseUrl: 'mlx://local',
+                apiKey: 'mlx-local',
+                streamSimple,
+                models: models.map((m) => m.piModel),
+            });
+            pi.on('session_start', (_event, ctx) => {
+                rootCacheOwnerId = ctx.sessionManager.getSessionId();
+            });
+            pi.on('message_end', (event, ctx) => {
+                performanceStatus.showMessage(event, ctx);
+            });
+            // Do not clear on turn_start. Pi emits a fresh turn after every tool
+            // result, before the next inference has terminal metrics to replace the
+            // completed sample; clearing here makes the footer disappear precisely
+            // while a long tool-follow-up prefill is running.
+            pi.on('model_select', (_event, ctx) => {
+                performanceStatus.clear(ctx);
+            });
+            pi.on('session_shutdown', (_event, ctx) => {
+                performanceStatus.clear(ctx);
+            });
+        },
+    };
+}

package/dist/provider/inference-trace.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Privacy-safe, best-effort inference tracing for the in-process mlx agent.
+ *
+ * The trace is deliberately metadata-only. Callers can only supply fields from
+ * the allowlist below; prompt/output text, tool payloads, paths, token ids, and
+ * error messages have no serialization path. Tracing is enabled only when
+ * `MLX_INFERENCE_TRACE` is explicitly truthy and
+ * `MLX_INFERENCE_TRACE_FILE` is non-empty.
+ *
+ * Writes are synchronous because this is a bounded, high-level lifecycle trace
+ * (roughly a dozen records per request), not a token/layer trace. Every write is
+ * swallowed on failure so observability can never change inference behavior.
+ */
+export type InferenceTraceEvent = 'request.created' | 'host.queue.enter' | 'host.start' | 'host.resident' | 'host.load.start' | 'host.load.end' | 'host.callback.end' | 'session.reset' | 'session.prime' | 'session.config' | 'native.stream.start' | 'native.stream.first_delta' | 'request.terminal';
+export type InferenceTraceStatus = 'ok' | 'error' | 'aborted';
+export interface InferenceTraceFields {
+    status?: InferenceTraceStatus;
+    resident?: 'hit' | 'load' | 'swap';
+    resetMode?: 'preserve' | 'full';
+    finishReason?: 'stop' | 'length' | 'cancelled' | 'error' | 'other';
+    reasoningEffort?: 'none' | 'low' | 'medium' | 'high';
+    modelType?: 'gemma4' | 'qwen3' | 'qwen3_5' | 'qwen3_5_moe' | 'lfm2' | 'lfm2_moe' | 'other';
+    streaming?: boolean;
+    reportPerformance?: boolean;
+    isReasoning?: boolean;
+    durationMs?: number;
+    queueMs?: number;
+    messageCount?: number;
+    toolCount?: number;
+    maxNewTokens?: number;
+    promptTokens?: number;
+    cachedTokens?: number;
+    generatedTokens?: number;
+    reasoningTokens?: number;
+    ttftMs?: number;
+    prefillTokensPerSecond?: number;
+    decodeTokensPerSecond?: number;
+    mtpMeanAcceptedTokens?: number;
+    mtpMeanAcceptedTokensTotal?: number;
+    mtpCycles?: number;
+    mtpMeanDepth?: number;
+    mtpAcceptanceByPosition?: readonly number[];
+}
+export interface InferenceTraceSink {
+    write(line: string): void;
+}
+export declare class InferenceTrace {
+    private readonly sink;
+    readonly requestId: string;
+    private terminalWritten;
+    constructor(sink?: InferenceTraceSink | undefined);
+    emit(event: InferenceTraceEvent, fields?: InferenceTraceFields): void;
+    terminal(status: InferenceTraceStatus, fields?: InferenceTraceFields): void;
+}
+export declare function createInferenceTrace(): InferenceTrace;
+export declare function classifyFinishReason(value: string): NonNullable<InferenceTraceFields['finishReason']>;
+export declare function classifyModelType(value: string): NonNullable<InferenceTraceFields['modelType']>;
+//# sourceMappingURL=inference-trace.d.ts.map

package/dist/provider/inference-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-trace.d.ts","sourceRoot":"","sources":["../../src/provider/inference-trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,MAAM,mBAAmB,GAC3B,iBAAiB,GACjB,kBAAkB,GAClB,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,eAAe,GACf,gBAAgB,GAChB,qBAAqB,GACrB,2BAA2B,GAC3B,kBAAkB,CAAC;AAEvB,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACnC,SAAS,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;IACnE,eAAe,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrD,SAAS,CAAC,EACN,QAAQ,GACR,OAAO,GACP,SAAS,GACT,aAAa,GACb,MAAM,GACN,UAAU,GACV,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA+ID,qBAAa,cAAc;IAIb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,QAAQ,CAAC,SAAS,SAAmB;IACrC,OAAO,CAAC,eAAe,CAAS;IAEhC,YAA6B,IAAI,GAAE,kBAAkB,GAAG,SAAyB,EAAI;IAErF,IAAI,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,GAAE,oBAAyB,GAAG,IAAI,CAiBxE;IAED,QAAQ,CAAC,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAE,oBAAyB,GAAG,IAAI,CAI9E;CACF;AAED,wBAAgB,oBAAoB,IAAI,cAAc,CAErD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC,CAUrG;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAY/F"}

package/dist/provider/inference-trace.js

@@ -0,0 +1,205 @@
+/**
+ * Privacy-safe, best-effort inference tracing for the in-process mlx agent.
+ *
+ * The trace is deliberately metadata-only. Callers can only supply fields from
+ * the allowlist below; prompt/output text, tool payloads, paths, token ids, and
+ * error messages have no serialization path. Tracing is enabled only when
+ * `MLX_INFERENCE_TRACE` is explicitly truthy and
+ * `MLX_INFERENCE_TRACE_FILE` is non-empty.
+ *
+ * Writes are synchronous because this is a bounded, high-level lifecycle trace
+ * (roughly a dozen records per request), not a token/layer trace. Every write is
+ * swallowed on failure so observability can never change inference behavior.
+ */
+import { appendFileSync } from 'node:fs';
+const EVENTS = new Set([
+    'request.created',
+    'host.queue.enter',
+    'host.start',
+    'host.resident',
+    'host.load.start',
+    'host.load.end',
+    'host.callback.end',
+    'session.reset',
+    'session.prime',
+    'session.config',
+    'native.stream.start',
+    'native.stream.first_delta',
+    'request.terminal',
+]);
+const STATUS = new Set(['ok', 'error', 'aborted']);
+const RESIDENT = new Set(['hit', 'load', 'swap']);
+const RESET_MODE = new Set(['preserve', 'full']);
+const FINISH_REASON = new Set([
+    'stop',
+    'length',
+    'cancelled',
+    'error',
+    'other',
+]);
+const REASONING_EFFORT = new Set([
+    'none',
+    'low',
+    'medium',
+    'high',
+]);
+const MODEL_TYPE = new Set([
+    'gemma4',
+    'qwen3',
+    'qwen3_5',
+    'qwen3_5_moe',
+    'lfm2',
+    'lfm2_moe',
+    'other',
+]);
+let requestSequence = 0;
+let eventSequence = 0;
+function envFlagEnabled(value) {
+    if (value == null)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+function defaultSink() {
+    if (!envFlagEnabled(process.env.MLX_INFERENCE_TRACE))
+        return undefined;
+    const path = process.env.MLX_INFERENCE_TRACE_FILE?.trim();
+    if (!path)
+        return undefined;
+    return {
+        write(line) {
+            appendFileSync(path, line, { encoding: 'utf8', flag: 'a', mode: 0o600 });
+        },
+    };
+}
+function nextRequestId() {
+    requestSequence += 1;
+    return `agent-${process.pid.toString(36)}-${requestSequence.toString(36)}`;
+}
+function nonNegativeFinite(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function nonNegativeInteger(value) {
+    const n = nonNegativeFinite(value);
+    return n !== undefined && Number.isSafeInteger(n) ? n : undefined;
+}
+function copyNumber(out, fields, key, integer) {
+    const value = integer ? nonNegativeInteger(fields[key]) : nonNegativeFinite(fields[key]);
+    if (value !== undefined)
+        out[key] = value;
+}
+/** Runtime allowlist: protects the file even if an untyped caller supplies extras. */
+function sanitizeFields(fields) {
+    const out = {};
+    if (fields.status !== undefined && STATUS.has(fields.status))
+        out.status = fields.status;
+    if (fields.resident !== undefined && RESIDENT.has(fields.resident))
+        out.resident = fields.resident;
+    if (fields.resetMode !== undefined && RESET_MODE.has(fields.resetMode))
+        out.resetMode = fields.resetMode;
+    if (fields.finishReason !== undefined && FINISH_REASON.has(fields.finishReason)) {
+        out.finishReason = fields.finishReason;
+    }
+    if (fields.reasoningEffort !== undefined && REASONING_EFFORT.has(fields.reasoningEffort)) {
+        out.reasoningEffort = fields.reasoningEffort;
+    }
+    if (fields.modelType !== undefined && MODEL_TYPE.has(fields.modelType))
+        out.modelType = fields.modelType;
+    for (const key of ['streaming', 'reportPerformance', 'isReasoning']) {
+        if (typeof fields[key] === 'boolean')
+            out[key] = fields[key];
+    }
+    for (const key of [
+        'durationMs',
+        'queueMs',
+        'ttftMs',
+        'prefillTokensPerSecond',
+        'decodeTokensPerSecond',
+        'mtpMeanAcceptedTokens',
+        'mtpMeanAcceptedTokensTotal',
+        'mtpMeanDepth',
+    ]) {
+        copyNumber(out, fields, key, false);
+    }
+    for (const key of [
+        'messageCount',
+        'toolCount',
+        'maxNewTokens',
+        'promptTokens',
+        'cachedTokens',
+        'generatedTokens',
+        'reasoningTokens',
+        'mtpCycles',
+    ]) {
+        copyNumber(out, fields, key, true);
+    }
+    if (Array.isArray(fields.mtpAcceptanceByPosition)) {
+        const values = fields.mtpAcceptanceByPosition
+            .slice(0, 16)
+            .map(nonNegativeFinite)
+            .filter((value) => value !== undefined);
+        if (values.length > 0)
+            out.mtpAcceptanceByPosition = values;
+    }
+    return out;
+}
+export class InferenceTrace {
+    sink;
+    requestId = nextRequestId();
+    terminalWritten = false;
+    constructor(sink = defaultSink()) {
+        this.sink = sink;
+    }
+    emit(event, fields = {}) {
+        if (!this.sink || !EVENTS.has(event))
+            return;
+        try {
+            eventSequence += 1;
+            const record = {
+                timestamp: new Date().toISOString(),
+                pid: process.pid,
+                seq: eventSequence,
+                requestId: this.requestId,
+                component: 'agent',
+                event,
+                ...sanitizeFields(fields),
+            };
+            this.sink.write(`${JSON.stringify(record)}\n`);
+        }
+        catch {
+            // Diagnostics are best-effort and must never affect inference.
+        }
+    }
+    terminal(status, fields = {}) {
+        if (this.terminalWritten)
+            return;
+        this.terminalWritten = true;
+        this.emit('request.terminal', { ...fields, status });
+    }
+}
+export function createInferenceTrace() {
+    return new InferenceTrace();
+}
+export function classifyFinishReason(value) {
+    switch (value) {
+        case 'stop':
+        case 'length':
+        case 'cancelled':
+        case 'error':
+            return value;
+        default:
+            return 'other';
+    }
+}
+export function classifyModelType(value) {
+    switch (value) {
+        case 'gemma4':
+        case 'qwen3':
+        case 'qwen3_5':
+        case 'qwen3_5_moe':
+        case 'lfm2':
+        case 'lfm2_moe':
+            return value;
+        default:
+            return 'other';
+    }
+}