@mlx-node/agent 0.0.12 → 0.0.15

package/dist/provider/models.js

@@ -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 })`.
  *
@@ -15,243 +15,21 @@
  * 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 { launchPresetFor, detectModelType, familyTraitsFor, NON_GENERATIVE_FAMILY_IDS, } from '@mlx-node/lm';
-/**
- * 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 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;
-}
-function nonEmptyRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
-}
-/**
- * Read cheap discovery metadata from `<modelPath>/config.json`.
- *
- * The trained context window comes from:
- * root `max_position_embeddings` first (qwen3, lfm2), then
- * `text_config.max_position_embeddings` (qwen3_5, qwen3_5_moe, gemma4
- * unified), else the family fallback.
- *
- * Image support is advertised only when a family with a native multimodal
- * implementation carries its valid, non-empty vision marker: `vision_config`
- * for Qwen, and either `vision_config` or `unified_vision_config` for Gemma.
- * This lets Pi's model picker and `--list-models` expose checkpoint capability
- * without loading weights. The first resident load remains authoritative and
- * reconciles this optimistic config-level advertisement via
- * `session.supportsImages()` (for example, when conversion stripped an
- * incompatible vision tower).
- *
- * `detectModelType` already parsed this file, so a read/parse failure here
- * (e.g. a racing rewrite) lands on the context fallback and text-only input
- * instead of dropping the model or guessing a positive capability.
- */
-async function readDiscoveryMetadata(modelPath, modelType, fallbackContextWindow) {
-    try {
-        const raw = await readFile(join(modelPath, 'config.json'), 'utf-8');
-        const config = JSON.parse(raw);
-        const root = positiveInteger(config.max_position_embeddings);
-        const textConfig = config.text_config;
-        const nested = nonEmptyRecord(textConfig) ? positiveInteger(textConfig.max_position_embeddings) : undefined;
-        const hasVisionConfig = nonEmptyRecord(config.vision_config);
-        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, draftOnly: false };
-    }
-}
-/**
- * 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.
- */
+import { discoverLocalChatModels } from '@mlx-node/lm/model-discovery';
+/** Pair the shared local inventory with pi provider metadata, without loading weights. */
 export async function discoverMlxModels(modelsDir) {
-    const debug = Boolean(process.env.MLX_DEBUG);
-    let entries;
-    try {
-        entries = await readdir(modelsDir, { withFileTypes: true });
-    }
-    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 = {
+    return (await discoverLocalChatModels(modelsDir)).map(({ name, path, modelType, preset, traits, supportsImages, contextWindow }) => ({
+        discovered: { name, path, modelType },
+        piModel: {
+            id: name,
             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);
-        let modelType;
-        try {
-            modelType = await detectModelType(full);
-        }
-        catch (err) {
-            if (debug)
-                console.warn(`[mlx] skip ${full}: ${err.message}`);
-            continue;
-        }
-        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;
-        }
-        // 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 supported direct GGUF target`);
-            continue;
-        }
-        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;
+            reasoning: traits.reasoning,
+            // pi types are agent-only; keep the shared structural map assignable.
+            thinkingLevelMap: traits.thinkingLevelMap,
+            input: supportsImages ? ['text', 'image'] : ['text'],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow,
+            maxTokens: preset.maxOutputTokens,
+        },
+    }));
 }

package/dist/provider/stream-adapter.d.ts

