@bendyline/gezel-inference 1.0.0 → 1.0.2

package/dist/engines/native-manifest.d.ts

@@ -40,17 +40,25 @@
  * but logs that it could not anchor to a baked-in digest.
  */
 /** Native release version this build pins. Placeholder until first public release. */
-export declare const NATIVE_ENGINE_RELEASE = "0.1.49";
+export declare const NATIVE_ENGINE_RELEASE = "0.1.51";
 /** sha256 of the pinned release's `SHA256SUMS` asset. All-zeros = unpinned. */
-export declare const SHA256SUMS_DIGEST = "51e9d1fcd18174967fed451d11a7401035076330dfedadd6a0ce396ab636cff7";
-/** Exact SHA256 values for every engine archive published by native-v0.1.49. */
+export declare const SHA256SUMS_DIGEST = "499a87aa18e113cdb52ee277bff71365e9176b63b536dbea7f3c2aa5ff5dbe68";
+/** Exact SHA256 values for every engine archive published by native-v0.1.51. */
 export declare const NATIVE_ENGINE_ARCHIVE_SHA256: Readonly<Record<string, string>>;
+/** Download size in bytes of every engine archive published by native-v0.1.51. */
+export declare const NATIVE_ENGINE_ARCHIVE_BYTES: Readonly<Record<string, number>>;
 /**
  * True only when the pinned release's standalone macOS archives were
  * Developer ID signed and accepted by Apple's notary service before
  * packaging. Electron notarization is a separate distribution contract.
  */
 export declare const NATIVE_ENGINE_MACOS_NOTARIZED = true;
+/**
+ * The download size of the archive the resolver fetches for this platform
+ * and variant, when this build pins it. Undefined under a dev release
+ * override, whose archives this build has no sizes for.
+ */
+export declare function pinnedEngineArchiveBytes(platformKey: string, variant: string | undefined, platform?: NodeJS.Platform): number | undefined;
 /** True when a sha256 hex string is the all-zeros placeholder. */
 export declare function isPlaceholderDigest(digest: string): boolean;
 /**

package/dist/engines/native-manifest.js

@@ -40,27 +40,45 @@
  * but logs that it could not anchor to a baked-in digest.
  */
 /** Native release version this build pins. Placeholder until first public release. */
-export const NATIVE_ENGINE_RELEASE = '0.1.49';
+export const NATIVE_ENGINE_RELEASE = '0.1.51';
 /** sha256 of the pinned release's `SHA256SUMS` asset. All-zeros = unpinned. */
-export const SHA256SUMS_DIGEST = '51e9d1fcd18174967fed451d11a7401035076330dfedadd6a0ce396ab636cff7';
+export const SHA256SUMS_DIGEST = '499a87aa18e113cdb52ee277bff71365e9176b63b536dbea7f3c2aa5ff5dbe68';
 // BEGIN PINNED NATIVE ARCHIVE HASHES
