@mlx-node/agent 0.0.8 → 0.0.10

package/dist/provider/chat-config.js

@@ -54,6 +54,9 @@ const THINKING_LEVEL_TO_EFFORT = {
     xhigh: 'high',
     max: 'high',
 };
+function isPositiveSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
 /**
  * Resolve Pi's thinking level once for both native config and persisted replay
  * provenance. Keeping these values together prevents a low/minimal turn from
@@ -67,7 +70,7 @@ export function resolveReasoningMode(reasoning) {
         thinkingEnabled: reasoningEffort === 'medium' || reasoningEffort === 'high',
     };
 }
-export function buildChatConfig(modelType, options, tools, rootCacheOwnerId, resolvedReasoning = resolveReasoningMode(options?.reasoning)) {
+export function buildChatConfig(modelType, options, tools, rootCacheOwnerId, resolvedReasoning = resolveReasoningMode(options?.reasoning), modelMaxTokens) {
     const preset = launchPresetFor(modelType);
     if (!preset) {
         const known = [...new Set([...Object.keys(LAUNCH_PRESETS), ...Object.keys(AGENT_LAUNCH_PRESETS)])].join(', ');
@@ -92,8 +95,17 @@ export function buildChatConfig(modelType, options, tools, rootCacheOwnerId, res
     // which branch the bounded GDN sidecar store protects from child eviction.
     if (rootCacheOwnerId !== undefined)
         config.cacheRootOwnerId = rootCacheOwnerId;
-    if (options?.maxTokens !== undefined)
-        config.maxNewTokens = options.maxTokens;
+    const explicitMaxTokens = options?.maxTokens;
+    if (isPositiveSafeInteger(explicitMaxTokens)) {
+        // A valid per-call provider option is the topmost layer.
+        config.maxNewTokens = explicitMaxTokens;
+    }
+    else if (isPositiveSafeInteger(modelMaxTokens)) {
+        // Normal Pi agent turns omit SimpleStreamOptions.maxTokens. Honor the
+        // composed Model metadata (including models.json modelOverrides) without
+        // allowing malformed/hostile metadata to replace the family preset.
+        config.maxNewTokens = modelMaxTokens;
+    }
     if (options?.temperature !== undefined)
         config.temperature = options.temperature;
     if (tools && tools.length > 0)

package/dist/provider/events.d.ts

@@ -21,6 +21,15 @@ import type { ChatStreamDelta, ChatStreamFinal, PerformanceMetrics } from '@mlx-
 export declare function emptyUsage(): Usage;
 export declare class TurnEmitter {
     private readonly onPerformance?;
+    /**
+     * Correlation id for this turn. Minted here, stamped on the partial message
+     * as the custom `mlxTraceId` field (survives pi's JSONL round-trip like
+     * `mlxThinkingEnabled`), and surfaced so the stream adapter can join a
+     * `MetricsTrace` record to the persisted pi message. The pi entry id is not
+     * knowable in-turn (pi emits `message_end` before persisting), so this
+     * minted id is the durable join key.
+     */
+    readonly traceId: string;
     private readonly stream;
     private readonly partial;
     private readonly textBuffer;

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/provider/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,gBAAgB,EAChB,2BAA2B,EAC3B,KAAK,EAIL,KAAK,EACN,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAkB,MAAM,cAAc,CAAC;AAMzG;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,CASlC;AA2CD,qBAAa,WAAW;IAkBpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAjBjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;IAC3D;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB,CAAM;IACtC,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,QAAQ,CAAS;IAEzB,YACE,MAAM,EAAE,2BAA2B,EACnC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACA,aAAa,CAAC,GAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,KAAK,IAAI,aAAA,EACrG,eAAe,CAAC,EAAE,OAAO,EAuB1B;IAED,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAqBpC;IAED,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CA8CpC;IAED;;;;;OAKG;IACH,SAAS,IAAI,IAAI,CAGhB;IAED;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAG1B;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,UAAU;CAGnB"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/provider/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EACV,GAAG,EACH,gBAAgB,EAChB,2BAA2B,EAC3B,KAAK,EAIL,KAAK,EACN,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAkB,MAAM,cAAc,CAAC;AAMzG;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,CASlC;AA2CD,qBAAa,WAAW;IA2BpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IA1BjC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;IAC3D;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB,CAAM;IACtC,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,QAAQ,CAAS;IAEzB,YACE,MAAM,EAAE,2BAA2B,EACnC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EACA,aAAa,CAAC,GAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,KAAK,IAAI,aAAA,EACrG,eAAe,CAAC,EAAE,OAAO,EA4B1B;IAED,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAqBpC;IAED,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CA8CpC;IAED;;;;;OAKG;IACH,SAAS,IAAI,IAAI,CAGhB;IAED;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAG1B;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,UAAU;CAGnB"}