@@ -51,7 +51,7 @@ export interface StreamSimpleHost {
      * `fn` receives a `resident` boolean: `true` when the model was already warm
      * (reused), `false` when this turn had to load/swap it.
      */
-    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 resident as post-error so the next turn does a full reset (see `MlxModelHost`). */
     markResidentDirty(modelId: string): void;
     /** Read-and-clear the resident's post-error flag; `true` ⇒ full-reset this turn. */
@@ -90,5 +90,5 @@ export type TurnRecorder = (rec: {
     /** `true` when the model was already warm/resident, `false` on a cold load/swap this turn. */
     resident: boolean;
 }) => void;
-export declare function makeMlxStreamSimple(host: StreamSimpleHost, onPerformance?: PerformanceRecorder, resolveRootCacheOwner?: RootCacheOwnerResolver, onTurnRecord?: TurnRecorder, onTurnStart?: () => void, resolveRootSessionFile?: RootSessionFileResolver): (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+export declare function makeMlxStreamSimple(host: StreamSimpleHost, onPerformance?: PerformanceRecorder, resolveRootCacheOwner?: RootCacheOwnerResolver, onTurnRecord?: TurnRecorder, onTurnStart?: () => void, resolveRootSessionFile?: RootSessionFileResolver, resolveThinkingBudget?: () => number | undefined): (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
 //# sourceMappingURL=stream-adapter.d.ts.map

package/dist/provider/stream-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-adapter.d.ts","sourceRoot":"","sources":["../../src/provider/stream-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,gBAAgB,EAChB,2BAA2B,EAC3B,OAAO,EACP,KAAK,EACL,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAErF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAOvD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAC5D;;;;OAIG;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,CAAC;IAC7G,+FAA+F;IAC/F,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oFAAoF;IACpF,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/C,gFAAgF;IAChF,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,KAAK,IAAI,CAAC;AACvG,MAAM,MAAM,sBAAsB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAC9D,qFAAqF;AACrF,MAAM,MAAM,uBAAuB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;IACvB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,EAAE,OAAO,CAAC;CACnB,KAAK,IAAI,CAAC;AAwGX,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,gBAAgB,EACtB,aAAa,CAAC,EAAE,mBAAmB,EACnC,qBAAqB,CAAC,EAAE,sBAAsB,EAC9C,YAAY,CAAC,EAAE,YAAY,EAC3B,WAAW,CAAC,EAAE,MAAM,IAAI,EACxB,sBAAsB,CAAC,EAAE,uBAAuB,GAC/C,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,2BAA2B,CA6RrG"}
+{"version":3,"file":"stream-adapter.d.ts","sourceRoot":"","sources":["../../src/provider/stream-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,gBAAgB,EAChB,2BAA2B,EAC3B,OAAO,EACP,KAAK,EACL,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAErF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAOvD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAC5D;;;;OAIG;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,CAAC;IACd,+FAA+F;IAC/F,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oFAAoF;IACpF,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/C,gFAAgF;IAChF,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,KAAK,IAAI,CAAC;AACvG,MAAM,MAAM,sBAAsB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAC9D,qFAAqF;AACrF,MAAM,MAAM,uBAAuB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;IACvB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,QAAQ,EAAE,OAAO,CAAC;CACnB,KAAK,IAAI,CAAC;AAwGX,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,gBAAgB,EACtB,aAAa,CAAC,EAAE,mBAAmB,EACnC,qBAAqB,CAAC,EAAE,sBAAsB,EAC9C,YAAY,CAAC,EAAE,YAAY,EAC3B,WAAW,CAAC,EAAE,MAAM,IAAI,EACxB,sBAAsB,CAAC,EAAE,uBAAuB,EAChD,qBAAqB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GAC/C,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,2BAA2B,CAiSrG"}

package/dist/provider/stream-adapter.js

@@ -140,9 +140,10 @@ function failsafeMessage(model, reason, message) {
         timestamp: Date.now(),
     };
 }
-export function makeMlxStreamSimple(host, onPerformance, resolveRootCacheOwner, onTurnRecord, onTurnStart, resolveRootSessionFile) {
+export function makeMlxStreamSimple(host, onPerformance, resolveRootCacheOwner, onTurnRecord, onTurnStart, resolveRootSessionFile, resolveThinkingBudget) {
     return (model, context, options) => {
         const stream = createAssistantMessageEventStream();
+        let thinkingTokenBudget;
         /**
          * Exactly-one-terminal guard for the WHOLE turn. `TurnEmitter` has its
          * own `finished` flag, but it cannot cover pre-emitter failures or the
@@ -231,7 +232,8 @@ export function makeMlxStreamSimple(host, onPerformance, resolveRootCacheOwner,
             rootSessionFile = resolveRootSessionFile?.();
             // Snapshot once: the native config and the replay provenance must describe
             // the same resolved template mode. Presence alone is wrong for Pi's
-            // minimal/low levels, both of which resolve to disabled thinking.
+            // off is disabled; low remains enabled thinking.
+            thinkingTokenBudget = resolveThinkingBudget?.();
             resolvedReasoning = resolveReasoningMode(options?.reasoning);
             emitter = new TurnEmitter(stream, model, onPerformance, resolvedReasoning.thinkingEnabled);
         }
@@ -261,7 +263,7 @@ export function makeMlxStreamSimple(host, onPerformance, resolveRootCacheOwner,
             // prefill + decode) so a MetricsTrace record can report wall-clock
             // duration. Read at the terminal only on the success path below.
             const turnStartedAt = Date.now();
-            await host.runWithResident(model.id, async (session, resident) => {
+            const runTurn = async (session, resident) => {
                 // Callback entry: the queue wait + any cold model load/swap have now
                 // resolved, but no native work (prime/prefill/decode) has started. This
                 // is the seam that separates queue+load latency from execution time —
@@ -319,7 +321,7 @@ export function makeMlxStreamSimple(host, onPerformance, resolveRootCacheOwner,
                     return;
                 try {
                     session.primeHistory(contextToChatMessages(context, supportsImages));
-                    const config = buildChatConfig(discovered.modelType, options, toolsToDefinitions(context.tools), rootCacheOwnerId, resolvedReasoning, configuredModelMaxTokens);
+                    const config = buildChatConfig(discovered.modelType, options, toolsToDefinitions(context.tools), rootCacheOwnerId, resolvedReasoning, configuredModelMaxTokens, thinkingTokenBudget);
                     for await (const event of session.startFromHistoryStream(config, signal)) {
                         if (event.done) {
                             if (event.finishReason === 'error') {
@@ -414,7 +416,8 @@ export function makeMlxStreamSimple(host, onPerformance, resolveRootCacheOwner,
                     }
                     throw err;
                 }
-            });
+            };
+            await host.runWithResident(model.id, runTurn, options?.sessionId);
             if (!terminated && !sawNativeFinal) {
                 // An aborted native stream ends cleanly with NO final event; any
                 // other final-less ending is a native-protocol violation.

package/dist/run-agent.d.ts

@@ -33,6 +33,10 @@ export interface AgentPagedConfigOverrides {
     cleanup(): Promise<void>;
 }
 export interface RunAgentOptions {
+    /** Focused worker tools/permissions; inference and session defaults remain shared. */
+    mode?: 'delegate';
+    /** Explicit approval supplied by the outer caller, captured before the worker starts. */
+    delegateCallerApproved?: boolean;
     /** Resolved models directory (context for callers/diagnostics — discovery already ran). */
     modelsDir: string;
     /** Discovered models to serve through the in-process `mlx` provider. */

package/dist/run-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-agent.d.ts","sourceRoot":"","sources":["../src/run-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAWvE,OAAO,EACL,KAAK,iCAAiC,EAEvC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE;IAAE,kBAAkB,EAAE,eAAe,EAAE,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9G,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,iCAAiC,CAAC;CACjD;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,yDAAyD;IACzD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,yBAAyB,CAAC;CAClD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA2EnE"}
+{"version":3,"file":"run-agent.d.ts","sourceRoot":"","sources":["../src/run-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAYvE,OAAO,EACL,KAAK,iCAAiC,EAEvC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE;IAAE,kBAAkB,EAAE,eAAe,EAAE,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9G,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,iCAAiC,CAAC;CACjD;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,yFAAyF;IACzF,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,yDAAyD;IACzD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,yBAAyB,CAAC;CAClD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgFnE"}

package/dist/run-agent.js

@@ -20,6 +20,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { coldCacheDrain } from '@mlx-node/core';
 import { PagedConfigOverrideManager } from '@mlx-node/lm';
+import { createDelegationExtension } from './extensions/delegation.js';
 import { createLocalImageInputExtension } from './extensions/local-image-input.js';
 import { createPermissionGateExtension } from './extensions/permission-gate.js';
 import { createSubagentExtension } from './extensions/subagent.js';
@@ -77,13 +78,18 @@ export async function runAgent(opts) {
     // facade), which is where the selector / listing / resolution paths read.
     const pi = opts.piImpl ?? (await import('@earendil-works/pi-coding-agent'));
     const restoreModelRegistry = installMlxOnlyModelRegistryFilter(pi.ModelRuntime, opts.models.map((model) => model.discovered.name));
-    const subagentsEnabled = opts.models.length > 0 && !opts.argv.includes('--no-extensions') && !opts.argv.includes('-ne');
+    const subagentsEnabled = opts.mode !== 'delegate' &&
+        opts.models.length > 0 &&
+        !opts.argv.includes('--no-extensions') &&
+        !opts.argv.includes('-ne');
     try {
         await pi.main(opts.argv, {
             extensionFactories: [
                 createMlxProviderExtension(opts.models, modelHost),
                 createLocalImageInputExtension(),
-                createPermissionGateExtension(),
+                opts.mode === 'delegate'
+                    ? createDelegationExtension({ callerApproved: opts.delegateCallerApproved })
+                    : createPermissionGateExtension(),
                 ...(subagentsEnabled ? [createSubagentExtension()] : []),
                 ...(opts.traceLogFile !== undefined ? [createTraceNoticeExtension(opts.traceLogFile)] : []),
                 createTerminalTitleExtension(),

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export interface DiscoveredModelLike {
     name: string;
     path: string;
     modelType: ModelType;
-    /** Optional external speculative drafter paired with this target checkpoint. */
+    /** External speculative drafter. When supplied, forwarded unchanged for loader validation. */
     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;IACrB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}
+{"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,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlx-node/agent",
-  "version": "0.0.12",
+  "version": "0.0.15",
   "homepage": "https://github.com/mlx-node/mlx-node",
   "bugs": {
     "url": "https://github.com/mlx-node/mlx-node/issues"
@@ -12,19 +12,37 @@
     "directory": "packages/agent"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "@mlx-node/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./delegate": {
+      "@mlx-node/source": "./src/delegate.ts",
+      "types": "./dist/delegate.d.ts",
+      "default": "./dist/delegate.js"
+    },
     "./catalog": {
+      "@mlx-node/source": "./src/catalog.ts",
       "types": "./dist/catalog.d.ts",
       "default": "./dist/catalog.js"
+    },
+    "./paths": {
+      "@mlx-node/source": "./src/paths.ts",
+      "types": "./dist/paths.d.ts",
+      "default": "./dist/paths.js"
+    },
+    "./models": {
+      "@mlx-node/source": "./src/provider/models.ts",
+      "types": "./dist/provider/models.d.ts",
+      "default": "./dist/provider/models.js"
     }
   },
   "scripts": {
@@ -33,9 +51,9 @@
   "dependencies": {
     "@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",
+    "@mlx-node/core": "0.0.15",
+    "@mlx-node/lm": "0.0.15",
+    "@mlx-node/server": "0.0.15",
     "typebox": "1.3.23"
   },
   "devDependencies": {