@atomic-chat/core 0.5.1

package/dist/runtime/mlx/config.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The settings of one MLX load, turned into the six values mlx-server is started with.
+ *
+ * Ported from: extensions/mlx-extension/src/buildMlxConfig.ts (verbatim logic).
+ */
+/** What `build_mlx_server_args` reads (tauri-plugin-mlx/src/commands.rs `MlxConfig`). */
+export interface MlxServerConfig {
+    ctx_size: number;
+    draft_model_path: string;
+    block_size: number;
+    draft_kind: string;
+    kv_bits: number;
+    kv_quant_scheme: string;
+}
+export type MlxDraftKind = 'dflash' | 'mtp' | 'eagle3';
+/**
+ * Settings arrive as whatever the settings machinery stored: the number
+ * inputs in `settings.json` ship string defaults ("3.5", "16") and the UI's
+ * number field hands back strings too. Every numeric knob goes through
+ * {@link asNumber}; a `typeof === 'number'` check silently threw the value
+ * away — which is how KV-cache quantisation could never switch on
+ * (ATO-466).
+ */
+type Numeric = number | string;
+export interface MlxExtensionConfigInput {
+    ctx_size?: Numeric;
+    draft_model_path?: string;
+    block_size?: Numeric;
+    dflash_enabled?: boolean;
+    mtp_enabled?: boolean;
+    mtp_block_size?: Numeric;
+    eagle3_enabled?: boolean;
+    eagle3_block_size?: Numeric;
+    kv_bits?: Numeric;
+    kv_quant_scheme?: string;
+}
+export interface MlxDraftSelection {
+    draftKind: MlxDraftKind;
+    draftPath: string;
+    blockSize: number;
+}
+/**
+ * The context a model loads at when nothing pins one: the training maximum,
+ * capped — a 256K coder model must not allocate a 256K KV cache on a 16 GB
+ * Mac just because it could. The auto-increase ladder still climbs from
+ * here, capped at the training maximum. See ADR 2026-06-15.
+ */
+export declare const MLX_DEFAULT_CTX_CAP = 16384;
+/**
+ * When the training maximum could not be read from `config.json`. Smaller
+ * than the cap on purpose: with nothing known about the model, the safe
+ * assumption is the small one.
+ */
+export declare const MLX_DEFAULT_CTX_FALLBACK = 4096;
+/** A finite number from a number or a numeric string; otherwise `undefined`. */
+export declare function asNumber(value: unknown): number | undefined;
+export declare function selectMlxDraftSettings(config: MlxExtensionConfigInput): MlxDraftSelection;
+/**
+ * The context window to load with.
+ *
+ * An explicit, valid `ctx_size` (a user-pinned value, or the auto-increase
+ * override) wins, clamped to the training maximum when that is known — MLX
+ * never clamped, unlike llama.cpp, so it could ask for a window the model
+ * was not trained to hold. Unset falls back to `min(trainMax, cap)`, or
+ * {@link MLX_DEFAULT_CTX_FALLBACK} when the training maximum is unknown.
+ */
+export declare function resolveMlxCtxSize(ctxSize: Numeric | undefined, maxCtxTrain: number | undefined): number;
+export declare function buildMlxConfig(config: MlxExtensionConfigInput, draft: MlxDraftSelection, options?: {
+    maxCtxTrain?: number;
+}): MlxServerConfig;
+export {};

package/dist/runtime/mlx/config.js

