@bendyline/gezel-inference 1.0.1 → 1.0.3

package/dist/providers/native/device-capacity.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { readdir, stat } from 'node:fs/promises';
 import { homedir, totalmem } from 'node:os';
 import { join } from 'node:path';
-import { GEZEL_VERSION, NativeCapacityCommandSchema, NativeCapacityReplySchema, awakeNow, createLogger, isUnstampedDevBuild, } from '@bendyline/gezel';
+import { DS4_FULL_RESIDENCY_HEADROOM_BYTES, GEZEL_VERSION, NativeCapacityCommandSchema, NativeCapacityReplySchema, awakeNow, createLogger, isUnstampedDevBuild, } from '@bendyline/gezel';
 import { readSystemServiceRuntime, systemServiceHome } from '@bendyline/gezel-client/node';
 import { ConfigStore } from '../../fs/config-store.js';
 import { createPinnedFetch } from '../../remotes/pinned-fetch.js';
@@ -119,21 +119,39 @@ export function configuredEngineMemoryBytes(config) {
         ? config.localEngineMemoryGb * GIB
         : undefined;
 }
+/**
+ * GPU bytes a unified host may commit to one launch. macOS keeps 0.75 × RAM,
+ * near where Metal's recommended GPU working set sits. Linux unified hosts
+ * (DGX Spark GB10) have no such limit, so a large one may commit all but the
+ * OS reserve ds4's residency gate keeps: on a 121.6 GiB Spark, 0.75 × RAM
+ * (91.2 GiB) refused a GLM 5.3 Q2 launch that runs at 105 GiB with ~9 GiB to
+ * spare. Smaller Linux hosts stay on the 0.75 curve, which is the larger one there.
+ */
+function unifiedGpuCeilingBytes(ramBytes, platform) {
+    const curve = ramBytes * 0.75;
+    return platform === 'linux'
+        ? Math.max(curve, ramBytes - DS4_FULL_RESIDENCY_HEADROOM_BYTES)
+        : curve;
+}
 /**
  * The ledger's static ceilings: a request above either is refused at acquire,
  * whatever else is running. Shared with the media fit check so a model the
  * download pages hide is exactly one the launch path refuses. Omit
  * `configuredBytes` for the machine's automatic ceilings.
  */
