@mlx-node/agent 0.0.10 → 0.0.12

package/dist/catalog.d.ts

@@ -1,41 +1,103 @@
 /**
  * Curated model catalog for `mlx agent`.
  *
- * The first-run download wizard (Task 8) offers `visibleCatalog()` and
- * feeds the chosen `hfRepo` to `mlx download model`. Slugs are settled
- * with the user and verified against the Brooooooklyn HF account —
- * use them verbatim.
+ * The first-run download wizard offers `visibleCatalog()` and feeds the chosen
+ * entry's `catalogRepo()` to `mlx download model`. Slugs are verified against the Brooooooklyn
+ * HF account — use them verbatim.
  */
 export interface CatalogEntry {
     /** Wizard display name. */
     label: string;
-    /** HF slug for `mlx download model`. */
+    /** HF slug for `mlx download model` on Apple Silicon — the MXFP4 build. */
     hfRepo: string;
+    /**
+     * HF slug on Linux + NVIDIA CUDA — the NVFP4 build.
+     *
+     * Absent means the entry has no CUDA-specific build and {@link hfRepo}
+     * serves both. Resolve with {@link catalogRepo}, never by reading the field.
+     */
+    hfRepoCuda?: string;
     /** Approximate download size in GB, for display. */
     sizeGb: number;
     /** One line for the wizard. */
     description: string;
     /** Exactly one entry carries this. */
     isDefault?: boolean;
-    /** Not offered by the wizard (repo not yet published). */
+    /**
+     * The repo is not published yet, so no UI may offer it as a download.
+     *
+     * Two consumers honour this: the agent wizard via {@link visibleCatalog},
+     * and the dashboard Models page, which filters `!item.hidden` before
+     * rendering cards (`packages/dashboard/ui/src/pages/models.tsx`).
+     * `catalogWithState()` deliberately keeps hidden entries so the UI, not the
+     * dashboard core, decides.
+     *
+     * Also honoured by the download allowlist: `DownloadManager.start`
+     * (`packages/dashboard/src/download.ts`) refuses a hidden repo up front
+     * rather than allocating a job that fails mid-download with a 401 from
+     * Hugging Face. No UI reaches that path for a hidden entry, but a direct
+     * API call does.
+     */
     hidden?: boolean;
 }
 export declare const MODEL_CATALOG: readonly CatalogEntry[];
+/**
+ * The repo THIS platform installs for `entry`. Linux is the CUDA preview
+ * target (README "Platform Support"); everything else is Apple Silicon.
+ *
+ * NOT because Metal cannot run NVFP4 — it can. MLX ships the same 234
+ * quantized Metal kernels for `nvfp4` as for `mxfp4`, NAX variants included,
+ * and only `fp8_e4m3` reconstructs BF16 at load. The MSL 4.1 hardware
+ * block-scale format (`metal_fp8_ue8m0_format`) appears nowhere in MLX's Metal
+ * backend, so it constrains neither format here.
+ *
+ * The split is:
+ * - CUDA takes NVFP4 through `CublasQQMM` (`nvfp4` -> `CUDA_R_4F_E2M1`), a
+ *   native path with no MXFP4 equivalent.
+ * - Metal has no such native-path advantage either way, so prefer the format
+ *   that survives quantization better. NVFP4 stores a block scale as `amax/6`
+ *   in E4M3, and real FFN blocks land in its subnormal band;
+ *   `apply_nvfp4_pow2_lift` repairs that for dense SwiGLU FFNs but SKIPS MoE
+ *   experts by design (`NVFP4_LIFT_MOE_MARKERS`, `crates/mlx-core/src/
+ *   convert.rs`), because the norm there also drives the router and the
+ *   shared-expert gate, neither scale-invariant. Two of the three visible
+ *   entries are MoE. MXFP4's E8M0 block scales have no such failure.
+ *
+ * Unmeasured: whether nvfp4 or mxfp4 decodes faster on Metal. The choice above
+ * is made on quantization quality, not throughput.
+ *
+ * Every consumer that turns a catalog entry into a download, a slug, or an
+ * allowlist check must go through here. Reading `entry.hfRepo` directly
+ * installs the macOS build on a CUDA box.
+ */
+export declare function catalogRepo(entry: CatalogEntry): string;
+/**
+ * {@link catalogRepo} with the platform passed in — the pure half.
+ *
+ * Exists so both branches can be asserted without touching `process.platform`.
+ * Mutating that global leaks across test files sharing a worker: it made
+ * `catalogRepo` disagree with a sibling suite's module-level constant and fail
+ * a download allowlist check that has nothing to do with the catalog.
+ */
+export declare function catalogRepoFor(entry: CatalogEntry, platform: NodeJS.Platform): string;
 /** Catalog entries the wizard offers (hidden entries filtered out). */
 export declare function visibleCatalog(): CatalogEntry[];
 /**
- * Cold-tier facts, re-exported through this subpath.
+ * Cold-tier facts and family registration data, re-exported through this
+ * subpath.
  *
  * `@mlx-node/agent/catalog` is the agent package's one NATIVE-FREE entry point:
  * the package root re-exports `provider/index.ts`, which value-imports
  * `@mlx-node/core`. The dashboard is a separate viewer process that must never
  * link the addon (docs/dashboard.md: "no Metal init, instant start"), and
  * `mlx agent --help` must print without loading weights — so both reach the
- * cold-tier allowlist and the cache-root canonicalizer through here.
+ * cold-tier allowlist, the cache-root canonicalizer, and the family detection
+ * data through here.
  *
- * These are RE-EXPORTS. The definitions live in `./cold-tier.ts` and there is
- * exactly one of each; `packages/agent/__test__/cold-tier-families.test.ts`
- * guards the allowlist against the native side.
+ * Every module reachable from here must therefore stay free of runtime addon
+ * imports. `packages/agent/__test__/catalog-native-free.test.ts` gates that in a
+ * real subprocess.
  */
 export { COLD_TIER_RESTORE_FAMILIES, canonicalCacheRoot, coldTierRestoreFamilyList } from './cold-tier.js';