@@ -0,0 +1,91 @@
+/**
+ * The settings of one MLX load, turned into the six values mlx-server is started with.
+ *
+ * Ported from: extensions/mlx-extension/src/buildMlxConfig.ts (verbatim logic).
+ */
+import { DEFAULT_CTX_LEN } from '../llamacpp/ctx-ladder.js';
+/**
+ * The context a model loads at when nothing pins one: the training maximum,
+ * capped — a 256K coder model must not allocate a 256K KV cache on a 16 GB
+ * Mac just because it could. The auto-increase ladder still climbs from
+ * here, capped at the training maximum. See ADR 2026-06-15.
+ */
+export const MLX_DEFAULT_CTX_CAP = DEFAULT_CTX_LEN;
+/**
+ * When the training maximum could not be read from `config.json`. Smaller
+ * than the cap on purpose: with nothing known about the model, the safe
+ * assumption is the small one.
+ */
+export const MLX_DEFAULT_CTX_FALLBACK = 4096;
+/** A finite number from a number or a numeric string; otherwise `undefined`. */
+export function asNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+export function selectMlxDraftSettings(config) {
+    if (config.mtp_enabled) {
+        return {
+            draftKind: 'mtp',
+            draftPath: config.draft_model_path ?? '',
+            blockSize: asNumber(config.mtp_block_size) ?? 4,
+        };
+    }
+    if (config.eagle3_enabled) {
+        return {
+            draftKind: 'eagle3',
+            draftPath: config.draft_model_path ?? '',
+            blockSize: asNumber(config.eagle3_block_size) ?? 0,
+        };
+    }
+    if (config.dflash_enabled) {
+        return {
+            draftKind: 'dflash',
+            draftPath: config.draft_model_path ?? '',
+            blockSize: asNumber(config.block_size) ?? 16,
+        };
+    }
+    return {
+        draftKind: 'dflash',
+        draftPath: '',
+        blockSize: 0,
+    };
+}
+/**
+ * The context window to load with.
+ *
+ * An explicit, valid `ctx_size` (a user-pinned value, or the auto-increase
+ * override) wins, clamped to the training maximum when that is known — MLX
+ * never clamped, unlike llama.cpp, so it could ask for a window the model
+ * was not trained to hold. Unset falls back to `min(trainMax, cap)`, or
+ * {@link MLX_DEFAULT_CTX_FALLBACK} when the training maximum is unknown.
+ */
+export function resolveMlxCtxSize(ctxSize, maxCtxTrain) {
+    const trainMax = typeof maxCtxTrain === 'number' && maxCtxTrain > 0 ? maxCtxTrain : undefined;
+    const explicit = asNumber(ctxSize);
+    if (explicit !== undefined && explicit > 0) {
+        return trainMax ? Math.min(explicit, trainMax) : explicit;
+    }
+    return trainMax ? Math.min(trainMax, MLX_DEFAULT_CTX_CAP) : MLX_DEFAULT_CTX_FALLBACK;
+}
+export function buildMlxConfig(config, draft, options = {}) {
+    const draftPath = draft.draftPath.trim();
+    const kvScheme = config.kv_quant_scheme === 'uniform' || config.kv_quant_scheme === 'turboquant'
+        ? config.kv_quant_scheme
+        : '';
+    const kvBitsRaw = asNumber(config.kv_bits);
+    const kvBits = kvScheme && kvBitsRaw !== undefined && kvBitsRaw > 0 ? kvBitsRaw : 0;
+    return {
+        ctx_size: resolveMlxCtxSize(config.ctx_size, options.maxCtxTrain),
+        draft_model_path: draftPath,
+        block_size: draftPath ? draft.blockSize : 0,
+        draft_kind: draftPath ? draft.draftKind : 'dflash',
+        kv_bits: kvBits,
+        kv_quant_scheme: kvBits > 0 ? kvScheme : '',
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/runtime/mlx/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/runtime/mlx/config.ts"],"names":[],"mappings":"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"}

package/dist/runtime/mlx/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How an mlx-server that failed is explained.
+ *
+ * Ported from: tauri-plugin-mlx/src/error.rs (`MlxError::from_stderr`) and the startup branches of
+ * commands.rs (`load_mlx_model_impl`). Contract: test/fixtures/app/mlx-errors.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import type { ExitInfo } from '../llamacpp/errors.js';
+export declare function classifyMlxStderr(stderr: string): AtomicCoreError;
+/** stdout lines that mean the server is up (commands.rs, stdout reader). */
+export declare const MLX_STDOUT_READY_MARKERS: readonly ["uvicorn running on", "application startup complete", "http server listening", "server is listening", "server started", "ready to accept", "server started and listening on"];
+/** stderr lines that mean the server is up (commands.rs, stderr reader) — a different set. */
+export declare const MLX_STDERR_READY_MARKERS: readonly ["uvicorn running on", "application startup complete", "server is listening", "server listening on", "server started and listening on"];
+export declare function mlxTimeout(timeoutSecs: number, stderr: string): AtomicCoreError;
+export declare function mlxBinaryMissing(path: string): AtomicCoreError;
+export declare function mlxModelMissing(path: string): AtomicCoreError;
+/**
+ * The wording of an exit, for `session:died` and the log: the plugin's diagnosis that an external
+ * kill leaves no stderr behind, which is what users and support ask first.
+ */
+export declare function describeMlxExit(exit: ExitInfo, stderr: string): string;

package/dist/runtime/mlx/errors.js

@@ -0,0 +1,73 @@
+/**
+ * How an mlx-server that failed is explained.
+ *
+ * Ported from: tauri-plugin-mlx/src/error.rs (`MlxError::from_stderr`) and the startup branches of
+ * commands.rs (`load_mlx_model_impl`). Contract: test/fixtures/app/mlx-errors.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+const OOM_PATTERNS = [
+    'out of memory',
+    'failed to allocate',
+    'insufficient memory',
+    'metal::malloc',
+    'maximum allowed buffer size',
+    'recommended max working set size',
+    'recommended working set size',
+    'kiogpucommandbuffercallbackerroroutofmemory',
+    'erroroutofdevicememory',
+];
+const ARCH_PATTERNS = [
+    'unknown model type',
+    "no module named 'mlx_vlm.models",
+    "no module named 'mlx_vlm.speculative.drafters",
+    "no module named 'mlx_lm.models",
+    'switch_mlp',
+];
+export function classifyMlxStderr(stderr) {
+    const lower = stderr.toLowerCase();
+    if (OOM_PATTERNS.some((pattern) => lower.includes(pattern)))
+        return new AtomicCoreError('OUT_OF_MEMORY', 'Out of memory. The model requires more memory than is available on this device.', stderr);
+    if ((lower.includes('model type') && lower.includes('not supported')) ||
+        ARCH_PATTERNS.some((pattern) => lower.includes(pattern)))
+        return new AtomicCoreError('MODEL_ARCH_NOT_SUPPORTED', "This model's architecture isn't supported by the current MLX backend yet.", stderr);
+    return new AtomicCoreError('MLX_PROCESS_ERROR', 'The MLX model process encountered an unexpected error.', stderr);
+}
+/** stdout lines that mean the server is up (commands.rs, stdout reader). */
+export const MLX_STDOUT_READY_MARKERS = [
+    'uvicorn running on',
+    'application startup complete',
+    'http server listening',
+    'server is listening',
+    'server started',
+    'ready to accept',
+    'server started and listening on',
+];
+/** stderr lines that mean the server is up (commands.rs, stderr reader) — a different set. */
+export const MLX_STDERR_READY_MARKERS = [
+    'uvicorn running on',
+    'application startup complete',
+    'server is listening',
+    'server listening on',
+    'server started and listening on',
+];
+export function mlxTimeout(timeoutSecs, stderr) {
+    return new AtomicCoreError('MODEL_LOAD_TIMED_OUT', 'The MLX model took too long to load and timed out.', `Timeout: ${timeoutSecs}s\n\nStderr:\n${stderr}`);
+}
+export function mlxBinaryMissing(path) {
+    return new AtomicCoreError('BINARY_NOT_FOUND', `MLX server binary not found at: ${path}`);
+}
+export function mlxModelMissing(path) {
+    return new AtomicCoreError('MODEL_FILE_NOT_FOUND', `Model file not found at: ${path}`);
+}
+/**
+ * The wording of an exit, for `session:died` and the log: the plugin's diagnosis that an external
+ * kill leaves no stderr behind, which is what users and support ask first.
+ */
+export function describeMlxExit(exit, stderr) {
+    if (exit.signal)
+        return `MLX server terminated by signal ${exit.signal} — an external process killed it.`;
+    if (stderr.trim() === '')
+        return `MLX server exited with code ${exit.code ?? -1} and produced no stderr — the signature of an external kill.`;
+    return classifyMlxStderr(stderr).message;
+}
+//# sourceMappingURL=errors.js.map

package/dist/runtime/mlx/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/runtime/mlx/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAG1D,MAAM,YAAY,GAAG;IACnB,eAAe;IACf,oBAAoB;IACpB,qBAAqB;IACrB,eAAe;IACf,6BAA6B;IAC7B,kCAAkC;IAClC,8BAA8B;IAC9B,6CAA6C;IAC7C,wBAAwB;CACzB,CAAA;AAED,MAAM,aAAa,GAAG;IACpB,oBAAoB;IACpB,iCAAiC;IACjC,+CAA+C;IAC/C,gCAAgC;IAChC,YAAY;CACb,CAAA;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAA;IAClC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACzD,OAAO,IAAI,eAAe,CACxB,eAAe,EACf,iFAAiF,EACjF,MAAM,CACP,CAAA;IACH,IACE,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QACjE,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAExD,OAAO,IAAI,eAAe,CACxB,0BAA0B,EAC1B,2EAA2E,EAC3E,MAAM,CACP,CAAA;IACH,OAAO,IAAI,eAAe,CACxB,mBAAmB,EACnB,wDAAwD,EACxD,MAAM,CACP,CAAA;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,oBAAoB;IACpB,8BAA8B;IAC9B,uBAAuB;IACvB,qBAAqB;IACrB,gBAAgB;IAChB,iBAAiB;IACjB,iCAAiC;CACzB,CAAA;AAEV,8FAA8F;AAC9F,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,oBAAoB;IACpB,8BAA8B;IAC9B,qBAAqB;IACrB,qBAAqB;IACrB,iCAAiC;CACzB,CAAA;AAEV,MAAM,UAAU,UAAU,CAAC,WAAmB,EAAE,MAAc;IAC5D,OAAO,IAAI,eAAe,CACxB,sBAAsB,EACtB,oDAAoD,EACpD,YAAY,WAAW,iBAAiB,MAAM,EAAE,CACjD,CAAA;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,eAAe,CAAC,kBAAkB,EAAE,mCAAmC,IAAI,EAAE,CAAC,CAAA;AAC3F,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,eAAe,CAAC,sBAAsB,EAAE,4BAA4B,IAAI,EAAE,CAAC,CAAA;AACxF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAc,EAAE,MAAc;IAC5D,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,mCAAmC,IAAI,CAAC,MAAM,mCAAmC,CAAA;IACzG,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QACtB,OAAO,+BAA+B,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,8DAA8D,CAAA;IACrH,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC,OAAO,CAAA;AAC1C,CAAC"}

package/dist/runtime/mlx/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * mlx-vlm sidecar runtime (Apple Silicon).
+ *
+ * Ported from: tauri-plugin-mlx/src/commands.rs, extensions/mlx-extension
+ * See PLAN.md §3.2. Public API of this module is exported from this file only.
+ */
+export * from './args.js';
+export * from './config.js';
+export * from './errors.js';
+export * from './shard-repair.js';
+export * from './model-files.js';
+export * from './runtime.js';

package/dist/runtime/mlx/index.js

@@ -0,0 +1,13 @@
+/**
+ * mlx-vlm sidecar runtime (Apple Silicon).
+ *
+ * Ported from: tauri-plugin-mlx/src/commands.rs, extensions/mlx-extension
+ * See PLAN.md §3.2. Public API of this module is exported from this file only.
+ */
+export * from './args.js';
+export * from './config.js';
+export * from './errors.js';
+export * from './shard-repair.js';
+export * from './model-files.js';
+export * from './runtime.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/mlx/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/mlx/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA"}

package/dist/runtime/mlx/model-files.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What an MLX load reads from a model folder: the trained context, a mis-named first shard to heal,
+ * and a drafter already on disk.
+ *
+ * Ported from: extensions/mlx-extension/src/index.ts (`resolveModelMaxCtxTrain`,
+ * `repairLegacyShardName`, `resolveLocalDraftDir`).
+ */
+import type { DataLayout } from '../../config/index.js';
+import type { ModelRegistry, ModelYmlDocument } from '../../models/index.js';
+/** A model path's folder: the path itself when it is a folder, its parent otherwise. */
+export declare function mlxModelDir(modelPath: string): Promise<string>;
+/**
+ * `max_position_embeddings` from `config.json`, or the nested `text_config` one Hugging Face
+ * VLM/omni configs use. `undefined` when the file or the key is missing or not a positive number.
+ */
+export declare function readMlxMaxCtxTrain(modelPath: string): Promise<number | undefined>;
+/**
+ * Rename a first shard stored as `model.safetensors` to the name its index expects, and repoint
+ * `model.yml`. Returns the document to load from; any failure leaves everything as it was, so the
+ * load reports its own error.
+ */
+export declare function repairLegacyShardName(registry: ModelRegistry, modelId: string, yml: ModelYmlDocument, warn?: (message: string) => void): Promise<ModelYmlDocument>;
+/** Where downloaded drafters live: `<data>/mlx/draft-models/<owner>/<repo>`. */
+export declare function mlxDraftModelsDir(layout: DataLayout): string;
+/**
+ * A drafter already on disk: imported as a model (`mlx/models/<owner_repo>`) or downloaded as a
+ * draft (`mlx/draft-models/<owner>/<repo>`), with a `config.json` and some safetensors weights.
+ */
+export declare function resolveLocalDraftDir(layout: DataLayout, repo: string): Promise<string | undefined>;

package/dist/runtime/mlx/model-files.js

@@ -0,0 +1,82 @@
+/**
+ * What an MLX load reads from a model folder: the trained context, a mis-named first shard to heal,
+ * and a drafter already on disk.
+ *
+ * Ported from: extensions/mlx-extension/src/index.ts (`resolveModelMaxCtxTrain`,
+ * `repairLegacyShardName`, `resolveLocalDraftDir`).
+ */
+import { readdir, readFile, rename, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { planMlxShardRepair, repointLegacyWeightPath } from './shard-repair.js';
+/** A model path's folder: the path itself when it is a folder, its parent otherwise. */
+export async function mlxModelDir(modelPath) {
+    const info = await stat(modelPath).catch(() => undefined);
+    return info?.isDirectory() ? modelPath : dirname(modelPath);
+}
+/**
+ * `max_position_embeddings` from `config.json`, or the nested `text_config` one Hugging Face
+ * VLM/omni configs use. `undefined` when the file or the key is missing or not a positive number.
+ */
+export async function readMlxMaxCtxTrain(modelPath) {
+    try {
+        const config = JSON.parse(await readFile(join(await mlxModelDir(modelPath), 'config.json'), 'utf8'));
+        const candidate = config?.max_position_embeddings ?? config?.text_config?.max_position_embeddings;
+        const parsed = typeof candidate === 'number' ? candidate : candidate != null ? parseInt(String(candidate), 10) : NaN;
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Rename a first shard stored as `model.safetensors` to the name its index expects, and repoint
+ * `model.yml`. Returns the document to load from; any failure leaves everything as it was, so the
+ * load reports its own error.
+ */
+export async function repairLegacyShardName(registry, modelId, yml, warn = () => { }) {
+    try {
+        const { modelPath } = registry.resolvePaths(yml);
+        const modelDir = modelPath.endsWith('.safetensors') ? dirname(modelPath) : modelPath;
+        const index = JSON.parse(await readFile(join(modelDir, 'model.safetensors.index.json'), 'utf8'));
+        const plan = planMlxShardRepair(index?.weight_map, await readdir(modelDir));
+        if (!plan)
+            return yml;
+        await rename(join(modelDir, plan.from), join(modelDir, plan.to));
+        const repaired = {
+            ...yml,
+            model_path: repointLegacyWeightPath(yml.model_path, plan.to),
+            ...(yml.mmproj_path ? { mmproj_path: repointLegacyWeightPath(yml.mmproj_path, plan.to) } : {}),
+        };
+        await registry.write(modelId, repaired);
+        warn(`Repaired mis-named MLX shard in ${modelDir}: ${plan.from} -> ${plan.to}`);
+        return repaired;
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            warn(`MLX shard-name repair failed: ${String(e)}`);
+        return yml;
+    }
+}
+/** Where downloaded drafters live: `<data>/mlx/draft-models/<owner>/<repo>`. */
+export function mlxDraftModelsDir(layout) {
+    return join(layout.root, 'mlx', 'draft-models');
+}
+/**
+ * A drafter already on disk: imported as a model (`mlx/models/<owner_repo>`) or downloaded as a
+ * draft (`mlx/draft-models/<owner>/<repo>`), with a `config.json` and some safetensors weights.
+ */
+export async function resolveLocalDraftDir(layout, repo) {
+    const candidates = [
+        join(layout.root, 'mlx', 'models', repo.split('/').join('_')),
+        join(mlxDraftModelsDir(layout), ...repo.split('/')),
+    ];
+    for (const dir of candidates) {
+        const entries = await readdir(dir).catch(() => undefined);
+        if (!entries?.includes('config.json'))
+            continue;
+        if (entries.some((entry) => /\.safetensors$/i.test(entry)))
+            return dir;
+    }
+    return undefined;
+}
+//# sourceMappingURL=model-files.js.map

package/dist/runtime/mlx/model-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-files.js","sourceRoot":"","sources":["../../../src/runtime/mlx/model-files.ts"],"names":[],"mappings":"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"}

package/dist/runtime/mlx/runtime.d.ts

@@ -0,0 +1,77 @@
+/**
+ * MLX models, served one process per model by the bundled `mlx-server` (mlx-vlm), Apple Silicon.
+ *
+ * Ported from: tauri-plugin-mlx/src/commands.rs (`load_mlx_model_impl`, unload, cleanup) and
+ * extensions/mlx-extension/src/index.ts (`performLoad`, `handleAutoIncreaseCtx`).
+ *
+ * The extension planned a load (settings, drafter, context) and the plugin ran it; here both halves
+ * are one. The core keeps the extension's model catalogue where it was — listing, importing and
+ * downloading MLX models stays in the app — and takes over what needs a process: load, unload,
+ * growing the context, restarting.
+ *
+ * Deliberate differences, each for a reason the app had no way to act on:
+ *  - loading a loaded model answers with its session, and unloading an unloaded one succeeds — the
+ *    shared semantics of every core runtime (the extension threw in both cases);
+ *  - a drafter that is switched on but not on disk is not downloaded at load time: the app still
+ *    downloads it before asking (its adapter passes `draft_model_path`), and a CLI load runs without
+ *    it, as the extension already did whenever that download failed;
+ *  - a session that dies is removed and reported with `session:died`; the plugin kept it until a
+ *    chat request found the dead port.
+ */
+import type { DataLayout } from '../../config/index.js';
+import type { SessionInfo, UnloadResult } from '../../contracts/index.js';
+import type { ProcessJournal } from '../../lock/index.js';
+import type { ModelRegistry } from '../../models/index.js';
+import type { CtxIncreaseResult, EmitFn, LocalLoadOptions, LocalRuntime, RecreateResult } from '../shared/index.js';
+import { spawnAndAwaitReady } from '../shared/index.js';
+import type { MlxDraftKind } from './config.js';
+export declare const MLX_SERVER_BINARY = "mlx-server";
+/** The extension's `timeout` default, in seconds. */
+export declare const MLX_DEFAULT_TIMEOUT_SECS = 600;
+export interface MlxRuntimeOptions {
+    layout: DataLayout;
+    registry: ModelRegistry;
+    instanceId: string;
+    /** The bundled binaries folder (the app's `resources/bin`); `mlx-server` is looked up here. */
+    resourcesDir?: string | undefined;
+    /** The `mlx` provider settings, re-read per load. */
+    readSettings: () => Promise<Record<string, unknown>>;
+    journal?: ProcessJournal | undefined;
+    emit?: EmitFn;
+    baseEnv?: NodeJS.ProcessEnv;
+    /**
+     * A drafter that is switched on but has no path. Defaults to one already on disk; a caller that
+     * can download may do so here.
+     */
+    resolveDraft?: (kind: MlxDraftKind, modelId: string) => Promise<string | undefined>;
+    /** Test seams. */
+    spawn?: typeof spawnAndAwaitReady;
+    exists?: (path: string) => boolean;
+}
+export declare class MlxRuntime implements LocalRuntime {
+    private readonly options;
+    private readonly table;
+    private readonly emit;
+    constructor(options: MlxRuntimeOptions);
+    binaryPath(): string | undefined;
+    list(): SessionInfo[];
+    findSession(modelId: string): SessionInfo | undefined;
+    getLoadedModels(): string[];
+    isLoading(modelId: string): boolean;
+    /** The context a loaded session runs with. */
+    getCtxSize(modelId: string): number | undefined;
+    load(modelId: string, opts?: LocalLoadOptions): Promise<SessionInfo>;
+    private start;
+    private localDraft;
+    unload(modelId: string): Promise<UnloadResult>;
+    /**
+     * Reload with the next context up the ladder, because a request did not fit — clamped to what the
+     * model was trained for, where the reload would change nothing (`at_max`).
+     */
+    autoIncreaseCtx(modelId: string, reason?: string): Promise<CtxIncreaseResult>;
+    recreateSession(modelId: string): Promise<RecreateResult>;
+    /** Unload (a failure does not stop the reload) and load again without evicting other models. */
+    private reload;
+    shutdown(): Promise<void>;
+    private exists;
+}