@mlx-node/agent 0.0.8 → 0.0.10

package/dist/provider/metrics-trace.js

@@ -0,0 +1,174 @@
+/**
+ * `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.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { metricsTraceDir } from '../paths.js';
+/**
+ * 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 const COLD_COUNTER_FIELDS = [
+    '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 const COLD_SIDECAR_FIELDS = [
+    'coldSidecarCaptureReached',
+    'coldSidecarChainEmpty',
+    'coldSidecarBoundarySkips',
+    'coldSidecarAlreadyPersisted',
+    'coldSidecarEnqueued',
+    'coldSidecarQueueDrops',
+    'coldSidecarInstalled',
+    'coldSidecarRestoreSuppressed',
+];
+/** Every cold-tier per-turn delta field, in native-struct order. */
+export const COLD_DELTA_FIELDS = [...COLD_COUNTER_FIELDS, ...COLD_SIDECAR_FIELDS];
+function envDisabled() {
+    const raw = process.env.MLX_AGENT_METRICS;
+    if (raw === undefined)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === '0' || normalized === 'false' || normalized === 'off';
+}
+/** A finite number, or `undefined` if the value is absent / non-finite. */
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+export class MetricsTrace {
+    enabled;
+    dir;
+    now;
+    constructor(opts) {
+        this.enabled = !envDisabled();
+        this.dir = opts?.dir ?? metricsTraceDir();
+        this.now = opts?.now ?? Date.now;
+    }
+    /** `<dir>/<YYYY-MM-DD>-<pid>.jsonl` — UTC date so rotation is timezone-stable. */
+    currentFile() {
+        const date = new Date(this.now()).toISOString().slice(0, 10);
+        return join(this.dir, `${date}-${process.pid}.jsonl`);
+    }
+    /**
+     * 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) {
+        if (!this.enabled)
+            return;
+        try {
+            const out = {
+                v: 1,
+                traceId: rec.traceId,
+                ts: rec.ts,
+                model: rec.model,
+                durationMs: rec.durationMs,
+                finishReason: rec.finishReason,
+                promptTokens: rec.promptTokens,
+                cachedTokens: rec.cachedTokens,
+                outputTokens: rec.outputTokens,
+                reasoningTokens: rec.reasoningTokens,
+            };
+            if (rec.sessionId !== undefined)
+                out.sessionId = rec.sessionId;
+            if (rec.rootSessionId !== undefined)
+                out.rootSessionId = rec.rootSessionId;
+            if (rec.rootSessionFile !== undefined)
+                out.rootSessionFile = rec.rootSessionFile;
+            const queueMs = finite(rec.queueMs);
+            if (queueMs !== undefined)
+                out.queueMs = queueMs;
+            if (typeof rec.resident === 'boolean')
+                out.resident = rec.resident;
+            const ttftMs = finite(rec.ttftMs);
+            if (ttftMs !== undefined)
+                out.ttftMs = ttftMs;
+            const prefillTps = finite(rec.prefillTps);
+            if (prefillTps !== undefined)
+                out.prefillTps = prefillTps;
+            const decodeTps = finite(rec.decodeTps);
+            if (decodeTps !== undefined)
+                out.decodeTps = decodeTps;
+            const mtpCycles = finite(rec.mtpCycles);
+            if (mtpCycles !== undefined)
+                out.mtpCycles = mtpCycles;
+            const mtpMeanAccepted = finite(rec.mtpMeanAccepted);
+            if (mtpMeanAccepted !== undefined)
+                out.mtpMeanAccepted = mtpMeanAccepted;
+            // Every cold-tier delta comes off ONE list, so a counter can only be
+            // dropped from the JSONL by being dropped from `COLD_DELTA_FIELDS` —
+            // which `__test__/cold-counter-fields.test.ts` pins to the native structs.
+            // Spelling them out here is what let four `coldCacheStats()` counters sit
+            // unwritten for the life of the feature.
+            for (const key of COLD_DELTA_FIELDS) {
+                const value = finite(rec[key]);
+                if (value !== undefined)
+                    out[key] = value;
+            }
+            // A cache identity is only meaningful for a tier that was actually open;
+            // an empty root would create a bucket no dashboard root can ever match.
+            if (typeof rec.coldRoot === 'string' && rec.coldRoot.length > 0)
+                out.coldRoot = rec.coldRoot;
+            if (typeof rec.coldEnabled === 'boolean')
+                out.coldEnabled = rec.coldEnabled;
+            const coldCorruptionsTotal = finite(rec.coldCorruptionsTotal);
+            if (coldCorruptionsTotal !== undefined)
+                out.coldCorruptionsTotal = coldCorruptionsTotal;
+            const coldQueueDropsTotal = finite(rec.coldQueueDropsTotal);
+            if (coldQueueDropsTotal !== undefined)
+                out.coldQueueDropsTotal = coldQueueDropsTotal;
+            const coldWriteErrorsTotal = finite(rec.coldWriteErrorsTotal);
+            if (coldWriteErrorsTotal !== undefined)
+                out.coldWriteErrorsTotal = coldWriteErrorsTotal;
+            const file = this.currentFile();
+            mkdirSync(dirname(file), { recursive: true });
+            appendFileSync(file, `${JSON.stringify(out)}\n`);
+        }
+        catch {
+            // Telemetry is best-effort; a broken sink must never break inference.
+        }
+    }
+}

package/dist/provider/mlx-identity.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Identity of the single in-process `mlx` provider, shared between the provider
+ * registration ({@link ../provider/index.ts}) and the mlx-only policy adapter
+ * ({@link ./model-registry-filter.ts}) so the two can never drift. In particular
+ * the adapter pins mlx auth to {@link MLX_API_KEY}/{@link MLX_BASE_URL}, which
+ * MUST match what `registerProvider('mlx', …)` sets.
+ */
+/** Reserved provider id for the local mlx provider. */
+export declare const MLX_PROVIDER_ID = "mlx";
+/** Provider `api` tag for local mlx models. */
+export declare const MLX_API = "mlx";
+/** Local (non-network) base URL for the mlx provider. */
+export declare const MLX_BASE_URL = "mlx://local";
+/** Literal marker apiKey — flags the provider configured; never a real key. */
+export declare const MLX_API_KEY = "mlx-local";
+//# sourceMappingURL=mlx-identity.d.ts.map

package/dist/provider/mlx-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mlx-identity.d.ts","sourceRoot":"","sources":["../../src/provider/mlx-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uDAAuD;AACvD,eAAO,MAAM,eAAe,QAAQ,CAAC;AACrC,+CAA+C;AAC/C,eAAO,MAAM,OAAO,QAAQ,CAAC;AAC7B,yDAAyD;AACzD,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAC1C,+EAA+E;AAC/E,eAAO,MAAM,WAAW,cAAc,CAAC"}

package/dist/provider/mlx-identity.js

@@ -0,0 +1,15 @@
+/**
+ * Identity of the single in-process `mlx` provider, shared between the provider
+ * registration ({@link ../provider/index.ts}) and the mlx-only policy adapter
+ * ({@link ./model-registry-filter.ts}) so the two can never drift. In particular
+ * the adapter pins mlx auth to {@link MLX_API_KEY}/{@link MLX_BASE_URL}, which
+ * MUST match what `registerProvider('mlx', …)` sets.
+ */
+/** Reserved provider id for the local mlx provider. */
+export const MLX_PROVIDER_ID = 'mlx';
+/** Provider `api` tag for local mlx models. */
+export const MLX_API = 'mlx';
+/** Local (non-network) base URL for the mlx provider. */
+export const MLX_BASE_URL = 'mlx://local';
+/** Literal marker apiKey — flags the provider configured; never a real key. */
+export const MLX_API_KEY = 'mlx-local';

package/dist/provider/model-host.d.ts

@@ -13,16 +13,43 @@
  * overlapping native activity on the compiled-path globals).
  */
 import { ChatSession, loadModel } from '@mlx-node/lm';
