@bendyline/gezel-inference 1.0.1 → 1.0.2

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

@@ -40,12 +40,12 @@
  * 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.49. */
+/** 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

package/dist/engines/native-manifest.js

@@ -40,45 +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.49. */
+/** 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.49-darwin-arm64-metal.tar.gz': 6895181,
-    'gezel-native-0.1.49-darwin-arm64.tar.gz': 41543602,
-    'gezel-native-0.1.49-linux-arm64-cpu.tar.gz': 8681742,
-    'gezel-native-0.1.49-linux-arm64-cuda.tar.gz': 618839431,
-    'gezel-native-0.1.49-linux-arm64.tar.gz': 41977168,
-    'gezel-native-0.1.49-linux-x64-cpu.tar.gz': 13085558,
-    'gezel-native-0.1.49-linux-x64-cuda.tar.gz': 987396266,
-    'gezel-native-0.1.49-linux-x64-vulkan.tar.gz': 27140717,
-    'gezel-native-0.1.49-linux-x64.tar.gz': 58057802,
-    'gezel-native-0.1.49-win32-arm64-cpu.zip': 5459336,
-    'gezel-native-0.1.49-win32-arm64.zip': 42048477,
-    'gezel-native-0.1.49-win32-x64-cpu.zip': 8603082,
-    'gezel-native-0.1.49-win32-x64-cuda.zip': 641853362,
-    'gezel-native-0.1.49-win32-x64-vulkan.zip': 22326156,
-    'gezel-native-0.1.49-win32-x64.zip': 56551783,
+    '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
 /**

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

@@ -6,6 +6,8 @@ import { streamSSE } from 'hono/streaming';
 import { z } from 'zod';
 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';
@@ -212,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

@@ -10,6 +10,7 @@ import { EXTERNAL_CONVERSATION_ID_HEADER, EXTERNAL_PROJECT_HEADER, EXTERNAL_WORK
 import { appendCallerOwnedActionLedger } from '../openai-compat/action-ledger.js';
 import { profileForCallerOwnedInference } from '../openai-compat/caller-owned-profile.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';
@@ -536,12 +537,13 @@ export function v1ChatRoutes(ctx, opts = {}) {
                             clientAborted,
                             error: describeErrorChain(err),
                         })}`);
+                        const failure = engineFailure(err);
                         await stream
                             .writeSSE({
                             data: JSON.stringify({
                                 error: err instanceof UnsupportedResponseFormatError
                                     ? { message, type: 'invalid_request_error', code: err.code }
-                                    : { message, type: 'server_error', code: 'provider_error' },
+                                    : { message, type: failure.type, code: failure.code },
                             }),
                         })
                             .catch((sseErr) => {
@@ -644,6 +646,13 @@ export function v1ChatRoutes(ctx, opts = {}) {
                 }, 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.js

@@ -1,6 +1,7 @@
-import { estimateManifestKvBytes, externalGezelModelId, isRecommendedModel, localContextFloorTokens, rateModelsForDevice, resolveDistributionProfile, } from '@bendyline/gezel';
+import { estimateManifestKvBytes, externalGezelModelId, isRecommendedModel, llamaCppBackendExclusion, localContextFloorTokens, rateModelsForDevice, resolveDistributionProfile, } from '@bendyline/gezel';
 import { resolveOnDeviceProvider } from '@bendyline/gezel/native';
 import { Hono } from 'hono';
+import { currentLlamaCppBackend } from '../../providers/llama-cpp/backend-health.js';
 import { CapacityBroker } from '../../providers/native/capacity-broker.js';
 import { detectMemoryProfileCached } from '../../system/memory.js';
 import { appleSystemModel } from '../openai-compat/apple-model.js';
@@ -59,14 +60,15 @@ function catalogBackend(manifest) {
     // Store hosts have no provisioned Python runtime. Only advertise models
     // backed by bundled native engines until a frozen MLX runtime ships.
     const store = resolveDistributionProfile().pythonProvisioning === 'frozen-only';
+    const llamaCpp = manifest.llamaCpp && !llamaCppBackendExclusion(manifest.llamaCpp, currentLlamaCppBackend());
     if (store)
-        return manifest.llamaCpp ? 'llama-cpp' : ds4;
+        return llamaCpp ? 'llama-cpp' : ds4;
     const preferred = resolveOnDeviceProvider(process.platform, process.arch);
     if (preferred === 'mlx' && manifest.mlx && !manifest.mlx.disabledReason)
         return 'mlx';
-    if (preferred === 'llama-cpp' && manifest.llamaCpp)
+    if (preferred === 'llama-cpp' && llamaCpp)
         return 'llama-cpp';
-    if (manifest.llamaCpp)
+    if (llamaCpp)
         return 'llama-cpp';
     if (manifest.mlx && !manifest.mlx.disabledReason && process.platform === 'darwin')
         return 'mlx';

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

@@ -8,6 +8,7 @@ import { ExternalToolsUnsupportedError, ModelNotInstalledError, } from '../../pr
 import { appendCallerOwnedActionLedger } from '../openai-compat/action-ledger.js';
 import { profileForCallerOwnedInference } from '../openai-compat/caller-owned-profile.js';
 import { resolveChatTarget, resolvePinnedModelTarget, } from '../openai-compat/chat-target.js';
+import { engineFailure } from '../openai-compat/engine-failure.js';
 import { runResponsesNonStreaming, runResponsesStreaming, } from '../openai-compat/responses-streaming.js';
 import { ResponsesRequestSchema, translateResponsesRequest, } from '../openai-compat/responses-translate.js';
 import { flattenTranscriptIntoPrompt, parseGezelModelRef, resolveModelTarget, } from '../openai-compat/translate.js';
@@ -221,7 +222,7 @@ export function v1ResponsesRoutes(ctx, opts = {}) {
                             event: 'error',
                             data: JSON.stringify({
                                 type: 'error',
-                                code: 'provider_error',
+                                code: engineFailure(err).code,
                                 message: 'The response stream ended unexpectedly.',
                                 param: null,
                             }),
@@ -264,6 +265,11 @@ export function v1ResponsesRoutes(ctx, opts = {}) {
                 return invalidRequest(c, err.message, err.code);
             }
             const message = err instanceof Error ? err.message : String(err);
+            const failure = engineFailure(err);
+            if (failure.code !== 'provider_error') {
+                log.warn(`Responses request 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/knowledge/catalog-host.d.ts

@@ -7,7 +7,7 @@
  * (docs/gezk-format.md). The in-process implementation is test/CLI-only;
  * production fails closed if its worker becomes unavailable.
  */
