@atomic-chat/core 0.21.0 → 0.21.2

package/dist/runtime/llamacpp/devices.d.ts

@@ -22,5 +22,16 @@ export declare function findMemoryPattern(text: string): {
 /** First whitespace token as i32 (`"7721 MiB free"` → 7721). */
 export declare function parseMemoryValue(memStr: string): number | undefined;
 export declare function parseDeviceLine(rawLine: string): DeviceInfo | undefined;
+/**
+ * A `--device` value checked against what the build lists: the names it has (llama.cpp matches them
+ * case-insensitively, `ggml_backend_dev_by_name`) and `none` are kept in the order given, every other
+ * name is dropped. llama-server exits on a name it does not have ("use --list-devices to see a list of
+ * available devices"), which is what a value copied from a CUDA build does on a Vulkan or ROCm one.
+ * `device` is `''` when nothing is left: llama.cpp then picks its devices itself.
+ */
+export declare function validateDeviceList(requested: string, devices: readonly DeviceInfo[]): {
+    device: string;
+    dropped: string[];
+};
 /** Throws `DEVICE_LIST_PARSE_FAILED` (details = the whole output) when the header is missing. */
 export declare function parseDeviceOutput(output: string): DeviceInfo[];

package/dist/runtime/llamacpp/devices.js

@@ -63,6 +63,28 @@ export function parseDeviceLine(rawLine) {
         return undefined;
     return { id, name, mem: total, free };
 }
+/**
+ * A `--device` value checked against what the build lists: the names it has (llama.cpp matches them
+ * case-insensitively, `ggml_backend_dev_by_name`) and `none` are kept in the order given, every other
+ * name is dropped. llama-server exits on a name it does not have ("use --list-devices to see a list of
+ * available devices"), which is what a value copied from a CUDA build does on a Vulkan or ROCm one.
+ * `device` is `''` when nothing is left: llama.cpp then picks its devices itself.
+ */
+export function validateDeviceList(requested, devices) {
+    const known = new Set(devices.map((d) => d.id.toLowerCase()));
+    const kept = [];
+    const dropped = [];
+    for (const raw of String(requested).split(',')) {
+        const name = raw.trim();
+        if (name === '')
+            continue;
+        if (name.toLowerCase() === 'none' || known.has(name.toLowerCase()))
+            kept.push(name);
+        else
+            dropped.push(name);
+    }
+    return { device: kept.join(','), dropped };
+}
 /** Throws `DEVICE_LIST_PARSE_FAILED` (details = the whole output) when the header is missing. */
 export function parseDeviceOutput(output) {
     const devices = [];

package/dist/runtime/llamacpp/devices.js.map

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

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

@@ -2,8 +2,8 @@
  * Classification of a failed `llama-server` process into the app's error contract. Port of
  * `src-tauri/plugins/tauri-plugin-llamacpp-upstream/src/error.rs` (`LlamacppError::from_stderr`,
  * `from_exit_status`, `from_process_output`). Pinned by `test/contract/errors.test.ts`. The
- * TurboQuant fork's `error.rs` differs in one rule, `wrong number of tensors` (app commit
- * `ec1fd3ea7`), so the provider is a parameter.
+ * recorded desktop fixture predates the tensor-layout correction: a tensor-count mismatch alone
+ * is backend incompatibility on every provider (2026-11-02-tensor-layout-error).
  *
  * The cascade is ordered: the first matching group wins. Messages are the app's user-facing strings
  * and are part of the contract. `details` is always set (the raw stream), even when empty.
@@ -18,18 +18,48 @@ export interface ExitInfo {
 }
 /** Normalise a Node signal name to the Unix number Rust sees. */
 export declare function signalNumber(signal: number | string | null): number | null;
+/**
+ * NTSTATUS codes a Windows process ends with when the loader gives up before `main`, so it prints
+ * nothing of its own — the same set `src/diffusion/install.ts` and `src/audio/install.ts` read for
+ * their engines: a missing DLL, a missing ordinal or entry point, a bad image, a DLL whose init failed.
+ */
+export declare const WINDOWS_LOADER_FAILURES: ReadonlyMap<number, string>;
+/** STATUS_ILLEGAL_INSTRUCTION: the build uses an instruction this CPU does not have. */
+export declare const WINDOWS_ILLEGAL_INSTRUCTION = 3221225501;
+/**
+ * An exit status as the load diagnostics spell it: `0x`-prefixed upper-case hex on Windows (NTSTATUS
+ * codes arrive signed or unsigned), decimal elsewhere; `undefined` when the process was killed by a
+ * signal or never started.
+ */
+export declare function formatExitCode(code: number | null, platform: NodeJS.Platform): string | undefined;
 /** A hard native crash (segfault / abort) rather than a normal non-zero exit. */
 export declare function isCrashExit(exit: ExitInfo, platform: NodeJS.Platform): boolean;
+export declare const GPU_BACKEND_INCOMPATIBLE_MESSAGE = "This GPU build of the model engine does not run on this graphics card with its current driver. Update the NVIDIA graphics driver, or switch to another backend (CUDA 12, Vulkan or CPU).";
+export declare const ENGINE_BINARY_BROKEN_MESSAGE = "The model engine could not load a library it needs, so it did not start. Its files may be incomplete or blocked by antivirus software: reinstall this backend or switch to another one.";
+export declare const CPU_INSTRUCTION_UNSUPPORTED_MESSAGE = "The model engine stopped on a processor instruction this computer does not have. Switch to another backend, such as the CPU build, which picks the instructions this processor supports.";
 export declare const ARGUMENT_REJECTED_MESSAGE = "This llama.cpp backend does not accept one of the arguments it was started with. If you added custom arguments to this model, remove them; otherwise switch to another backend version or update Atomic Chat.";
 export declare const GENERIC_PROCESS_ERROR_MESSAGE = "The model process encountered an unexpected error.";
 export declare const CRASH_MESSAGE = "The model process crashed unexpectedly (access violation / segfault). This usually means the model is incompatible with this backend, or its speculative-decoding (MTP) configuration is unsupported here.";
 /** `LlamacppError::from_stderr`: ordered substring cascade over the lowercased stream. */
 export declare function classifyStderr(stderr: string, provider?: LocalProviderId): AtomicCoreError;
-/** `LlamacppError::from_exit_status`: a recognised crash upgrades the generic error's message. */
+/**
+ * A Windows exit status that names its own cause when stderr named none: the loader gave up before
+ * `main` (`ENGINE_BINARY_BROKEN`), or the build hit an instruction this CPU lacks
+ * (`CPU_INSTRUCTION_UNSUPPORTED`). `undefined` for anything else, and off Windows.
+ */
+export declare function windowsExitCause(exit: ExitInfo, platform: NodeJS.Platform): {
+    code: 'ENGINE_BINARY_BROKEN' | 'CPU_INSTRUCTION_UNSUPPORTED';
+    message: string;
+} | undefined;
+/**
+ * `LlamacppError::from_exit_status`: a recognised crash upgrades the generic error's message; beyond
+ * the app, a Windows loader or illegal-instruction status that stderr did not explain gets its own code.
+ */
 export declare function classifyExit(exit: ExitInfo, stderr: string, platform: NodeJS.Platform, provider?: LocalProviderId): AtomicCoreError;
 /**
  * `LlamacppError::from_process_output`: stderr classification wins; otherwise try stdout (several
  * llama.cpp builds report loader failures there); otherwise keep the exit-status error but hand the
- * caller stdout as details when stderr is blank.
+ * caller stdout as details when stderr is blank. A code read from the Windows exit status alone ranks
+ * with the exit status, below stdout.
  */
 export declare function classifyProcessOutput(exit: ExitInfo, stderr: string, stdout: string, platform: NodeJS.Platform, provider?: LocalProviderId): AtomicCoreError;

package/dist/runtime/llamacpp/errors.js

@@ -2,8 +2,8 @@
  * Classification of a failed `llama-server` process into the app's error contract. Port of
  * `src-tauri/plugins/tauri-plugin-llamacpp-upstream/src/error.rs` (`LlamacppError::from_stderr`,
  * `from_exit_status`, `from_process_output`). Pinned by `test/contract/errors.test.ts`. The
- * TurboQuant fork's `error.rs` differs in one rule, `wrong number of tensors` (app commit
- * `ec1fd3ea7`), so the provider is a parameter.
+ * recorded desktop fixture predates the tensor-layout correction: a tensor-count mismatch alone
+ * is backend incompatibility on every provider (2026-11-02-tensor-layout-error).
  *
  * The cascade is ordered: the first matching group wins. Messages are the app's user-facing strings
  * and are part of the contract. `details` is always set (the raw stream), even when empty.
