@mlx-node/agent 0.0.7

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

@@ -0,0 +1,94 @@
+/**
+ * `MlxModelHost` — single-resident, lazily-loaded model + `ChatSession`
+ * owner for the provider bridge.
+ *
+ * Mirrors the CLI launch-claude swap semantics (drop-then-load, one
+ * serialized operation chain) without the registry/alias machinery: the
+ * agent process serves exactly one model at a time, and every operation
+ * that touches the resident runs on one promise chain. Crucially the
+ * resident check/load AND the caller's full inference callback execute
+ * inside the SAME serialized closure ({@link MlxModelHost.runWithResident}),
+ * so a queued swap to another model can never replace the resident while
+ * an earlier caller is still mid-turn on it (stale session handle,
+ * overlapping native activity on the compiled-path globals).
+ */
+import { ChatSession, loadModel } from '@mlx-node/lm';
+import type { DiscoveredModelLike } from '../types.js';
+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.
+     */
+    resolveModelPathFn?: (model: DiscoveredModelLike) => Promise<string>;
+    /**
+     * Reject a loaded model unless its native paged-cache adapter is active.
+     * The agent entrypoint enables this so a model/platform incompatibility
+     * fails clearly instead of silently falling back to flat KV cache. Gemma4
+     * with an attached external draft is the deliberate exception used only by
+     * the agent's explicit draft opt-in: its DSpark / assistant speculative
+     * executor is currently flat-cache-only.
+     */
+    requirePagedCache?: boolean;
+}
+export declare class MlxModelHost {
+    private readonly byName;
+    private readonly loadModelFn;
+    private readonly resolveModelPathFn;
+    private readonly requirePagedCache;
+    private resident;
+    private chain;
+    constructor(models: DiscoveredModelLike[], opts?: MlxModelHostOptions);
+    get residentId(): string | null;
+    /**
+     * Read-only lookup of the discovery record behind `modelId` (name, path,
+     * `ModelType`). Pure map read — never touches the serialized chain or
+     * the resident. The stream adapter uses it to pick the launch preset
+     * for the model it is about to run.
+     */
+    modelInfo(modelId: string): DiscoveredModelLike | undefined;
+    /**
+     * Make `modelId` resident (loading or swapping on demand) and run `fn`
+     * against its `ChatSession` — both inside one serialized closure, so no
+     * other queued operation (in particular a swap to a different model)
+     * can touch the resident until `fn` settles. This is the ONLY way to
+     * use the resident session; there is deliberately no method that
+     * returns a session outside the serialized section.
+     *
+     * 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>;
+    /**
+     * 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
+     * resident (a load failure or a swap already dropped/replaced it, and a
+     * reloaded model starts with a clean cache).
+     */
+    markResidentDirty(modelId: string): void;
+    /**
+     * Read-and-clear the resident's post-error `dirty` flag. Returns `true`
+     * only when `modelId` is the live resident AND it was dirty — the signal
+     * for the caller to run a full `session.reset()` this turn instead of the
+     * warm-reuse wipe.
+     */
+    consumeResidentDirty(modelId: string): boolean;
+    /**
+     * Drop the current resident so the next `runWithResident` reloads it from
+     * scratch. Used when a post-error full reset itself fails and the session
+     * can no longer be trusted. No-op unless `modelId` is the live resident.
+     */
+    invalidateResident(modelId: string): void;
+    /**
+     * Run `fn` after every previously queued operation completes. The
+     * chain advances regardless of `fn`'s outcome — a rejection reaches
+     * only this call's returned promise, never later queued operations.
+     */
+    private runSerialized;
+}
+//# sourceMappingURL=model-host.d.ts.map

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

@@ -0,0 +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"}

package/dist/provider/model-host.js