+export { CHAT_FAMILY_IDS, matchFamily, NON_GENERATIVE_FAMILY_IDS, rawModelTypeToCanonical, } from '@mlx-node/lm/family-data';
 //# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EA+BhD,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,YAAY,EAAE,CAE/C;AAED;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EA0DhD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,CAErF;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,YAAY,EAAE,CAE/C;AAED;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3G,OAAO,EACL,eAAe,EACf,WAAW,EACX,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC"}

package/dist/catalog.js

@@ -1,29 +1,31 @@
 /**
  * Curated model catalog for `mlx agent`.
  *
- * The first-run download wizard (Task 8) offers `visibleCatalog()` and
- * feeds the chosen `hfRepo` to `mlx download model`. Slugs are settled
- * with the user and verified against the Brooooooklyn HF account —
- * use them verbatim.
+ * The first-run download wizard offers `visibleCatalog()` and feeds the chosen
+ * entry's `catalogRepo()` to `mlx download model`. Slugs are verified against the Brooooooklyn
+ * HF account — use them verbatim.
  */
 export const MODEL_CATALOG = [
     {
-        label: 'Qwen3.6-27B',
-        hfRepo: 'Brooooooklyn/Qwen3.6-27B-NVFP4-mlx',
-        sizeGb: 22.2,
+        label: 'Qwen3.8-27B',
+        hfRepo: 'Brooooooklyn/Qwen3.8-27B-MXFP4-mlx',
+        hfRepoCuda: 'Brooooooklyn/Qwen3.8-27B-NVFP4-mlx',
+        sizeGb: 23.3,
         description: 'Best tool use — recommended default',
         isDefault: true,
     },
     {
         label: 'Qwen-AgentWorld-35B',
-        hfRepo: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-nvfp4-mlx',
-        sizeGb: 22.7,
+        hfRepo: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-mxfp4-mlx',
+        hfRepoCuda: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-nvfp4-mlx',
+        sizeGb: 23.3,
         description: 'Agent-tuned MoE, fast decode',
     },
     {
         label: 'Gemma-4-26B-A4B',
-        hfRepo: 'Brooooooklyn/Gemma-4-26B-A4B-NVFP4-mlx',
-        sizeGb: 18.8,
+        hfRepo: 'Brooooooklyn/Gemma-4-26B-A4B-Unsloth-MXFP4-mlx',
+        hfRepoCuda: 'Brooooooklyn/Gemma-4-26B-A4B-Unsloth-NVFP4-mlx',
+        sizeGb: 16.2,
         description: 'MoE, fast decode',
     },
     {
@@ -37,23 +39,93 @@ export const MODEL_CATALOG = [
         description: 'Compact (mxfp4 MLP + mxfp8 attention), fits smaller machines',
         hidden: true,
     },
+    {
+        // NOT DOWNLOADABLE. This repo does not exist: the slug below is a
+        // placeholder the user has not uploaded to, and Hugging Face answers 401
+        // for it. Nothing may offer it as an install until the upload happens and
+        // `hidden` is dropped — and do not guess a substitute slug, because a
+        // wrong-but-live repo would install the wrong weights silently.
+        //
+        // The only route to this model today is local conversion from NVIDIA's
+        // modelopt checkpoint:
+        //   mlx convert -m nemotron_h \
+        //     -i <nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4> \
+        //     -o <models>/nemotron-3.5-lightning-30b-a3b-nvfp4-mlx
+        // (NVFP4 preserved byte-for-byte; the FP8 Mamba-2 projections are
+        // re-quantized. See docs/cli.md "modelopt NVFP4 ingest".)
+        //
+        // The entry is kept — rather than deleted — so the wizard, the dashboard
+        // catalog state, and `catalogSlug()` recognize a locally converted
+        // checkpoint sitting at the canonical slug.
+        label: 'Nemotron-3.5-Lightning-30B-A3B',
+        hfRepo: 'Brooooooklyn/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-nvfp4-mlx',
+        sizeGb: 23,
+        description: 'Hybrid Mamba-2 + MoE, native MTP, 1M context',
+        hidden: true,
+    },
 ];
+/**
+ * The repo THIS platform installs for `entry`. Linux is the CUDA preview
+ * target (README "Platform Support"); everything else is Apple Silicon.
+ *
+ * NOT because Metal cannot run NVFP4 — it can. MLX ships the same 234
+ * quantized Metal kernels for `nvfp4` as for `mxfp4`, NAX variants included,
+ * and only `fp8_e4m3` reconstructs BF16 at load. The MSL 4.1 hardware
+ * block-scale format (`metal_fp8_ue8m0_format`) appears nowhere in MLX's Metal
+ * backend, so it constrains neither format here.
+ *
+ * The split is:
+ * - CUDA takes NVFP4 through `CublasQQMM` (`nvfp4` -> `CUDA_R_4F_E2M1`), a
+ *   native path with no MXFP4 equivalent.
+ * - Metal has no such native-path advantage either way, so prefer the format
+ *   that survives quantization better. NVFP4 stores a block scale as `amax/6`
+ *   in E4M3, and real FFN blocks land in its subnormal band;
+ *   `apply_nvfp4_pow2_lift` repairs that for dense SwiGLU FFNs but SKIPS MoE
+ *   experts by design (`NVFP4_LIFT_MOE_MARKERS`, `crates/mlx-core/src/
+ *   convert.rs`), because the norm there also drives the router and the
+ *   shared-expert gate, neither scale-invariant. Two of the three visible
+ *   entries are MoE. MXFP4's E8M0 block scales have no such failure.
+ *
+ * Unmeasured: whether nvfp4 or mxfp4 decodes faster on Metal. The choice above
+ * is made on quantization quality, not throughput.
+ *
+ * Every consumer that turns a catalog entry into a download, a slug, or an
+ * allowlist check must go through here. Reading `entry.hfRepo` directly
+ * installs the macOS build on a CUDA box.
+ */
+export function catalogRepo(entry) {
+    return catalogRepoFor(entry, process.platform);
+}
+/**
+ * {@link catalogRepo} with the platform passed in — the pure half.
+ *
+ * Exists so both branches can be asserted without touching `process.platform`.
+ * Mutating that global leaks across test files sharing a worker: it made
+ * `catalogRepo` disagree with a sibling suite's module-level constant and fail
+ * a download allowlist check that has nothing to do with the catalog.
+ */
+export function catalogRepoFor(entry, platform) {
+    return platform === 'linux' && entry.hfRepoCuda !== undefined ? entry.hfRepoCuda : entry.hfRepo;
+}
 /** Catalog entries the wizard offers (hidden entries filtered out). */
 export function visibleCatalog() {
     return MODEL_CATALOG.filter((entry) => !entry.hidden);
 }
 /**
- * Cold-tier facts, re-exported through this subpath.
+ * Cold-tier facts and family registration data, re-exported through this
+ * subpath.
  *
  * `@mlx-node/agent/catalog` is the agent package's one NATIVE-FREE entry point:
  * the package root re-exports `provider/index.ts`, which value-imports
  * `@mlx-node/core`. The dashboard is a separate viewer process that must never
  * link the addon (docs/dashboard.md: "no Metal init, instant start"), and
  * `mlx agent --help` must print without loading weights — so both reach the
- * cold-tier allowlist and the cache-root canonicalizer through here.
+ * cold-tier allowlist, the cache-root canonicalizer, and the family detection
+ * data through here.
  *
- * These are RE-EXPORTS. The definitions live in `./cold-tier.ts` and there is
- * exactly one of each; `packages/agent/__test__/cold-tier-families.test.ts`
- * guards the allowlist against the native side.
+ * Every module reachable from here must therefore stay free of runtime addon
+ * imports. `packages/agent/__test__/catalog-native-free.test.ts` gates that in a
+ * real subprocess.
  */
 export { COLD_TIER_RESTORE_FAMILIES, canonicalCacheRoot, coldTierRestoreFamilyList } from './cold-tier.js';
+export { CHAT_FAMILY_IDS, matchFamily, NON_GENERATIVE_FAMILY_IDS, rawModelTypeToCanonical, } from '@mlx-node/lm/family-data';

package/dist/cold-tier.d.ts

@@ -31,10 +31,11 @@
  *
  *  - `qwen3` (dense) sizes its pool over all layers, so the pool holds the
  *    complete KV for the prefix and needs no sidecar.
- *  - `gemma4` sizes its pool over the full-attention layers only, but persists
- *    its out-of-pool sliding-window `RotatingKVCache` state as a
- *    `ColdGroup::SlidingWindow` sidecar, and its `ColdSidecarPolicy` makes the
- *    native restore walk refuse any boundary a validated sidecar does not back.
+ *  - `gemma4` owns full and sliding attention in distinct paged groups. The
+ *    full-attention chain is authoritative and one grouped sliding sidecar
+ *    restores every sliding group at the same exact boundary, atomically.
+ *  - `muse_glimmer` uses the same hybrid contract for its 13 full-attention
+ *    and 39 sliding-attention layers.
  *  - `qwen3_5` (dense) sizes its pool over the full-attention layers only, but
  *    persists its out-of-pool GDN recurrent state (conv + recurrent) as a
  *    `ColdGroup::GdnState` sidecar, and its `ColdSidecarPolicy` reconciles the
@@ -43,13 +44,12 @@
  *  - `qwen3_5_moe` keeps the SAME GDN recurrent state outside the pool — same
  *    shapes, same dtype, same layer mapping — so it shares the dense family's
  *    sidecar codec and `ColdSidecarPolicy` verbatim. Its restart-parity gate has
- *    since been run on `Qwen3.6-35b-a3b-UD-Q2_K_XL-mlx`: the restore reconciled
+ *    since been run on `Qwen3.6-35B-A3B-mxfp4-mlx`: the restore reconciled
  *    onto ladder rung 304 of `[16, 64, 304, 1248]` with `hits=42` and
  *    `corruptions=0`, and the text matched a no-persist baseline.
- *  - `lfm2` / `lfm2_moe` keep short-conv state outside the pool with no
- *    serialization path for it at all, AND drive the uniform native adapter
- *    API whose restore branch is already wired to the tier — asking for
- *    persistence on their behalf would restore an incomplete prefix silently.
+ *  - `lfm2` / `lfm2_moe` keep ShortConv state outside the full-attention pool.
+ *    A `ColdGroup::ConvState` sidecar persists that state at the same exact
+ *    boundary; missing or malformed state reconciles down or restarts at zero.
  *
  * Widening this set is a correctness decision, never a perf one, and it is
  * authorized by exactly one thing: the family's native restart-parity gate

package/dist/cold-tier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cold-tier.d.ts","sourceRoot":"","sources":["../src/cold-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAKzD,CAAC;AAEH,qFAAqF;AACrF,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBvD"}
+{"version":3,"file":"cold-tier.d.ts","sourceRoot":"","sources":["../src/cold-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAQzD,CAAC;AAEH,qFAAqF;AACrF,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBvD"}

package/dist/cold-tier.js

@@ -34,10 +34,11 @@ import { basename, dirname, join, resolve } from 'node:path';
  *
  *  - `qwen3` (dense) sizes its pool over all layers, so the pool holds the
  *    complete KV for the prefix and needs no sidecar.
- *  - `gemma4` sizes its pool over the full-attention layers only, but persists
- *    its out-of-pool sliding-window `RotatingKVCache` state as a
- *    `ColdGroup::SlidingWindow` sidecar, and its `ColdSidecarPolicy` makes the
- *    native restore walk refuse any boundary a validated sidecar does not back.
+ *  - `gemma4` owns full and sliding attention in distinct paged groups. The
+ *    full-attention chain is authoritative and one grouped sliding sidecar
+ *    restores every sliding group at the same exact boundary, atomically.
+ *  - `muse_glimmer` uses the same hybrid contract for its 13 full-attention
+ *    and 39 sliding-attention layers.
  *  - `qwen3_5` (dense) sizes its pool over the full-attention layers only, but
  *    persists its out-of-pool GDN recurrent state (conv + recurrent) as a
  *    `ColdGroup::GdnState` sidecar, and its `ColdSidecarPolicy` reconciles the
@@ -46,13 +47,12 @@ import { basename, dirname, join, resolve } from 'node:path';
  *  - `qwen3_5_moe` keeps the SAME GDN recurrent state outside the pool — same
  *    shapes, same dtype, same layer mapping — so it shares the dense family's
  *    sidecar codec and `ColdSidecarPolicy` verbatim. Its restart-parity gate has
- *    since been run on `Qwen3.6-35b-a3b-UD-Q2_K_XL-mlx`: the restore reconciled
+ *    since been run on `Qwen3.6-35B-A3B-mxfp4-mlx`: the restore reconciled
  *    onto ladder rung 304 of `[16, 64, 304, 1248]` with `hits=42` and
  *    `corruptions=0`, and the text matched a no-persist baseline.
- *  - `lfm2` / `lfm2_moe` keep short-conv state outside the pool with no
- *    serialization path for it at all, AND drive the uniform native adapter
- *    API whose restore branch is already wired to the tier — asking for
- *    persistence on their behalf would restore an incomplete prefix silently.
+ *  - `lfm2` / `lfm2_moe` keep ShortConv state outside the full-attention pool.
+ *    A `ColdGroup::ConvState` sidecar persists that state at the same exact
+ *    boundary; missing or malformed state reconciles down or restarts at zero.
  *
  * Widening this set is a correctness decision, never a perf one, and it is
  * authorized by exactly one thing: the family's native restart-parity gate
@@ -69,10 +69,13 @@ import { basename, dirname, join, resolve } from 'node:path';
  * and asserted by `packages/cli/__test__/agent-cmd.test.ts`.
  */
 export const COLD_TIER_RESTORE_FAMILIES = new Set([
-    'gemma4',
     'qwen3',
     'qwen3_5',
     'qwen3_5_moe',
+    'gemma4',
+    'muse_glimmer',
+    'lfm2',
+    'lfm2_moe',
 ]);
 /** Allowlisted families in a stable, human-facing order (help text, API payload). */
 export function coldTierRestoreFamilyList() {
@@ -83,19 +86,6 @@ export function coldTierRestoreFamilyList() {
  * prefix that is part of a longer name (`~cache`) is left alone — only the
  * shell's own two spellings are expanded.
  */
-/**
- * `realpath(3)` rather than Node's JS walk.
- *
- * On a case-insensitive volume — APFS's default, i.e. essentially every Mac —
- * `MLX_COLD_CACHE_DIR=~/CacheDir` and `~/cachedir` name the SAME directory, but
- * `fs.realpathSync` hands back whichever spelling the caller typed. Two join
- * keys for one cache is the F1 symptom inverted: a populated disk scan sitting
- * beside a flat 0/0 trend. `realpathSync.native` folds each existing component
- * to its on-disk spelling, so both env spellings produce one key.
- */
-function realpathNative(path) {
-    return realpathSync.native(path);
-}
 function expandTilde(path) {
     if (path === '~')
         return homedir();
@@ -139,7 +129,12 @@ export function canonicalCacheRoot(root) {
     let cursor = absolute;
     for (;;) {
         try {
-            const resolved = realpathNative(cursor);
+            // `realpathSync.native` (realpath(3)), not Node's JS walk: on a
+            // case-insensitive volume — APFS's default — `~/CacheDir` and `~/cachedir`
+            // name the SAME directory, but `fs.realpathSync` returns whichever spelling
+            // the caller typed. `.native` folds each existing component to its on-disk
+            // spelling, so both env spellings produce one join key.
+            const resolved = realpathSync.native(cursor);
             return missing.length === 0 ? resolved : join(resolved, ...missing);
         }
         catch {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { DiscoveredModelLike } from './types.js';
-export { type CatalogEntry, MODEL_CATALOG, visibleCatalog } from './catalog.js';
+export { type CatalogEntry, catalogRepo, catalogRepoFor, MODEL_CATALOG, visibleCatalog } from './catalog.js';
 export { createPermissionGateExtension } from './extensions/permission-gate.js';
 export { createSubagentExtension, discoverSubagents, normalizeSubagentMode, type InProcessSubagentSession, type SubagentConfig, type SubagentExtensionOptions, type SubagentMode, type SubagentSessionCreateOptions, } from './extensions/subagent.js';
 export { createTerminalTitleExtension } from './extensions/terminal-title.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,KAAK,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EACjB,KAAK,4BAA4B,GAClC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,KAAK,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7G,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EACjB,KAAK,4BAA4B,GAClC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { MODEL_CATALOG, visibleCatalog } from './catalog.js';
+export { catalogRepo, catalogRepoFor, MODEL_CATALOG, visibleCatalog } from './catalog.js';
 export { createPermissionGateExtension } from './extensions/permission-gate.js';
 export { createSubagentExtension, discoverSubagents, normalizeSubagentMode, } from './extensions/subagent.js';
 export { createTerminalTitleExtension } from './extensions/terminal-title.js';

package/dist/provider/chat-config.d.ts

@@ -1,23 +1,11 @@
 /**
  * Per-call `ChatConfig` assembly for the provider bridge.
  *
- * Base sampling + output budget come from `@mlx-node/server`'s
- * `LAUNCH_PRESETS` (the ONLY allowed server import in this package —
- * presets/preset types, nothing else) extended by the agent-local
- * {@link AGENT_LAUNCH_PRESETS}, then pi's per-call `SimpleStreamOptions`
- * overlay on top.
+ * Base sampling + output budget come from the family-data launch preset
+ * (`@mlx-node/lm`), then pi's per-call `SimpleStreamOptions` overlay on top.
  */
 import type { SimpleStreamOptions, ThinkingLevel } from '@earendil-works/pi-ai';
-import type { ChatConfig, ModelType, ToolDefinition } from '@mlx-node/lm';
-import { type LaunchPreset } from '@mlx-node/server';
-/**
- * Preset lookup — agent-local entries win over `LAUNCH_PRESETS` (they
- * exist precisely because the server table has no correct entry for the
- * type). This is the ONE preset resolution shared by discovery
- * (`models.ts`) and per-call config assembly, so a model can never be
- * discovered without also being streamable (and vice versa).
- */
-export declare function launchPresetFor(modelType: ModelType): LaunchPreset | undefined;
+import { type ChatConfig, type ModelType, type ToolDefinition } from '@mlx-node/lm';
 export interface ResolvedReasoningMode {
     reasoningEffort: 'none' | 'low' | 'medium' | 'high';
     /** The `enable_thinking` value implied by `reasoningEffort` for templates. */

package/dist/provider/chat-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-config.d.ts","sourceRoot":"","sources":["../../src/provider/chat-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0BrE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAE9E;AAgBD,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,GAAG,qBAAqB,CAMhG;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,KAAK,EAAE,cAAc,EAAE,GAAG,SAAS,EACnC,gBAAgB,CAAC,EAAE,MAAM,EACzB,iBAAiB,wBAA2C,EAC5D,cAAc,CAAC,EAAE,OAAO,GACvB,UAAU,CAsCZ"}
+{"version":3,"file":"chat-config.d.ts","sourceRoot":"","sources":["../../src/provider/chat-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAGL,KAAK,UAAU,EAEf,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AA8BtB,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,GAAG,qBAAqB,CAMhG;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,KAAK,EAAE,cAAc,EAAE,GAAG,SAAS,EACnC,gBAAgB,CAAC,EAAE,MAAM,EACzB,iBAAiB,wBAA2C,EAC5D,cAAc,CAAC,EAAE,OAAO,GACvB,UAAU,CAsCZ"}

package/dist/provider/chat-config.js

@@ -1,46 +1,23 @@
 /**
  * Per-call `ChatConfig` assembly for the provider bridge.
  *
- * Base sampling + output budget come from `@mlx-node/server`'s
- * `LAUNCH_PRESETS` (the ONLY allowed server import in this package —
- * presets/preset types, nothing else) extended by the agent-local
- * {@link AGENT_LAUNCH_PRESETS}, then pi's per-call `SimpleStreamOptions`
- * overlay on top.
+ * Base sampling + output budget come from the family-data launch preset
+ * (`@mlx-node/lm`), then pi's per-call `SimpleStreamOptions` overlay on top.
  */
-import { LAUNCH_PRESETS } from '@mlx-node/server';
+import { launchPresetFor, MODEL_FAMILY_DATA, } from '@mlx-node/lm';
 /**
- * Agent-local launch presets for model types `LAUNCH_PRESETS` does not
- * cover (kept here — this package must not fork `packages/server`).
- *
- * `lfm2_moe` (LFM2.5-8B-A1B): LiquidAI's HF model card for the MoE
- * checkpoint recommends temperature 0.2 / top_k 80 — deliberately NOT
- * the dense `lfm2` preset (LFM2.5-1.2B guidance: temperature 0.05 /
- * top_k 50). repetitionPenalty 1.05 and the 8192-token output budget
- * match the dense family entry.
+ * Model types the no-preset error names: trainable rows, then loadable rows,
+ * each in registry order. Pinned byte-exactly by
+ * `packages/agent/__test__/chat-config.test.ts`.
  */
-const AGENT_LAUNCH_PRESETS = {
-    lfm2_moe: {
-        sampling: {
-            temperature: 0.2,
-            topP: 1.0,
-            topK: 80,
-            minP: 0.0,
-            presencePenalty: 0.0,
-            repetitionPenalty: 1.05,
-        },
-        maxOutputTokens: 8192,
-    },
-};
-/**
- * Preset lookup — agent-local entries win over `LAUNCH_PRESETS` (they
- * exist precisely because the server table has no correct entry for the
- * type). This is the ONE preset resolution shared by discovery
- * (`models.ts`) and per-call config assembly, so a model can never be
- * discovered without also being streamable (and vice versa).
- */
-export function launchPresetFor(modelType) {
-    return AGENT_LAUNCH_PRESETS[modelType] ?? LAUNCH_PRESETS[modelType];
-}
+const KNOWN_PRESET_MODEL_TYPES = (() => {
+    const rows = MODEL_FAMILY_DATA;
+    const chatRows = rows.filter((row) => row.kind === 'trainable' || row.kind === 'loadable');
+    return [
+        ...chatRows.filter((row) => row.kind === 'trainable'),
+        ...chatRows.filter((row) => row.kind === 'loadable'),
+    ].map((row) => row.id);
+})();
 /**
  * pi thinking level → native `reasoningEffort`. pi never delivers 'off'
  * here (the agent loop converts it to `undefined` before the provider
@@ -73,7 +50,7 @@ export function resolveReasoningMode(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(', ');
+        const known = KNOWN_PRESET_MODEL_TYPES.join(', ');
         throw new Error(`buildChatConfig: no launch preset for model type "${modelType}" (known types: ${known})`);
     }
     const config = {

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,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"}
+{"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,CAuD3G;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

@@ -99,7 +99,13 @@ export class MlxModelHost {
                 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);
+                // Preserve the ordinary one-argument call for unpaired checkpoints.
+                // A discovered DFlash2 companion is an explicit load option rather
+                // than a second advertised model: target and draft become one
+                // resident session and the native loader validates their compatibility.
+                const model = entry.draftModelPath === undefined
+                    ? await this.loadModelFn(resolvedPath)
+                    : await this.loadModelFn(resolvedPath, { draftModelPath: entry.draftModelPath });
                 const sessionModel = model;
                 const gemmaDraftActive = entry.modelType === 'gemma4' && sessionModel.hasMtpWeights?.() === true;
                 if (this.requirePagedCache && sessionModel.hasBlockPagedCache?.() !== true && !gemmaDraftActive) {

package/dist/provider/models.d.ts

@@ -1,18 +1,19 @@
 /**
  * Local model discovery for the mlx pi provider.
  *
- * Ports the discovery walk from `@mlx-node/server/host`
- * (`packages/server/src/host/discover.ts`; that copy stays untouched) and
- * pairs every discovered checkpoint with a pi `ProviderModelConfig` entry
- * ready for `pi.registerProvider('mlx', { models })`.
+ * The same discovery walk as `@mlx-node/server/host`
+ * (`packages/server/src/host/discover.ts`), pairing every discovered checkpoint
+ * with a pi `ProviderModelConfig` entry ready for
+ * `pi.registerProvider('mlx', { models })`.
  *
  * `contextWindow` starts as the checkpoint's trained window, read from the model dir's
  * `config.json` `max_position_embeddings` (root first, then the
  * `text_config` nesting used by qwen3_5 / qwen3_5_moe / gemma4 unified
- * checkpoints). Once a Qwen model loads, the provider narrows this shared
- * model metadata to the physical paged-cache window so pi's later
- * auto-compaction thresholds match reality. When both config fields are
- * absent the documented per-family fallback below applies.
+ * checkpoints). Once a Qwen or Muse-Glimmer model loads, the provider narrows
+ * this shared model metadata to the physical paged-cache window so pi's later
+ * auto-compaction thresholds match reality. When both config fields are absent
+ * the per-family fallback documented on `FamilyTraits` (`@mlx-node/lm`
+ * family-data) applies.
  */
 import type { ProviderModelConfig } from '@earendil-works/pi-coding-agent';
 import type { DiscoveredModelLike } from '../types.js';
@@ -22,13 +23,16 @@ export interface MlxModelInfo {
     piModel: ProviderModelConfig;
 }
 /**
- * Scan `modelsDir` for chat-capable model subdirectories and build their
- * pi provider entries. Same tolerance as the cli discover walk: an
- * unreadable dir yields `[]`; entries with an undetectable config, a
- * non-generative type, or no launch preset are skipped silently
- * (warnings only when `MLX_DEBUG` is set). Cheap by contract — no
- * weights are loaded here. Results are sorted by directory name, which
- * becomes both the pi model `id` and display `name`.
+ * Scan `modelsDir` for chat-capable model subdirectories and native dense
+ * Qwen3.5/Qwen3.8 `Q<number>_K_XL.gguf` files, then build their pi provider
+ * entries. XL files may live directly under `modelsDir` or one level inside a
+ * downloaded GGUF repository. Each is registered by filename stem so multiple
+ * quant variants in one repository remain independently selectable.
+ *
+ * Same tolerance as the cli discover walk: an unreadable dir yields `[]`;
+ * entries with an undetectable config, a non-generative type, or no launch
+ * preset are skipped silently (warnings only when `MLX_DEBUG` is set). Cheap
+ * by contract — no weights are loaded here. Results are sorted by model name.
  */
 export declare function discoverMlxModels(modelsDir: string): Promise<MlxModelInfo[]>;
 //# sourceMappingURL=models.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/provider/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAG3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,mBAAmB,CAAC;IAChC,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAmHD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAuDlF"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/provider/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAS3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,mBAAmB,CAAC;IAChC,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAyHD;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsIlF"}

package/dist/provider/models.js

@@ -1,49 +1,70 @@
 /**
  * Local model discovery for the mlx pi provider.
  *
- * Ports the discovery walk from `@mlx-node/server/host`
- * (`packages/server/src/host/discover.ts`; that copy stays untouched) and
- * pairs every discovered checkpoint with a pi `ProviderModelConfig` entry
- * ready for `pi.registerProvider('mlx', { models })`.
+ * The same discovery walk as `@mlx-node/server/host`
+ * (`packages/server/src/host/discover.ts`), pairing every discovered checkpoint
+ * with a pi `ProviderModelConfig` entry ready for
+ * `pi.registerProvider('mlx', { models })`.
  *
  * `contextWindow` starts as the checkpoint's trained window, read from the model dir's
  * `config.json` `max_position_embeddings` (root first, then the
  * `text_config` nesting used by qwen3_5 / qwen3_5_moe / gemma4 unified
- * checkpoints). Once a Qwen model loads, the provider narrows this shared
- * model metadata to the physical paged-cache window so pi's later
- * auto-compaction thresholds match reality. When both config fields are
- * absent the documented per-family fallback below applies.
+ * checkpoints). Once a Qwen or Muse-Glimmer model loads, the provider narrows
+ * this shared model metadata to the physical paged-cache window so pi's later
+ * auto-compaction thresholds match reality. When both config fields are absent
+ * the per-family fallback documented on `FamilyTraits` (`@mlx-node/lm`
+ * family-data) applies.
  */
 import { readdir, readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { detectModelType } from '@mlx-node/lm';
-import { launchPresetFor } from './chat-config.js';
-// Non-generative detection results that cannot back a chat endpoint
-// (mirrors the cli discover walk).
-const NON_GENERATIVE = new Set(['harrier', 'qianfan-ocr', 'internvl_chat']);
+import { launchPresetFor, detectModelType, familyTraitsFor, NON_GENERATIVE_FAMILY_IDS, } from '@mlx-node/lm';
 /**
- * Keyed by `ModelType`: a chat-capable family must have BOTH an entry
- * here and a launch preset via `launchPresetFor` (which serves `lfm2_moe`
- * from the agent-local MoE preset) to be served — missing either side is
- * skipped, never guessed.
+ * Native direct-GGUF loading currently exists for dense Qwen3.5/Qwen3.8.
+ * Match the Unsloth Dynamic XL target names users download, while excluding
+ * ordinary Q4_K_M files and companion artifacts such as imatrix/mmproj/draft.
  */
-const FAMILY_TRAITS = {
-    qwen3: { reasoning: true, fallbackContextWindow: 40960 },
-    qwen3_5: { reasoning: true, fallbackContextWindow: 262144 },
-    qwen3_5_moe: { reasoning: true, fallbackContextWindow: 262144 },
-    gemma4: {
-        reasoning: true,
-        thinkingLevelMap: {
-            minimal: 'minimal',
-            low: null,
-            medium: null,
-            high: 'high',
-        },
-        fallbackContextWindow: 131072,
-    },
-    lfm2: { reasoning: true, fallbackContextWindow: 128000 },
-    lfm2_moe: { reasoning: true, fallbackContextWindow: 128000 },
-};
+const QWEN35_XL_GGUF = /(?:^|[-_.])Q\d+_K_XL\.gguf$/i;
+const GGUF_COMPANION_NAME = /(?:^|[-_.])(?:imatrix|mmproj|dflash|draft)(?:[-_.]|$)/i;
+function isQwen35XlGguf(name) {
+    return QWEN35_XL_GGUF.test(name) && !GGUF_COMPANION_NAME.test(name);
+}
+function ggufModelName(name) {
+    return name.slice(0, -'.gguf'.length);
+}
+/**
+ * Agent-local convention for pairing a dense Qwen3.5/Qwen3.8 target with an
+ * external DFlash2 checkpoint. mlx-vlm accepts an explicit `--draft-model`
+ * path and does not define a combined directory layout; the agent needs a
+ * deterministic relationship it can discover without another CLI flag.
+ */
+async function embeddedDFlash2Path(modelDir) {
+    const draftPath = join(modelDir, 'draft');
+    try {
+        const raw = await readFile(join(draftPath, 'config.json'), 'utf-8');
+        const config = JSON.parse(raw);
+        return Array.isArray(config.architectures) && config.architectures.includes('DFlash2DraftModel')
+            ? draftPath
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function modelFileInventory(modelDir) {
+    try {
+        const files = (await readdir(modelDir, { withFileTypes: true }))
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name);
+        return {
+            xlGgufs: files.filter(isQwen35XlGguf).sort(),
+            hasGguf: files.some((name) => name.toLowerCase().endsWith('.gguf')),
+            hasSafetensors: files.some((name) => name.toLowerCase().endsWith('.safetensors')),
+        };
+    }
+    catch {
+        return { xlGgufs: [], hasGguf: false, hasSafetensors: false };
+    }
+}
 function positiveInteger(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
 }
@@ -82,23 +103,28 @@ async function readDiscoveryMetadata(modelPath, modelType, fallbackContextWindow
         const supportsImages = modelType === 'gemma4'
             ? hasVisionConfig || nonEmptyRecord(config.unified_vision_config)
             : (modelType === 'qwen3_5' || modelType === 'qwen3_5_moe') && hasVisionConfig;
+        const draftOnly = Array.isArray(config.architectures) && config.architectures.includes('DFlash2DraftModel');
         return {
             contextWindow: root ?? nested ?? fallbackContextWindow,
             supportsImages,
+            draftOnly,
         };
     }
     catch {
-        return { contextWindow: fallbackContextWindow, supportsImages: false };
+        return { contextWindow: fallbackContextWindow, supportsImages: false, draftOnly: false };
     }
 }
 /**
- * Scan `modelsDir` for chat-capable model subdirectories and build their
- * pi provider entries. Same tolerance as the cli discover walk: an
- * unreadable dir yields `[]`; entries with an undetectable config, a
- * non-generative type, or no launch preset are skipped silently
- * (warnings only when `MLX_DEBUG` is set). Cheap by contract — no
- * weights are loaded here. Results are sorted by directory name, which
- * becomes both the pi model `id` and display `name`.
+ * Scan `modelsDir` for chat-capable model subdirectories and native dense
+ * Qwen3.5/Qwen3.8 `Q<number>_K_XL.gguf` files, then build their pi provider
+ * entries. XL files may live directly under `modelsDir` or one level inside a
+ * downloaded GGUF repository. Each is registered by filename stem so multiple
+ * quant variants in one repository remain independently selectable.
+ *
+ * Same tolerance as the cli discover walk: an unreadable dir yields `[]`;
+ * entries with an undetectable config, a non-generative type, or no launch
+ * preset are skipped silently (warnings only when `MLX_DEBUG` is set). Cheap
+ * by contract — no weights are loaded here. Results are sorted by model name.
  */
 export async function discoverMlxModels(modelsDir) {
     const debug = Boolean(process.env.MLX_DEBUG);
@@ -109,8 +135,84 @@ export async function discoverMlxModels(modelsDir) {
     catch {
         return [];
     }
+    // Collision resolution below gives the first occurrence the bare filename
+    // stem. Directory enumeration order is unspecified, so sort before assigning
+    // IDs to keep persisted `mlx/<id>` selections stable across filesystems.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     const out = [];
+    const usedNames = new Set();
+    const append = async (preferredName, path, metadataRoot, modelType, scopeName, draftModelPath) => {
+        if (NON_GENERATIVE_FAMILY_IDS.has(modelType))
+            return;
+        // Fail-closed guards: dead-by-construction for chat families (the
+        // family-data row type requires traits + a preset), live for any foreign
+        // string that slips through detection.
+        const preset = launchPresetFor(modelType);
+        if (!preset) {
+            if (debug)
+                console.warn(`[mlx] skip ${path}: no launch preset for ${modelType}`);
+            return;
+        }
+        const traits = familyTraitsFor(modelType);
+        if (!traits) {
+            if (debug)
+                console.warn(`[mlx] skip ${path}: no FAMILY_TRAITS entry for ${modelType}`);
+            return;
+        }
+        const metadata = await readDiscoveryMetadata(metadataRoot, modelType, traits.fallbackContextWindow);
+        if (metadata.draftOnly) {
+            if (debug)
+                console.warn(`[mlx] skip ${path}: companion draft checkpoint is not a chat model`);
+            return;
+        }
+        let name = preferredName;
+        if (usedNames.has(name)) {
+            name = `${scopeName}-${preferredName}`;
+            let suffix = 2;
+            while (usedNames.has(name))
+                name = `${scopeName}-${preferredName}-${suffix++}`;
+        }
+        usedNames.add(name);
+        const discovered = {
+            name,
+            path,
+            modelType,
+            ...(draftModelPath === undefined ? {} : { draftModelPath }),
+        };
+        out.push({
+            discovered,
+            piModel: {
+                id: name,
+                name,
+                reasoning: traits.reasoning,
+                // The structural FamilyThinkingLevelMap must stay assignable to the
+                // pi type (pi types are agent-only, so family-data cannot name it).
+                thinkingLevelMap: traits.thinkingLevelMap,
+                input: metadata.supportsImages ? ['text', 'image'] : ['text'],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                contextWindow: metadata.contextWindow,
+                maxTokens: preset.maxOutputTokens,
+            },
+        });
+    };
     for (const entry of entries) {
+        if (entry.isFile() && isQwen35XlGguf(entry.name)) {
+            const full = join(modelsDir, entry.name);
+            try {
+                const modelType = await detectModelType(full);
+                if (modelType === 'qwen3_5') {
+                    await append(ggufModelName(entry.name), full, modelsDir, modelType, basename(modelsDir));
+                }
+                else if (debug) {
+                    console.warn(`[mlx] skip ${full}: direct XL GGUF loading is not supported for ${modelType}`);
+                }
+            }
+            catch (err) {
+                if (debug)
+                    console.warn(`[mlx] skip ${full}: ${err.message}`);
+            }
+            continue;
+        }
         if (!entry.isDirectory())
             continue;
         const full = join(modelsDir, entry.name);
@@ -123,35 +225,32 @@ export async function discoverMlxModels(modelsDir) {
                 console.warn(`[mlx] skip ${full}: ${err.message}`);
             continue;
         }
-        if (NON_GENERATIVE.has(modelType))
-            continue;
-        const preset = launchPresetFor(modelType);
-        if (!preset) {
-            if (debug)
-                console.warn(`[mlx] skip ${full}: no launch preset for ${modelType}`);
+        const inventory = await modelFileInventory(full);
+        const { xlGgufs } = inventory;
+        if (xlGgufs.length > 0) {
+            if (modelType !== 'qwen3_5') {
+                if (debug) {
+                    console.warn(`[mlx] skip ${full}: direct XL GGUF loading is not supported for ${modelType}`);
+                }
+                continue;
+            }
+            const draftModelPath = await embeddedDFlash2Path(full);
+            for (const gguf of xlGgufs) {
+                await append(ggufModelName(gguf), join(full, gguf), full, modelType, entry.name, draftModelPath);
+            }
             continue;
         }
-        const traits = FAMILY_TRAITS[modelType];
-        if (!traits) {
+        // A raw GGUF repository is not itself a loadable model path. Only the
+        // selected native Qwen3.5 XL files above may be handed directly to the
+        // loader. Keep converted model directories discoverable when they retain
+        // an imatrix/source GGUF beside their actual SafeTensors weights.
+        if (inventory.hasGguf && !inventory.hasSafetensors) {
             if (debug)
-                console.warn(`[mlx] skip ${full}: no FAMILY_TRAITS entry for ${modelType}`);
+                console.warn(`[mlx] skip ${full}: no supported direct GGUF target`);
             continue;
         }
-        const name = basename(full);
-        const { contextWindow, supportsImages } = await readDiscoveryMetadata(full, modelType, traits.fallbackContextWindow);
-        out.push({
-            discovered: { name, path: full, modelType },
-            piModel: {
-                id: name,
-                name,
-                reasoning: traits.reasoning,
-                thinkingLevelMap: traits.thinkingLevelMap,
-                input: supportsImages ? ['text', 'image'] : ['text'],
-                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-                contextWindow,
-                maxTokens: preset.maxOutputTokens,
-            },
-        });
+        const draftModelPath = modelType === 'qwen3_5' ? await embeddedDFlash2Path(full) : undefined;
+        await append(basename(full), full, full, modelType, entry.name, draftModelPath);
     }
     out.sort((a, b) => (a.discovered.name < b.discovered.name ? -1 : a.discovered.name > b.discovered.name ? 1 : 0));
     return out;

package/dist/types.d.ts

@@ -4,5 +4,7 @@ export interface DiscoveredModelLike {
     name: string;
     path: string;
     modelType: ModelType;
+    /** Optional external speculative drafter paired with this target checkpoint. */
+    draftModelPath?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC;IACrB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlx-node/agent",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "homepage": "https://github.com/mlx-node/mlx-node",
   "bugs": {
     "url": "https://github.com/mlx-node/mlx-node/issues"
@@ -31,15 +31,15 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "0.81.1",
-    "@earendil-works/pi-coding-agent": "0.81.1",
-    "@mlx-node/core": "0.0.10",
-    "@mlx-node/lm": "0.0.10",
-    "@mlx-node/server": "0.0.10",
-    "typebox": "1.3.6"
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@mlx-node/core": "0.0.12",
+    "@mlx-node/lm": "0.0.12",
+    "@mlx-node/server": "0.0.12",
+    "typebox": "1.3.23"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0"
+    "@types/node": "^26.4.0"
   },
   "engines": {
     "node": ">=22.19.0"