-/** Exact SHA256 values for every engine archive published by native-v0.1.49. */
+/** Exact SHA256 values for every engine archive published by native-v0.1.51. */
 export const NATIVE_ENGINE_ARCHIVE_SHA256 = Object.freeze({
-    'gezel-native-0.1.49-darwin-arm64-metal.tar.gz': 'a484487893151fdbe1ba5b3ea9d4dff3692efe8735e0a681d8f4ab84d5ffb09d',
-    'gezel-native-0.1.49-darwin-arm64.tar.gz': '7dc049ffd09dfb51befbf5c955e569556de6024991478eeb6900646e4672c723',
-    'gezel-native-0.1.49-linux-arm64-cpu.tar.gz': '19490ce26e843c2cab7321b91f9fac781ab3bab9ade6e3945543b312bf1a29e8',
-    'gezel-native-0.1.49-linux-arm64-cuda.tar.gz': '6802852803b0748d7ced99805a8aac281637f8816d02937460e64fbcd8da0637',
-    'gezel-native-0.1.49-linux-arm64.tar.gz': '8d3cd77b5c029fc0c4b4ae83000a72450008973eaf69168c4a21c58bfb75bf33',
-    'gezel-native-0.1.49-linux-x64-cpu.tar.gz': '030eaf798727ab13dcd7e7f4b3124c0f02e6f638e58f81c5d9a399c57d1c0a0a',
-    'gezel-native-0.1.49-linux-x64-cuda.tar.gz': 'd31d21d0c4c5504c9f29eaed32b500b26676bec0fd5ed23fdfd598baecafd748',
-    'gezel-native-0.1.49-linux-x64-vulkan.tar.gz': '114956cb94d174f00105f86b97ba932e1583cac80d9d0ab6b0edf396ea410506',
-    'gezel-native-0.1.49-linux-x64.tar.gz': 'd6a711c2be9329b00ad6bb20e4c16062677ef4d5804a2033d579b2347f5e2802',
-    'gezel-native-0.1.49-win32-arm64-cpu.zip': 'c2e8f10a45bae6cee4801845b605588c5b8b7b3c2e81a512e89296a2f9b7afce',
-    'gezel-native-0.1.49-win32-arm64.zip': '23173db21533dfe3f3189f5582cde9a0550859515b2c94688fb34d342d97e3e5',
-    'gezel-native-0.1.49-win32-x64-cpu.zip': 'cf6a8806e2c2b0a964804169cfb3d9283032536a6c262dc70b65a37b45451f3e',
-    'gezel-native-0.1.49-win32-x64-cuda.zip': '9a1e090829cf2f16389e1a01506853d8ac3ed151a32994831000c1c3658cef08',
-    'gezel-native-0.1.49-win32-x64-vulkan.zip': '0b7fe1cab3b881ac4a5cc24f08b0206c38edab30940ea79888a70776925a8bfb',
-    'gezel-native-0.1.49-win32-x64.zip': 'e8996f82ea358903010e050d6b8b93beec683286af512b11cd8eeefdea50aa6d',
+    'gezel-native-0.1.51-darwin-arm64-metal.tar.gz': '5abbfd156fbcc717da96c89dc5baa507a56d2b55b501f1a975803a763e6414c4',
+    'gezel-native-0.1.51-darwin-arm64.tar.gz': '799bca88b0ea10aeb2dad9ed3065c9396f42383a6fd5c7347ed76abf0706f128',
+    'gezel-native-0.1.51-linux-arm64-cpu.tar.gz': '1612e5928693262884bcc2c60ba3975af4dc4267c2bd75597ef91e83681fa96e',
+    'gezel-native-0.1.51-linux-arm64-cuda.tar.gz': '4a457df5dbb8475ca0eb2f1a2373f1960bbb3f86a0ecd938a407f884cd6026a2',
+    'gezel-native-0.1.51-linux-arm64.tar.gz': '2aaead65bfd42ffef9a1f45a70fa24095bc2814842750536989cbcb7a9a0db24',
+    'gezel-native-0.1.51-linux-x64-cpu.tar.gz': '7453d6a3ef2de7ece967a033d5bd634789e41edefa4a823b580329f0ad98abb0',
+    'gezel-native-0.1.51-linux-x64-cuda.tar.gz': 'ac1054a33339bcf6167c309b867f5671def58e036bb612978c4a434cd7ac39d6',
+    'gezel-native-0.1.51-linux-x64-vulkan.tar.gz': '6739c9dca6cbcf53fb5d69dbd342ac6be49fe2f0d86471d66975e61a64c95e9f',
+    'gezel-native-0.1.51-linux-x64.tar.gz': 'a176ac570131db874e0a81fdec939415dd161a639827219a82f2a610f5ebd8d3',
+    'gezel-native-0.1.51-win32-arm64-cpu.zip': 'f79c0c8490d46f2d60e73fd948bf74ae93dfc7c650a878f7db5e227bbdbb85b9',
+    'gezel-native-0.1.51-win32-arm64.zip': 'c829c9c1fd08756aff9e677ea1addcf80a8739f13df3c9b6788a6237e53efacb',
+    'gezel-native-0.1.51-win32-x64-cpu.zip': 'f8e0ffeacc8aeea1f2fc91024382bdcdaeeeb65b8a45935af422acb4d7027190',
+    'gezel-native-0.1.51-win32-x64-cuda.zip': '6bd7dc2c43443a847058a4c4f1c53281c99563c214394a92470281a70f725d1e',
+    'gezel-native-0.1.51-win32-x64-vulkan.zip': 'e20fb148c854f267aa50981525e337c38d3ee496fd483393a676251d9c0a496f',
+    'gezel-native-0.1.51-win32-x64.zip': 'ca5d7866fa2ff2e89da9267fcb409eb9aff01ef1c43ed726327e4967d3ed5e56',
+});
+/** Download size in bytes of every engine archive published by native-v0.1.51. */
+export const NATIVE_ENGINE_ARCHIVE_BYTES = Object.freeze({
+    'gezel-native-0.1.51-darwin-arm64-metal.tar.gz': 7056609,
+    'gezel-native-0.1.51-darwin-arm64.tar.gz': 41556782,
+    'gezel-native-0.1.51-linux-arm64-cpu.tar.gz': 8836261,
+    'gezel-native-0.1.51-linux-arm64-cuda.tar.gz': 619480627,
+    'gezel-native-0.1.51-linux-arm64.tar.gz': 41979458,
+    'gezel-native-0.1.51-linux-x64-cpu.tar.gz': 12914417,
+    'gezel-native-0.1.51-linux-x64-cuda.tar.gz': 989771250,
+    'gezel-native-0.1.51-linux-x64-vulkan.tar.gz': 25672179,
+    'gezel-native-0.1.51-linux-x64.tar.gz': 58057226,
+    'gezel-native-0.1.51-win32-arm64-cpu.zip': 5618599,
+    'gezel-native-0.1.51-win32-arm64.zip': 42055408,
+    'gezel-native-0.1.51-win32-x64-cpu.zip': 8714418,
+    'gezel-native-0.1.51-win32-x64-cuda.zip': 749850276,
+    'gezel-native-0.1.51-win32-x64-vulkan.zip': 21123169,
+    'gezel-native-0.1.51-win32-x64.zip': 56558016,
 });
 // END PINNED NATIVE ARCHIVE HASHES
 /**
@@ -69,6 +87,18 @@ export const NATIVE_ENGINE_ARCHIVE_SHA256 = Object.freeze({
  * packaging. Electron notarization is a separate distribution contract.
  */
 export const NATIVE_ENGINE_MACOS_NOTARIZED = true;