-export function staticCapacityCeilings(budget, ramBytes, configuredBytes) {
+export function staticCapacityCeilings(budget, ramBytes, configuredBytes, platform = process.platform) {
     const budgetBytes = configuredBytes === undefined
         ? budget.budgetBytes
         : Math.min(configuredBytes, budget.budgetBytes);
     return {
         budgetBytes,
-        // Keep non-reclaimable accelerator commitments on the conservative curve;
-        // a larger RAM budget is not permission to wire the whole machine.
-        gpuBudgetBytes: Math.min(budgetBytes, budget.kind === 'unified' ? Math.min(budget.fastBytes, ramBytes * 0.75) : budget.fastBytes),
+        // Non-reclaimable accelerator commitments get their own ceiling: a larger
+        // RAM budget is not permission to wire the whole machine. An integrated
+        // GPU's carve-out (`vramBytes` on a unified host) is already the GPU's,
+        // and sits outside `ramBytes`.
+        gpuBudgetBytes: Math.min(budgetBytes, budget.kind === 'unified'
+            ? Math.min(budget.fastBytes, unifiedGpuCeilingBytes(ramBytes, platform) + budget.vramBytes)
+            : budget.fastBytes),
     };
 }
 export async function sampleDeviceCapacity(home) {

package/dist/providers/native/local-engine-runtime.js

@@ -223,11 +223,19 @@ export class LocalEngineRuntime {
             return null;
         if (this.engineRouterInitPromise)
             return this.engineRouterInitPromise;
-        this.engineRouterInitPromise = this.buildEngineRouter().then((r) => {
+        const pending = this.buildEngineRouter().then((r) => {
             this.engineRouterCache = r;
             return r;
+        }, (err) => {
+            // A failed build must not be cached. One that ran while a dev rebuild
+            // had emptied dist/ failed every later local turn with "Cannot find
+            // module …engine-router.js" until the app restarted (2026-10-19).
+            if (this.engineRouterInitPromise === pending)
+                this.engineRouterInitPromise = null;
+            throw err;
         });
-        return this.engineRouterInitPromise;
+        this.engineRouterInitPromise = pending;
+        return pending;
     }
     async buildEngineRouter() {
         const { EngineRouter } = await import('./engine-router.js');
@@ -260,6 +268,8 @@ export class LocalEngineRuntime {
                 ? {
                     unifiedMemory: memoryProfile.gpuMemoryKind === 'integrated' ||
                         memoryProfile.gpuMemoryKind === 'unified',
+                    reservedGpuBytes: memoryProfile.gpuReservedBytes ?? null,
+                    gpuAddressableBytes: memoryProfile.gpuAddressableBytes ?? null,
                 }
                 : {}),
             allowRamSpillover: config.allowRamSpillover ?? null,
@@ -1134,17 +1144,12 @@ export class LocalEngineRuntime {
         const manifestEngineConfig = await resolveCatalogLlamaCppEngineConfig(this.catalog, modelId);
         const perModelCtxOverride = config.modelContextOverrides?.[`llama-cpp:${modelId}`];
         const explicitContextWindow = envNumCtx ?? perModelCtxOverride ?? config.llamaCppNumCtx;
-        // A per-model override below the host floor is deliberate user intent —
-        // lower the admission floor to the override instead of silently raising
-        // the request back to 64K. Env / machine-wide values keep their
-        // historical floor semantics. Mirrors buildLlamaCppProvider.
+        // The shared resolver honors every explicit numeric context below the
+        // host floor. Keep per-model override state for the Settings auto marker.
         const overrideActive = perModelCtxOverride !== undefined && explicitContextWindow === perModelCtxOverride;
-        const minViableTokens = overrideActive
-            ? Math.min(contextFloor, perModelCtxOverride)
-            : contextFloor;
         const contextRequirement = resolveLlamaCppContextRequirement({
             modelContextWindow: installed.contextWindow,
-            minViableContextTokens: minViableTokens,
+            minViableContextTokens: contextFloor,
             ...(explicitContextWindow !== undefined ? { explicitContextWindow } : {}),
             ...(manifestEngineConfig?.contextSize !== undefined
                 ? {
@@ -1160,8 +1165,8 @@ export class LocalEngineRuntime {
         // per-model override deliberately does NOT short-circuit on a resident
         // engine: the full plan must run so a stale resident window surfaces as
         // restart-required instead of masquerading as the applied setting.
-        const shortCircuit = (residentContextWindow !== undefined && !overrideActive) || envNumCtx !== undefined;
-        const { autoKvCacheMaxBytes, defaultLocalEngineSlots, estimatePerSlotKvBytes, kvQuantScale, llamaCppSlotCeiling, planAdaptiveContextGrowth, planCtxTokensForMemory, plannedLocalEngineSlots, } = await import('./capacity-broker.js');
+        const shortCircuit = residentContextWindow !== undefined && !overrideActive;
+        const { defaultLocalEngineSlots, estimatePerSlotKvBytes, kvQuantScale, llamaCppSlotCeiling, planAdaptiveContextGrowth, planCtxTokensForMemory, plannedLocalEngineSlots, } = await import('./capacity-broker.js');
         const capacity = await this.previewCapacityInputs('llama-cpp', modelId, capacityOpts);
         const { budgetBytes: admissionBudgetBytes, fastBudgetBytes, committedOtherBytes } = capacity;
         const configuredSlots = config.providerConcurrency?.['llama-cpp'];
@@ -1481,27 +1486,18 @@ export class LocalEngineRuntime {
                     vramBytes: capacity.vramBytes,
                 });
                 // Mirror the launch path's windowed-cache admission (see
-                // buildLlamaCppProvider): when the launch will decline the Gemma
-                // `--swa-full` auto-default (or the windowed cache is pinned), the
-                // full-attention plan above overstates the real allocation — re-plan
-                // with the windowed linearization so the previewed window matches
-                // what the engine will actually grant.
+                // buildLlamaCppProvider): unless `swaFull` is pinned, a
+                // sliding-window model runs the windowed cache, which the
+                // full-attention plan above overstates — re-plan with the windowed
+                // linearization so the previewed window matches what the engine will
+                // actually grant.
                 // Strict model-max deliberately does NOT gate this: for SWA models
                 // the windowed cache is the only layout whose native-window KV can
                 // fit real machines, and the strict minimum rides inside
                 // `requirement.minimumPerTurnCtxTokens`, so the windowed
                 // re-plan sheds slots or denies but never shortens the window.
                 const explicitSwaFull = config.llamaCppSwaFull ?? manifestEngineConfig?.swaFull;
-                const fullCacheOverCeiling = exactKvAtReference !== undefined &&
-                    (exactKvAtReference / referenceCtx) * grantedCtx * slots > autoKvCacheMaxBytes();
-                const windowedCacheWillRun = (!admission.minimumSatisfied ||
-                    admission.clamped ||
-                    admission.slots < slots ||
-                    fullCacheOverCeiling) &&
-                    (explicitSwaFull === false ||
-                        (explicitSwaFull === undefined &&
-                            isGemmaModel({ architecture: installed.architecture, modelId })));
-                if (windowedCacheWillRun) {
+                if (explicitSwaFull !== true) {
                     const windowed = estimateWindowedKvLinearization({
                         blockCount: summary.blockCount,
                         embeddingLength: summary.embeddingLength,
@@ -1541,9 +1537,13 @@ export class LocalEngineRuntime {
                             fixedPerSlotBytes: windowed.fixedBytes,
                         };
                     }
-                    else if ((summary.slidingWindow ?? 0) > 0 || explicitSwaFull === undefined) {
-                        // SWA model without a readable layout: the launch path leaves
-                        // such a launch untouched — preview the requested window.
+                    else if ((!admission.minimumSatisfied || admission.clamped || admission.slots < slots) &&
+                        (explicitSwaFull === false
+                            ? (summary.slidingWindow ?? 0) > 0
+                            : isGemmaModel({ architecture: installed.architecture, modelId }))) {
+                        // SWA model without a readable layout, over budget on full
+                        // math: the launch path leaves such a launch untouched — preview
+                        // the requested window.
                         return { grantedCtx, slots, kvCacheType: kv, plannedFieldsOk: false };
                     }
                 }
@@ -1590,7 +1590,7 @@ export class LocalEngineRuntime {
             }
             return { grantedCtx, slots, kvCacheType: kv, plannedFieldsOk: true };
         };
-        const plan = llamaPlanPass(explicitContextWindow, minViableTokens);
+        const plan = llamaPlanPass(explicitContextWindow, contextFloor);
         let autoContextWindow;
         if (overrideActive) {
             try {

package/dist/providers/native/measured-budget.js

@@ -50,5 +50,7 @@ export async function measuredCapacityBudget() {
         systemRamBytes: profile.totalRamBytes,
         gpuVramBytes: profile.gpuVramBytes,
         unifiedMemory: profile.gpuMemoryKind === 'integrated' || profile.gpuMemoryKind === 'unified',
+        reservedGpuBytes: profile.gpuReservedBytes ?? null,
+        gpuAddressableBytes: profile.gpuAddressableBytes ?? null,
     });
 }

package/dist/providers/native/supervisor.d.ts

@@ -158,6 +158,11 @@ export interface NativeEngineSupervisorOptions {
     onLog?: (line: string) => void;
     /** Called for both expected and unexpected exits after a snapshot is sealed. */
     onExit?: (snapshot: NativeEngineExitSnapshot) => void | Promise<void>;
+    /**
+     * Called each time a start reaches readiness. Errors are caught and logged;
+     * a failing hook never fails the start.
+     */
+    onReady?: (launch: NativeEngineLaunch) => void;
     /**
      * Consulted after a start attempt fails (child died or never became
      * ready — not spawn errors, and not crashes after readiness). Return
@@ -214,6 +219,13 @@ export interface NativeEngineSupervisorOptions {
     psRunner?: () => Promise<NativeProcessSnapshot[]>;
     /** Platform seam for Windows owner-liveness semantics in orphan tests. */
     platform?: NodeJS.Platform;
+    /**
+     * The kernel's running count of out-of-memory kills, or null when it
+     * cannot be read. Compared across a child's life to tell Linux's
+     * out-of-memory killer from any other SIGKILL. Defaults to `oom_kill` in
+     * `/proc/vmstat` on Linux (any account can read it) and null elsewhere.
+     */
+    readOomKillCount?: () => number | null;
     /**
      * Test seam paired with `psRunner` — invoked instead of
      * `process.kill(pid, 'SIGKILL')`. Lets unit tests assert which pids
@@ -263,6 +275,7 @@ export declare class NativeEngineSupervisor {
     private readonly fetchImpl;
     private readonly onLog;
     private readonly onExit?;
+    private readonly onReady?;
     private readonly recoverStartup?;
     private readonly onRawLine?;
     private readonly logPrefix;
@@ -271,6 +284,9 @@ export declare class NativeEngineSupervisor {
     private readonly psRunner;
     private readonly killProcess;
     private readonly platform;
+    private readonly readOomKillCount;
+    /** `oom_kill` when the current child spawned; null where it cannot be read. */
+    private currentOomKills;
     private readonly logListeners;
     private recentStarts;
     private lastUsedAt;
@@ -482,6 +498,13 @@ export declare class NativeEngineSupervisor {
      */
     private runFreeze;
     private clearIdleTimer;
+    /**
+     * The counter's movement since `before`, when it rose. Another process
+     * killed in the same window would also move it, but a child that died by a
+     * SIGKILL this supervisor did not send while the counter rose is, in
+     * practice, the one the killer chose.
+     */
+    private oomKillsSince;
     private clearFreezeTimer;
     private clearHealthTimer;
 }
@@ -490,6 +513,8 @@ export declare function classifyNativeEnginePanic(line: string): {
     kind: NativeEnginePanicKind;
     line: string;
 } | undefined;
+/** `oom_kill` from `/proc/vmstat` (Linux 4.13+), or null when it cannot be read. */
+export declare function readLinuxOomKillCount(): number | null;
 /** Parse the portable `ps -axo pid=,ppid=,command=` shape. */
 export declare function parseNativeProcessSnapshot(stdout: string): NativeProcessSnapshot[];
 /** `code` stamped on every engine-launch failure. See {@link isEngineLaunchError}. */

package/dist/providers/native/supervisor.js

@@ -21,6 +21,7 @@
  * so we can drive the lifecycle without a real binary.
  */
 import { spawn as nodeSpawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { awakeNow, createLogger } from '@bendyline/gezel';
 import { listProcessSnapshots } from '@bendyline/gezel-client/node';
@@ -54,7 +55,9 @@ const RESTART_WINDOW_MS = 60_000;
 /**
  * Ceiling on `recoverStartup` retries within one start. Two covers the
  * full MoE degradation ladder (partial split → all experts to RAM →
- * engine-owned fit); a hook that keeps asking past that is looping.
+ * engine-owned fit), or one slot and one offload rung; a hook that keeps
+ * asking past that is looping. Every failed start also spends the restart
+ * budget, which refuses a fourth start inside its window anyway.
  */
 const MAX_STARTUP_RECOVERIES = 2;
 const HEALTH_FAIL_THRESHOLD = 3;
@@ -179,6 +182,7 @@ export class NativeEngineSupervisor {
     fetchImpl;
     onLog;
     onExit;
+    onReady;
     recoverStartup;
     onRawLine;
     logPrefix;
@@ -187,6 +191,9 @@ export class NativeEngineSupervisor {
     psRunner;
     killProcess;
     platform;
+    readOomKillCount;
+    /** `oom_kill` when the current child spawned; null where it cannot be read. */
+    currentOomKills = null;
     // Ad-hoc log listeners attached at runtime (vs. the construction-time
     // `onLog` / `onRawLine` hooks). Used by the owning provider to
     // subscribe to engine log lines for the duration of a single request
@@ -274,6 +281,8 @@ export class NativeEngineSupervisor {
         this.onLog = opts.onLog ?? ((line) => log.info(line));
         if (opts.onExit)
             this.onExit = opts.onExit;
+        if (opts.onReady)
+            this.onReady = opts.onReady;
         if (opts.recoverStartup)
             this.recoverStartup = opts.recoverStartup;
         if (opts.onRawLine)
@@ -282,6 +291,8 @@ export class NativeEngineSupervisor {
         this.readinessPath = opts.readinessPath ?? '/health';
         this.readyOnAnyResponse = opts.readyOnAnyResponse ?? false;
         this.platform = opts.platform ?? process.platform;
+        this.readOomKillCount =
+            opts.readOomKillCount ?? (this.platform === 'linux' ? readLinuxOomKillCount : () => null);
         this.psRunner = opts.psRunner ?? (() => defaultPsRunner(this.platform));
         this.killProcess = opts.killProcess ?? ((pid, sig) => process.kill(pid, sig));
     }
@@ -600,6 +611,7 @@ export class NativeEngineSupervisor {
         this.currentDiagnostics = launch.diagnostics ? { ...launch.diagnostics } : undefined;
         this.currentOutput = '';
         this.currentPanic = undefined;
+        this.currentOomKills = this.readOomKillCount();
         this.expectedExitReason = undefined;
         this.onLog(`${this.logPrefix} launch ${JSON.stringify({
             pid: this.currentPid ?? null,
@@ -698,6 +710,12 @@ export class NativeEngineSupervisor {
             this.state = { kind: 'running', launch, child, healthFails: 0 };
             this.resetIdleTimer();
             this.startHealthWatch();
+            try {
+                this.onReady?.(launch);
+            }
+            catch (hookErr) {
+                this.onLog(`${this.logPrefix} onReady hook threw: ${hookErr instanceof Error ? hookErr.message : hookErr}`);
+            }
         }
         catch (err) {
             // The panic classifier state is cleared by handleExit — read it now,
@@ -998,13 +1016,23 @@ export class NativeEngineSupervisor {
         // the output didn't already explain the death more precisely: an
         // engine that printed `CUDA error: …` and then took SIGILL on the
         // way down is a CUDA fault, not an unrunnable build.
-        const panic = this.currentPanic ??
-            (signal === 'SIGILL'
-                ? {
-                    kind: 'illegal-instruction',
-                    line: 'engine terminated by SIGILL (illegal instruction) with no diagnostic output',
-                }
-                : undefined);
+        // An out-of-memory kill outranks anything the engine printed: a CUDA or
+        // Vulkan allocation line on the way there is a symptom of the same
+        // shortage, and the GPU-to-RAM ladder those lines trigger cannot help
+        // when RAM is what ran out.
+        const oomKilled = signal === 'SIGKILL' && !expected ? this.oomKillsSince(this.currentOomKills) : null;
+        const panic = oomKilled
+            ? {
+                kind: 'host-out-of-memory',
+                line: `engine killed by the Linux out-of-memory killer (oom_kill ${oomKilled.before} -> ${oomKilled.after})`,
+            }
+            : (this.currentPanic ??
+                (signal === 'SIGILL'
+                    ? {
+                        kind: 'illegal-instruction',
+                        line: 'engine terminated by SIGILL (illegal instruction) with no diagnostic output',
+                    }
+                    : undefined));
         const snapshot = {
             incidentId: `native-${pid ?? 'unknown'}-${exitedAt}`,
             ...(pid !== undefined ? { pid } : {}),
@@ -1062,6 +1090,7 @@ export class NativeEngineSupervisor {
         this.currentDiagnostics = undefined;
         this.currentOutput = '';
         this.currentPanic = undefined;
+        this.currentOomKills = null;
         this.expectedExitReason = undefined;
         if (priorState.kind === 'stopped')
             return;
@@ -1313,6 +1342,18 @@ export class NativeEngineSupervisor {
             this.idleTimer = undefined;
         }
     }
+    /**
+     * The counter's movement since `before`, when it rose. Another process
+     * killed in the same window would also move it, but a child that died by a
+     * SIGKILL this supervisor did not send while the counter rose is, in
+     * practice, the one the killer chose.
+     */
+    oomKillsSince(before) {
+        if (before === null)
+            return null;
+        const after = this.readOomKillCount();
+        return after !== null && after > before ? { before, after } : null;
+    }
     clearFreezeTimer() {
         if (this.freezeTimer) {
             clearTimeout(this.freezeTimer);
@@ -1346,6 +1387,9 @@ export function classifyNativeEnginePanic(line) {
     if (/CUDA error:.*device-side assert/i.test(line)) {
         return { kind: 'cuda-device-assert', line: clipped };
     }
+    if (/CUDA error:\s*(?:no kernel image is available|the provided PTX was compiled with an unsupported toolchain)/i.test(line)) {
+        return { kind: 'cuda-unsupported-device', line: clipped };
+    }
     if (/CUDA error:/i.test(line))
         return { kind: 'cuda-error', line: clipped };
     if (/assert(?:ion)? failed|GGML_ASSERT/i.test(line)) {
@@ -1353,6 +1397,16 @@ export function classifyNativeEnginePanic(line) {
     }
     return undefined;
 }
+/** `oom_kill` from `/proc/vmstat` (Linux 4.13+), or null when it cannot be read. */
+export function readLinuxOomKillCount() {
+    try {
+        const match = /^oom_kill (\d+)$/m.exec(readFileSync('/proc/vmstat', 'utf8'));
+        return match?.[1] ? Number(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
 function panicPriority(kind) {
     if (kind === 'cuda-error')
         return 1;

package/dist/providers/queue.d.ts

@@ -5,11 +5,18 @@
  * service's import point and keeps the one piece that reads the process
  * environment.
  */
-export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
-export type { EnqueueRequest, Lane, ProviderQueueOptions, QueueSnapshot, QueueWaitOpts, } from '@bendyline/gezel/runtime';
+export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, DEFAULT_LOCAL_YIELD_QUANTUM_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
+export type { EnqueueRequest, Lane, ProviderQueueOptions, QueueLease, QueueSnapshot, QueueWaitOpts, } from '@bendyline/gezel/runtime';
 /**
  * Ambient quiet window for local engine queues. Override with
  * `GEZEL_AMBIENT_QUIET_MS` (milliseconds; `0` disables ambient gating
  * entirely).
  */
 export declare function defaultAmbientQuietMs(): number;
+/**
+ * How long a local turn holds its queue slot before it hands the slot to
+ * another conversation that is waiting. Override with
+ * `GEZEL_QUEUE_YIELD_QUANTUM_MS` (milliseconds; `0` keeps a slot for the
+ * whole turn).
+ */
+export declare function defaultQueueYieldQuantumMs(): number;

package/dist/providers/queue.js

@@ -5,8 +5,8 @@
  * service's import point and keeps the one piece that reads the process
  * environment.
  */
-import { DEFAULT_AMBIENT_QUIET_MS } from '@bendyline/gezel/runtime';
-export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
+import { DEFAULT_AMBIENT_QUIET_MS, DEFAULT_LOCAL_YIELD_QUANTUM_MS } from '@bendyline/gezel/runtime';
+export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, DEFAULT_LOCAL_YIELD_QUANTUM_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
 /**
  * Ambient quiet window for local engine queues. Override with
  * `GEZEL_AMBIENT_QUIET_MS` (milliseconds; `0` disables ambient gating
@@ -21,3 +21,18 @@ export function defaultAmbientQuietMs() {
     }
     return DEFAULT_AMBIENT_QUIET_MS;
 }
+/**
+ * How long a local turn holds its queue slot before it hands the slot to
+ * another conversation that is waiting. Override with
+ * `GEZEL_QUEUE_YIELD_QUANTUM_MS` (milliseconds; `0` keeps a slot for the
+ * whole turn).
+ */
+export function defaultQueueYieldQuantumMs() {
+    const raw = process.env.GEZEL_QUEUE_YIELD_QUANTUM_MS;
+    if (raw !== undefined) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return DEFAULT_LOCAL_YIELD_QUANTUM_MS;
+}

package/dist/providers/session-hooks.d.ts

@@ -22,5 +22,8 @@ export interface ToolGroundingHooks {
         kind: 'allow';
         args: Record<string, unknown>;
     } | null;
-    labelEvidence(toolName: string, args: Record<string, unknown>, text: string): string | null;
+    /** `source.thirdParty` is true for a tool served by any server but gezel's own. */
+    labelEvidence(toolName: string, args: Record<string, unknown>, text: string, source?: {
+        thirdParty: boolean;
+    }): string | null;
 }

package/dist/system/amdgpu-adapters.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The amdgpu devices Linux describes in sysfs, for the carve-out decision in
+ * gpu-carve-out.ts — the Linux counterpart of the DXCore adapter listing the
+ * device-health helper reads on Windows. Everything read here is
+ * world-readable, so the machine service's unprivileged account sees it too.
+ */
+import type { GpuAdapterFacts } from './gpu-carve-out.js';
+export interface SysfsIo {
+    readFile?: (path: string) => string;
+    readDir?: (path: string) => string[];
+}
+/**
+ * One entry per amdgpu device: `dedicatedBytes` from `mem_info_vram_total`,
+ * `sharedSystemBytes` from `mem_info_gtt_total` (the system RAM the kernel
+ * lets it map). Connector entries (`card0-HDMI-A-1`) and render nodes are
+ * skipped. Empty off Linux, without amdgpu, or when sysfs cannot be read.
+ */
+export declare function readAmdgpuAdapters(io?: SysfsIo): GpuAdapterFacts[];

package/dist/system/amdgpu-adapters.js

@@ -0,0 +1,55 @@
+/**
+ * The amdgpu devices Linux describes in sysfs, for the carve-out decision in
+ * gpu-carve-out.ts — the Linux counterpart of the DXCore adapter listing the
+ * device-health helper reads on Windows. Everything read here is
+ * world-readable, so the machine service's unprivileged account sees it too.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+const DRM_ROOT = '/sys/class/drm';
+const AMD_PCI_VENDOR = 0x1002;
+/**
+ * One entry per amdgpu device: `dedicatedBytes` from `mem_info_vram_total`,
+ * `sharedSystemBytes` from `mem_info_gtt_total` (the system RAM the kernel
+ * lets it map). Connector entries (`card0-HDMI-A-1`) and render nodes are
+ * skipped. Empty off Linux, without amdgpu, or when sysfs cannot be read.
+ */
+export function readAmdgpuAdapters(io = {}) {
+    const readFile = io.readFile ?? ((path) => readFileSync(path, 'utf8'));
+    const readDir = io.readDir ?? ((path) => readdirSync(path));
+    const read = (path) => {
+        try {
+            return readFile(path).trim();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    let cards;
+    try {
+        cards = readDir(DRM_ROOT).filter((entry) => /^card\d+$/.test(entry));
+    }
+    catch {
+        return [];
+    }
+    const adapters = [];
+    for (const card of cards) {
+        const device = join(DRM_ROOT, card, 'device');
+        if (Number.parseInt(read(join(device, 'vendor')) ?? '', 16) !== AMD_PCI_VENDOR)
+            continue;
+        const vram = byteCount(read(join(device, 'mem_info_vram_total')));
+        if (vram === undefined)
+            continue;
+        const gtt = byteCount(read(join(device, 'mem_info_gtt_total')));
+        adapters.push({
+            vendorId: AMD_PCI_VENDOR,
+            dedicatedBytes: vram,
+            ...(gtt !== undefined ? { sharedSystemBytes: gtt } : {}),
+        });
+    }
+    return adapters;
+}
+function byteCount(raw) {
+    const value = raw ? Number(raw) : Number.NaN;
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}

package/dist/system/gpu-carve-out.d.ts

@@ -0,0 +1,84 @@
+/**
+ * How much memory firmware set aside for an integrated GPU, if any.
+ *
+ * Two kinds of integrated GPU report "VRAM" through Vulkan, and they mean
+ * opposite things:
+ *
+ * - A **shared view** (Intel, Snapdragon, most iGPUs): the number is a slice
+ *   of the same RAM the OS already counts. Adding it double-counts, which is
+ *   why integrated hosts budget from system RAM alone.
+ * - A **carve-out** (an AMD APU's "UMA frame buffer", set in firmware or by
+ *   AMD's Variable Graphics Memory): memory removed before the OS ever counts
+ *   RAM. It sits in neither `os.totalmem()` nor any free-RAM reading, and only
+ *   the GPU can use it. Budgeting from system RAM alone loses it entirely, so
+ *   on a 16 GB laptop raising the carve-out from 3 GB to 8 GB cut the budget
+ *   from ~9 GB to ~4 GB.
+ *
+ * Windows answers directly when the device-health helper can list adapters
+ * (DXCore): an integrated adapter's dedicated memory IS its carve-out. Where
+ * installed RAM is known too, the two must agree — the carve-out has to fit
+ * in the memory that is installed but missing from the OS's count — so one
+ * odd driver figure cannot inflate the budget.
+ *
+ * Without an adapter listing, the GPU's Vulkan-reported memory stands in: a
+ * carve-out fits inside that same gap, a shared view is far larger than it
+ * (a few hundred MB of firmware reservations is the usual gap without one).
+ *
+ * Linux answers through the amdgpu driver instead (see
+ * {@link linuxGpuCarveOutBytes}). Installed RAM is not readable there without
+ * root, and the Vulkan figure cannot stand in: llama.cpp sums every heap of an
+ * integrated GPU, and RADV reports an APU's GTT — borrowed system RAM — beside
+ * the carve-out.
+ *
+ * Anything uncertain answers null — integrated GPUs budgeted from system RAM
+ * alone, as before.
+ */
+export declare function gpuCarveOutBytes(input: {
+    /** Physically installed RAM, or null when it could not be read. */
+    installedRamBytes: number | null;
+    /** RAM the OS reports (`os.totalmem()`). */
+    visibleRamBytes: number;
+    /** Memory the integrated GPU reports for itself through Vulkan. */
+    deviceBytes: number;
+    /** Windows' figure for the integrated adapter's own memory, when listed. */
+    adapterDedicatedBytes?: number | null;
+}): number | null;
+/**
+ * An AMD APU's carve-out on Linux: amdgpu's `mem_info_vram_total`, which on an
+ * APU is the frame buffer firmware reserved before the kernel counted RAM, so
+ * it is absent from MemTotal. Read only for the one amdgpu device there is —
+ * sysfs does not say which of two is integrated — and only when it fits in
+ * what Vulkan reports, which for an integrated GPU is the carve-out plus GTT.
+ * The caller has already decided the GPU llama.cpp picked is integrated.
+ */
+export declare function linuxGpuCarveOutBytes(input: {
+    /** amdgpu devices from sysfs (`readAmdgpuAdapters`). */
+    adapters: readonly GpuAdapterFacts[];
+    visibleRamBytes: number;
+    /** Memory the integrated GPU reports for itself through Vulkan. */
+    deviceBytes: number;
+}): number | null;
+/**
+ * Everything an AMD APU can reach on Linux: its carve-out plus GTT, the
+ * window of system RAM amdgpu lets it map (half of RAM on recent kernels
+ * unless `ttm.pages_limit` raises it). Past that, allocations fail however
+ * much RAM is free. Null without both figures for the one amdgpu device.
+ */
+export declare function linuxGpuAddressableBytes(adapters: readonly GpuAdapterFacts[]): number | null;
+/** The part of a helper adapter record (`DeviceGpuAdapter`) this module reads. */
+export interface GpuAdapterFacts {
+    name?: string;
+    vendorId: number;
+    integrated?: boolean;
+    dedicatedBytes?: number;
+    /** System RAM the adapter may borrow on top of its own (Linux: GTT). */
+    sharedSystemBytes?: number;
+}
+/**
+ * The adapter Windows lists for the GPU llama.cpp picked: the one with the
+ * same name, else the only adapter there is. Null when that is ambiguous —
+ * the name-based guesses then stand.
+ */
+export declare function matchGpuAdapter<T extends GpuAdapterFacts>(adapters: readonly T[], deviceName: string): T | null;
+/** GPU maker from its PCI vendor id. */
+export declare function gpuVendorFromPciId(vendorId: number): 'amd' | 'intel' | 'nvidia' | undefined;