@@ -36,6 +36,32 @@ export function signalNumber(signal) {
 }
 /** Windows: STATUS_ACCESS_VIOLATION / STATUS_STACK_OVERFLOW / STATUS_STACK_BUFFER_OVERRUN. */
 const WINDOWS_CRASH_CODES = new Set([0xc000_0005, 0xc000_00fd, 0xc000_0409]);
+/**
+ * NTSTATUS codes a Windows process ends with when the loader gives up before `main`, so it prints
+ * nothing of its own — the same set `src/diffusion/install.ts` and `src/audio/install.ts` read for
+ * their engines: a missing DLL, a missing ordinal or entry point, a bad image, a DLL whose init failed.
+ */
+export const WINDOWS_LOADER_FAILURES = new Map([
+    [0xc000_0135, 'STATUS_DLL_NOT_FOUND'],
+    [0xc000_0138, 'STATUS_ORDINAL_NOT_FOUND'],
+    [0xc000_0139, 'STATUS_ENTRYPOINT_NOT_FOUND'],
+    [0xc000_007b, 'STATUS_INVALID_IMAGE_FORMAT'],
+    [0xc000_0142, 'STATUS_DLL_INIT_FAILED'],
+]);
+/** STATUS_ILLEGAL_INSTRUCTION: the build uses an instruction this CPU does not have. */
+export const WINDOWS_ILLEGAL_INSTRUCTION = 0xc000_001d;
+/**
+ * An exit status as the load diagnostics spell it: `0x`-prefixed upper-case hex on Windows (NTSTATUS
+ * codes arrive signed or unsigned), decimal elsewhere; `undefined` when the process was killed by a
+ * signal or never started.
+ */
+export function formatExitCode(code, platform) {
+    if (code === null)
+        return undefined;
+    if (platform !== 'win32')
+        return String(code);
+    return `0x${(code >>> 0).toString(16).toUpperCase()}`;
+}
 /** A hard native crash (segfault / abort) rather than a normal non-zero exit. */
 export function isCrashExit(exit, platform) {
     if (platform === 'win32') {
@@ -48,11 +74,25 @@ const includesAny = (lower, needles) => needles.some((n) => lower.includes(n));
 /**
  * TurboQuant (`llamacpp`) can know an architecture and still expect a tensor layout that differs
  * from a valid upstream GGUF: re-downloading cannot fix that, and the same file loads in stock
- * llama.cpp, so there the mismatch is an unsupported architecture. Upstream it still means a
- * damaged file.
+ * llama.cpp, so there the mismatch is an unsupported architecture. Ollama conversions can differ
+ * from upstream too, so on any build a tensor count alone does not prove a damaged file.
  */
 const TENSOR_COUNT_MISMATCH = 'wrong number of tensors';
-const tensorLayoutIsArchitecture = (provider) => provider === 'llamacpp';
+/**
+ * What CUDA prints when a build cannot run on this card or driver: a driver too old for the toolchain
+ * the build's PTX came from (CUDA 13.x on Turing before R616), or no kernels for this architecture at
+ * all. The bare `ggml_cuda_kernel_can_use_pdl` + `cudaFuncGetAttributes` pair is the same failure when
+ * the CUDA error line itself was cut off. Lowercase, like the stream the cascade reads.
+ */
+const GPU_BUILD_INCOMPATIBLE_MARKERS = [
+    'provided ptx was compiled with an unsupported toolchain',
+    'no kernel image is available for execution on the device',
+];
+const isGpuBuildIncompatible = (l) => includesAny(l, GPU_BUILD_INCOMPATIBLE_MARKERS) ||
+    (l.includes('ggml_cuda_kernel_can_use_pdl') && l.includes('cudafuncgetattributes'));
+export const GPU_BACKEND_INCOMPATIBLE_MESSAGE = 'This GPU build of the model engine does not run on this graphics card with its current driver. Update the NVIDIA graphics driver, or switch to another backend (CUDA 12, Vulkan or CPU).';
+export const ENGINE_BINARY_BROKEN_MESSAGE = 'The model engine could not load a library it needs, so it did not start. Its files may be incomplete or blocked by antivirus software: reinstall this backend or switch to another one.';
+export const CPU_INSTRUCTION_UNSUPPORTED_MESSAGE = 'The model engine stopped on a processor instruction this computer does not have. Switch to another backend, such as the CPU build, which picks the instructions this processor supports.';
 export const ARGUMENT_REJECTED_MESSAGE = 'This llama.cpp backend does not accept one of the arguments it was started with. If you added custom arguments to this model, remove them; otherwise switch to another backend version or update Atomic Chat.';
 const CASCADE = [
     {
@@ -72,16 +112,23 @@ const CASCADE = [
             'cuda_error_out_of_memory',
         ]),
     },
+    {
+        // After out-of-memory (a card that ran out of VRAM is not an incompatible one), before every
+        // model rule: the build never got far enough for the model to be the reason.
+        code: 'GPU_BACKEND_INCOMPATIBLE',
+        message: GPU_BACKEND_INCOMPATIBLE_MESSAGE,
+        match: isGpuBuildIncompatible,
+    },
     {
         code: 'MODEL_ARCH_NOT_SUPPORTED',
         message: "The model's architecture or format is not supported by this version of the backend.",
-        match: (l, provider) => includesAny(l, [
+        match: (l) => includesAny(l, [
             'error loading model architecture',
             'unknown model architecture',
             'error loading model hyperparameters',
             'key not found in model',
-        ]) ||
-            (tensorLayoutIsArchitecture(provider) && l.includes(TENSOR_COUNT_MISMATCH)),
+            TENSOR_COUNT_MISMATCH,
+        ]),
     },
     {
         code: 'MULTIMODAL_PROJECTOR_LOAD_FAILED',
@@ -91,13 +138,12 @@ const CASCADE = [
     {
         code: 'MODEL_FILE_CORRUPT',
         message: 'The model file appears to be incomplete or corrupted. Try deleting and re-downloading the model.',
-        match: (l, provider) => includesAny(l, [
+        match: (l) => includesAny(l, [
             'corrupted or incomplete',
             'invalid magic',
             'unexpectedly reached end of file',
             'failed to read tensor',
-        ]) ||
-            (!tensorLayoutIsArchitecture(provider) && l.includes(TENSOR_COUNT_MISMATCH)),
+        ]),
     },
     {
         // `common_params_parse` (upstream, TurboQuant and Prism alike): a flag the build does not know,
@@ -120,28 +166,65 @@ export function classifyStderr(stderr, provider = 'llamacpp-upstream') {
     }
     return new AtomicCoreError('LLAMA_CPP_PROCESS_ERROR', GENERIC_PROCESS_ERROR_MESSAGE, stderr);
 }
-/** `LlamacppError::from_exit_status`: a recognised crash upgrades the generic error's message. */
+/**
+ * A Windows exit status that names its own cause when stderr named none: the loader gave up before
+ * `main` (`ENGINE_BINARY_BROKEN`), or the build hit an instruction this CPU lacks
+ * (`CPU_INSTRUCTION_UNSUPPORTED`). `undefined` for anything else, and off Windows.
+ */
+export function windowsExitCause(exit, platform) {
+    if (platform !== 'win32' || exit.code === null)
+        return undefined;
+    const status = exit.code >>> 0;
+    if (WINDOWS_LOADER_FAILURES.has(status))
+        return { code: 'ENGINE_BINARY_BROKEN', message: ENGINE_BINARY_BROKEN_MESSAGE };
+    if (status === WINDOWS_ILLEGAL_INSTRUCTION)
+        return { code: 'CPU_INSTRUCTION_UNSUPPORTED', message: CPU_INSTRUCTION_UNSUPPORTED_MESSAGE };
+    return undefined;
+}
+/**
+ * `LlamacppError::from_exit_status`: a recognised crash upgrades the generic error's message; beyond
+ * the app, a Windows loader or illegal-instruction status that stderr did not explain gets its own code.
+ */
 export function classifyExit(exit, stderr, platform, provider = 'llamacpp-upstream') {
     const base = classifyStderr(stderr, provider);
-    if (base.code !== 'LLAMA_CPP_PROCESS_ERROR' || !isCrashExit(exit, platform))
+    if (base.code !== 'LLAMA_CPP_PROCESS_ERROR')
+        return base;
+    const cause = windowsExitCause(exit, platform);
+    if (cause)
+        return new AtomicCoreError(cause.code, cause.message, stderr);
+    if (!isCrashExit(exit, platform))
         return base;
     return new AtomicCoreError('LLAMA_CPP_PROCESS_ERROR', CRASH_MESSAGE, stderr);
 }
 /**
  * `LlamacppError::from_process_output`: stderr classification wins; otherwise try stdout (several
  * llama.cpp builds report loader failures there); otherwise keep the exit-status error but hand the
- * caller stdout as details when stderr is blank.
+ * caller stdout as details when stderr is blank. A code read from the Windows exit status alone ranks
+ * with the exit status, below stdout.
  */
 export function classifyProcessOutput(exit, stderr, stdout, platform, provider = 'llamacpp-upstream') {
     const base = classifyExit(exit, stderr, platform, provider);
-    if (base.code !== 'LLAMA_CPP_PROCESS_ERROR')
-        return base;
     const fromStdout = classifyStderr(stdout, provider);
-    if (fromStdout.code !== 'LLAMA_CPP_PROCESS_ERROR')
-        return fromStdout;
-    if (stderr.trim() === '' && stdout.trim() !== '') {
-        return new AtomicCoreError(base.code, base.message, stdout);
-    }
-    return base;
+    const fromStderr = base.code !== 'LLAMA_CPP_PROCESS_ERROR' && base.code !== windowsExitCause(exit, platform)?.code;
+    const selected = fromStderr
+        ? base
+        : fromStdout.code !== 'LLAMA_CPP_PROCESS_ERROR'
+            ? fromStdout
+            : stderr.trim() === '' && stdout.trim() !== ''
+                ? new AtomicCoreError(base.code, base.message, stdout)
+                : base;
+    // Preserve the Rust-compatible body while retaining facts that disappear when details are scrubbed.
+    return new AtomicCoreError(selected.code, selected.message, selected.details, {
+        diagnostic: {
+            component: 'runtime',
+            operation: 'load',
+            stage: 'ready',
+            exitCode: exit.code,
+            signal: exit.signal,
+            ...(selected.code === 'LLAMA_CPP_PROCESS_ERROR' && /GGML_ASSERT/.test(stderr + stdout)
+                ? { nativeFailure: 'assertion', reason: 'native_crash' }
+                : {}),
+        },
+    });
 }
 //# sourceMappingURL=errors.js.map

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

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

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

@@ -12,4 +12,5 @@ export * from './policy.js';
 export * from './probe.js';
 export * from './fit-margin.js';
 export * from './load-plan.js';
+export * from './load-failure.js';
 export * from './runtime.js';

package/dist/runtime/llamacpp/index.js

@@ -12,5 +12,6 @@ export * from './policy.js';
 export * from './probe.js';
 export * from './fit-margin.js';
 export * from './load-plan.js';
+export * from './load-failure.js';
 export * from './runtime.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/llamacpp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/llamacpp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA"}

package/dist/runtime/llamacpp/load-failure.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What a failed llama.cpp load carries beyond its error body: the `atomic-core-diag` line the app
+ * reads from the tail of `details` (`src/contracts/load-diag.ts`), the stage the load stopped at, and
+ * whether the failure is one a single retry on another installed build may get past. Pure; the
+ * runtime gathers the facts while it spawns.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import type { LoadDiag } from '../../contracts/index.js';
+export declare function isWeightsLoadedLine(line: string): boolean;
+/**
+ * Where a load stopped. `spawn`: the process never ran its own code — it could not be started, the
+ * Windows loader refused it, or it exited without printing a line. `load`: it died or timed out while
+ * loading the weights. `ready`: the weights were loaded and it never said it was listening.
+ * `runtime`: it had said so, and the load failed after that.
+ */
+export declare function loadFailureStage(input: {
+    code: string;
+    printed: boolean;
+    weightsLoaded: boolean;
+    ready: boolean;
+}): NonNullable<LoadDiag['stage']>;
+/**
+ * `error` with the diag line appended to its details (replacing an earlier one) and `engineVersion`
+ * added to its telemetry diagnostic. Anything that is not an `AtomicCoreError`, a cancel and a stop
+ * are returned as they are.
+ */
+export declare function withLoadFailureDiag(error: unknown, diag: LoadDiag, engineVersion?: string): unknown;
+/** The diag line of one spawn attempt, from the error and what the runtime saw of the process. */
+export declare function attemptLoadDiag(error: AtomicCoreError, facts: {
+    platform: NodeJS.Platform;
+    backend: string;
+    version: string;
+    printed: boolean;
+    stderrPrinted: boolean;
+    weightsLoaded: boolean;
+    ready: boolean;
+}): LoadDiag;
+/** What made a load try another build: the reason recorded against the build that failed. */
+export type BackendFallbackTrigger = 'GPU_BACKEND_INCOMPATIBLE' | 'ENGINE_BINARY_BROKEN' | 'EMPTY_STDERR_CRASH';
+/**
+ * Whether a failed load may be retried once on the next installed build, and why: the build cannot
+ * run on this card or driver; or, on a GPU build, Windows could not start it, or it died before
+ * printing anything (an empty stderr: a missing DLL or an illegal instruction rather than the model).
+ * Reads the diag line the attempt left in `details`.
+ */
+export declare function backendFallbackTrigger(error: unknown, backend: string): BackendFallbackTrigger | undefined;
+/** The diag of the error a load ends with after a fallback, the fallback's own facts kept. */
+export declare function withFallbackDiag(error: unknown, fallback: {
+    from: string;
+    to: string;
+    ok: boolean;
+}): unknown;

package/dist/runtime/llamacpp/load-failure.js

@@ -0,0 +1,105 @@
+/**
+ * What a failed llama.cpp load carries beyond its error body: the `atomic-core-diag` line the app
+ * reads from the tail of `details` (`src/contracts/load-diag.ts`), the stage the load stopped at, and
+ * whether the failure is one a single retry on another installed build may get past. Pure; the
+ * runtime gathers the facts while it spawns.
+ */
+import { AtomicCoreError, parseLoadDiag, withLoadDiag } from '../../contracts/index.js';
+import { formatExitCode } from './errors.js';
+/** What llama-server prints once the weights are in memory, before it starts listening. */
+const WEIGHTS_LOADED = /\bmodel loaded\b/i;
+export function isWeightsLoadedLine(line) {
+    return WEIGHTS_LOADED.test(line);
+}
+/**
+ * Where a load stopped. `spawn`: the process never ran its own code — it could not be started, the
+ * Windows loader refused it, or it exited without printing a line. `load`: it died or timed out while
+ * loading the weights. `ready`: the weights were loaded and it never said it was listening.
+ * `runtime`: it had said so, and the load failed after that.
+ */
+export function loadFailureStage(input) {
+    if (input.ready)
+        return 'runtime';
+    if (input.code === 'IO_ERROR' || input.code === 'ENGINE_BINARY_BROKEN')
+        return 'spawn';
+    if (input.weightsLoaded)
+        return 'ready';
+    if (input.code === 'MODEL_LOAD_TIMED_OUT' || input.printed)
+        return 'load';
+    return 'spawn';
+}
+/** Errors that end a load without being a failure of it: the user's cancel, the owner stopping. */
+const NOT_LOAD_FAILURES = new Set(['MODEL_LOAD_CANCELLED', 'CORE_NOT_RUNNING']);
+/**
+ * `error` with the diag line appended to its details (replacing an earlier one) and `engineVersion`
+ * added to its telemetry diagnostic. Anything that is not an `AtomicCoreError`, a cancel and a stop
+ * are returned as they are.
+ */
+export function withLoadFailureDiag(error, diag, engineVersion) {
+    if (!(error instanceof AtomicCoreError) || NOT_LOAD_FAILURES.has(error.code))
+        return error;
+    const diagnostic = error.diagnostic
+        ? { ...error.diagnostic, ...(engineVersion ? { engineVersion } : {}) }
+        : engineVersion
+            ? { component: 'runtime', operation: 'load', engineVersion }
+            : undefined;
+    const wrapped = new AtomicCoreError(error.code, error.message, withLoadDiag(error.details, diag), {
+        ...(diagnostic ? { diagnostic } : {}),
+        ...(error.cause !== undefined ? { cause: error.cause } : {}),
+    });
+    if (error.stack)
+        wrapped.stack = error.stack;
+    return wrapped;
+}
+/** The diag line of one spawn attempt, from the error and what the runtime saw of the process. */
+export function attemptLoadDiag(error, facts) {
+    const exitCode = error.diagnostic?.exitCode;
+    const signal = error.diagnostic?.signal;
+    const exit = typeof exitCode === 'number' ? formatExitCode(exitCode, facts.platform) : undefined;
+    return {
+        ...(exit !== undefined ? { exit_code: exit } : {}),
+        ...(typeof signal === 'string' ? { signal } : {}),
+        stage: loadFailureStage({ code: error.code, ...facts }),
+        backend: facts.backend,
+        // `cli` is the placeholder of an executable the CLI was pointed at, not a build tag.
+        ...(facts.version && facts.version !== 'cli' ? { build: facts.version } : {}),
+        ...(!facts.stderrPrinted ? { empty_stderr: true } : {}),
+    };
+}
+/** A build whose id names a GPU API; only these fall back on a broken binary or a silent crash. */
+const GPU_BUILD = /cuda|vulkan|rocm|hip|sycl|opencl|musa|cann/i;
+/**
+ * Whether a failed load may be retried once on the next installed build, and why: the build cannot
+ * run on this card or driver; or, on a GPU build, Windows could not start it, or it died before
+ * printing anything (an empty stderr: a missing DLL or an illegal instruction rather than the model).
+ * Reads the diag line the attempt left in `details`.
+ */
+export function backendFallbackTrigger(error, backend) {
+    if (!(error instanceof AtomicCoreError))
+        return undefined;
+    if (error.code === 'GPU_BACKEND_INCOMPATIBLE')
+        return 'GPU_BACKEND_INCOMPATIBLE';
+    if (!GPU_BUILD.test(backend))
+        return undefined;
+    if (error.code === 'ENGINE_BINARY_BROKEN')
+        return 'ENGINE_BINARY_BROKEN';
+    if (error.code !== 'LLAMA_CPP_PROCESS_ERROR' && error.code !== 'CPU_INSTRUCTION_UNSUPPORTED')
+        return undefined;
+    const diag = parseLoadDiag(error.details);
+    const died = (diag?.exit_code !== undefined && diag.exit_code !== '0' && diag.exit_code !== '0x0') ||
+        diag?.signal !== undefined;
+    return diag?.empty_stderr === true && died ? 'EMPTY_STDERR_CRASH' : undefined;
+}
+/** The diag of the error a load ends with after a fallback, the fallback's own facts kept. */
+export function withFallbackDiag(error, fallback) {
+    if (!(error instanceof AtomicCoreError) || NOT_LOAD_FAILURES.has(error.code))
+        return error;
+    const diag = {
+        ...(parseLoadDiag(error.details) ?? {}),
+        fallback_from: fallback.from,
+        fallback_to: fallback.to,
+        fallback_ok: fallback.ok,
+    };
+    return withLoadFailureDiag(error, diag);
+}
+//# sourceMappingURL=load-failure.js.map

package/dist/runtime/llamacpp/load-failure.js.map

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

package/dist/runtime/llamacpp/load-plan.d.ts

@@ -110,6 +110,11 @@ export interface LoadPlan {
     fitCtxCeiling?: number;
     /** `--cache-ram` (MiB) on a machine with at most 16 GiB of RAM; absent: llama.cpp's 8192 MiB. */
     cacheRamMiB?: number;
+    /**
+     * Set by the runtime on the plan of a backend fallback: the `version_backend` the settings asked for,
+     * which `config.version_backend` (the build that runs) no longer is.
+     */
+    configuredVersionBackend?: string;
     warnings: string[];
 }
 /** Which loaded text sessions to unload before loading `modelId` (auto-unload policy). */

package/dist/runtime/llamacpp/load-plan.js

@@ -13,8 +13,9 @@
 import { AtomicCoreError } from '../../contracts/index.js';
 import { effectiveCtxSize, estimateKvCache, firstGgufShardPath, ggufShardSetPaths, isMtpCapable, matchesMtpLoadFailure, parseGgufShard, } from '../../models/index.js';
 import { generateApiKey } from '../shared/index.js';
-import { withLlamacppDefaults } from './args.js';
+import { resolveFitCtx, withLlamacppDefaults } from './args.js';
 import { DEFAULT_CTX_LEN } from './ctx-ladder.js';
+import { validateDeviceList } from './devices.js';
 import { DEFAULT_FIT_CTX, DEFAULT_FIT_TARGET_MIB, metalDevice, smallMemoryDefaultCtx, smallUnifiedMemoryCtxCeiling, unifiedMemoryFitTargetMiB, } from './fit-margin.js';
 import { promptCacheRamMiB, resolveNPredict } from './generation-limits.js';
 import { BACKEND_NOT_CONFIGURED_MESSAGE, CPU_NO_AVX_ERROR_CODE, CPU_NO_AVX_MESSAGE, codedLoadError, formatLoadError, isCpuBackend, isUnsupportedNoAvxCpu, modelLoadReadyTimeoutSecs, parseBuildNumberStrict, parseEnvString, stripBom, } from './policy.js';
@@ -61,8 +62,9 @@ export async function planLlamaLoad(input, deps) {
         deps.warn?.(m);
     };
     const { modelId } = input;
-    // 2. settings merge (per-model overrides win)
+    // 2. settings merge (per-model overrides win; a model's `fit_ctx` only when it names a window)
     const cfg = withLlamacppDefaults({ ...input.config, ...(input.overrides ?? {}) });
+    cfg.fit_ctx = resolveFitCtx(input.config.fit_ctx, input.overrides?.fit_ctx);
     const env = {};
     // 3. `latest/<backend>` sentinel
     if (stripBom(cfg.version_backend || '').startsWith('latest/')) {
@@ -95,6 +97,33 @@ export async function planLlamaLoad(input, deps) {
     version = ready.version;
     backend = ready.backend;
     const exePath = ready.exePath;
+    // One `--list-devices` per executable and plan: the device check below and fit's Metal margin
+    // read the same list.
+    if (deps.listDevices) {
+        const listDevices = deps.listDevices;
+        const lists = new Map();
+        deps = {
+            ...deps,
+            listDevices: (path) => {
+                const listed = lists.get(path) ?? listDevices(path);
+                lists.set(path, listed);
+                return listed;
+            },
+        };
+    }
+    // 7b. a `--device` this build does not have would make llama-server exit; it is dropped instead.
+    // A device list that cannot be read changes nothing.
+    if (String(cfg.device ?? '').trim() !== '' && deps.listDevices) {
+        const devices = await deps.listDevices(exePath).catch(() => undefined);
+        if (devices) {
+            const checked = validateDeviceList(cfg.device, devices);
+            if (checked.dropped.length > 0) {
+                const listedIds = devices.map((d) => d.id).join(', ') || 'none';
+                warn(`Ignoring device ${checked.dropped.join(', ')} for "${modelId}": ${version}/${backend} does not have it (it lists ${listedIds}).`);
+                cfg.device = checked.device;
+            }
+        }
+    }
     // 8-9. model.yml, port, key, env
     const modelConfig = input.modelPath
         ? {
@@ -219,8 +248,9 @@ export async function planLlamaLoad(input, deps) {
             warn(`Unified memory: fitting "${modelId}" with a ${fit.marginMiB} MiB margin so llama.cpp leaves half of RAM to the system.`);
         }
         if (fit?.ctxCeiling !== undefined) {
-            fitCtxCeiling = fit.ctxCeiling;
-            warn(`Unified memory below 16 GiB: capping the window fit may pick for "${modelId}" at ${fit.ctxCeiling} tokens.`);
+            // Never below the floor fit is given (`fit_ctx`, which the app raises to grow the window).
+            fitCtxCeiling = Math.max(fit.ctxCeiling, fitMinCtx(cfg));
+            warn(`Unified memory below 16 GiB: capping the window fit may pick for "${modelId}" at ${fitCtxCeiling} tokens.`);
         }
     }
     // 19c. fit off with no window chosen: llama.cpp would take the whole trained context (`n_ctx = 0`,