+/**
+ * The download size of the archive the resolver fetches for this platform
+ * and variant, when this build pins it. Undefined under a dev release
+ * override, whose archives this build has no sizes for.
+ */
+export function pinnedEngineArchiveBytes(platformKey, variant, platform = process.platform) {
+    if (effectiveEngineRelease() !== NATIVE_ENGINE_RELEASE)
+        return undefined;
+    const key = variant ? `${platformKey}-${variant}` : platformKey;
+    const ext = platform === 'win32' ? 'zip' : 'tar.gz';
+    return NATIVE_ENGINE_ARCHIVE_BYTES[`gezel-native-${NATIVE_ENGINE_RELEASE}-${key}.${ext}`];
+}
 /** True when a sha256 hex string is the all-zeros placeholder. */
 export function isPlaceholderDigest(digest) {
     return /^0{64}$/.test(digest.trim().toLowerCase());

package/dist/http/openai-compat/apple-model.d.ts

@@ -1,3 +1,5 @@
 import type { AppModel } from '@bendyline/gezel/app-models';
+/** @internal Lets tests list models under a changed Apple status. */
+export declare function resetAppleStatusCache(): void;
 /** Inventory owns system readiness, so embedders never speak the native helper protocol. */
 export declare function appleSystemModel(created: number): Promise<AppModel[]>;

package/dist/http/openai-compat/apple-model.js

@@ -1,7 +1,27 @@
 import { appleFoundationModelsStatus } from '../../providers/apple-foundation-models/status.js';
+/**
+ * How long listings reuse Apple's readiness. Each check launches the
+ * `gezel-apple-fm` helper for one handshake (26-59 ms measured), and the SDK's
+ * `streamText` lists models before every call, so a fresh check per listing
+ * cost a process launch per chat. Short enough that Apple Intelligence
+ * enabled in System Settings shows up almost at once.
+ */
+const STATUS_TTL_MS = 10_000;
+let cachedStatus = null;
+/** Concurrent listings share one in-flight check. */
+function appleStatus() {
+    const now = Date.now();
+    if (!cachedStatus || now - cachedStatus.at > STATUS_TTL_MS)
+        cachedStatus = { at: now, status: appleFoundationModelsStatus() };
+    return cachedStatus.status;
+}
+/** @internal Lets tests list models under a changed Apple status. */
+export function resetAppleStatusCache() {
+    cachedStatus = null;
+}
 /** Inventory owns system readiness, so embedders never speak the native helper protocol. */
 export async function appleSystemModel(created) {
-    const status = await appleFoundationModelsStatus();
+    const status = await appleStatus();
     if (!status.supported || !status.installed)
         return [];
     return [

package/dist/http/openai-compat/chat-target.d.ts

@@ -43,6 +43,18 @@ export type ChatTargetInput = {
     provider: ProviderName;
     model: string | undefined;
 };
+/**
+ * The on-device model a bare id names, when this install pins it as a default.
+ *
+ * `ensureModel` hands an app the bare id it asked for (`qwen3.5-0.8b-q4`) and
+ * pins it; an inference-only host, which has no gezel to fall back to, then
+ * answered that id with "Unknown model". Only a pin is trusted, so an unpinned
+ * bare id still reaches the serving gezel like any other unknown string. When
+ * several engines pin the same id, the configured provider decides. A cloud
+ * provider's pin never matches: an app's hardcoded `gpt-4o` must reach the
+ * serving gezel, not leave the machine because it equals the OpenAI default.
+ */
+export declare function resolvePinnedModelTarget(ctx: ServiceContext, model: string): Promise<ChatTarget | null>;
 /**
  * Pick the gezel that guarantees a persona-backed fallback for public
  * inference requests.

package/dist/http/openai-compat/chat-target.js

@@ -1,4 +1,30 @@
-import { externalGezelModelId } from '@bendyline/gezel';
+import { externalGezelModelId, isLocalProvider } from '@bendyline/gezel';
+import { resolveModelTarget } from './translate.js';
+/**
+ * The on-device model a bare id names, when this install pins it as a default.
+ *
+ * `ensureModel` hands an app the bare id it asked for (`qwen3.5-0.8b-q4`) and
+ * pins it; an inference-only host, which has no gezel to fall back to, then
+ * answered that id with "Unknown model". Only a pin is trusted, so an unpinned
+ * bare id still reaches the serving gezel like any other unknown string. When
+ * several engines pin the same id, the configured provider decides. A cloud
+ * provider's pin never matches: an app's hardcoded `gpt-4o` must reach the
+ * serving gezel, not leave the machine because it equals the OpenAI default.
+ */
+export async function resolvePinnedModelTarget(ctx, model) {
+    const id = model.trim();
+    if (!id)
+        return null;
+    const config = await ctx.store.readConfig().catch(() => null);
+    const pins = Object.entries(config?.defaultModel ?? {}).filter(([provider, pinned]) => pinned === id &&
+        isLocalProvider(provider) &&
+        resolveModelTarget(`${provider}:${id}`) !== null);
+    const chosen = pins.find(([provider]) => provider === config?.provider) ??
+        (pins.length === 1 ? pins[0] : undefined);
+    if (!chosen)
+        return null;
+    return { provider: chosen[0], model: id, systemPrefix: '' };
+}
 /**
  * Pick the gezel that guarantees a persona-backed fallback for public
  * inference requests.

package/dist/http/openai-compat/engine-failure.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The OpenAI-compatible routes' vocabulary for an on-device engine failure.
+ *
+ * Providers already throw typed errors that say exactly what went wrong: the
+ * capacity broker refused the model's memory, the engine crashed, the prompt
+ * overflowed its context. These routes kept only the message and stamped every
+ * one `provider_error`, so a connected app could not tell "this machine cannot
+ * fit the model" from "try again in a second" without parsing prose — and the
+ * prose is exactly what a sanitizing proxy strips. Each internal code maps to
+ * one stable wire code here; anything unrecognized stays `provider_error`.
+ */
+export type EngineFailureCode = 'capacity_denied' | 'engine_busy' | 'engine_launch_failed' | 'engine_crashed' | 'engine_out_of_memory' | 'context_length_exceeded' | 'engine_not_ready' | 'model_not_ready';
+export interface EngineFailure {
+    code: EngineFailureCode | 'provider_error';
+    type: 'server_error' | 'invalid_request_error';
+    status: 400 | 500;
+}
+/**
+ * Stand-ins for an engine failure's own message wherever a response body must
+ * not carry internal detail (the service's opaque-error middleware). The
+ * provider's message can name binaries and model paths.
+ */
+export declare const ENGINE_FAILURE_SUMMARIES: Readonly<Record<EngineFailureCode, string>>;
+export declare function isEngineFailureCode(value: unknown): value is EngineFailureCode;
+export declare function engineFailure(err: unknown): EngineFailure;

package/dist/http/openai-compat/engine-failure.js

@@ -0,0 +1,76 @@
+/**
+ * The OpenAI-compatible routes' vocabulary for an on-device engine failure.
+ *
+ * Providers already throw typed errors that say exactly what went wrong: the
+ * capacity broker refused the model's memory, the engine crashed, the prompt
+ * overflowed its context. These routes kept only the message and stamped every
+ * one `provider_error`, so a connected app could not tell "this machine cannot
+ * fit the model" from "try again in a second" without parsing prose — and the
+ * prose is exactly what a sanitizing proxy strips. Each internal code maps to
+ * one stable wire code here; anything unrecognized stays `provider_error`.
+ */
+/** Internal error `code` (as thrown) → wire code (as sent). */
+const WIRE_CODES = new Map([
+    ['capacity-denied', 'capacity_denied'],
+    ['engine-busy', 'engine_busy'],
+    ['engine-launch', 'engine_launch_failed'],
+    ['native-engine-crash', 'engine_crashed'],
+    ['context-overflow', 'context_length_exceeded'],
+    ['engine-not-ready', 'engine_not_ready'],
+    ['model-not-ready', 'model_not_ready'],
+]);
+/**
+ * Stand-ins for an engine failure's own message wherever a response body must
+ * not carry internal detail (the service's opaque-error middleware). The
+ * provider's message can name binaries and model paths.
+ */
+export const ENGINE_FAILURE_SUMMARIES = {
+    capacity_denied: 'This machine does not have enough free memory to run this model right now.',
+    engine_busy: 'The on-device engine is busy with another request. Try again shortly.',
+    engine_launch_failed: 'The on-device engine could not be started on this machine.',
+    engine_crashed: 'The on-device engine stopped unexpectedly. Try again.',
+    engine_out_of_memory: 'This computer ran out of memory and the on-device engine was stopped. Close other programs or use a smaller model, then try again.',
+    context_length_exceeded: 'The prompt is longer than this model can read at once.',
+    engine_not_ready: 'The on-device engine is still getting ready. Try again shortly.',
+    model_not_ready: 'This model is not ready yet.',
+};
+export function isEngineFailureCode(value) {
+    return typeof value === 'string' && Object.hasOwn(ENGINE_FAILURE_SUMMARIES, value);
+}
+const MAX_CAUSE_DEPTH = 5;
+/**
+ * The outermost recognized code wins: a wrapper such as
+ * `NativeEngineCrashedError` is the provider's own classification of the
+ * cause it carries.
+ */
+function internalCode(err) {
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+        if (!current || typeof current !== 'object' || seen.has(current))
+            return undefined;
+        seen.add(current);
+        const code = current.code;
+        const wire = typeof code === 'string' ? WIRE_CODES.get(code) : undefined;
+        // A crash the out-of-memory killer caused is a capacity fact, not a fault.
+        if (wire === 'engine_crashed' &&
+            current.panicKind === 'host-out-of-memory') {
+            return 'engine_out_of_memory';
+        }
+        if (wire)
+            return wire;
+        current = current.cause;
+    }
+    return undefined;
+}
+export function engineFailure(err) {
+    const code = internalCode(err);
+    if (!code)
+        return { code: 'provider_error', type: 'server_error', status: 500 };
+    // OpenAI's own spelling and status for an over-long prompt. A 500 makes
+    // every SDK retry a request that cannot fit no matter how often it is sent.
+    if (code === 'context_length_exceeded') {
+        return { code, type: 'invalid_request_error', status: 400 };
+    }
+    return { code, type: 'server_error', status: 500 };
+}

package/dist/http/openai-compat/responses-streaming.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { engineFailure } from './engine-failure.js';
 import { unwrapCustomToolInput } from './responses-translate.js';
 const DEFAULT_LIMITS = {
     maxOutputTextChars: 4_000_000,
@@ -673,7 +674,7 @@ export async function runResponsesStreaming(session, prompt, echoModel, sink, no
     }
     catch (error) {
         options.onProviderError?.(error);
-        enqueue(serializer.fail('The model provider failed while generating this response.', 'provider_error'));
+        enqueue(serializer.fail('The model provider failed while generating this response.', engineFailure(error).code));
     }
     finally {
         unsubscribeDelta();

package/dist/http/openai-compat/responses-translate.d.ts

@@ -134,8 +134,8 @@ export declare const ResponsesRequestSchema: z.ZodObject<{
     }, z.core.$loose>]>>>;
     tool_choice: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
         none: "none";
-        auto: "auto";
         required: "required";
+        auto: "auto";
     }>, z.ZodObject<{
         type: z.ZodEnum<{
             function: "function";

package/dist/http/openai-compat/translate.d.ts

@@ -121,8 +121,8 @@ export declare const ChatCompletionRequestSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
         none: "none";
-        auto: "auto";
         required: "required";
+        auto: "auto";
     }>, z.ZodObject<{
         type: z.ZodLiteral<"function">;
         function: z.ZodObject<{

package/dist/http/routes/engines.js

@@ -4,8 +4,10 @@ import { resolvePlatformKey } from '@bendyline/gezel/native';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { z } from 'zod';
-import { effectiveEngineRelease, isEnginePinned } from '../../engines/native-manifest.js';
+import { effectiveEngineRelease, isEnginePinned, pinnedEngineArchiveBytes, } from '../../engines/native-manifest.js';
 import { KNOWN_ENGINES, isKnownEngine } from '../../engines/registry.js';
+import { llamaBackendHealthView } from '../../providers/llama-cpp/backend-health.js';
+import { isLlamaBackend, liftLlamaQuarantine, llamaQuarantineView, } from '../../providers/llama-cpp/backend-quarantine.js';
 import { EngineBusyError } from '../../providers/native/capacity-broker.js';
 import { invalidateModelsCache } from '../model-inventory-cache.js';
 import { isMachineEngineProvider, machineEngineProxy } from './machine-engine-proxy.js';
@@ -39,17 +41,23 @@ export function enginesRoutes(ctx) {
     app.get('/binaries/status', (c) => {
         const backendRaw = process.env.GEZEL_LLAMA_SERVER_BACKEND ?? process.env.GEZEL_LLAMA_DETECTED_BACKEND;
         const llamaBackend = ['cuda', 'vulkan', 'metal', 'cpu'].find((value) => value === backendRaw);
+        const platformKey = resolvePlatformKey();
         return c.json({
             release: effectiveEngineRelease(),
             pinned: isEnginePinned(),
-            platformKey: resolvePlatformKey(),
+            platformKey,
             ...(llamaBackend ? { llamaBackend } : {}),
             engines: KNOWN_ENGINES.map((name) => {
                 const path = process.env[ENGINE_ENV_VAR[name]];
+                const installed = !!path && existsSync(path);
+                const downloadBytes = !installed && name === 'llama-server' && platformKey && llamaBackend
+                    ? pinnedEngineArchiveBytes(platformKey, llamaBackend)
+                    : undefined;
                 return {
                     name,
-                    installed: !!path && existsSync(path),
+                    installed,
                     ...(path ? { path } : {}),
+                    ...(downloadBytes ? { downloadBytes } : {}),
                 };
             }),
         });
@@ -206,6 +214,39 @@ export function enginesRoutes(ctx) {
         }
         return c.json({ policy: effective });
     });
+    /**
+     * llama-server builds switched off on this machine after crashing while
+     * starting, and the undo behind the engine's Settings tab. Engine-owner
+     * state like the policies above: the quarantine file lives in the home of
+     * the process that launches the engines, so packaged user daemons proxy
+     * this to the machine engine.
+     */
+    app.get('/llama-cpp/quarantine', (c) => c.json(llamaQuarantineView(ctx.home)));
+    /**
+     * Whether llama-server is getting this machine's hardware: a CUDA build the
+     * driver cannot run, a GPU build that started without its GPU, the
+     * out-of-memory killer. Engine-owner state, proxied like the quarantine.
+     */
+    app.get('/llama-cpp/backend-health', (c) => c.json(llamaBackendHealthView()));
+    app.delete('/llama-cpp/quarantine/:backend', async (c) => {
+        const backend = c.req.param('backend');
+        if (!isLlamaBackend(backend)) {
+            return c.json({ error: 'backend must be "cuda", "vulkan", "metal", or "cpu"' }, 400);
+        }
+        const override = (await ctx.store.readConfig()).llamaCppBackendOverride;
+        const { restored } = liftLlamaQuarantine(ctx.home, backend, {
+            pinned: override !== undefined && override !== 'auto',
+        });
+        if (restored) {
+            log.info(`llama-server ${backend} quarantine lifted; next launch uses ${restored.path}`);
+            // Engines resolve their binary when the provider is built, so a resident
+            // engine keeps running the fallback until it restarts. Same soft reset
+            // as the policies above: idle engines go now, busy ones after their turn.
+            invalidateModelsCache();
+            await ctx.chat.resetClient({ deferBusy: true });
+        }
+        return c.json(llamaQuarantineView(ctx.home));
+    });
     /**
      * Per-model context overrides (Settings → Local models → Context size…).
      * Engine-owner state like the sizing policy above — packaged user daemons

package/dist/http/routes/v1-chat.js

@@ -3,12 +3,14 @@ import { createLogger, isLocalProvider } from '@bendyline/gezel';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { ZodError } from 'zod';
+import { UnsupportedResponseFormatError } from '../../providers/mlx/runtime-diagnostics.js';
 import { OLLAMA_TURN_TIMEOUT_MS } from '../../providers/turn-timeout.js';
 import { ExternalToolsUnsupportedError, ModelNotInstalledError, } from '../../providers/types.js';
 import { EXTERNAL_CONVERSATION_ID_HEADER, EXTERNAL_PROJECT_HEADER, EXTERNAL_WORKING_DIRECTORY_HEADER, } from '../external-conversation-headers.js';
 import { appendCallerOwnedActionLedger } from '../openai-compat/action-ledger.js';
 import { profileForCallerOwnedInference } from '../openai-compat/caller-owned-profile.js';
-import { resolveChatTarget, resolveFallbackGezelId } from '../openai-compat/chat-target.js';
+import { resolveChatTarget, resolveFallbackGezelId, resolvePinnedModelTarget, } from '../openai-compat/chat-target.js';
+import { engineFailure } from '../openai-compat/engine-failure.js';
 import { overlayOpenAiRequestTuning } from '../openai-compat/request-tuning.js';
 import { createStreamingDiagnostics, snapshotStreamingDiagnostics, } from '../openai-compat/streaming-telemetry.js';
 import { runNonStreaming, runStreaming } from '../openai-compat/streaming.js';
@@ -188,7 +190,11 @@ export function v1ChatRoutes(ctx, opts = {}) {
             }
             else {
                 const modelTarget = resolveModelTarget(parsed.model);
-                if (!modelTarget) {
+                const pinnedTarget = modelTarget ? null : await resolvePinnedModelTarget(ctx, parsed.model);
+                if (pinnedTarget) {
+                    target = pinnedTarget;
+                }
+                else if (!modelTarget) {
                     // Unknown model string (e.g. a client's hardcoded "gpt-4o").
                     // Route through the configured fallback gezel, or the Meester
                     // when no explicit override is set. Persona + tuning apply
@@ -199,7 +205,7 @@ export function v1ChatRoutes(ctx, opts = {}) {
                     if (!fallbackGezelId) {
                         return c.json({
                             error: {
-                                message: `Unknown model "${parsed.model}", and no gezel is available to answer it.`,
+                                message: `Unknown model "${parsed.model}", and no gezel is available to answer it. Use a <provider>:<model> id from GET /v1/models, such as "llama-cpp:${parsed.model}".`,
                                 type: 'invalid_request_error',
                                 code: 'gezel_not_found',
                             },
@@ -531,14 +537,13 @@ export function v1ChatRoutes(ctx, opts = {}) {
                             clientAborted,
                             error: describeErrorChain(err),
                         })}`);
+                        const failure = engineFailure(err);
                         await stream
                             .writeSSE({
                             data: JSON.stringify({
-                                error: {
-                                    message,
-                                    type: 'server_error',
-                                    code: 'provider_error',
-                                },
+                                error: err instanceof UnsupportedResponseFormatError
+                                    ? { message, type: 'invalid_request_error', code: err.code }
+                                    : { message, type: failure.type, code: failure.code },
                             }),
                         })
                             .catch((sseErr) => {
@@ -630,7 +635,24 @@ export function v1ChatRoutes(ctx, opts = {}) {
                     },
                 }, 400);
             }
+            if (err instanceof UnsupportedResponseFormatError) {
+                return c.json({
+                    error: {
+                        message: err.message,
+                        type: 'invalid_request_error',
+                        param: 'response_format',
+                        code: err.code,
+                    },
+                }, 400);
+            }
             const message = err instanceof Error ? err.message : String(err);
+            // Before the prose checks below: an engine's own message can contain
+            // "empty", and a typed failure says more than any substring does.
+            const failure = engineFailure(err);
+            if (failure.code !== 'provider_error') {
+                log.warn(`chat completion failed (${failure.code}): ${message}`);
+                return c.json({ error: { message, type: failure.type, code: failure.code } }, failure.status);
+            }
             if (message.includes('messages must') ||
                 message.includes('empty') ||
                 message.includes('cannot be an assistant turn')) {

package/dist/http/routes/v1-models.d.ts

@@ -1,8 +1,14 @@
 import { Hono } from 'hono';
+import { type MemoryProfile } from '../../system/memory.js';
 import type { InferenceContext as ServiceContext } from '../inference-context.js';
 interface V1ModelsRouteOptions {
     /** List only on-device engines plus downloadable on-device catalog entries. */
     localOnly?: boolean;
+    /**
+     * This machine's memory, which downloadable entries are rated against.
+     * Defaults to the cached probe `/api/system/memory` reads.
+     */
+    memoryProfile?: () => Promise<MemoryProfile>;
 }
 export declare function v1ModelsRoutes(ctx: ServiceContext, options?: V1ModelsRouteOptions): Hono;
 export {};