@mlx-node/agent 0.0.12 → 0.0.15

package/dist/catalog.d.ts

@@ -19,6 +19,12 @@ export interface CatalogEntry {
     hfRepoCuda?: string;
     /** Approximate download size in GB, for display. */
     sizeGb: number;
+    /** Optional companion, downloaded separately and never offered as a chat model. */
+    draft?: {
+        label: string;
+        hfRepo: string;
+        sizeGb: number;
+    };
     /** One line for the wizard. */
     description: string;
     /** Exactly one entry carries this. */
@@ -41,6 +47,8 @@ export interface CatalogEntry {
     hidden?: boolean;
 }
 export declare const MODEL_CATALOG: readonly CatalogEntry[];
+/** Visible target repos plus their optional companion downloads. */
+export declare function catalogDownloadRepos(): string[];
 /**
  * The repo THIS platform installs for `entry`. Linux is the CUDA preview
  * target (README "Platform Support"); everything else is Apple Silicon.
@@ -86,7 +94,8 @@ export declare function visibleCatalog(): CatalogEntry[];
  * 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:
+ * `@mlx-node/agent/catalog` is a NATIVE-FREE entry point, alongside the
+ * `delegate` client and `models` discovery subpaths:
  * 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

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,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,mFAAmF;IACnF,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,+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,EA2DhD,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAQ/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;GAgBG;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

@@ -5,6 +5,7 @@
  * entry's `catalogRepo()` to `mlx download model`. Slugs are verified against the Brooooooklyn
  * HF account — use them verbatim.
  */
+import { QWEN38_DFLASH2 } from '@mlx-node/lm/draft-companion';
 export const MODEL_CATALOG = [
     {
         label: 'Qwen3.8-27B',
@@ -13,9 +14,10 @@ export const MODEL_CATALOG = [
         sizeGb: 23.3,
         description: 'Best tool use — recommended default',
         isDefault: true,
+        draft: QWEN38_DFLASH2,
     },
     {
-        label: 'Qwen-AgentWorld-35B',
+        label: 'Qwen-AgentWorld-35B-A3B',
         hfRepo: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-mxfp4-mlx',
         hfRepoCuda: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-nvfp4-mlx',
         sizeGb: 23.3,
@@ -64,6 +66,12 @@ export const MODEL_CATALOG = [
         hidden: true,
     },
 ];
+/** Visible target repos plus their optional companion downloads. */
+export function catalogDownloadRepos() {
+    return [
+        ...new Set(MODEL_CATALOG.filter((entry) => !entry.hidden).flatMap((entry) => entry.draft === undefined ? [catalogRepo(entry)] : [catalogRepo(entry), entry.draft.hfRepo])),
+    ];
+}
 /**
  * The repo THIS platform installs for `entry`. Linux is the CUDA preview
  * target (README "Platform Support"); everything else is Apple Silicon.
@@ -115,7 +123,8 @@ export function visibleCatalog() {
  * 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:
+ * `@mlx-node/agent/catalog` is a NATIVE-FREE entry point, alongside the
+ * `delegate` client and `models` discovery subpaths:
  * 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

package/dist/delegate.d.ts

@@ -0,0 +1,29 @@
+export declare const DELEGATION_PROMPT = "Delegate GitHub investigation to `mlx delegate github --caller-approved --repo OWNER/REPO \"TASK\"`. Approve the bounded task and its tool execution before invoking. Include the PR, issue, or run number. Wait for the final handoff and read it once; do not poll by dumping worker transcripts. Use its findings and evidence for implementation; address specific gaps with a focused follow-up or relevant evidence excerpt. Add `--allow-write` only for GitHub changes already authorized by the user. If delegation fails or reports incomplete work, continue from its handoff.";
+/** Absolute paths avoid dependence on each coding agent's shell startup/PATH. */
+export declare function delegationCommand(path: string): string;
+export declare function delegationPrompt(path: string): string;
+export interface LocalInferenceConnection {
+    url: string;
+    token?: string;
+    model: string;
+}
+export interface LocalMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/** Shared by setup requests and their verdict cache key. Includes thinking and final output. */
+export declare const INSTALL_CHECK_GENERATION: Readonly<{
+    reasoning: Readonly<{
+        effort: 'medium';
+    }>;
+    max_output_tokens: 16384;
+    temperature: 0;
+}>;
+export declare const INSTALL_CHECK_TIMEOUT_MS = 600000;
+export declare function expandHome(path: string, home?: string): string;
+/** Match the persisted default used by `mlx agent`; never select a cloud provider. */
+export declare function preferredLocalModel(home?: string, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/** Refuse remote endpoints even if a caller accidentally supplies a cloud API URL. */
+export declare function localCompletion(connection: LocalInferenceConnection, system: string, messages: LocalMessage[], signal?: AbortSignal, maxTokens?: number): Promise<string>;
+export declare function parseLocalJson(text: string): unknown;
+//# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,iBAAiB,8jBAC6hB,CAAC;AAE5jB,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gGAAgG;AAChG,eAAO,MAAM,wBAAwB;;gBACA,QAAQ;;;;EAG3C,CAAC;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAEhD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAY,GAAG,MAAM,CAEjE;AAED,sFAAsF;AACtF,wBAAsB,mBAAmB,CAAC,IAAI,SAAY,EAAE,GAAG,oBAAc,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe1G;AAED,sFAAsF;AACtF,wBAAsB,eAAe,CACnC,UAAU,EAAE,wBAAwB,EACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,EAAE,EACxB,MAAM,CAAC,EAAE,WAAW,EACpB,SAAS,GAAE,MAAmD,GAC7D,OAAO,CAAC,MAAM,CAAC,CA0DjB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpD"}

package/dist/delegate.js

@@ -0,0 +1,106 @@
+/** Addon-free client for the desktop's global instruction installation checks. */
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { expandPiAgentDir } from './paths.js';
+export const DELEGATION_PROMPT = 'Delegate GitHub investigation to `mlx delegate github --caller-approved --repo OWNER/REPO "TASK"`. Approve the bounded task and its tool execution before invoking. Include the PR, issue, or run number. Wait for the final handoff and read it once; do not poll by dumping worker transcripts. Use its findings and evidence for implementation; address specific gaps with a focused follow-up or relevant evidence excerpt. Add `--allow-write` only for GitHub changes already authorized by the user. If delegation fails or reports incomplete work, continue from its handoff.';
+/** Absolute paths avoid dependence on each coding agent's shell startup/PATH. */
+export function delegationCommand(path) {
+    if (/[\0\r\n`]/.test(path))
+        throw new Error('The delegation command path cannot be represented in instructions.');
+    return `'${path.replaceAll("'", "'\\''")}'`;
+}
+export function delegationPrompt(path) {
+    return DELEGATION_PROMPT.replace('`mlx delegate', `\`${delegationCommand(path)} delegate`);
+}
+/** Shared by setup requests and their verdict cache key. Includes thinking and final output. */
+export const INSTALL_CHECK_GENERATION = Object.freeze({
+    reasoning: Object.freeze({ effort: 'medium' }),
+    max_output_tokens: 16384,
+    temperature: 0,
+});
+export const INSTALL_CHECK_TIMEOUT_MS = 600_000;
+export function expandHome(path, home = homedir()) {
+    return path === '~' ? home : path.startsWith('~/') ? join(home, path.slice(2)) : path;
+}
+/** Match the persisted default used by `mlx agent`; never select a cloud provider. */
+export async function preferredLocalModel(home = homedir(), env = process.env) {
+    try {
+        const dir = env.PI_CODING_AGENT_DIR
+            ? expandPiAgentDir(env.PI_CODING_AGENT_DIR, home)
+            : join(home, '.mlx-node', 'agent');
+        const value = JSON.parse(await readFile(join(dir, 'settings.json'), 'utf8'));
+        if (value.defaultProvider === 'mlx' && typeof value.defaultModel === 'string') {
+            return value.defaultModel.replace(/^mlx\//, '');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error('Could not read the default local model. Open mlx agent and select a model again.');
+        }
+    }
+    return undefined;
+}
+/** Refuse remote endpoints even if a caller accidentally supplies a cloud API URL. */
+export async function localCompletion(connection, system, messages, signal, maxTokens = INSTALL_CHECK_GENERATION.max_output_tokens) {
+    const url = new URL(connection.url);
+    if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)) {
+        throw new Error('Delegation requires a local inference server.');
+    }
+    const controller = new AbortController();
+    const cancel = () => controller.abort(signal?.reason);
+    if (signal?.aborted)
+        cancel();
+    else
+        signal?.addEventListener('abort', cancel, { once: true });
+    const timer = setTimeout(() => controller.abort(new Error('The local model request timed out.')), INSTALL_CHECK_TIMEOUT_MS);
+    try {
+        const headers = {
+            'content-type': 'application/json',
+            ...(connection.token ? { 'x-api-key': connection.token } : {}),
+        };
+        const catalog = await fetch(new URL('/v1/models', url), { headers, signal: controller.signal, redirect: 'error' });
+        if (!catalog.ok)
+            throw new Error('The local model service is unavailable. Restart it and try again.');
+        const models = (await catalog.json());
+        if (!models.data?.some((model) => model.id === connection.model)) {
+            throw new Error('The default model is not available in the running service. Restart the local model service and try again.');
+        }
+        const response = await fetch(new URL('/v1/responses', url), {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                model: connection.model,
+                instructions: system,
+                input: messages,
+                ...INSTALL_CHECK_GENERATION,
+                max_output_tokens: maxTokens,
+                store: false,
+                stream: false,
+            }),
+            signal: controller.signal,
+            redirect: 'error',
+        });
+        if (!response.ok)
+            throw new Error(`The local model could not complete the request (HTTP ${response.status}).`);
+        const body = (await response.json());
+        if (body.incomplete_details?.reason === 'max_output_tokens')
+            throw new Error('The local model ran out of output space. Try checking again.');
+        if (body.status !== 'completed')
+            throw new Error('The local model did not complete its answer. Try checking again.');
+        const text = body.output_text?.trim();
+        if (!text)
+            throw new Error('The local model returned no answer. Try checking again.');
+        return text;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', cancel);
+    }
+}
+export function parseLocalJson(text) {
+    return JSON.parse(text
+        .trim()
+        .replace(/^```(?:json)?\s*\n?/, '')
+        .replace(/\n?```$/, ''));
+}

package/dist/extensions/delegation.d.ts

@@ -0,0 +1,15 @@
+import type { InlineExtension } from '@earendil-works/pi-coding-agent';
+export interface DelegateCallerPermissions {
+    source: 'codex';
+    /** Opaque Codex profile/backend when supplied; otherwise just inherited process permissions. */
+    profile: string;
+    networkDisabled: boolean;
+}
+/** Child processes stay inside Codex's actual sandbox; this metadata grants no OS access. */
+export declare function delegateCallerPermissions(env?: NodeJS.ProcessEnv): DelegateCallerPermissions | undefined;
+/** Only failed tool executions qualify; quoted CI logs in a successful result do not. */
+export declare function delegationBlocker(text: string): boolean;
+export declare function createDelegationExtension(options?: {
+    callerApproved?: boolean;
+}): InlineExtension;
+//# sourceMappingURL=delegation.d.ts.map

package/dist/extensions/delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../../src/extensions/delegation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvG,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,gGAAgG;IAChG,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,6FAA6F;AAC7F,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,yBAAyB,GAAG,SAAS,CAWrH;AAID,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIvD;AAED,wBAAgB,yBAAyB,CAAC,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,eAAe,CA4ErG"}

package/dist/extensions/delegation.js

@@ -0,0 +1,93 @@
+/** Child processes stay inside Codex's actual sandbox; this metadata grants no OS access. */
+export function delegateCallerPermissions(env = process.env) {
+    if (!env.CODEX_THREAD_ID?.trim())
+        return undefined;
+    const profile = env.CODEX_PERMISSION_PROFILE?.trim();
+    // Permission metadata is optional in Codex launches. The thread identifies
+    // the caller; subprocesses inherit its real sandbox regardless of these labels.
+    const sandbox = env.CODEX_SANDBOX;
+    return {
+        source: 'codex',
+        profile: profile || (sandbox === 'seatbelt' || sandbox === 'landlock' ? `sandbox:${sandbox}` : 'inherited'),
+        networkDisabled: env.CODEX_SANDBOX_NETWORK_DISABLED === '1',
+    };
+}
+const READ_TOOLS = new Set(['read', 'grep', 'find', 'ls']);
+/** Only failed tool executions qualify; quoted CI logs in a successful result do not. */
+export function delegationBlocker(text) {
+    return /permission denied|operation not permitted|\bEACCES\b|\bEPERM\b|network access was denied|sandbox.*(?:denied|blocked)|(?:HTTP\s+|status(?: code)?[: ]+)(?:401|403)\b|gh auth login|could not resolve host|could not resolve proxy|failed to connect|error connecting to api\.github\.com/i.test(text);
+}
+export function createDelegationExtension(options = {}) {
+    // Capture before any model/tool code runs. Never consult model-written settings.
+    const caller = delegateCallerPermissions();
+    const explicitlyApproved = options.callerApproved === true || process.env.MLX_AGENT_AUTO_APPROVE === '1';
+    return {
+        name: 'mlx-delegation',
+        factory: (pi) => {
+            let handoff;
+            const stop = (reason, ctx) => {
+                if (!handoff) {
+                    const sessionFile = ctx.sessionManager.getSessionFile();
+                    handoff = `Delegation incomplete: ${reason}\nContinue this task in the calling agent. Do not retry with changed permissions or another agent.${sessionFile ? `\nSaved evidence and tool results: ${sessionFile}` : ''}`;
+                    pi.appendEntry('mlx-delegate-handoff', { reason, caller, sessionFile });
+                    // Print mode otherwise shows only the final assistant message. A deterministic
+                    // diagnostic and failure status let the caller recover without another inference.
+                    process.stderr.write(`${handoff}\n`);
+                    process.exitCode = 1;
+                }
+                ctx.abort();
+                return handoff;
+            };
+            pi.on('before_agent_start', (event, ctx) => {
+                handoff = undefined;
+                // A boundary per invocation keeps ordinary history/resumes out of the
+                // delegate estimate. Custom entries are persisted, never model context.
+                pi.appendEntry('mlx-delegate-session', { version: 1, sessionId: ctx.sessionManager.getSessionId() });
+                const permissions = caller
+                    ? `Tool execution inherits the calling Codex process's permissions (${caller.profile}).${caller.networkDisabled ? ' The caller disables network access.' : ''} Additional approval must be handled by the calling agent; this worker cannot request escalation.`
+                    : explicitlyApproved
+                        ? "The caller explicitly approved tool execution for this bounded task. Child processes inherit its OS sandbox, environment and credentials; this does not copy the calling agent's tool approval rules or grant additional access. Stay within the task authorization."
+                        : 'No inherited caller permission context is available. Tools requiring approval will stop this task and return a handoff.';
+                return { systemPrompt: `${event.systemPrompt}\n\n${permissions}` };
+            });
+            pi.on('tool_call', (event, ctx) => {
+                if (handoff)
+                    return { block: true, terminate: true, reason: handoff };
+                if (event.toolName === 'subagent') {
+                    return { block: true, terminate: true, reason: stop('This worker cannot create subagents.', ctx) };
+                }
+                if (READ_TOOLS.has(event.toolName))
+                    return undefined;
+                if (!caller && !explicitlyApproved) {
+                    return {
+                        block: true,
+                        terminate: true,
+                        reason: stop(`No caller permission context is available to authorize ${event.toolName}. The calling agent can use --caller-approved after approving this bounded task.`, ctx),
+                    };
+                }
+                if (event.toolName === 'bash') {
+                    const input = event.input;
+                    if (typeof input.command === 'string') {
+                        // Preserve failures through pipelines such as `gh ... | head`, and
+                        // stop a multi-command script before later output masks a denial.
+                        // This changes shell options only; cwd, environment and sandbox remain inherited.
+                        input.command = `set -e -o pipefail\n${input.command}`;
+                    }
+                }
+                return undefined;
+            });
+            pi.on('tool_result', (event, ctx) => {
+                if (!event.isError)
+                    return undefined;
+                const text = event.content
+                    .filter((part) => part.type === 'text')
+                    .map((part) => part.text)
+                    .join('\n');
+                if (!delegationBlocker(text))
+                    return undefined;
+                const reason = stop(`${event.toolName} was blocked. ${text.slice(0, 2000)}`, ctx);
+                return { content: [{ type: 'text', text: reason }], isError: true };
+            });
+        },
+    };
+}

package/dist/paths.d.ts

@@ -6,6 +6,12 @@
  * `resolveMlxNodeHome()` in `@mlx-node/server/host/paths`
  * (`packages/server/src/host/paths.ts`).
  */
+/**
+ * Expand an agent directory for both the CLI and desktop settings readers.
+ * Accept home-relative paths and file URLs without trimming literal paths or
+ * expanding another user's `~user` prefix. `home` is a test seam.
+ */
+export declare function expandPiAgentDir(dir: string, home?: string): string;
 /** Absolute path to `$HOME/.mlx-node`. */
 export declare function mlxNodeHome(): string;
 /** Directory holding per-process `MetricsTrace` JSONL files. */

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,0CAA0C;AAC1C,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,gEAAgE;AAChE,wBAAgB,eAAe,IAAI,MAAM,CAExC"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAO9E;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,gEAAgE;AAChE,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/paths.js

@@ -8,6 +8,22 @@
  */
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Expand an agent directory for both the CLI and desktop settings readers.
+ * Accept home-relative paths and file URLs without trimming literal paths or
+ * expanding another user's `~user` prefix. `home` is a test seam.
+ */
+export function expandPiAgentDir(dir, home = homedir()) {
+    if (dir === '~')
+        return home;
+    if (dir.startsWith('~/') || (process.platform === 'win32' && dir.startsWith('~\\'))) {
+        return join(home, dir.slice(2));
+    }
+    if (dir.startsWith('file://'))
+        return fileURLToPath(dir);
+    return dir;
+}
 /** Absolute path to `$HOME/.mlx-node`. */
 export function mlxNodeHome() {
     return join(homedir(), '.mlx-node');

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

@@ -7,16 +7,17 @@
 import type { SimpleStreamOptions, ThinkingLevel } from '@earendil-works/pi-ai';
 import { type ChatConfig, type ModelType, type ToolDefinition } from '@mlx-node/lm';
 export interface ResolvedReasoningMode {
-    reasoningEffort: 'none' | 'low' | 'medium' | 'high';
+    reasoningEffort: 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
     /** The `enable_thinking` value implied by `reasoningEffort` for templates. */
     thinkingEnabled: boolean;
 }
 /**
  * Resolve Pi's thinking level once for both native config and persisted replay
- * provenance. Keeping these values together prevents a low/minimal turn from
- * being replayed later as an enabled-thinking turn merely because the Pi
- * option was present.
+ * provenance. Keeping these values together gives generation and replay the same
+ * enabled-thinking state, including low/minimal turns.
  */
 export declare function resolveReasoningMode(reasoning: ThinkingLevel | undefined): ResolvedReasoningMode;
-export declare function buildChatConfig(modelType: ModelType, options: SimpleStreamOptions | undefined, tools: ToolDefinition[] | undefined, rootCacheOwnerId?: string, resolvedReasoning?: ResolvedReasoningMode, modelMaxTokens?: unknown): ChatConfig;
+/** An explicit hard cap, independent from the model's reasoning effort. */
+export declare function parseThinkingBudget(value: unknown): number | undefined;
+export declare function buildChatConfig(modelType: ModelType, options: SimpleStreamOptions | undefined, tools: ToolDefinition[] | undefined, rootCacheOwnerId?: string, resolvedReasoning?: ResolvedReasoningMode, modelMaxTokens?: unknown, thinkingTokenBudget?: number): ChatConfig;
 //# sourceMappingURL=chat-config.d.ts.map

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;;;;;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"}
+{"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,GAAG,OAAO,GAAG,KAAK,CAAC;IACtE,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,SAAS,GAAG,qBAAqB,CAMhG;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOtE;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,EACxB,mBAAmB,CAAC,EAAE,MAAM,GAC3B,UAAU,CA6CZ"}

package/dist/provider/chat-config.js

@@ -28,32 +28,46 @@ const THINKING_LEVEL_TO_EFFORT = {
     low: 'low',
     medium: 'medium',
     high: 'high',
-    xhigh: 'high',
-    max: 'high',
+    xhigh: 'xhigh',
+    max: 'max',
 };
 function isPositiveSafeInteger(value) {
     return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
 }
 /**
  * Resolve Pi's thinking level once for both native config and persisted replay
- * provenance. Keeping these values together prevents a low/minimal turn from
- * being replayed later as an enabled-thinking turn merely because the Pi
- * option was present.
+ * provenance. Keeping these values together gives generation and replay the same
+ * enabled-thinking state, including low/minimal turns.
  */
 export function resolveReasoningMode(reasoning) {
     const reasoningEffort = reasoning === undefined ? 'none' : THINKING_LEVEL_TO_EFFORT[reasoning];
     return {
         reasoningEffort,
-        thinkingEnabled: reasoningEffort === 'medium' || reasoningEffort === 'high',
+        thinkingEnabled: reasoningEffort !== 'none',
     };
 }
-export function buildChatConfig(modelType, options, tools, rootCacheOwnerId, resolvedReasoning = resolveReasoningMode(options?.reasoning), modelMaxTokens) {
+/** An explicit hard cap, independent from the model's reasoning effort. */
+export function parseThinkingBudget(value) {
+    if (value === undefined)
+        return undefined;
+    const budget = typeof value === 'string' && /^\d+$/.test(value) ? Number(value) : value;
+    if (typeof budget !== 'number' || !Number.isSafeInteger(budget) || budget < 0 || budget > 2_147_483_647) {
+        throw new Error('Thinking budget must be an integer between 0 and 2147483647.');
+    }
+    return budget;
+}
+export function buildChatConfig(modelType, options, tools, rootCacheOwnerId, resolvedReasoning = resolveReasoningMode(options?.reasoning), modelMaxTokens, thinkingTokenBudget) {
     const preset = launchPresetFor(modelType);
     if (!preset) {
         const known = KNOWN_PRESET_MODEL_TYPES.join(', ');
         throw new Error(`buildChatConfig: no launch preset for model type "${modelType}" (known types: ${known})`);
     }
+    // Pi's numeric budget settings currently stop at high. Preserve effort
+    // itself while using that highest configured cap for xhigh/max.
+    const budgetLevel = options?.reasoning === 'xhigh' || options?.reasoning === 'max' ? 'high' : options?.reasoning;
+    const budget = parseThinkingBudget(thinkingTokenBudget ?? (budgetLevel === undefined ? undefined : options?.thinkingBudgets?.[budgetLevel]));
     const config = {
+        ...(budget === undefined ? {} : { thinkingTokenBudget: budget }),
         ...preset.sampling,
         maxNewTokens: preset.maxOutputTokens,
         reasoningEffort: resolvedReasoning.reasoningEffort,

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAoC,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG9G,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA4BhD,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAC7C,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,gBAAgB,GAAG,SAAS,CAAC;IAClD,iFAAiF;IACjF,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,YAAY,EAAE,EACtB,IAAI,CAAC,EAAE,YAAY,EACnB,IAAI,GAAE,wBAA6B,GAClC,eAAe,CA6KjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAoC,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAI9G,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA4BhD,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAC7C,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,gBAAgB,GAAG,SAAS,CAAC;IAClD,iFAAiF;IACjF,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,YAAY,EAAE,EACtB,IAAI,CAAC,EAAE,YAAY,EACnB,IAAI,GAAE,wBAA6B,GAClC,eAAe,CAoLjB"}

package/dist/provider/index.js

@@ -16,6 +16,7 @@
  */
 import { coldCacheStats, coldSidecarStats } from '@mlx-node/core';
 import { canonicalCacheRoot } from '../cold-tier.js';
+import { parseThinkingBudget } from './chat-config.js';
 import { MetricsTrace } from './metrics-trace.js';
 import { MLX_API, MLX_API_KEY, MLX_BASE_URL, MLX_PROVIDER_ID } from './mlx-identity.js';
 import { MlxModelHost } from './model-host.js';
@@ -173,10 +174,16 @@ export function createMlxProviderExtension(models, host, deps = {}) {
         }
         metricsTrace.record(rec);
     };
-    const streamSimple = makeMlxStreamSimple(resolvedHost, performanceStatus.record, () => rootCacheOwnerId, onTurnRecord, onTurnStart, () => rootSessionFile);
+    let getThinkingBudget = () => undefined;
+    const streamSimple = makeMlxStreamSimple(resolvedHost, performanceStatus.record, () => rootCacheOwnerId, onTurnRecord, onTurnStart, () => rootSessionFile, () => getThinkingBudget());
     return {
         name: 'mlx-provider',
         factory: (pi) => {
+            pi.registerFlag('thinking-budget', {
+                type: 'string',
+                description: 'Maximum reasoning tokens per model turn; 0 closes thinking immediately.',
+            });
+            getThinkingBudget = () => parseThinkingBudget(pi.getFlag('thinking-budget'));
             pi.registerProvider(MLX_PROVIDER_ID, {
                 api: MLX_API,
                 baseUrl: MLX_BASE_URL,

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

@@ -105,7 +105,7 @@ export declare class MlxModelHost {
      * 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, resident: boolean) => Promise<T>): Promise<T>;
+    runWithResident<T>(modelId: string, fn: (session: ChatSession, resident: boolean) => Promise<T>, ownerId?: string): 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,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"}
+{"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;AAGhF,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;AAqBD,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,EACf,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,EAC3D,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAuEZ;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,6 +13,7 @@
  * overlapping native activity on the compiled-path globals).
  */
 import { ChatSession, loadModel } from '@mlx-node/lm';
+import { findDFlash2Draft } from '@mlx-node/lm/draft-companion';
 import { COLD_TIER_RESTORE_FAMILIES } from '../cold-tier.js';
 /**
  * Re-exported so the HOST consults exactly the symbol the drift guard and the
@@ -72,7 +73,8 @@ export class MlxModelHost {
      * retries); a failure thrown by `fn` rejects only this call's promise
      * and keeps the resident loaded for later callers.
      */
-    runWithResident(modelId, fn) {
+    runWithResident(modelId, fn, ownerId) {
+        ownerId = ownerId || undefined;
         const entry = this.byName.get(modelId);
         if (!entry) {
             const known = [...this.byName.keys()].join(', ');
@@ -84,6 +86,21 @@ export class MlxModelHost {
             // it loaded/swapped the checkpoint first (cold).
             let resident;
             if (this.resident?.id === modelId) {
+                if (this.resident.ownerId !== ownerId) {
+                    // Stay on the same serialization chain: the preceding native turn must
+                    // finish before its owner is released. Keep weights loaded, but never
+                    // reassign the immutable owner of the old ChatSession.
+                    try {
+                        await this.resident.session.dispose();
+                    }
+                    catch (error) {
+                        this.resident = null;
+                        throw error;
+                    }
+                    this.resident.session = new ChatSession(this.resident.model);
+                    this.resident.ownerId = ownerId;
+                    this.resident.dirty = false;
+                }
                 session = this.resident.session;
                 resident = true;
             }
@@ -100,12 +117,13 @@ export class MlxModelHost {
                     ? await this.resolveModelPathFn(entry, { persistPagedCache: this.persistPagedCache })
                     : await this.resolveModelPathFn(entry);
                 // 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
+                // Supplied paths are authoritative across draft families. Let the
+                // loader validate them and report errors; only absent paths opt into
+                // Qwen DFlash2 discovery, resolved against the original target path.
+                const draftModelPath = entry.draftModelPath ?? findDFlash2Draft(entry.path, entry.modelType);
+                const model = draftModelPath === undefined
                     ? await this.loadModelFn(resolvedPath)
-                    : await this.loadModelFn(resolvedPath, { draftModelPath: entry.draftModelPath });
+                    : await this.loadModelFn(resolvedPath, { draftModelPath });
                 const sessionModel = model;
                 const gemmaDraftActive = entry.modelType === 'gemma4' && sessionModel.hasMtpWeights?.() === true;
                 if (this.requirePagedCache && sessionModel.hasBlockPagedCache?.() !== true && !gemmaDraftActive) {
@@ -119,7 +137,7 @@ export class MlxModelHost {
                         `this agent session to paged autoregressive decoding`);
                 }
                 session = new ChatSession(sessionModel);
-                this.resident = { id: modelId, session, model, dirty: false };
+                this.resident = { id: modelId, session, model, ownerId, dirty: false };
             }
             return await fn(session, resident);
         });

package/dist/provider/models.d.ts

@@ -1,8 +1,8 @@
 /**
  * Local model discovery for the mlx pi provider.
  *
- * The same discovery walk as `@mlx-node/server/host`
- * (`packages/server/src/host/discover.ts`), pairing every discovered checkpoint
+ * Uses the same native-free inventory as the inference host and setup UI,
+ * pairing every discovered checkpoint
  * with a pi `ProviderModelConfig` entry ready for
  * `pi.registerProvider('mlx', { models })`.
  *
@@ -22,17 +22,6 @@ export interface MlxModelInfo {
     discovered: DiscoveredModelLike;
     piModel: ProviderModelConfig;
 }
-/**
- * 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.
- */
+/** Pair the shared local inventory with pi provider metadata, without loading weights. */
 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;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/provider/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAG3E,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;AAED,0FAA0F;AAC1F,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAiBlF"}