+import { COLD_TIER_RESTORE_FAMILIES } from '../cold-tier.js';
 import type { DiscoveredModelLike } from '../types.js';
+/**
+ * Re-exported so the HOST consults exactly the symbol the drift guard and the
+ * `--no-persist-cache` help text consult. The definition lives in the
+ * native-free `../cold-tier.js` leaf (reachable off-package through the
+ * `@mlx-node/agent/catalog` subpath, which re-exports it)
+ * because this module value-imports `@mlx-node/lm`, which loads the native
+ * addon — the dashboard and the CLI help path must be able to read the list
+ * without that.
+ */
+export { COLD_TIER_RESTORE_FAMILIES };
+/** Per-load policy handed to {@link MlxModelHostOptions.resolveModelPathFn}. */
+export interface ModelLoadPolicy {
+    /**
+     * Authoritative cold-tier directive for the config overlay
+     * (`persist_paged_cache` in the cloned config.json). Present ONLY for loads
+     * of a {@link COLD_TIER_RESTORE_FAMILIES} family, carrying the resolved
+     * {@link MlxModelHostOptions.persistPagedCache} value as an EXPLICIT
+     * boolean: `true` enables the SSD cold tier, `false` authoritatively
+     * disables it — overriding any `persist_paged_cache` the checkpoint's own
+     * config.json hard-codes, so `mlx agent --no-persist-cache` truly wins.
+     * Every other family receives no policy at all, so the overlay never touches
+     * the field for them.
+     */
+    persistPagedCache: boolean;
+}
 export interface MlxModelHostOptions {
     /** Injectable model loader so tests can stub native loading. */
     loadModelFn?: typeof loadModel;
     /**
      * Optional load-path policy. `mlx agent` uses this to point the loader at
      * an ephemeral config overlay with block-paged attention enabled while
-     * leaving the checkpoint directory untouched.
+     * leaving the checkpoint directory untouched. The optional per-load policy
+     * carries the qwen3 cold-tier opt-in (see {@link ModelLoadPolicy}).
      */
-    resolveModelPathFn?: (model: DiscoveredModelLike) => Promise<string>;
+    resolveModelPathFn?: (model: DiscoveredModelLike, policy?: ModelLoadPolicy) => Promise<string>;
     /**
      * Reject a loaded model unless its native paged-cache adapter is active.
      * The agent entrypoint enables this so a model/platform incompatibility
@@ -32,12 +59,21 @@ export interface MlxModelHostOptions {
      * executor is currently flat-cache-only.
      */
     requirePagedCache?: boolean;
+    /**
+     * Enable the cold tier (persisted paged prefix blocks) by default. `mlx
+     * agent` turns this on; `mlx agent --no-persist-cache` sets it false.
+     * Applied only to loads of a {@link COLD_TIER_RESTORE_FAMILIES} family —
+     * every other family keeps per-layer state outside the paged pool, so its
+     * prefix cannot be restored soundly. Defaults true.
+     */
+    persistPagedCache?: boolean;
 }
 export declare class MlxModelHost {
     private readonly byName;
     private readonly loadModelFn;
     private readonly resolveModelPathFn;
     private readonly requirePagedCache;
+    private readonly persistPagedCache;
     private resident;
     private chain;
     constructor(models: DiscoveredModelLike[], opts?: MlxModelHostOptions);
@@ -57,13 +93,19 @@ export declare class MlxModelHost {
      * use the resident session; there is deliberately no method that
      * returns a session outside the serialized section.
      *
+     * `fn` also receives a `resident` boolean: `true` when the turn reused
+     * the already-loaded model (warm — no load happened), `false` when it had
+     * to load or swap the checkpoint first. This is the same warm/cold
+     * distinction the branch below already makes; surfacing it lets a metrics
+     * consumer separate queue wait from cold-load time without another channel.
+     *
      * Swaps drop the old session + model refs BEFORE loading the new
      * checkpoint so GC + native destructors can reclaim the old weights
      * during the load. A load failure leaves no resident (next call
      * retries); a failure thrown by `fn` rejects only this call's promise
      * and keeps the resident loaded for later callers.
      */
-    runWithResident<T>(modelId: string, fn: (session: ChatSession) => Promise<T>): Promise<T>;
+    runWithResident<T>(modelId: string, fn: (session: ChatSession, resident: boolean) => Promise<T>): Promise<T>;
     /**
      * Flag the current resident as post-error so the next turn does a full
      * reset instead of a warm reuse. No-op unless `modelId` is the live

package/dist/provider/model-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-host.d.ts","sourceRoot":"","sources":["../../src/provider/model-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAA4B,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,SAAS,CAAC;IAC/B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAmBD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAkD;IACrF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,KAAK,CAAuC;IAEpD,YAAY,MAAM,EAAE,mBAAmB,EAAE,EAAE,IAAI,GAAE,mBAAwB,EAKxE;IAED,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAE9B;IAED;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAE1D;IAED;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAmCxF;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAIvC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO7C;IAED;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAIxC;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;CAQtB"}
+{"version":3,"file":"model-host.d.ts","sourceRoot":"","sources":["../../src/provider/model-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAA4B,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;;;GAQG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;OAUG;IACH,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,SAAS,CAAC;IAC/B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/F;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAmBD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA4E;IAC/G,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,KAAK,CAAuC;IAEpD,YAAY,MAAM,EAAE,mBAAmB,EAAE,EAAE,IAAI,GAAE,mBAAwB,EAMxE;IAED,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAE9B;IAED;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAE1D;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgD3G;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAIvC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO7C;IAED;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAIxC;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;CAQtB"}

package/dist/provider/model-host.js

@@ -13,11 +13,23 @@
  * overlapping native activity on the compiled-path globals).
  */
 import { ChatSession, loadModel } from '@mlx-node/lm';
+import { COLD_TIER_RESTORE_FAMILIES } from '../cold-tier.js';
+/**
+ * Re-exported so the HOST consults exactly the symbol the drift guard and the
+ * `--no-persist-cache` help text consult. The definition lives in the
+ * native-free `../cold-tier.js` leaf (reachable off-package through the
+ * `@mlx-node/agent/catalog` subpath, which re-exports it)
+ * because this module value-imports `@mlx-node/lm`, which loads the native
+ * addon — the dashboard and the CLI help path must be able to read the list
+ * without that.
+ */
+export { COLD_TIER_RESTORE_FAMILIES };
 export class MlxModelHost {
     byName = new Map();
     loadModelFn;
     resolveModelPathFn;
     requirePagedCache;
+    persistPagedCache;
     resident = null;
     chain = Promise.resolve();
     constructor(models, opts = {}) {
@@ -26,6 +38,7 @@ export class MlxModelHost {
         this.loadModelFn = opts.loadModelFn ?? loadModel;
         this.resolveModelPathFn = opts.resolveModelPathFn ?? (async (model) => model.path);
         this.requirePagedCache = opts.requirePagedCache ?? false;
+        this.persistPagedCache = opts.persistPagedCache ?? true;
     }
     get residentId() {
         return this.resident?.id ?? null;
@@ -47,6 +60,12 @@ export class MlxModelHost {
      * use the resident session; there is deliberately no method that
      * returns a session outside the serialized section.
      *
+     * `fn` also receives a `resident` boolean: `true` when the turn reused
+     * the already-loaded model (warm — no load happened), `false` when it had
+     * to load or swap the checkpoint first. This is the same warm/cold
+     * distinction the branch below already makes; surfacing it lets a metrics
+     * consumer separate queue wait from cold-load time without another channel.
+     *
      * Swaps drop the old session + model refs BEFORE loading the new
      * checkpoint so GC + native destructors can reclaim the old weights
      * during the load. A load failure leaves no resident (next call
@@ -61,12 +80,25 @@ export class MlxModelHost {
         }
         return this.runSerialized(async () => {
             let session;
+            // `true` when this turn reuses the loaded resident (warm), `false` when
+            // it loaded/swapped the checkpoint first (cold).
+            let resident;
             if (this.resident?.id === modelId) {
                 session = this.resident.session;
+                resident = true;
             }
             else {
+                resident = false;
                 this.resident = null;
-                const resolvedPath = await this.resolveModelPathFn(entry);
+                // Only a COLD_TIER_RESTORE_FAMILIES family has a sound paged cold
+                // restore. Hand it an EXPLICIT tri-state directive so the overlay can
+                // authoritatively set the flag either way (default-on, or
+                // `--no-persist-cache` off — overriding any value in the checkpoint's
+                // config.json). Every other family gets no policy at all, so the
+                // overlay never touches the field for them.
+                const resolvedPath = COLD_TIER_RESTORE_FAMILIES.has(entry.modelType)
+                    ? await this.resolveModelPathFn(entry, { persistPagedCache: this.persistPagedCache })
+                    : await this.resolveModelPathFn(entry);
                 const model = await this.loadModelFn(resolvedPath);
                 const sessionModel = model;
                 const gemmaDraftActive = entry.modelType === 'gemma4' && sessionModel.hasMtpWeights?.() === true;
@@ -83,7 +115,7 @@ export class MlxModelHost {
                 session = new ChatSession(sessionModel);
                 this.resident = { id: modelId, session, model, dirty: false };
             }
-            return await fn(session);
+            return await fn(session, resident);
         });
     }
     /**

package/dist/provider/model-registry-filter.d.ts

@@ -1,36 +1,92 @@
 /**
- * Process-local policy adapter for pi's public ModelRegistry.
+ * Process-local policy adapter for pi's canonical `ModelRuntime`.
  *
- * `mlx agent` is an offline/local product, but pi's registry also contains
- * every authenticated built-in cloud provider. CLI `--models mlx/*` only sets
- * the initial selector scope: Tab, `/models`, RPC enumeration, explicit model
- * resolution, and restored sessions still consult the registry's unscoped
- * reads. Filter those reads at their shared boundary before pi constructs its
- * runtime so every path sees only the exact local models this process serves.
+ * `mlx agent` is an offline/local product, but pi's runtime also composes every
+ * built-in cloud provider. CLI `--models mlx/*` only sets the initial selector
+ * scope: Tab, `/models`, RPC enumeration, explicit model resolution, and
+ * restored sessions all read the runtime's unscoped catalog/availability
+ * directly (the `ModelRegistry` facade handed to extensions delegates to the
+ * same runtime). Filter those reads at their shared boundary — the runtime
+ * prototype — so every path sees only the exact local models this process
+ * serves. Patching the runtime (not the extension-only facade) is what keeps
+ * the mlx-only guarantee across the selector / listing / resolution paths.
+ *
+ * The guarantee is an ALLOWLIST across three surfaces, all keyed on the `mlx`
+ * provider id:
+ *  1. Model reads (`getModels`/`getAvailable*`/`getModel`) — exact local-model
+ *     identity (`api === 'mlx' && baseUrl === 'mlx://local'`).
+ *  2. Provider/auth reads (`getProviders`/`getProvider`/`checkAuth`/`getAuth`/
+ *     `isUsingOAuth`/`hasConfiguredAuth`/`listCredentials`/`getProviderAuthStatus`)
+ *     — never surface, report configured, resolve auth for, or enumerate a
+ *     credential of any non-`mlx` provider. `getAuth` is the pivotal one: pi's
+ *     `/login`, `/logout`, and the built-in `/llama` command all resolve auth
+ *     through it, and its OAuth/`LLAMA_BASE_URL` `fetch` consults neither
+ *     `PI_OFFLINE` nor any allow-network flag; returning `undefined` for non-mlx
+ *     makes those commands fail before any network or second-model-host load.
+ *  3. Auth mutation / network (`login` rejected for non-mlx; `refresh` forced to
+ *     `allowNetwork: false` so an explicit `allowNetwork: true` — e.g. pi's
+ *     `update --models` package command — can never override offline mode).
+ *
+ * The `mlx` provider is registered with a literal apiKey and never needs
+ * `/login`; streaming still works because `prepareRequest` calls `getAuth(model)`
+ * with `model.provider === 'mlx'`, which passes through.
+ *
+ * Surfaces 1-3 patch the runtime's PUBLIC facade, but pi's own internals read the
+ * composed provider map `this.models` (pi-ai `ModelsImpl`) directly — a boundary
+ * the facade patches cannot reach (e.g. `refresh` resolving a command-backed
+ * cloud credential). So there is a 4th, structural surface: the `recomposeProvider`
+ * choke composes ONLY `mlx` into `this.models`, making every internal read
+ * mlx-only by construction. It requires installation before the runtime is
+ * constructed (which `runAgent` guarantees).
  *
  * Keep this adapter isolated: once pi exposes a first-class provider allowlist
  * in `MainOptions`, this file can be replaced by that option without touching
  * the provider or CLI layers.
  */
-interface RegistryModel {
+interface RuntimeModel {
     provider: string;
     id: string;
     api: string;
     baseUrl: string;
 }
-export interface FilterableModelRegistry<TModel extends RegistryModel = RegistryModel> {
-    getAll(): TModel[];
-    getAvailable(): TModel[];
-    find(provider: string, modelId: string): TModel | undefined;
-    hasConfiguredAuth(model: TModel): boolean;
+/** Minimal shape of a pi `Provider` — only the id is needed to gate on provider. */
+interface RuntimeProvider {
+    id: string;
+}
+/** Minimal shape of a pi `CredentialInfo` — only the provider id is needed. */
+interface RuntimeCredential {
+    providerId: string;
+}
+/** Minimal shape of a pi `AuthStatus` — only the configured flag is asserted. */
+interface RuntimeAuthStatus {
+    configured: boolean;
+}
+export interface FilterableModelRuntime<TModel extends RuntimeModel = RuntimeModel> {
+    getModels(providerId?: string): readonly TModel[];
+    getAvailableSnapshot(): readonly TModel[];
+    getAvailable(providerId?: string): Promise<readonly TModel[]>;
+    getModel(provider: string, modelId: string): TModel | undefined;
+    getProvider(providerId: string): RuntimeProvider | undefined;
+    hasConfiguredAuth(providerId: string): boolean;
+    checkAuth(providerId: string): Promise<unknown>;
+    isUsingOAuth(providerId: string): boolean;
+    getProviders(): readonly RuntimeProvider[];
+    listCredentials(): Promise<readonly RuntimeCredential[]>;
+    getProviderAuthStatus(providerId: string): RuntimeAuthStatus;
+    login(providerId: string, type: unknown, interaction: unknown): Promise<unknown>;
+    refresh(options?: {
+        allowNetwork?: boolean;
+        force?: boolean;
+        signal?: unknown;
+    }): Promise<unknown>;
 }
-export interface FilterableModelRegistryConstructor<TModel extends RegistryModel = RegistryModel> {
-    prototype: FilterableModelRegistry<TModel>;
+export interface FilterableModelRuntimeConstructor<TModel extends RuntimeModel = RuntimeModel> {
+    prototype: FilterableModelRuntime<TModel>;
 }
 /**
- * Install an exact local-model read policy for one `runAgent()` lifetime.
- * Returns an idempotent restore callback.
+ * Install an exact local-model / mlx-only-provider policy for one `runAgent()`
+ * lifetime. Returns an idempotent restore callback.
  */
-export declare function installMlxOnlyModelRegistryFilter<TModel extends RegistryModel>(Registry: FilterableModelRegistryConstructor<TModel>, modelIds: Iterable<string>): () => void;
+export declare function installMlxOnlyModelRegistryFilter<TModel extends RuntimeModel>(Runtime: FilterableModelRuntimeConstructor<TModel>, modelIds: Iterable<string>): () => void;
 export {};
 //# sourceMappingURL=model-registry-filter.d.ts.map

package/dist/provider/model-registry-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-registry-filter.d.ts","sourceRoot":"","sources":["../../src/provider/model-registry-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB,CAAC,MAAM,SAAS,aAAa,GAAG,aAAa;IACnF,MAAM,IAAI,MAAM,EAAE,CAAC;IACnB,YAAY,IAAI,MAAM,EAAE,CAAC;IACzB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5D,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3C;AAED,MAAM,WAAW,kCAAkC,CAAC,MAAM,SAAS,aAAa,GAAG,aAAa;IAC9F,SAAS,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAC;CAC5C;AAcD;;;GAGG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,SAAS,aAAa,EAC5E,QAAQ,EAAE,kCAAkC,CAAC,MAAM,CAAC,EACpD,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GACzB,MAAM,IAAI,CA0DZ"}
+{"version":3,"file":"model-registry-filter.d.ts","sourceRoot":"","sources":["../../src/provider/model-registry-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oFAAoF;AACpF,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,+EAA+E;AAC/E,UAAU,iBAAiB;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iFAAiF;AACjF,UAAU,iBAAiB;IACzB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IAChF,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAClD,oBAAoB,IAAI,SAAS,MAAM,EAAE,CAAC;IAC1C,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAChE,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAC7D,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/C,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1C,YAAY,IAAI,SAAS,eAAe,EAAE,CAAC;IAC3C,eAAe,IAAI,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;IACzD,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAAC;IAC7D,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpG;AAED,MAAM,WAAW,iCAAiC,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IAC3F,SAAS,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;CAC3C;AAqCD;;;GAGG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,SAAS,YAAY,EAC3E,OAAO,EAAE,iCAAiC,CAAC,MAAM,CAAC,EAClD,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GACzB,MAAM,IAAI,CA2MZ"}