-import type { CatalogAssetFile, CatalogAssetInfo, CatalogAssetRead, CatalogChunkHit, CatalogDocumentMeta, CatalogTopic, CatalogValidationReport } from '@bendyline/gezel-knowledge';
+import type { CatalogAssetFile, CatalogAssetInfo, CatalogAssetRead, CatalogChunkHit, CatalogDocumentInitial, CatalogDocumentMeta, CatalogTopic, CatalogValidationReport } from '@bendyline/gezel-knowledge';
 import type { KnowledgeRadius } from '@bendyline/gezel';
 import type { SpatialMatch } from '@bendyline/gezel-knowledge';
 export interface MountSpec {
@@ -78,6 +78,14 @@ export interface KnowledgeCatalogHost {
         documents: CatalogDocumentMeta[];
         total: number;
     }>;
+    documentInitials(key: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): Promise<CatalogDocumentInitial[]>;
+    documentPosition(key: string, documentId: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): Promise<number | null>;
     nearbyDocuments(key: string, radius: KnowledgeRadius, opts: {
         offset?: number;
         limit?: number;

package/dist/knowledge/catalog-host.js

@@ -158,6 +158,8 @@ export async function createInProcessCatalogHost() {
         validate: async (rootDir, deep) => validateExtractedCatalog(rootDir, { deep }),
         topics: async (key) => mustGet(handles, key).topics(),
         documentsPage: async (key, opts) => mustGet(handles, key).documentsPage(opts),
+        documentInitials: async (key, opts) => mustGet(handles, key).documentInitials(opts),
+        documentPosition: async (key, documentId, opts) => mustGet(handles, key).documentPosition(documentId, opts),
         nearbyDocuments: async (key, radius, opts) => mustGet(handles, key).nearbyDocuments(radius, opts),
         getDocument: async (key, documentId) => mustGet(handles, key).getDocument(documentId),
         getChunk: async (key, documentId, chunkUid) => mustGet(handles, key).getChunk(documentId, chunkUid),

package/dist/knowledge/manager.d.ts

@@ -121,6 +121,12 @@ export declare class KnowledgeManager {
      * what the Knowledge screen's browser renders. Offline-safe: gilde is local.
      */
     available(): Promise<KnowledgeAvailableCatalog[]>;
+    /**
+     * The search model an install of a catalog with this profile would also
+     * download. None when the catalog searches with the daemon's own embedder
+     * (an install never fetches that) or the profile's pinned files are cached.
+     */
+    private searchModelDownloadBytes;
     /** Resolve a catalogId (URI authority) to its mounted info, or null. */
     mountedCatalog(catalogId: string): MountedInfo | null;
     /**
@@ -206,6 +212,14 @@ export declare class KnowledgeManager {
         limit?: number;
         descendants?: boolean;
     }): ReturnType<KnowledgeCatalogHost['documentsPage']>;
+    documentInitials(catalogId: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): ReturnType<KnowledgeCatalogHost['documentInitials']>;
+    documentPosition(catalogId: string, documentId: string, opts: {
+        topicId?: string;
+        descendants?: boolean;
+    }): ReturnType<KnowledgeCatalogHost['documentPosition']>;
     getDocument(catalogId: string, documentId: string): ReturnType<KnowledgeCatalogHost['getDocument']>;
     /** One passage by its citation id, with the document's title and origin. */
     getPassage(catalogId: string, documentId: string, chunkUid: string): Promise<KnowledgePassageRead | null>;

package/dist/knowledge/manager.js

@@ -13,7 +13,7 @@ import { readFile, readdir, rm, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { KnowledgeMachineInventorySchema, KnowledgeNearbyRequestSchema, createLogger, formatKnowledgeUri, parseKnowledgeUri, resolveSecurityPolicy, sameVectorSpace, } from '@bendyline/gezel';
-import { compareCatalogVersions, knowledgeEmbeddingProfile, readGezkManifest, } from '@bendyline/gezel-knowledge';
+import { compareCatalogVersions, knowledgeEmbeddingProfile, knowledgeProfileQueryModelBytes, missingPinnedFiles, readGezkManifest, } from '@bendyline/gezel-knowledge';
 import { knowledgeCatalogVersionDir, knowledgeCatalogsDir, knowledgeDownloadsDir, } from '@bendyline/gezel/paths';
 import { HANDBOEK_KNOWLEDGE_CATALOG, HANDBOEK_KNOWLEDGE_PUBLISHER } from './bundled-catalog.js';
 import { scoreResult } from '@bendyline/gezel';
@@ -21,10 +21,11 @@ import { sharedKnowledgeRoot, sharedKnowledgeVersionDir, } from '../machine-engi
 import { embedKnowledgeQuery, sharesDaemonEmbedder } from '../memory/embeddings.js';
 import { ChatModelInstallRegistry } from '../models/install-registry.js';
 import { beginPerfWork } from '../perf/responsiveness.js';
+import { HF_CACHE_DIR_ENV, transformersCacheDir } from '../transformers-cache.js';
 import { resolveKnowledgeCatalogSource } from './catalog-source.js';
 import { KNOWLEDGE_DOWNLOAD_KEY_PATTERN, installKnowledgeCatalog, knowledgeDownloadKey, pruneOtherKnowledgeCatalogVersions, } from './install.js';
 import { KnowledgeRegistry } from './registry.js';
-import { KnowledgeSpatialCursorError, encodeNearbyCursor, nearbyCursorOffset, regionalDocumentIdentity, } from './spatial-query.js';
+import { KnowledgeSpatialCursorError, encodeNearbyCursor, nearbyCursorOffset, spatialDocumentIdentity, } from './spatial-query.js';
 import { resolveKnowledgeVectorFloors } from './vector-floors.js';
 const log = createLogger('knowledge');
 /** Explicit-search shard budget (S) across every active catalog (§3.4). */
@@ -59,6 +60,9 @@ function semanticSearchModeFor(profile) {
         return 'profile';
     return 'keyword-only';
 }
+function searchModelOf(profile) {
+    return { profileId: profile.id, repo: profile.model.repo };
+}
 /**
  * Explicit search fuses three arms per catalog by reciprocal rank (k = 60):
  * the vector chunks (best chunk per document, by rerank cosine), the
@@ -409,10 +413,18 @@ export class KnowledgeManager {
         const shared = await this.sharedInventoryKeys();
         const activeIds = new Set(this.installs.active().map((a) => a.id));
         const partials = await this.partialDownloadKeys();
+        const modelBytes = new Map();
+        for (const item of gilde.values()) {
+            const profileId = item.embeddingProfile.id;
+            if (!modelBytes.has(profileId)) {
+                modelBytes.set(profileId, await this.searchModelDownloadBytes(profileId));
+            }
+        }
         return [...gilde.values()]
             .sort((a, b) => a.name.localeCompare(b.name))
             .map((item) => {
             const entry = registry.find((c) => c.ref.publisherId === item.publisherId && c.ref.catalogId === item.id);
+            const searchModelDownloadBytes = modelBytes.get(item.embeddingProfile.id);
             return {
                 id: item.id,
                 publisherId: item.publisherId,
@@ -451,9 +463,24 @@ export class KnowledgeManager {
                 sharedOnDevice: shared.has(`${item.publisherId}/${item.id}/${item.version}/${item.sha256}`),
                 installing: activeIds.has(item.id),
                 incompleteDownload: partials.has(item.sha256.slice(0, 16)),
+                ...(searchModelDownloadBytes ? { searchModelDownloadBytes } : {}),
             };
         });
     }
+    /**
+     * The search model an install of a catalog with this profile would also
+     * download. None when the catalog searches with the daemon's own embedder
+     * (an install never fetches that) or the profile's pinned files are cached.
+     */
+    async searchModelDownloadBytes(profileId) {
+        const profile = knowledgeEmbeddingProfile(profileId);
+        const bytes = knowledgeProfileQueryModelBytes(profileId);
+        if (!profile || bytes === null || semanticSearchModeFor(profile) !== 'profile')
+            return undefined;
+        const cacheDir = process.env[HF_CACHE_DIR_ENV] ?? transformersCacheDir(this.opts.home);
+        const missing = await missingPinnedFiles(profile, { cacheDir });
+        return missing.length > 0 ? bytes : undefined;
+    }
     /** Resolve a catalogId (URI authority) to its mounted info, or null. */
     mountedCatalog(catalogId) {
         for (const info of this.mountedByKey.values()) {
@@ -676,7 +703,13 @@ export class KnowledgeManager {
         let warning;
         const mounted = this.mountedByKey.get(key);
         if (mounted?.semanticSearch === 'profile') {
-            yield { type: 'progress', phase: 'embedder', bytesDone: 0, bytesTotal: 0 };
+            yield {
+                type: 'progress',
+                phase: 'embedder',
+                bytesDone: 0,
+                bytesTotal: 0,
+                searchModel: searchModelOf(mounted.embedding),
+            };
             warning = yield* this.prewarmProfile(mounted.embedding);
         }
         yield { ...event, ...(warning ? { warning } : {}) };
@@ -746,7 +779,12 @@ export class KnowledgeManager {
                     (settled || Date.now() - lastReportAt >= EMBEDDER_PROGRESS_INTERVAL_MS)) {
                     progress.reported = latest;
                     lastReportAt = Date.now();
-                    yield { type: 'progress', phase: 'embedder', ...latest };
+                    yield {
+                        type: 'progress',
+                        phase: 'embedder',
+                        ...latest,
+                        searchModel: searchModelOf(profile),
+                    };
                     continue;
                 }
                 if (settled)
@@ -802,6 +840,9 @@ export class KnowledgeManager {
                 phase,
                 bytesDone: lastEvent?.type === 'progress' ? lastEvent.bytesDone : 0,
                 bytesTotal: lastEvent?.type === 'progress' ? lastEvent.bytesTotal : 0,
+                ...(lastEvent?.type === 'progress' && lastEvent.searchModel
+                    ? { searchModel: lastEvent.searchModel }
+                    : {}),
             };
         });
     }
@@ -1035,6 +1076,12 @@ export class KnowledgeManager {
     async documentsPage(catalogId, opts) {
         return this.opts.host.documentsPage(this.requireMounted(catalogId).key, opts);
     }
+    async documentInitials(catalogId, opts) {
+        return this.opts.host.documentInitials(this.requireMounted(catalogId).key, opts);
+    }
+    async documentPosition(catalogId, documentId, opts) {
+        return this.opts.host.documentPosition(this.requireMounted(catalogId).key, documentId, opts);
+    }
     async getDocument(catalogId, documentId) {
         return this.opts.host.getDocument(this.requireMounted(catalogId).key, documentId);
     }
@@ -1145,7 +1192,7 @@ export class KnowledgeManager {
                             documentId: document.id,
                         }),
                     };
-                    const identity = regionalDocumentIdentity(info.ref.publisherId, info.ref.catalogId, document.id);
+                    const identity = spatialDocumentIdentity(info.ref.publisherId, info.ref.catalogId, document.id);
                     const previous = unique.get(identity);
                     if (!previous || result.distanceMeters < previous.distanceMeters)
                         unique.set(identity, result);
@@ -1383,7 +1430,7 @@ export class KnowledgeManager {
             const count = perCatalogCount.get(entry.catalogKey) ?? 0;
             if (capPerCatalog && count >= PER_CATALOG_CAP)
                 continue;
-            const spatialIdentity = regionalDocumentIdentity(info.ref.publisherId, info.ref.catalogId, entry.documentId);
+            const spatialIdentity = spatialDocumentIdentity(info.ref.publisherId, info.ref.catalogId, entry.documentId);
             if (opts.spatial && seenSpatial.has(spatialIdentity))
                 continue;
             const relevance = fusedRankRelevance(out.length);

package/dist/knowledge/search-worker.d.ts

@@ -12,6 +12,6 @@
  */
 export interface KnowledgeWorkerRequest {
     id: number;
-    op: 'mount' | 'unmount' | 'mounted' | 'prewarm' | 'validate' | 'topics' | 'documentsPage' | 'nearbyDocuments' | 'getDocument' | 'getChunk' | 'assets' | 'readAsset' | 'assetFile' | 'search' | 'dispose';
+    op: 'mount' | 'unmount' | 'mounted' | 'prewarm' | 'validate' | 'topics' | 'documentsPage' | 'documentInitials' | 'documentPosition' | 'nearbyDocuments' | 'getDocument' | 'getChunk' | 'assets' | 'readAsset' | 'assetFile' | 'search' | 'dispose';
     args: unknown[];
 }

package/dist/knowledge/spatial-query.d.ts

@@ -1,11 +1,10 @@
 /**
  * Radius pagination binds offsets to the authorized catalog snapshot and
  * query. Cursors confer no authority; the manager recalculates scope on
- * every request. Regional replicas share identity only under Qualla's
- * declared regional catalog and source-document naming convention.
+ * every request.
  */
 export declare class KnowledgeSpatialCursorError extends Error {
 }
 export declare function encodeNearbyCursor(snapshot: string, offset: number): string;
 export declare function nearbyCursorOffset(cursor: string | undefined, snapshot: string): number;
-export declare function regionalDocumentIdentity(publisherId: string, catalogId: string, documentId: string): string;
+export declare function spatialDocumentIdentity(publisherId: string, catalogId: string, documentId: string): string;