@bendyline/gezel-inference 1.0.0 → 1.0.1

package/dist/catalog/provenance.json

@@ -1,6 +1,6 @@
 {
   "package": "@bendyline/gilde",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "kinds": [
     "chat-models",
     "knowledge-catalogs"

package/dist/engines/electron-native-reuse.d.ts

@@ -35,6 +35,15 @@ export interface ElectronNativeReuseOptions {
      * this false so their parent app is also signature/notarization checked.
      */
     allowStandaloneMacPayload?: boolean;
+    /**
+     * Remember each pinned file that hashed to its pin, with its fingerprint
+     * (see file-fingerprint.ts in core), so a later call re-hashes only files
+     * whose metadata moved: `nativePayloadVerificationPath(home)`. Everything
+     * else still runs on every call, including the listing that rejects a
+     * loadable file the release does not pin. Keep it somewhere no easier to
+     * write than the payload itself: whoever can edit it can vouch for any bytes.
+     */
+    cacheFile?: string;
 }
 /**
  * Adopt Electron's extracted native payload, or an explicitly allowed

package/dist/engines/electron-native-reuse.js

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
-import { createReadStream } from 'node:fs';
-import { lstat, readdir, readlink } from 'node:fs/promises';
-import { basename, join, posix, relative, resolve, sep } from 'node:path';
-import { resolvePlatformKey } from '@bendyline/gezel/native';
+import { existsSync } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, readlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path';
+import { fileFingerprint, resolvePlatformKey, sameFileFingerprint, } from '@bendyline/gezel/native';
 import pinnedManifestJson from './native-file-manifest.json' with { type: 'json' };
 import { effectiveEngineRelease } from './native-manifest.js';
 import { BENDYLINE_APPLE_TEAM_ID, BENDYLINE_PUBLISHER, verifyCodeSignature } from './signature.js';
@@ -52,38 +52,89 @@ export async function verifyNativeBinaries(opts) {
             reason: `release ${release} has no pinned files for ${baseKey}`,
         };
     }
+    const cache = opts.cacheFile ? await readHashCache(opts.cacheFile) : null;
+    const pinnedCount = platformEntries.reduce((n, [, pin]) => n + Object.keys(pin.files).length, 0);
     const failures = [];
-    for (const candidate of opts.candidates) {
-        const startedAt = Date.now();
-        try {
-            await verifyCandidate({
-                root: candidate,
-                platform,
-                entries: platformEntries,
-                verifySignature: opts.verifySignature ?? verifyCodeSignature,
-                allowStandaloneMacPayload: opts.allowStandaloneMacPayload === true,
-            });
-            return {
-                reused: true,
-                nativeBinDir: resolve(candidate),
-                // The elapsed time is load-bearing diagnostics, not decoration: this
-                // is pre-bind boot work whose cost scales with the payload, and on a
-                // CUDA host it is the largest single read the daemon ever does at
-                // startup. Without it in the log there is nothing to attribute a slow
-                // launch to.
-                reason: `verified ${opts.allowStandaloneMacPayload ? 'standalone' : 'Electron'} native release ${release} in ${((Date.now() - startedAt) / 1000).toFixed(1)}s`,
-            };
+    try {
+        for (const candidate of opts.candidates) {
+            const startedAt = Date.now();
+            const hashedBefore = cache?.hashed ?? 0;
+            try {
+                await verifyCandidate({
+                    root: candidate,
+                    platform,
+                    entries: platformEntries,
+                    verifySignature: opts.verifySignature ?? verifyCodeSignature,
+                    allowStandaloneMacPayload: opts.allowStandaloneMacPayload === true,
+                    cache,
+                });
+                return {
+                    reused: true,
+                    nativeBinDir: resolve(candidate),
+                    // The elapsed time is load-bearing diagnostics, not decoration: this
+                    // is pre-bind boot work whose cost scales with the payload, and on a
+                    // CUDA host it is the largest single read the daemon ever does at
+                    // startup. Without it in the log there is nothing to attribute a slow
+                    // launch to.
+                    reason: `verified ${opts.allowStandaloneMacPayload ? 'standalone' : 'Electron'} native release ${release} in ${((Date.now() - startedAt) / 1000).toFixed(1)}s${cache ? ` (${cache.hashed - hashedBefore} of ${pinnedCount} files hashed)` : ''}`,
+                };
+            }
+            catch (error) {
+                failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+            }
         }
-        catch (error) {
-            failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            reused: false,
+            reason: failures.length > 0
+                ? failures.join('; ')
+                : 'no Electron native payload candidate was installed',
+        };
+    }
+    finally {
+        if (cache)
+            await saveHashCache(cache);
+    }
+}
+async function readHashCache(path) {
+    const known = new Map();
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        if (isRecord(parsed) && parsed.schema === 1 && isRecord(parsed.files)) {
+            for (const [file, record] of Object.entries(parsed.files)) {
+                // The fingerprint's shape is checked where it is compared.
+                if (isRecord(record) && typeof record.sha256 === 'string') {
+                    known.set(file, record);
+                }
+            }
         }
     }
-    return {
-        reused: false,
-        reason: failures.length > 0
-            ? failures.join('; ')
-            : 'no Electron native payload candidate was installed',
-    };
+    catch {
+        // Missing or unreadable: this call hashes everything and writes it anew.
+    }
+    return { path, known, examined: new Set(), confirmed: new Map(), hashed: 0 };
+}
+async function saveHashCache(cache) {
+    const dropped = [...cache.examined].some((file) => cache.known.has(file) && !cache.confirmed.has(file));
+    if (cache.hashed === 0 && !dropped)
+        return;
+    // Records this call never looked at belong to another candidate, which a
+    // dev launch verifies in a separate call against the same file. Dropping
+    // them would make the two calls erase each other and hash everything on
+    // every launch. They are kept while their files exist.
+    const files = {};
+    for (const [file, record] of cache.known) {
+        if (!cache.examined.has(file) && existsSync(file))
+            files[file] = record;
+    }
+    for (const [file, record] of cache.confirmed)
+        files[file] = record;
+    try {
+        await mkdir(dirname(cache.path), { recursive: true });
+        await writeFile(cache.path, `${JSON.stringify({ schema: 1, files }, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // Only a speedup: the next call hashes what it cannot find here.
+    }
 }
 async function verifyCandidate(opts) {
     const root = resolve(opts.root);
@@ -115,11 +166,13 @@ async function verifyCandidate(opts) {
         // Semantics are unchanged: any rejection still fails the candidate, and
         // the first one to fail wins the message.
         // The pin is the whole per-file check; see verifyNativeBinaries.
+        const hashBuffers = [];
         await mapWithConcurrency(Object.entries(platformPin.files), 4, async ([relativePath, pin]) => {
             if (!isSafeRelativePath(relativePath)) {
                 throw new Error(`unsafe pinned native path: ${relativePath}`);
             }
             const absolute = join(platformDir, ...relativePath.split('/'));
+            opts.cache?.examined.add(absolute);
             const info = await lstat(absolute);
             if (!info.isFile() || info.isSymbolicLink()) {
                 throw new Error(`pinned file is missing or not regular: ${platformKey}/${relativePath}`);
@@ -129,10 +182,26 @@ async function verifyCandidate(opts) {
             if (info.size !== pin.sizeBytes) {
                 throw new Error(`size mismatch: ${platformKey}/${relativePath}`);
             }
-            const actualSha = await sha256File(absolute);
-            if (actualSha !== pin.sha256.toLowerCase()) {
+            const want = pin.sha256.toLowerCase();
+            // Fingerprinted before hashing, so a file that changes mid-hash is
+            // recorded as it was and hashed again next time.
+            const fingerprint = opts.cache ? await fileFingerprint(absolute) : null;
+            const known = fingerprint ? opts.cache?.known.get(absolute) : undefined;
+            if (fingerprint &&
+                known?.sha256 === want &&
+                sameFileFingerprint(known.fingerprint, fingerprint)) {
+                opts.cache?.confirmed.set(absolute, known);
+                return;
+            }
+            const actualSha = await sha256File(absolute, hashBuffers);
+            if (actualSha !== want) {
                 throw new Error(`sha256 mismatch: ${platformKey}/${relativePath}`);
             }
+            if (opts.cache) {
+                opts.cache.hashed += 1;
+                if (fingerprint)
+                    opts.cache.confirmed.set(absolute, { sha256: want, fingerprint });
+            }
         });
         for (const [relativePath, target] of Object.entries(platformPin.symlinks)) {
             if (!isSafeRelativePath(relativePath)) {
@@ -203,18 +272,30 @@ async function listNativeEntries(root, platform) {
 }
 /**
  * Run `worker` over `items` with at most `limit` in flight, rejecting with the
- * first failure. Workers already in flight are allowed to settle; nothing here
- * mutates state, so an abandoned hash is inert.
+ * first failure. Workers already in flight are allowed to settle, and only
+ * record files that really did match, so an abandoned hash is inert. No new
+ * item starts after a failure: without that, the other workers went on hashing
+ * the rest of a rejected payload (a stale 1.6 GB dev checkout) in the
+ * background while the next candidate was being verified.
  */
 async function mapWithConcurrency(items, limit, worker) {
     let next = 0;
+    let failed = false;
     const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
         for (;;) {
+            if (failed)
+                return;
             const index = next++;
             const item = items[index];
             if (index >= items.length || item === undefined)
                 return;
-            await worker(item);
+            try {
+                await worker(item);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
         }
     });
     await Promise.all(runners);
@@ -286,15 +367,35 @@ function enclosingMacApp(path) {
 // daemon event loop (a 64 KB stream yields ~100k times and queues behind other
 // work). Engines is a lower layer than models, so this mirrors models'
 // MODEL_HASH_READ_BUFFER_BYTES rather than importing it.
+//
+// The buffer is reused, never one per chunk. A 16 MB `highWaterMark` stream
+// allocates a fresh 16 MB buffer for every read, and in Electron's main process
+// (where the dev supervisor runs this, and the embedded service after it) each
+// allocation cost ~44 ms and left V8 in a ~20 s garbage-collection storm once
+// the 1.7 GB Windows CUDA payload was done: the duckdb and MXC provisioning
+// after it took 4.5 s and 13 s on the splash, against ~50 ms each in isolation.
+// Reusing the buffer hashed the same payload in 1.1 s with no storm.
 const HASH_READ_BUFFER_BYTES = 16 * 1024 * 1024;
-function sha256File(path) {
-    return new Promise((resolveHash, reject) => {
-        const hash = createHash('sha256');
-        const stream = createReadStream(path, { highWaterMark: HASH_READ_BUFFER_BYTES });
-        stream.on('data', (chunk) => hash.update(chunk));
-        stream.on('error', reject);
-        stream.on('end', () => resolveHash(hash.digest('hex')));
-    });
+async function sha256File(path, buffers) {
+    const buffer = buffers.pop() ?? Buffer.allocUnsafe(HASH_READ_BUFFER_BYTES);
+    try {
+        const handle = await open(path, 'r');
+        try {
+            const hash = createHash('sha256');
+            for (;;) {
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+                if (bytesRead === 0)
+                    return hash.digest('hex');
+                hash.update(buffer.subarray(0, bytesRead));
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    finally {
+        buffers.push(buffer);
+    }
 }
 /** Legacy adoption API. New embedding hosts should use the side-effect-free verifier. */
 export async function reuseVerifiedElectronNativeBinaries(opts) {

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

@@ -45,12 +45,20 @@ export declare const NATIVE_ENGINE_RELEASE = "0.1.49";
 export declare const SHA256SUMS_DIGEST = "51e9d1fcd18174967fed451d11a7401035076330dfedadd6a0ce396ab636cff7";
 /** Exact SHA256 values for every engine archive published by native-v0.1.49. */
 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. */
+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

@@ -62,6 +62,24 @@ export const NATIVE_ENGINE_ARCHIVE_SHA256 = Object.freeze({
     'gezel-native-0.1.49-win32-x64-vulkan.zip': '0b7fe1cab3b881ac4a5cc24f08b0206c38edab30940ea79888a70776925a8bfb',
     'gezel-native-0.1.49-win32-x64.zip': 'e8996f82ea358903010e050d6b8b93beec683286af512b11cd8eeefdea50aa6d',
 });
+/** Download size in bytes of every engine archive published by native-v0.1.49. */
+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,
+});
 // END PINNED NATIVE ARCHIVE HASHES
 /**
  * True only when the pinned release's standalone macOS archives were
@@ -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/routes/engines.js

@@ -4,7 +4,7 @@ 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 { EngineBusyError } from '../../providers/native/capacity-broker.js';
 import { invalidateModelsCache } from '../model-inventory-cache.js';
@@ -39,17 +39,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 } : {}),
                 };
             }),
         });

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

@@ -3,12 +3,13 @@ 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 { 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 +189,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 +204,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',
                             },
@@ -534,11 +539,9 @@ export function v1ChatRoutes(ctx, opts = {}) {
                         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: 'server_error', code: 'provider_error' },
                             }),
                         })
                             .catch((sseErr) => {
@@ -630,6 +633,16 @@ 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);
             if (message.includes('messages must') ||
                 message.includes('empty') ||

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 {};