@@ -0,0 +1,134 @@
+/**
+ * `MlxModelHost` — single-resident, lazily-loaded model + `ChatSession`
+ * owner for the provider bridge.
+ *
+ * Mirrors the CLI launch-claude swap semantics (drop-then-load, one
+ * serialized operation chain) without the registry/alias machinery: the
+ * agent process serves exactly one model at a time, and every operation
+ * that touches the resident runs on one promise chain. Crucially the
+ * resident check/load AND the caller's full inference callback execute
+ * inside the SAME serialized closure ({@link MlxModelHost.runWithResident}),
+ * so a queued swap to another model can never replace the resident while
+ * an earlier caller is still mid-turn on it (stale session handle,
+ * overlapping native activity on the compiled-path globals).
+ */
+import { ChatSession, loadModel } from '@mlx-node/lm';
+export class MlxModelHost {
+    byName = new Map();
+    loadModelFn;
+    resolveModelPathFn;
+    requirePagedCache;
+    resident = null;
+    chain = Promise.resolve();
+    constructor(models, opts = {}) {
+        for (const model of models)
+            this.byName.set(model.name, model);
+        this.loadModelFn = opts.loadModelFn ?? loadModel;
+        this.resolveModelPathFn = opts.resolveModelPathFn ?? (async (model) => model.path);
+        this.requirePagedCache = opts.requirePagedCache ?? false;
+    }
+    get residentId() {
+        return this.resident?.id ?? null;
+    }
+    /**
+     * Read-only lookup of the discovery record behind `modelId` (name, path,
+     * `ModelType`). Pure map read — never touches the serialized chain or
+     * the resident. The stream adapter uses it to pick the launch preset
+     * for the model it is about to run.
+     */
+    modelInfo(modelId) {
+        return this.byName.get(modelId);
+    }
+    /**
+     * Make `modelId` resident (loading or swapping on demand) and run `fn`
+     * against its `ChatSession` — both inside one serialized closure, so no
+     * other queued operation (in particular a swap to a different model)
+     * can touch the resident until `fn` settles. This is the ONLY way to
+     * use the resident session; there is deliberately no method that
+     * returns a session outside the serialized section.
+     *
+     * 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(modelId, fn) {
+        const entry = this.byName.get(modelId);
+        if (!entry) {
+            const known = [...this.byName.keys()].join(', ');
+            return Promise.reject(new Error(`MlxModelHost: unknown model "${modelId}" (known models: ${known})`));
+        }
+        return this.runSerialized(async () => {
+            let session;
+            if (this.resident?.id === modelId) {
+                session = this.resident.session;
+            }
+            else {
+                this.resident = null;
+                const resolvedPath = await this.resolveModelPathFn(entry);
+                const model = await this.loadModelFn(resolvedPath);
+                const sessionModel = model;
+                const gemmaDraftActive = entry.modelType === 'gemma4' && sessionModel.hasMtpWeights?.() === true;
+                if (this.requirePagedCache && sessionModel.hasBlockPagedCache?.() !== true && !gemmaDraftActive) {
+                    throw new Error(`MlxModelHost: model "${modelId}" (${entry.modelType}) loaded without an active ` +
+                        `PagedAttention cache; this checkpoint, quantization, or platform is not compatible ` +
+                        `with the mlx agent paged-cache requirement`);
+                }
+                if (this.requirePagedCache && entry.modelType === 'qwen3_5_moe' && sessionModel.hasMtpWeights?.() === true) {
+                    throw new Error(`MlxModelHost: model "${modelId}" has Qwen3.5 MoE MTP weights, but the native MoE ` +
+                        `backend cannot combine MTP with PagedAttention yet; refusing to silently downgrade ` +
+                        `this agent session to paged autoregressive decoding`);
+                }
+                session = new ChatSession(sessionModel);
+                this.resident = { id: modelId, session, model, dirty: false };
+            }
+            return await fn(session);
+        });
+    }
+    /**
+     * 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
+     * resident (a load failure or a swap already dropped/replaced it, and a
+     * reloaded model starts with a clean cache).
+     */
+    markResidentDirty(modelId) {
+        if (this.resident?.id === modelId) {
+            this.resident.dirty = true;
+        }
+    }
+    /**
+     * Read-and-clear the resident's post-error `dirty` flag. Returns `true`
+     * only when `modelId` is the live resident AND it was dirty — the signal
+     * for the caller to run a full `session.reset()` this turn instead of the
+     * warm-reuse wipe.
+     */
+    consumeResidentDirty(modelId) {
+        if (this.resident?.id !== modelId) {
+            return false;
+        }
+        const wasDirty = this.resident.dirty;
+        this.resident.dirty = false;
+        return wasDirty;
+    }
+    /**
+     * Drop the current resident so the next `runWithResident` reloads it from
+     * scratch. Used when a post-error full reset itself fails and the session
+     * can no longer be trusted. No-op unless `modelId` is the live resident.
+     */
+    invalidateResident(modelId) {
+        if (this.resident?.id === modelId) {
+            this.resident = null;
+        }
+    }
+    /**
+     * Run `fn` after every previously queued operation completes. The
+     * chain advances regardless of `fn`'s outcome — a rejection reaches
+     * only this call's returned promise, never later queued operations.
+     */
+    runSerialized(fn) {
+        const result = this.chain.then(fn);
+        this.chain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Process-local policy adapter for pi's public ModelRegistry.
+ *
+ * `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.
+ *
+ * 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 {
+    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;
+}
+export interface FilterableModelRegistryConstructor<TModel extends RegistryModel = RegistryModel> {
+    prototype: FilterableModelRegistry<TModel>;
+}
+/**
+ * Install an exact local-model read 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 {};
+//# sourceMappingURL=model-registry-filter.d.ts.map

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

@@ -0,0 +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"}

package/dist/provider/model-registry-filter.js

@@ -0,0 +1,82 @@
+/**
+ * Process-local policy adapter for pi's public ModelRegistry.
+ *
+ * `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.
+ *
+ * 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.
+ */
+const activePrototypes = new WeakSet();
+function requireMethodDescriptor(prototype, name) {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+    if (!descriptor || typeof descriptor.value !== 'function' || descriptor.writable !== true) {
+        throw new Error(`mlx agent: incompatible pi ModelRegistry.${name}; expected a writable prototype method`);
+    }
+    return descriptor;
+}
+/**
+ * Install an exact local-model read policy for one `runAgent()` lifetime.
+ * Returns an idempotent restore callback.
+ */
+export function installMlxOnlyModelRegistryFilter(Registry, modelIds) {
+    const prototype = Registry.prototype;
+    if (activePrototypes.has(prototype)) {
+        throw new Error('mlx agent: concurrent ModelRegistry filtering in one process is not supported');
+    }
+    const allowedIds = new Set(modelIds);
+    const isAllowed = (model) => model.provider === 'mlx' && allowedIds.has(model.id) && model.api === 'mlx' && model.baseUrl === 'mlx://local';
+    const descriptors = {
+        getAll: requireMethodDescriptor(prototype, 'getAll'),
+        getAvailable: requireMethodDescriptor(prototype, 'getAvailable'),
+        find: requireMethodDescriptor(prototype, 'find'),
+        hasConfiguredAuth: requireMethodDescriptor(prototype, 'hasConfiguredAuth'),
+    };
+    const getAll = descriptors.getAll.value;
+    const getAvailable = descriptors.getAvailable.value;
+    const find = descriptors.find.value;
+    const hasConfiguredAuth = descriptors.hasConfiguredAuth.value;
+    Object.defineProperties(prototype, {
+        getAll: {
+            ...descriptors.getAll,
+            value() {
+                return getAll.call(this).filter(isAllowed);
+            },
+        },
+        getAvailable: {
+            ...descriptors.getAvailable,
+            value() {
+                return getAvailable.call(this).filter(isAllowed);
+            },
+        },
+        find: {
+            ...descriptors.find,
+            value(provider, modelId) {
+                if (provider !== 'mlx' || !allowedIds.has(modelId))
+                    return undefined;
+                const model = find.call(this, provider, modelId);
+                return model && isAllowed(model) ? model : undefined;
+            },
+        },
+        hasConfiguredAuth: {
+            ...descriptors.hasConfiguredAuth,
+            value(model) {
+                return isAllowed(model) && hasConfiguredAuth.call(this, model);
+            },
+        },
+    });
+    activePrototypes.add(prototype);
+    let restored = false;
+    return () => {
+        if (restored)
+            return;
+        Object.defineProperties(prototype, descriptors);
+        activePrototypes.delete(prototype);
+        restored = true;
+    };
+}

package/dist/provider/models.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Local model discovery for the mlx pi provider.
+ *
+ * Ports the discovery walk from
+ * `packages/cli/src/commands/launch-claude/discover.ts` (which is bin-only
+ * and must not be imported from here; the cli copy stays untouched) and
+ * pairs 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.
+ */
+import type { ProviderModelConfig } from '@earendil-works/pi-coding-agent';
+import type { DiscoveredModelLike } from '../types.js';
+/** A discovered local checkpoint paired with its pi provider model entry. */
+export interface MlxModelInfo {
+    discovered: DiscoveredModelLike;
+    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`.
+ */
+export declare function discoverMlxModels(modelsDir: string): Promise<MlxModelInfo[]>;
+//# sourceMappingURL=models.d.ts.map

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

@@ -0,0 +1 @@
+{"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;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;AAmED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsDlF"}

package/dist/provider/models.js

@@ -0,0 +1,132 @@
+/**
+ * Local model discovery for the mlx pi provider.
+ *
+ * Ports the discovery walk from
+ * `packages/cli/src/commands/launch-claude/discover.ts` (which is bin-only
+ * and must not be imported from here; the cli copy stays untouched) and
+ * pairs 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.
+ */
+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']);
+/**
+ * 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.
+ */
+const FAMILY_TRAITS = {
+    qwen3: { reasoning: true, fallbackContextWindow: 40960 },
+    qwen3_5: { reasoning: true, fallbackContextWindow: 262144 },
+    qwen3_5_moe: { reasoning: true, fallbackContextWindow: 262144 },
+    gemma4: { reasoning: false, fallbackContextWindow: 131072 },
+    lfm2: { reasoning: true, fallbackContextWindow: 128000 },
+    lfm2_moe: { reasoning: true, fallbackContextWindow: 128000 },
+};
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+/**
+ * Read the trained context window from `<modelPath>/config.json`:
+ * root `max_position_embeddings` first (qwen3, lfm2), then
+ * `text_config.max_position_embeddings` (qwen3_5, qwen3_5_moe, gemma4
+ * unified), else the family fallback. `detectModelType` already parsed
+ * this file, so a read/parse failure here (e.g. a racing rewrite) lands
+ * on the fallback instead of dropping the model.
+ */
+async function readContextWindow(modelPath, fallback) {
+    try {
+        const raw = await readFile(join(modelPath, 'config.json'), 'utf-8');
+        const config = JSON.parse(raw);
+        const root = positiveInteger(config.max_position_embeddings);
+        if (root !== undefined)
+            return root;
+        const textConfig = config.text_config;
+        if (typeof textConfig === 'object' && textConfig !== null && !Array.isArray(textConfig)) {
+            const nested = positiveInteger(textConfig.max_position_embeddings);
+            if (nested !== undefined)
+                return nested;
+        }
+    }
+    catch {
+        // fall through to the family fallback
+    }
+    return fallback;
+}
+/**
+ * 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`.
+ */
+export async function discoverMlxModels(modelsDir) {
+    const debug = Boolean(process.env.MLX_DEBUG);
+    let entries;
+    try {
+        entries = await readdir(modelsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const full = join(modelsDir, entry.name);
+        let modelType;
+        try {
+            modelType = await detectModelType(full);
+        }
+        catch (err) {
+            if (debug)
+                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}`);
+            continue;
+        }
+        const traits = FAMILY_TRAITS[modelType];
+        if (!traits) {
+            if (debug)
+                console.warn(`[mlx] skip ${full}: no FAMILY_TRAITS entry for ${modelType}`);
+            continue;
+        }
+        const name = basename(full);
+        const contextWindow = await readContextWindow(full, traits.fallbackContextWindow);
+        out.push({
+            discovered: { name, path: full, modelType },
+            piModel: {
+                id: name,
+                name,
+                reasoning: traits.reasoning,
+                input: ['text'],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                contextWindow,
+                maxTokens: preset.maxOutputTokens,
+            },
+        });
+    }
+    out.sort((a, b) => (a.discovered.name < b.discovered.name ? -1 : a.discovered.name > b.discovered.name ? 1 : 0));
+    return out;
+}

package/dist/provider/performance-status.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Transient per-message inference telemetry for the interactive agent footer.
+ *
+ * Pi's `Usage` object drives token accounting and compaction, so native
+ * throughput must not be smuggled into it. The exact AssistantMessage object
+ * is delivered to extension `message_end` handlers before persistence; a
+ * provider-scoped WeakMap therefore carries the metrics to the TUI without
+ * changing the conversation schema or retaining completed messages.
+ */
+import type { AssistantMessage } from '@earendil-works/pi-ai';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { PerformanceMetrics } from '@mlx-node/lm';
+interface MessageEndLike {
+    message: {
+        role: string;
+    };
+}
+export declare class PerformanceStatus {
+    private readonly byMessage;
+    /** Record only complete, displayable samples; malformed native metrics are ignored. */
+    readonly record: (message: AssistantMessage, performance: PerformanceMetrics) => void;
+    /** Render the successful mlx inference associated with this exact Pi message. */
+    showMessage(event: MessageEndLike, ctx: ExtensionContext): void;
+    /** Prevent the selected model's completed sample lingering after its lifecycle ends. */
+    clear(ctx: ExtensionContext): void;
+}
+export {};
+//# sourceMappingURL=performance-status.d.ts.map

package/dist/provider/performance-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-status.d.ts","sourceRoot":"","sources":["../../src/provider/performance-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAYvD,UAAU,cAAc;IACtB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3B;AAqDD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqD;IAE/E,uFAAuF;IACvF,QAAQ,CAAC,MAAM,YAAa,gBAAgB,eAAe,kBAAkB,KAAG,IAAI,CAclF;IAEF,iFAAiF;IACjF,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAK9D;IAED,wFAAwF;IACxF,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAEjC;CACF"}

package/dist/provider/performance-status.js

@@ -0,0 +1,91 @@
+/**
+ * Transient per-message inference telemetry for the interactive agent footer.
+ *
+ * Pi's `Usage` object drives token accounting and compaction, so native
+ * throughput must not be smuggled into it. The exact AssistantMessage object
+ * is delivered to extension `message_end` handlers before persistence; a
+ * provider-scoped WeakMap therefore carries the metrics to the TUI without
+ * changing the conversation schema or retaining completed messages.
+ */
+const STATUS_KEY = 'mlx-performance';
+function finiteRate(value) {
+    return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function finiteTokenCount(value) {
+    return value !== undefined && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function formatRate(value) {
+    return value.toLocaleString('en-US', {
+        minimumFractionDigits: 1,
+        maximumFractionDigits: 1,
+    });
+}
+function formatDuration(ttftMs) {
+    if (ttftMs < 1000)
+        return `${formatRate(ttftMs)} ms`;
+    return `${(ttftMs / 1000).toLocaleString('en-US', {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    })} s`;
+}
+function formatTokenCount(value) {
+    if (value < 1000)
+        return value.toLocaleString('en-US');
+    const [divisor, suffix] = value < 1_000_000 ? [1000, 'k'] : [1_000_000, 'm'];
+    return `${(value / divisor).toLocaleString('en-US', { maximumFractionDigits: 1 })}${suffix}`;
+}
+function formatContext(sample) {
+    let context = '';
+    if (sample.ttftMs !== undefined)
+        context += ` · TTFT ${formatDuration(sample.ttftMs)}`;
+    if (sample.inputTokens !== undefined && sample.cachedTokens !== undefined) {
+        if (sample.cachedTokens > 0) {
+            context +=
+                ` · input ${formatTokenCount(sample.inputTokens)} new` + ` + ${formatTokenCount(sample.cachedTokens)} cached`;
+        }
+        else {
+            context += ` · input ${formatTokenCount(sample.inputTokens)}`;
+        }
+    }
+    return context;
+}
+function formatSample(sample) {
+    return (`mlx${formatContext(sample)}` +
+        ` · prefill ${formatRate(sample.prefillTokensPerSecond)} tok/s` +
+        ` · decode ${formatRate(sample.decodeTokensPerSecond)} tok/s`);
+}
+export class PerformanceStatus {
+    byMessage = new WeakMap();
+    /** Record only complete, displayable samples; malformed native metrics are ignored. */
+    record = (message, performance) => {
+        const prefillTokensPerSecond = finiteRate(performance.prefillTokensPerSecond);
+        const decodeTokensPerSecond = finiteRate(performance.decodeTokensPerSecond);
+        if (prefillTokensPerSecond === undefined || decodeTokensPerSecond === undefined)
+            return;
+        const sample = { prefillTokensPerSecond, decodeTokensPerSecond };
+        const ttftMs = finiteRate(performance.ttftMs);
+        if (ttftMs !== undefined)
+            sample.ttftMs = ttftMs;
+        const inputTokens = finiteTokenCount(message.usage?.input);
+        const cachedTokens = finiteTokenCount(message.usage?.cacheRead);
+        if (inputTokens !== undefined && cachedTokens !== undefined) {
+            sample.inputTokens = inputTokens;
+            sample.cachedTokens = cachedTokens;
+        }
+        this.byMessage.set(message, sample);
+    };
+    /** Render the successful mlx inference associated with this exact Pi message. */
+    showMessage(event, ctx) {
+        if (ctx.mode !== 'tui' || event.message.role !== 'assistant')
+            return;
+        const sample = this.byMessage.get(event.message);
+        if (!sample)
+            return;
+        ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg('dim', formatSample(sample)));
+    }
+    /** Prevent the selected model's completed sample lingering after its lifecycle ends. */
+    clear(ctx) {
+        if (ctx.mode === 'tui')
+            ctx.ui.setStatus(STATUS_KEY, undefined);
+    }
+}