package/dist/provider/events.js

@@ -12,6 +12,7 @@
  *   - Every method is throw-safe: the pi StreamFn contract does not allow
  *     the emitter to throw, so internal failures route to {@link onError}.
  */
+import { randomUUID } from 'node:crypto';
 import { coerceErrorMessage } from './error-coercion.js';
 import { ReasoningTagBuffer } from './reasoning-tag-buffer.js';
 import { ToolCallTagBuffer } from './tool-call-buffer.js';
@@ -69,6 +70,15 @@ function toPiToolCall(call) {
 }
 export class TurnEmitter {
     onPerformance;
+    /**
+     * Correlation id for this turn. Minted here, stamped on the partial message
+     * as the custom `mlxTraceId` field (survives pi's JSONL round-trip like
+     * `mlxThinkingEnabled`), and surfaced so the stream adapter can join a
+     * `MetricsTrace` record to the persisted pi message. The pi entry id is not
+     * knowable in-turn (pi emits `message_end` before persisting), so this
+     * minted id is the durable join key.
+     */
+    traceId;
     stream;
     partial;
     textBuffer = new ToolCallTagBuffer();
@@ -85,6 +95,8 @@ export class TurnEmitter {
     constructor(stream, model, onPerformance, thinkingEnabled) {
         this.onPerformance = onPerformance;
         this.stream = stream;
+        const traceId = randomUUID();
+        this.traceId = traceId;
         this.partial = {
             role: 'assistant',
             content: [],
@@ -104,6 +116,9 @@ export class TurnEmitter {
         if (thinkingEnabled !== undefined) {
             this.partial.mlxThinkingEnabled = thinkingEnabled;
         }
+        // Same custom-field mechanism: stamp the trace id so a dashboard can join
+        // the durable MetricsTrace record back to this persisted pi message.
+        this.partial.mlxTraceId = traceId;
         stream.push({ type: 'start', partial: this.partial });
     }
     onDelta(delta) {

package/dist/provider/index.d.ts

@@ -15,8 +15,19 @@
  * `ExtensionAPI` value arrives as the factory argument.
  */
 import type { InlineExtension } from '@earendil-works/pi-coding-agent';
+import { type ColdCacheStats, type ColdSidecarStats } from '@mlx-node/core';
+import { MetricsTrace } from './metrics-trace.js';
 import { MlxModelHost } from './model-host.js';
 import type { MlxModelInfo } from './models.js';
+/** Injectable seams for {@link createMlxProviderExtension} (unit tests). */
+export interface MlxProviderExtensionDeps {
+    /** Process-wide cold-tier reader; defaults to the native addon (absent in unit tests). */
+    coldStats?: () => ColdCacheStats | undefined;
+    /** Process-wide sidecar-counter reader; defaults to the native addon. */
+    sidecarStats?: () => ColdSidecarStats | undefined;
+    /** Durable per-turn telemetry sink; defaults to a fresh {@link MetricsTrace}. */
+    metricsTrace?: MetricsTrace;
+}
 /**
  * Build the `mlx-provider` inline extension serving `models`. The host
  * (one per process — it owns the single GPU-resident model) is created
@@ -24,5 +35,5 @@ import type { MlxModelInfo } from './models.js';
  * host, but stays lazy about weights: nothing loads until the first
  * `streamSimple` call.
  */
-export declare function createMlxProviderExtension(models: MlxModelInfo[], host?: MlxModelHost): InlineExtension;
+export declare function createMlxProviderExtension(models: MlxModelInfo[], host?: MlxModelHost, deps?: MlxProviderExtensionDeps): InlineExtension;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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;AACrF,OAAO,EAAoC,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG9G,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA4BhD,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAC7C,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,gBAAgB,GAAG,SAAS,CAAC;IAClD,iFAAiF;IACjF,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,YAAY,EAAE,EACtB,IAAI,CAAC,EAAE,YAAY,EACnB,IAAI,GAAE,wBAA6B,GAClC,eAAe,CA6KjB"}

package/dist/provider/index.js

@@ -14,9 +14,37 @@
  * at module top level. Only type-only pi imports appear here; the
  * `ExtensionAPI` value arrives as the factory argument.
  */
+import { coldCacheStats, coldSidecarStats } from '@mlx-node/core';
+import { canonicalCacheRoot } from '../cold-tier.js';
+import { MetricsTrace } from './metrics-trace.js';
+import { MLX_API, MLX_API_KEY, MLX_BASE_URL, MLX_PROVIDER_ID } from './mlx-identity.js';
 import { MlxModelHost } from './model-host.js';
 import { PerformanceStatus } from './performance-status.js';
 import { makeMlxStreamSimple } from './stream-adapter.js';
+/** Read the process-wide cold-tier snapshot; the native addon may be absent (unit tests). */
+function safeColdStats() {
+    try {
+        return coldCacheStats();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the process-wide sidecar counters. Separate from {@link safeColdStats}
+ * because it reads a different native struct that has no `enabled` gate: the
+ * counters live in a plain static, not in the tier, so they are valid even
+ * when the tier never opened — which is exactly the case a run with zero
+ * sidecars needs distinguished.
+ */
+function safeSidecarStats() {
+    try {
+        return coldSidecarStats();
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Build the `mlx-provider` inline extension serving `models`. The host
  * (one per process — it owns the single GPU-resident model) is created
@@ -24,27 +52,145 @@ import { makeMlxStreamSimple } from './stream-adapter.js';
  * host, but stays lazy about weights: nothing loads until the first
  * `streamSimple` call.
  */
-export function createMlxProviderExtension(models, host) {
+export function createMlxProviderExtension(models, host, deps = {}) {
     const resolvedHost = host ?? new MlxModelHost(models.map((m) => m.discovered));
     const performanceStatus = new PerformanceStatus();
+    const metricsTrace = deps.metricsTrace ?? new MetricsTrace();
+    const readColdStats = deps.coldStats ?? safeColdStats;
+    const readSidecarStats = deps.sidecarStats ?? safeSidecarStats;
     // 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.
+    // using this registered stream. The root id doubles as the cache owner and
+    // the metrics-trace root; the JSONL path travels alongside it for metrics.
     let rootCacheOwnerId;
-    const streamSimple = makeMlxStreamSimple(resolvedHost, performanceStatus.record, () => rootCacheOwnerId);
+    let rootSessionFile;
+    // Cold-tier counters are cumulative since the tier opened. Snapshot them at
+    // each turn's native start (`onTurnStart`, fired inside the serialized host
+    // closure) and diff at the success terminal, so a turn that aborted or
+    // errored — which never reaches `onTurnRecord` — can't leak its restores into
+    // the next successful turn's delta. Inference is serialized per process (host
+    // promise chain), so by the time a turn snapshots, any prior turn has fully
+    // drained. The SYNCHRONOUS counters (hits/misses/bytesRestored/enqueued/
+    // corruptions/queueDrops/restoreDeclines) are exact per-turn; bytesWritten,
+    // evictions and writeErrors advance on the async writer thread, so those
+    // deltas are approximate (documented per field on the record).
+    //
+    // The SIDECAR counters are snapshotted the same way but are exact without
+    // exception: every one of them is recorded inside the native turn finalize,
+    // on the calling thread, before the turn returns. They also have no `enabled`
+    // gate — they live in a plain process static rather than in the tier — so
+    // they read honestly on a run where the tier never opened, which is the run
+    // that most needs them.
+    let turnStartCold = readColdStats();
+    let turnStartSidecar = readSidecarStats();
+    const onTurnStart = () => {
+        turnStartCold = readColdStats();
+        turnStartSidecar = readSidecarStats();
+    };
+    const onTurnRecord = ({ traceId, sessionId, rootSessionId, rootSessionFile, model, final, durationMs, queueMs, resident, }) => {
+        const rec = {
+            traceId,
+            ts: Date.now(),
+            sessionId,
+            rootSessionId,
+            rootSessionFile,
+            model,
+            durationMs,
+            queueMs,
+            resident,
+            finishReason: final.finishReason,
+            promptTokens: final.promptTokens,
+            cachedTokens: final.cachedTokens ?? 0,
+            outputTokens: final.numTokens,
+            reasoningTokens: final.reasoningTokens,
+        };
+        const perf = final.performance;
+        if (perf) {
+            rec.ttftMs = perf.ttftMs;
+            rec.prefillTps = perf.prefillTokensPerSecond;
+            rec.decodeTps = perf.decodeTokensPerSecond;
+            rec.mtpCycles = perf.mtpCycles;
+            // mlx-vlm-comparable headline accept rate (committed tokens per cycle).
+            rec.mtpMeanAccepted = perf.mtpMeanAcceptedTokensTotal;
+        }
+        const cold = readColdStats();
+        if (cold && turnStartCold) {
+            rec.coldHits = cold.hits - turnStartCold.hits;
+            rec.coldMisses = cold.misses - turnStartCold.misses;
+            rec.coldBytesWritten = cold.bytesWritten - turnStartCold.bytesWritten;
+            rec.coldBytesRestored = cold.bytesRestored - turnStartCold.bytesRestored;
+            rec.coldEnqueued = cold.enqueued - turnStartCold.enqueued;
+            rec.coldQueueDrops = cold.queueDrops - turnStartCold.queueDrops;
+            rec.coldEvictions = cold.evictions - turnStartCold.evictions;
+            rec.coldCorruptions = cold.corruptions - turnStartCold.corruptions;
+            rec.coldWriteErrors = cold.writeErrors - turnStartCold.writeErrors;
+            rec.coldRestoreDeclines = cold.restoreDeclines - turnStartCold.restoreDeclines;
+            // Absolutes, not deltas: an aborted/errored turn never reaches this
+            // recorder, so a corruption or a dropped write during one lands in NO
+            // delta. The cumulative counter observed by the next successful turn
+            // still carries it, which is what makes "corruptions must be 0"
+            // checkable at all (`MAX(total) > 0` over any window).
+            rec.coldCorruptionsTotal = cold.corruptions;
+            rec.coldQueueDropsTotal = cold.queueDrops;
+            // Same latch, and the counter that needs it most: a write error is
+            // raised on the background writer, so the one covering the LAST turn
+            // before a crash lands in no delta at all — and "is my cache root
+            // broken?" is a question about ever, not about this turn.
+            rec.coldWriteErrorsTotal = cold.writeErrors;
+            // Cache IDENTITY comes from the END-of-turn snapshot, never the baseline:
+            // the tier opens LAZILY on first use, so on a process's first turn
+            // `turnStartCold` is the all-zero default with `enabled: false` and an
+            // empty root. Canonicalized here — in the writer — so the dashboard
+            // never has to match whatever spelling Rust happened to construct.
+            rec.coldEnabled = cold.enabled;
+            // ONE emptiness test, applied to the CANONICAL value. Gating on the raw
+            // native string used a DIFFERENT test from the one `canonicalCacheRoot`
+            // applies (it trims), so a whitespace-only root passed `length > 0` here
+            // and canonicalized to `''` — which `MetricsTrace.record` then dropped,
+            // leaving a row that says the tier was ON while carrying no root at all.
+            if (cold.enabled) {
+                const canonicalRoot = canonicalCacheRoot(cold.root);
+                if (canonicalRoot.length > 0)
+                    rec.coldRoot = canonicalRoot;
+            }
+        }
+        // Its own guard, deliberately not folded into the block above: the sidecar
+        // reader never consults the tier, so it keeps reporting when `cold` is
+        // undefined or the tier failed to open. A run with `coldHits: 0` and no
+        // tier is exactly when "did the capture even run?" is the question, and
+        // gating these on `cold` would blank them precisely then.
+        const sidecar = readSidecarStats();
+        if (sidecar && turnStartSidecar) {
+            rec.coldSidecarCaptureReached = sidecar.captureReached - turnStartSidecar.captureReached;
+            rec.coldSidecarChainEmpty = sidecar.chainEmpty - turnStartSidecar.chainEmpty;
+            rec.coldSidecarBoundarySkips = sidecar.boundarySkips - turnStartSidecar.boundarySkips;
+            rec.coldSidecarAlreadyPersisted = sidecar.alreadyPersisted - turnStartSidecar.alreadyPersisted;
+            rec.coldSidecarEnqueued = sidecar.enqueued - turnStartSidecar.enqueued;
+            rec.coldSidecarQueueDrops = sidecar.queueDrops - turnStartSidecar.queueDrops;
+            rec.coldSidecarInstalled = sidecar.installed - turnStartSidecar.installed;
+            rec.coldSidecarRestoreSuppressed = sidecar.restoreSuppressed - turnStartSidecar.restoreSuppressed;
+        }
+        metricsTrace.record(rec);
+    };
+    const streamSimple = makeMlxStreamSimple(resolvedHost, performanceStatus.record, () => rootCacheOwnerId, onTurnRecord, onTurnStart, () => rootSessionFile);
     return {
         name: 'mlx-provider',
         factory: (pi) => {
-            pi.registerProvider('mlx', {
-                api: 'mlx',
-                baseUrl: 'mlx://local',
-                apiKey: 'mlx-local',
+            pi.registerProvider(MLX_PROVIDER_ID, {
+                api: MLX_API,
+                baseUrl: MLX_BASE_URL,
+                apiKey: MLX_API_KEY,
                 streamSimple,
                 models: models.map((m) => m.piModel),
             });
             pi.on('session_start', (_event, ctx) => {
                 rootCacheOwnerId = ctx.sessionManager.getSessionId();
+                // Snapshot the root JSONL path so a turn submitted under this root is
+                // correlated to it at completion — even for subagent turns, which have
+                // no session file of their own. `getSessionFile` is optional-chained so
+                // a minimal test/mock session manager without it still works.
+                rootSessionFile = ctx.sessionManager.getSessionFile?.();
             });
             pi.on('message_end', (event, ctx) => {
                 performanceStatus.showMessage(event, ctx);

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

@@ -0,0 +1,274 @@
+/**
+ * `MetricsTrace` — always-on per-turn inference telemetry, appended as JSON
+ * Lines to `$HOME/.mlx-node/metrics/traces/<YYYY-MM-DD>-<pid>.jsonl`.
+ *
+ * This is a durable sink that complements the transient in-memory
+ * {@link ./performance-status.ts} WeakMap (which only feeds the live TUI
+ * footer). One record is written per successful inference turn so the
+ * dashboard can correlate throughput, cache reuse, and cold-tier deltas back
+ * to the pi session that produced them via `mlxTraceId`.
+ *
+ * Contract:
+ *   - Default-on; the `MLX_AGENT_METRICS` env var set to `0` / `false` / `off`
+ *     (case-insensitive) is the only kill switch.
+ *   - `record()` NEVER throws: every field is allowlisted (no free text ever
+ *     lands on disk) and all fs work is wrapped — telemetry must never break
+ *     an inference turn.
+ */
+/**
+ * Per-turn delta of every COUNTER on the native `ColdCacheStats` — the paged
+ * K/V block traffic. One entry per native counter field, named
+ * `cold` + PascalCase(nativeKey); the three non-counter fields (`enabled`,
+ * `root`, `quotaBytes`) describe the tier's identity rather than a turn and are
+ * carried separately as {@link MetricsTraceRecord.coldEnabled} /
+ * {@link MetricsTraceRecord.coldRoot}.
+ *
+ * This is the TS half of a cross-language invariant.
+ * `__test__/cold-counter-fields.test.ts` derives the same names from
+ * `coldCacheStats()` at runtime and demands an exact match, so a counter added
+ * natively but not here — or, the failure this list exists for, one quietly
+ * dropped from here — is a red test rather than an empty dashboard column.
+ */
+export declare const COLD_COUNTER_FIELDS: readonly ['coldHits', 'coldMisses', 'coldEnqueued', 'coldQueueDrops', 'coldBytesWritten', 'coldBytesRestored', 'coldEvictions', 'coldCorruptions', 'coldWriteErrors', 'coldRestoreDeclines'];
+/**
+ * Per-turn delta of every counter on the native `ColdSidecarStats` — the
+ * recurrent / sliding-window state that lives OUTSIDE the paged pool. Named
+ * `coldSidecar` + PascalCase(nativeKey).
+ *
+ * Deliberately a second, differently-prefixed list rather than a merge: both
+ * native structs carry `enqueued` and `queueDrops`, and they count different
+ * objects (blocks vs sidecars). Flattening them into one namespace would make
+ * two unrelated numbers collide on one column.
+ */
+export declare const COLD_SIDECAR_FIELDS: readonly ['coldSidecarCaptureReached', 'coldSidecarChainEmpty', 'coldSidecarBoundarySkips', 'coldSidecarAlreadyPersisted', 'coldSidecarEnqueued', 'coldSidecarQueueDrops', 'coldSidecarInstalled', 'coldSidecarRestoreSuppressed'];
+/** Every cold-tier per-turn delta field, in native-struct order. */
+export declare const COLD_DELTA_FIELDS: readonly ["coldHits", "coldMisses", "coldEnqueued", "coldQueueDrops", "coldBytesWritten", "coldBytesRestored", "coldEvictions", "coldCorruptions", "coldWriteErrors", "coldRestoreDeclines", "coldSidecarCaptureReached", "coldSidecarChainEmpty", "coldSidecarBoundarySkips", "coldSidecarAlreadyPersisted", "coldSidecarEnqueued", "coldSidecarQueueDrops", "coldSidecarInstalled", "coldSidecarRestoreSuppressed"];
+/** A key of {@link COLD_DELTA_FIELDS}; every one is an optional `number`. */
+export type ColdDeltaField = (typeof COLD_DELTA_FIELDS)[number];
+/**
+ * One inference turn's telemetry. Every field is a number, a small
+ * enumerated string (`finishReason`), or an identifier — never model output
+ * text, tool arguments, or prompt content.
+ */
+export interface MetricsTraceRecord extends Partial<Record<ColdDeltaField, number>> {
+    /** Schema version. */
+    v: 1;
+    /** Join key minted by `TurnEmitter`; also stamped on the pi message as `mlxTraceId`. */
+    traceId: string;
+    /** Wall-clock write time (ms since epoch). */
+    ts: number;
+    /** pi per-request session id (parent vs each subagent differ). */
+    sessionId?: string;
+    /** Root pi session id the turn was SUBMITTED under (snapshotted at submit). */
+    rootSessionId?: string;
+    /** Root pi session JSONL file path the turn was SUBMITTED under (snapshotted at submit). */
+    rootSessionFile?: string;
+    /** Model id served this turn (`mlx/<dir-name>`'s `<dir-name>`). */
+    model: string;
+    /** Turn duration (ms) bracketing resident selection + prefill + decode. */
+    durationMs: number;
+    /**
+     * Queue + cold-load wait (ms) before native work began this turn — the gap
+     * between turn submission and the serialized inference callback firing.
+     * Subtract from `durationMs` to isolate execution-only latency.
+     */
+    queueMs?: number;
+    /** `true` when the model was already warm/resident, `false` on a cold load/swap. */
+    resident?: boolean;
+    /** Native finish reason (`stop` / `length` / `tool_calls` / …). */
+    finishReason: string;
+    promptTokens: number;
+    cachedTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    ttftMs?: number;
+    prefillTps?: number;
+    decodeTps?: number;
+    mtpCycles?: number;
+    mtpMeanAccepted?: number;
+    /** Cold-tier restore hits accrued this turn (synchronous counter — exact). */
+    coldHits?: number;
+    /** Cold-tier lookup misses accrued this turn (synchronous counter — exact). */
+    coldMisses?: number;
+    /**
+     * Cold-tier bytes that LANDED this turn — credited natively only after the
+     * payload sync, the commit rename and the directory fsync all succeeded, so
+     * a write that failed contributes nothing here and one {@link
+     * coldWriteErrors} instead.
+     *
+     * Advances on an async writer thread, so this delta is APPROXIMATE — it may
+     * attribute a prior turn's flush to the turn that observes it, and a write
+     * still in flight at the end of the turn lands in a later one. That is the
+     * only sense in which it lags; it is never an enqueue-time estimate.
+     */
+    coldBytesWritten?: number;
+    /** Cold-tier bytes read back on validated hits this turn (synchronous — exact). */
+    coldBytesRestored?: number;
+    /**
+     * Canonical cold-cache root this turn's tier was operating in, as produced by
+     * `canonicalCacheRoot` — the JOIN KEY the dashboard scopes its hit-rate and
+     * trend to. Written ONLY when the tier was actually open; a turn that ran
+     * with the tier off carries `coldEnabled: false` and NO root, and a record
+     * written by a build that predates this field carries neither. Those two
+     * states are deliberately distinguishable: the dashboard reports "recorded
+     * before cache attribution existed" separately from "the tier was off".
+     */
+    coldRoot?: string;
+    /** Whether the cold tier was open for this turn (`ColdCacheStats.enabled`). */
+    coldEnabled?: boolean;
+    /**
+     * Cold-tier write-queue submissions accrued this turn. Incremented on the
+     * calling thread, so this delta is EXACT.
+     */
+    coldEnqueued?: number;
+    /**
+     * Cold-tier writes REFUSED at admission this turn because the bounded queue
+     * was full. Incremented on the calling thread, so this delta is EXACT.
+     *
+     * Now admission refusals only: the commit-rename-failure arm used to be
+     * counted here too, which put one event under a name describing a different
+     * cause. It is a {@link coldWriteErrors} instead, and the two are disjoint —
+     * never sum them.
+     */
+    coldQueueDrops?: number;
+    /**
+     * Cold-tier objects evicted by quota enforcement this turn. Advances on the
+     * background writer thread — APPROXIMATE, same caveat as `coldBytesWritten`.
+     */
+    coldEvictions?: number;
+    /**
+     * Cold-tier objects that failed validation on restore this turn. Incremented
+     * on the calling thread, so this delta is EXACT. Always accompanied by a
+     * miss, i.e. corruptions are a SUBSET of `coldMisses` — never add the two.
+     */
+    coldCorruptions?: number;
+    /**
+     * CUMULATIVE corruptions since the tier opened in this process, not a delta.
+     * Carried because the acceptance bar is "corruptions must be 0" and a delta
+     * alone cannot prove it: a turn that aborts or errors never reaches
+     * `record()`, so a corruption during it lands in no delta at all. The next
+     * successful turn's absolute total still includes it, so `MAX(total) > 0`
+     * over any window is the sound "did this ever happen" latch.
+     */
+    coldCorruptionsTotal?: number;
+    /**
+     * CUMULATIVE queue drops since the tier opened in this process, for the same
+     * reason as {@link coldCorruptionsTotal}: an errored turn's dropped writes
+     * would otherwise be invisible.
+     */
+    coldQueueDropsTotal?: number;
+    /**
+     * Cold-tier writes this turn that the queue ACCEPTED and that never reached
+     * disk — a read-only, full or unmounted cache root, a quota the object
+     * cannot fit, a failed rename, a failed fsync.
+     *
+     * The native writer is deliberately fail-open (a broken cache root must not
+     * change a single emitted token) and it returns its error to nobody, so
+     * before this counter existed the entire class was invisible: a turn against
+     * an unwritable root reported `coldQueueDrops 0`, `coldCorruptions 0`, an
+     * empty stderr and a clean exit. Advances on the background writer thread,
+     * so APPROXIMATE per turn in the same way {@link coldBytesWritten} is —
+     * non-zero over a window is the signal, not the exact attribution.
+     */
+    coldWriteErrors?: number;
+    /**
+     * Restores REFUSED this turn: the tier held candidate blocks and the walk
+     * handed back none of them.
+     *
+     * Neither a hit nor a miss, because both of those count per-block lookups
+     * and a refusal happens instead of one — which is why a refused restore
+     * reported `coldHits 0, coldMisses 0`, exactly the row a turn that never
+     * consulted the tier produces. Incremented on the calling thread, so EXACT.
+     * The reason (`no_backed_boundary`, `parent_chain_unavailable`,
+     * `restore_short_of_boundary`) and the block geometry go to the
+     * `[MLX_TRACE] paged cold_restore_declined` line.
+     */
+    coldRestoreDeclines?: number;
+    /**
+     * CUMULATIVE write errors since the tier opened in this process, for the
+     * same reason as {@link coldCorruptionsTotal} — and more sharply, since this
+     * counter advances on the background writer: the error covering the last
+     * turn before a crash reaches no delta at all.
+     *
+     * No such total exists for {@link coldRestoreDeclines} on purpose. A "did it
+     * ever happen" latch is only meaningful for a counter whose healthy value is
+     * zero; the first turn of any new prompt legitimately declines, so a latch
+     * there would be pinned on from the first minute and mean nothing.
+     */
+    coldWriteErrorsTotal?: number;
+    /**
+     * Turns this turn's process spent reaching a family's sidecar capture. Every
+     * other `coldSidecar*` counter is a sub-count of this one, so `0` here while
+     * blocks were written means the finalize path never called the capture at
+     * all — a different bug from a capture that ran and declined.
+     */
+    coldSidecarCaptureReached?: number;
+    /**
+     * Sidecar captures that found no whole persisted block to anchor recurrent
+     * state under.
+     */
+    coldSidecarChainEmpty?: number;
+    /**
+     * Sidecar captures whose chain covered blocks but where no retained
+     * checkpoint sat at or below its reach — the "ladder collapsed to its
+     * deepest rung" signature.
+     */
+    coldSidecarBoundarySkips?: number;
+    /**
+     * Sidecar captures that selected a boundary already on disk. The STEADY
+     * STATE of a repeated prompt, not a fault: without it a healthy run
+     * (`coldSidecarEnqueued == 0` because the first turn already wrote it) is
+     * indistinguishable from a broken one.
+     */
+    coldSidecarAlreadyPersisted?: number;
+    /**
+     * Sidecars handed to the writer queue this turn. A SUBSET of
+     * {@link coldEnqueued}, which counts every object that took a queue slot —
+     * so summing them double-counts each sidecar.
+     */
+    coldSidecarEnqueued?: number;
+    /**
+     * Sidecars the writer queue refused because it was full. Likewise a subset
+     * of {@link coldQueueDrops}, not a separate population.
+     */
+    coldSidecarQueueDrops?: number;
+    /**
+     * Restored sidecars a family INSTALLED as its live per-turn state. The one
+     * read-side sidecar counter, and the only thing that separates "restored and
+     * used" from "restored, then silently re-derived by a full O(prefix) replay":
+     * the replay produces correct state, so `cachedTokens`, `coldHits`,
+     * `coldCorruptions` and the output text are all identical either way.
+     */
+    coldSidecarInstalled?: number;
+    /**
+     * Restored prefixes a family THREW AWAY this turn, releasing the request and
+     * restarting the turn cold (gemma4's large-sliding-restore suppression).
+     *
+     * A different event from {@link coldRestoreDeclines}: there the walk refused
+     * to serve anything, here it served and the family discarded it. This one is
+     * therefore preceded by real `coldHits` and `coldBytesRestored`, so the turn
+     * reads as successful reuse right up to the point where it recomputes the
+     * whole prompt anyway.
+     */
+    coldSidecarRestoreSuppressed?: number;
+}
+type MetricsTraceInput = Omit<MetricsTraceRecord, 'v'>;
+export declare class MetricsTrace {
+    readonly enabled: boolean;
+    private readonly dir;
+    private readonly now;
+    constructor(opts?: {
+        dir?: string;
+        now?: () => number;
+    });
+    /** `<dir>/<YYYY-MM-DD>-<pid>.jsonl` — UTC date so rotation is timezone-stable. */
+    currentFile(): string;
+    /**
+     * Append one allowlisted JSON line. Never throws: a broken sink must not
+     * surface into the inference path. Excess input properties are dropped — the
+     * record is rebuilt field by field so free text can never reach disk.
+     */
+    record(rec: MetricsTraceInput): void;
+}
+export {};
+//# sourceMappingURL=metrics-trace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-trace.d.ts","sourceRoot":"","sources":["../../src/provider/metrics-trace.ts"],"names":[],"mappings":"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"}