@bendyline/gezel-inference 1.0.1 → 1.0.3

package/dist/providers/llama-cpp/provider.d.ts

@@ -22,6 +22,7 @@
  * lazily respawn its process (see {@link shutdown}).
  */
 import { type DisableThinkingRequestShape, LlamaCppSession, type ReasoningEffortRequestShape, type ToolGrammarFallback } from '@bendyline/gezel/local-loop';
+import type { StartupCrashVerdict } from '@bendyline/gezel/native';
 import type { GpuArbiter } from '../gpu-arbiter.js';
 import type { NativeEngineLifecycleSnapshot, NativeEngineSupervisor } from '../native/supervisor.js';
 import { ProviderQueue } from '../queue.js';
@@ -55,6 +56,7 @@ export declare class LlamaCppProvider implements LLMProvider {
      */
     private toolGrammarFloor;
     private readonly supervisor?;
+    private readonly startupCrashVerdict?;
     /** Explicit base URL when no supervisor is managing the process. */
     private readonly externalBaseUrl?;
     private readonly defaultModel;
@@ -141,7 +143,9 @@ export declare class LlamaCppProvider implements LLMProvider {
     /** Request-scoped effort shape for compatible wrappers such as ds4-server. */
     private readonly reasoningEffortRequestShape;
     /** Engine batch width; see the `batchMaxConcurrency` constructor opt. */
-    private readonly batchMaxConcurrency;
+    private batchMaxConcurrency;
+    /** See the `reserveBackgroundSlot` constructor opt. */
+    private readonly reservesBackgroundLane;
     /**
      * Number of real llama-server request slots (`--parallel`). The provider
      * queue can intentionally be wider than this by one reserved background
@@ -150,7 +154,7 @@ export declare class LlamaCppProvider implements LLMProvider {
      * boundary: cache slot save/restore plus the streamed engine request must
      * never exceed the slots the native server actually owns.
      */
-    private readonly engineRequestWidth;
+    private engineRequestWidth;
     private engineRequestsActive;
     private readonly engineRequestWaiters;
     /**
@@ -242,6 +246,12 @@ export declare class LlamaCppProvider implements LLMProvider {
          * `baseUrl`.
          */
         supervisor?: NativeEngineSupervisor;
+        /**
+         * What a startup crash did to its build's standing (strike or
+         * quarantine), looked up by incident id when a start fails, so the error
+         * says what the next request will actually do.
+         */
+        startupCrashVerdict?: (incidentId: string) => StartupCrashVerdict | undefined;
         /**
          * Fixed base URL of an already-running llama-server. Used in
          * dev iteration and LAN-shared setups. Mutually exclusive with
@@ -401,7 +411,7 @@ export declare class LlamaCppProvider implements LLMProvider {
      */
     private cacheAdapter;
     private slotSavePath?;
-    private readonly launchedSlots;
+    private launchedSlots;
     setCacheAdapter(adapter: import('./cache-adapter.js').LlamaCppCacheAdapter): void;
     getCacheAdapter(): import('./cache-adapter.js').LlamaCppCacheAdapter | null;
     /**
@@ -422,6 +432,15 @@ export declare class LlamaCppProvider implements LLMProvider {
      * would 400 silently, and the debug probe's slot narration was fiction.
      */
     getLaunchedSlots(): number;
+    /**
+     * Follow a supervised engine that is relaunching with fewer `--parallel`
+     * slots because the wider launch ran the GPU out of memory. Runs between
+     * the failed start and the retry, while the request that asked for the
+     * engine still holds its lease. Refused when more requests hold leases
+     * than the narrower engine has slots: two turns on one slot would save and
+     * restore it under each other.
+     */
+    narrowEngineSlots(slots: number): boolean;
     /**
      * Claim one physical llama-server request slot.
      *

package/dist/providers/llama-cpp/provider.js

@@ -25,7 +25,7 @@ import * as os from 'node:os';
 import { createLogger } from '@bendyline/gezel';
 import { DEFAULT_NUM_CTX, LlamaCppSession, NativeEngineCrashedError, TOOL_GRAMMAR_FALLBACK_ORDER, constrainedToolNoSignalMsForModel, engineRequestAbortError, parseEnvMs, } from '@bendyline/gezel/local-loop';
 import { ProviderDisposedError } from '../provider-disposal.js';
-import { ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, defaultAmbientQuietMs, } from '../queue.js';
+import { ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, defaultAmbientQuietMs, defaultQueueYieldQuantumMs, } from '../queue.js';
 import { createToolExecutor } from '../tool-executor.js';
 import { classifyStartupLine } from './stdout-parser.js';
 // The session and its helpers live in core so a phone runs the same loop.
@@ -57,6 +57,7 @@ export class LlamaCppProvider {
      */
     toolGrammarFloor = null;
     supervisor;
+    startupCrashVerdict;
     /** Explicit base URL when no supervisor is managing the process. */
     externalBaseUrl;
     defaultModel;
@@ -146,6 +147,8 @@ export class LlamaCppProvider {
     reasoningEffortRequestShape;
     /** Engine batch width; see the `batchMaxConcurrency` constructor opt. */
     batchMaxConcurrency;
+    /** See the `reserveBackgroundSlot` constructor opt. */
+    reservesBackgroundLane;
     /**
      * Number of real llama-server request slots (`--parallel`). The provider
      * queue can intentionally be wider than this by one reserved background
@@ -247,6 +250,8 @@ export class LlamaCppProvider {
         }
         if (opts.supervisor)
             this.supervisor = opts.supervisor;
+        if (opts.startupCrashVerdict)
+            this.startupCrashVerdict = opts.startupCrashVerdict;
         if (opts.baseUrl)
             this.externalBaseUrl = opts.baseUrl.replace(/\/+$/, '');
         // Only register an evictor when we own the lifecycle. External-baseUrl
@@ -338,7 +343,10 @@ export class LlamaCppProvider {
         // mid-turn compaction wedges the turn, the same failure the MLX
         // single-slot path hit. See the matching note in the MLX provider.
         const interactiveConcurrency = batchMax;
-        const queueConcurrency = opts.reserveBackgroundSlot === false ? slots : Math.max(slots, interactiveConcurrency + 1);
+        this.reservesBackgroundLane = opts.reserveBackgroundSlot !== false;
+        const queueConcurrency = this.reservesBackgroundLane
+            ? Math.max(slots, interactiveConcurrency + 1)
+            : slots;
         this.queue = new ProviderQueue({
             // llama-server is launched with `--parallel ${slots}` (see
             // `buildLlamaCppProvider` in chat/manager.ts) so the engine has matching
@@ -361,6 +369,9 @@ export class LlamaCppProvider {
             // a multi-minute chore turn never lands right before their next
             // move. Applies to ds4 too — its provider wraps this class.
             ambientQuietMs: defaultAmbientQuietMs(),
+            // A tool loop hands the slot to a waiting conversation between
+            // iterations once it has held it this long (see `QueueLease`).
+            yieldQuantumMs: defaultQueueYieldQuantumMs(),
         });
     }
     /**
@@ -455,6 +466,31 @@ export class LlamaCppProvider {
     getLaunchedSlots() {
         return this.launchedSlots;
     }
+    /**
+     * Follow a supervised engine that is relaunching with fewer `--parallel`
+     * slots because the wider launch ran the GPU out of memory. Runs between
+     * the failed start and the retry, while the request that asked for the
+     * engine still holds its lease. Refused when more requests hold leases
+     * than the narrower engine has slots: two turns on one slot would save and
+     * restore it under each other.
+     */
+    narrowEngineSlots(slots) {
+        const next = Math.max(1, Math.floor(slots));
+        if (next >= this.launchedSlots || this.engineRequestsActive > next)
+            return false;
+        this.launchedSlots = next;
+        this.engineRequestWidth = next;
+        this.batchMaxConcurrency = Math.min(this.batchMaxConcurrency, next);
+        this.queue.narrow({
+            concurrency: this.reservesBackgroundLane
+                ? Math.max(next, this.batchMaxConcurrency + 1)
+                : next,
+            interactiveConcurrency: this.batchMaxConcurrency,
+            backgroundConcurrency: backgroundLaneCap(next),
+        });
+        this.cacheAdapter?.setSlotCount(next);
+        return true;
+    }
     /**
      * Claim one physical llama-server request slot.
      *
@@ -848,7 +884,7 @@ export class LlamaCppProvider {
         catch (err) {
             const nativeExit = this.supervisor.lastExitSnapshot?.();
             if (nativeExit && !nativeExit.expected && nativeExit.exitedAt >= ensureStartedAt) {
-                throw new NativeEngineCrashedError(nativeExit, err);
+                throw new NativeEngineCrashedError(nativeExit, err, this.startupCrashVerdict?.(nativeExit.incidentId));
             }
             throw err;
         }

package/dist/providers/mlx/provider.js

@@ -27,7 +27,7 @@
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
-import { AwakeBudget, autoCompactedNotice, createAwakeTimeout, createLogger, leaksUntaggedReasoning, turnCancelledMessage, } from '@bendyline/gezel';
+import { AwakeBudget, autoCompactedNotice, createAwakeTimeout, createLogger, isProjectStartingCall, leaksUntaggedReasoning, turnCancelledMessage, } from '@bendyline/gezel';
 import { leadingSystemMessages, standaloneTurnMessages, toolSurfaceSize, } from '@bendyline/gezel/local-loop';
 import { computeToolBudgetChars } from '@bendyline/gezel/local-loop';
 import { extractReasoningWithProfile, profileBehaviorConfig, profileHasBehavior, } from '../../model-profile/runtime.js';
@@ -58,7 +58,7 @@ import { MlxEngineGate } from './engine-gate.js';
 import { EngineHold, engineHoldLabelFor } from './engine-hold.js';
 import { EngineLogRouter } from './engine-log-router.js';
 import { MlxEngineStatsSampler } from './engine-stats-sampler.js';
-import { REASONING_OPEN_HEADER, StreamingReasoningSplit, engineOpensReasoning, requestOpensReasoning, } from './reasoning-stream.js';
+import { REASONING_OPEN_HEADER, StreamingReasoningSplit, engineOpensReasoning, reopenTemplateReasoning, requestOpensReasoning, } from './reasoning-stream.js';
 import { applyMlxRequestShape } from './request-shape.js';
 import { PRE_FIRST_BYTE_BASE_MS, buildMidStreamDropMessage, buildPreFirstByteAbortMessage, computePreFirstByteBudgetMs, estimatePromptTokens, formatTps, isMidStreamConnectionDrop, mlxHttpError, } from './runtime-diagnostics.js';
 import { classifyMlxFatalErrorLine, classifyMlxStartupLine, } from './stdout-parser.js';
@@ -2159,7 +2159,7 @@ class MlxSession extends StreamingSessionBase {
                 // accumulated into `lastTurnReasoning` so the chat bubble can
                 // render it behind a collapsed expander.
                 {
-                    const split = extractReasoningWithProfile(turnContent, this.deps.profile);
+                    const split = extractReasoningWithProfile(reopenTemplateReasoning(turnContent, opensInReasoning), this.deps.profile);
                     turnContent = split.visible;
                     if (split.reasoning) {
                         this.lastTurnReasoning =
@@ -2656,7 +2656,7 @@ class MlxSession extends StreamingSessionBase {
                         output =
                             "You already posted a question card to the user earlier in this turn. The second `ask_user_question` call was suppressed so the user only sees one card. END YOUR TURN NOW — the user's answer to the first question will arrive as the next user message; this turn produces no further visible content.";
                     }
-                    else if ((call.function.name === 'start_project' || call.function.name === 'start_job') &&
+                    else if (isProjectStartingCall(call.function.name, args) &&
                         startedProjectOrJobThisTurn) {
                         // Success-led phrasing — wild-caught on gemma4-26b/MLX,
                         // the previous "DO NOT call..." wording got misread by
@@ -2753,8 +2753,7 @@ class MlxSession extends StreamingSessionBase {
                         // Successful start_project / start_job → arm the
                         // per-turn macro guard so subsequent variants get
                         // intercepted above before reaching the bridge.
-                        if ((call.function.name === 'start_project' || call.function.name === 'start_job') &&
-                            !output.startsWith('ERROR:')) {
+                        if (isProjectStartingCall(call.function.name, args) && !output.startsWith('ERROR:')) {
                             startedProjectOrJobThisTurn = { tool: call.function.name, firstResult: output };
                         }
                     }

package/dist/providers/mlx/python/qwen4_ple.py

@@ -14,7 +14,6 @@ so concurrent replicas cannot observe a half-built view.
 
 from __future__ import annotations
 
-import fcntl
 import hashlib
 import json
 import os
@@ -23,6 +22,13 @@ import uuid
 from pathlib import Path
 from typing import Callable, Optional, Tuple
 
+try:
+    import fcntl
+except ImportError:
+    # Windows has no fcntl. The MLX engine never runs there, but this module's
+    # stdlib suite does (python-suites.test.ts), so it must still import.
+    fcntl = None
+
 
 PLE_MARKER = ".ple.ple_embedding.ngram_embedding.shards."
 VIEW_MARKER = "GEZEL_PLE_VIEW.json"
@@ -122,7 +128,8 @@ def prepare_external_ple_view(
     lock_path = target.parent / f".{target.name}.lock"
     try:
         with lock_path.open("a+b") as lock:
-            fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+            if fcntl is not None:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
             if _valid_view(target, signature):
                 return str(target), "reused", True
 

package/dist/providers/mlx/reasoning-stream.d.ts

@@ -56,6 +56,21 @@ export declare function templateTextOpensReasoning(template: string): TemplateRe
  * into the reasoning pane. Absent means on, matching the engine's default.
  */
 export declare function requestOpensReasoning(templateOpen: TemplateReasoningOpen | undefined, body: Record<string, unknown>): boolean;
+/**
+ * Restore the reasoning opener the chat template supplied, before the
+ * end-of-turn reasoning pass.
+ *
+ * When the rendered prompt left generation inside a reasoning block, the
+ * model's text starts mid-thought and carries only the closer. The live split
+ * knows that, but `extractReasoning` reads a lone `<channel|>` as stray and
+ * keeps the thoughts as the reply: Gemma 4 E4B, after a tool response, saved
+ * "The user wants to know…I need to answer in one sentence.The launch is on
+ * Friday…", and the stall check then asked it to answer again.
+ *
+ * Unchanged when the turn did not open in reasoning, when the model opened a
+ * block itself, or when no closer arrived.
+ */
+export declare function reopenTemplateReasoning(text: string, opensInReasoning: boolean): string;
 export interface ReasoningSplitChunk {
     visible: string;
     reasoning: string;

package/dist/providers/mlx/reasoning-stream.js

@@ -112,6 +112,41 @@ export function requestOpensReasoning(templateOpen, body) {
         return true;
     return kwargs.enable_thinking !== false;
 }
+/** The opener `extractReasoning` pairs with each closer a template-opened turn emits. */
+const OPENER_FOR_CLOSER = [
+    ['</think>', '<think>'],
+    ['</reasoning>', '<reasoning>'],
+    ['[/THINK]', '[THINK]'],
+    ['<channel|>', '<|channel>thought\n'],
+    ['<|end|>', '<|channel|>analysis<|message|>'],
+];
+/**
+ * Restore the reasoning opener the chat template supplied, before the
+ * end-of-turn reasoning pass.
+ *
+ * When the rendered prompt left generation inside a reasoning block, the
+ * model's text starts mid-thought and carries only the closer. The live split
+ * knows that, but `extractReasoning` reads a lone `<channel|>` as stray and
+ * keeps the thoughts as the reply: Gemma 4 E4B, after a tool response, saved
+ * "The user wants to know…I need to answer in one sentence.The launch is on
+ * Friday…", and the stall check then asked it to answer again.
+ *
+ * Unchanged when the turn did not open in reasoning, when the model opened a
+ * block itself, or when no closer arrived.
+ */
+export function reopenTemplateReasoning(text, opensInReasoning) {
+    if (!opensInReasoning || /^\s*(?:<think>|<reasoning>|\[THINK\]|<\|?channel\|?>)/i.test(text)) {
+        return text;
+    }
+    const lower = text.toLowerCase();
+    let first = null;
+    for (const [closer, opener] of OPENER_FOR_CLOSER) {
+        const index = lower.indexOf(closer.toLowerCase());
+        if (index !== -1 && (first === null || index < first.index))
+            first = { index, opener };
+    }
+    return first ? `${first.opener}${text}` : text;
+}
 /**
  * Incremental reasoning splitter for a streamed MLX turn.
  *

package/dist/providers/native/capacity-broker.d.ts

@@ -46,6 +46,14 @@ export interface CapacityBrokerOptions {
      * {@link computeCapacityBudget}. Omit to read the last published probe.
      */
     gpuVramBytes?: number | null;
+    /**
+     * An integrated GPU's firmware carve-out — see
+     * {@link CapacityBudgetInput.reservedGpuBytes}. Travels with
+     * `gpuVramBytes`/`unifiedMemory` as one description of the host.
+     */
+    reservedGpuBytes?: number | null;
+    /** What an integrated GPU can reach — see {@link CapacityBudgetInput.gpuAddressableBytes}. */
+    gpuAddressableBytes?: number | null;
     /**
      * May co-resident models spill into system RAM? `null`/omitted follows
      * {@link autoAllowRamSpillover} for this host. See
@@ -192,6 +200,8 @@ export declare class CapacityBroker {
     private readonly systemRamBytes;
     private readonly unifiedMemory;
     private readonly gpuVramBytes;
+    private readonly reservedGpuBytes;
+    private readonly gpuAddressableBytes;
     private explicitAllowRamSpillover;
     private readonly reservations;
     constructor(opts?: CapacityBrokerOptions);
@@ -503,11 +513,9 @@ export declare const MIN_VIABLE_LOCAL_CONTEXT_TOKENS = 65536;
 /** The same minimum on a host that has to trade context for memory. */
 export declare const MIN_VIABLE_CONSTRAINED_CONTEXT_TOKENS = 32768;
 /**
- * The most KV cache an automatic choice plans for one llama.cpp engine:
- * adaptive growth stops here, and the Gemma `--swa-full` auto-default is
- * declined when its full-size cache would pass it. Explicit settings (a
- * numeric context, a pinned `swaFull`) are the operator's call and bypass it;
- * it never shortens the ladder-settled base window either.
+ * The most KV cache adaptive growth plans for one llama.cpp engine. An
+ * explicit numeric context is the operator's call and skips growth
+ * altogether, and the ceiling never shortens the ladder-settled base window.
  *
  * Past this a bigger cache buys nothing: llama.cpp's prefill and decode cost
  * follows the tokens actually present, not the reservation, so the rest only
@@ -650,10 +658,10 @@ export interface CtxMemoryClampInput {
      */
     freeSystemRamBytes?: number;
     /**
-     * Usable VRAM on a discrete card; MUST be 0 on unified/shared-pool
-     * hosts, where the "VRAM" is the same physical RAM `freeSystemRamBytes`
-     * measures and adding it would double-count. `computeCapacityBudget`
-     * already reports `vramBytes: 0` for those hosts — pass its value.
+     * Usable VRAM on a discrete card. On a unified/shared-pool host it MUST be
+     * only an integrated GPU's firmware carve-out, which `freeSystemRamBytes`
+     * never sees; any "VRAM" that is the same physical RAM would double-count.
+     * `computeCapacityBudget` reports exactly that — pass its value.
      */
     vramBytes: number;
     minPerTurnCtxTokens?: number;
@@ -751,7 +759,7 @@ export interface AdaptiveCtxGrowthInput {
     fastBudgetBytes: number;
     committedOtherBytes?: number;
     budgetKind: CapacityBudget['kind'];
-    /** Usable VRAM on a discrete card (`liveBudget.vramBytes`); 0 elsewhere. */
+    /** Usable VRAM on a discrete card (`liveBudget.vramBytes`); ignored elsewhere. */
     vramBytes: number;
     /**
      * Graphics memory free right now on a discrete card, as device admission
@@ -796,11 +804,9 @@ export interface AdaptiveCtxGrowthResult {
  * settled slots and granted the un-grown request.
  *
  * Deliberately a second clamp pass rather than a bigger first request:
- * the first ladder pass sizes slot ceilings, the `--swa-full` fit verdict,
- * and RAM-spillover admission, all of which must stay anchored on the
- * practical 64K target — growing the request there would decline
- * `--swa-full` for models whose full cache fits at 64K and grow KV into
- * system-RAM spill on discrete cards.
+ * the first ladder pass sizes slot ceilings and RAM-spillover admission,
+ * both of which must stay anchored on the practical 64K target — growing
+ * the request there would grow KV into system-RAM spill on discrete cards.
  *
  * Slot trade: when `allowSlotTrade` is set and the target is out of reach
  * at the settled slot count, growth walks the count down — taking the

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

@@ -151,12 +151,16 @@ export class CapacityBroker {
     systemRamBytes;
     unifiedMemory;
     gpuVramBytes;
+    reservedGpuBytes;
+    gpuAddressableBytes;
     explicitAllowRamSpillover;
     reservations = new Map();
     constructor(opts = {}) {
         this.systemRamBytes = (opts.systemRamBytes ?? totalmem)();
         this.unifiedMemory = opts.unifiedMemory;
         this.gpuVramBytes = opts.gpuVramBytes;
+        this.reservedGpuBytes = opts.reservedGpuBytes;
+        this.gpuAddressableBytes = opts.gpuAddressableBytes;
         this.explicitAllowRamSpillover = opts.allowRamSpillover ?? null;
         this.explicitBudgetBytes = opts.budgetBytes ?? null;
         // Assigned by applyBudget; the definite-assignment dance TS wants for
@@ -189,6 +193,12 @@ export class CapacityBroker {
                 : {
                     ...(this.unifiedMemory === undefined ? {} : { unifiedMemory: this.unifiedMemory }),
                     ...(this.gpuVramBytes === undefined ? {} : { gpuVramBytes: this.gpuVramBytes }),
+                    ...(this.reservedGpuBytes === undefined
+                        ? {}
+                        : { reservedGpuBytes: this.reservedGpuBytes }),
+                    ...(this.gpuAddressableBytes === undefined
+                        ? {}
+                        : { gpuAddressableBytes: this.gpuAddressableBytes }),
                 }),
         });
     }
@@ -714,11 +724,9 @@ function envGrowthCeilingTokens() {
     return Number.isFinite(tokens) && tokens > 0 ? tokens : null;
 }
 /**
- * The most KV cache an automatic choice plans for one llama.cpp engine:
- * adaptive growth stops here, and the Gemma `--swa-full` auto-default is
- * declined when its full-size cache would pass it. Explicit settings (a
- * numeric context, a pinned `swaFull`) are the operator's call and bypass it;
- * it never shortens the ladder-settled base window either.
+ * The most KV cache adaptive growth plans for one llama.cpp engine. An
+ * explicit numeric context is the operator's call and skips growth
+ * altogether, and the ceiling never shortens the ladder-settled base window.
  *
  * Past this a bigger cache buys nothing: llama.cpp's prefill and decode cost
  * follows the tokens actually present, not the reservation, so the rest only
@@ -806,14 +814,20 @@ export function resolveLlamaCppContextRequirement(opts) {
     const strictModelMax = opts.contextSizing === 'model-max' && opts.explicitContextWindow === undefined;
     const requestedContextWindow = opts.explicitContextWindow ??
         (strictModelMax ? opts.modelContextWindow : opts.adaptiveContextWindow);
+    // Env, per-model and machine-wide numeric settings all express deliberate
+    // operator intent. The automatic host floor must not silently turn a 32K
+    // memory-saving request back into 64K. Resolve this here so launch and
+    // preview cannot apply different floors to the same explicit request.
+    const hostFloor = opts.minViableContextTokens ?? minViableLocalContextTokens();
+    const minimum = opts.explicitContextWindow !== undefined && opts.explicitContextWindow > 0
+        ? Math.min(hostFloor, opts.explicitContextWindow)
+        : hostFloor;
     const resolved = resolveLocalContextRequirement({
         ...(opts.modelContextWindow !== undefined
             ? { modelContextWindow: opts.modelContextWindow }
             : {}),
         ...(requestedContextWindow !== undefined ? { requestedContextWindow } : {}),
-        ...(opts.minViableContextTokens !== undefined
-            ? { minViableContextTokens: opts.minViableContextTokens }
-            : {}),
+        minViableContextTokens: minimum,
     });
     if (strictModelMax) {
         return {
@@ -959,11 +973,9 @@ export const ADAPTIVE_GROWTH_TRADE_MIN_GAIN = 1.25;
  * settled slots and granted the un-grown request.
  *
  * Deliberately a second clamp pass rather than a bigger first request:
- * the first ladder pass sizes slot ceilings, the `--swa-full` fit verdict,
- * and RAM-spillover admission, all of which must stay anchored on the
- * practical 64K target — growing the request there would decline
- * `--swa-full` for models whose full cache fits at 64K and grow KV into
- * system-RAM spill on discrete cards.
+ * the first ladder pass sizes slot ceilings and RAM-spillover admission,
+ * both of which must stay anchored on the practical 64K target — growing
+ * the request there would grow KV into system-RAM spill on discrete cards.
  *
  * Slot trade: when `allowSlotTrade` is set and the target is out of reach
  * at the settled slot count, growth walks the count down — taking the

package/dist/providers/native/capacity-budget.d.ts

@@ -5,7 +5,13 @@
  * VRAM and RAM are common on small discrete-GPU machines, so their ratio is
  * not enough to tell a GeForce from a genuinely shared GB10/iGPU pool.
  */
-export declare function setDetectedGpuVramBytes(bytes: number | null, unifiedMemory?: boolean): void;
+export declare function setDetectedGpuVramBytes(bytes: number | null, unifiedMemory?: boolean, reservedGpuBytes?: number | null, gpuAddressableBytes?: number | null): void;
+/**
+ * What engines may hold of memory an integrated GPU owns or can reach — its
+ * carve-out, or carve-out plus GTT — after the share the desktop it also
+ * drives needs.
+ */
+export declare function usableReservedGpuBytes(reservedGpuBytes: number | null | undefined): number;
 /** The published accelerator-memory figure, or null when none was measured. */
 export declare function getDetectedGpuVramBytes(): number | null;
 /**
@@ -26,13 +32,19 @@ export interface CapacityBudget {
     budgetBytes: number;
     /**
      * The FAST pool inside that budget: usable VRAM on a discrete card, the
-     * whole budget on unified / CPU hosts. Size KV slots and prompt caches
+     * whole budget on unified / CPU hosts — except an integrated GPU that can
+     * reach less than that (Linux GTT; see
+     * {@link CapacityBudgetInput.gpuAddressableBytes}). Size KV slots and prompt caches
      * against this, not against {@link budgetBytes} — on a discrete card the
      * rest of the budget is system RAM that weights stream from, and putting
      * more KV there than the card holds is how a GPU OOMs.
      */
     fastBytes: number;
-    /** Usable VRAM on a discrete card; 0 on unified / CPU-only hosts. */
+    /**
+     * Usable VRAM on a discrete card. On a unified host, the usable part of an
+     * integrated GPU's firmware carve-out — memory the GPU owns that free-RAM
+     * readings never include — and 0 when there is none. 0 on CPU-only hosts.
+     */
     vramBytes: number;
     /** The system-RAM share of the budget. */
     ramShareBytes: number;
@@ -59,6 +71,26 @@ export interface CapacityBudgetInput {
      */
     gpuVramBytes?: number | null;
     unifiedMemory?: boolean;
+    /**
+     * Memory firmware sets aside for an integrated GPU (an AMD "UMA frame
+     * buffer"): carved out before the OS counts RAM, so it is NOT inside
+     * `systemRamBytes`, and only the GPU can use it. Credited on a unified host
+     * only — an engine on the CPU build cannot reach it. Without this, raising
+     * the carve-out shrank the budget: the bytes left the RAM figure and were
+     * counted nowhere. Omit to fall back to the last published probe, under the
+     * same rule as `gpuVramBytes`.
+     */
+    reservedGpuBytes?: number | null;
+    /**
+     * The most memory an integrated GPU can reach: on Linux amdgpu, its
+     * carve-out plus GTT, the window of system RAM the kernel lets it map
+     * (half of RAM by default). Caps the FAST pool on a unified host — the GPU
+     * cannot hold more KV or weights than this, whatever the RAM share says —
+     * while the admission budget keeps the rest for layers the CPU runs. Omit
+     * to fall back to the last published probe, under the same rule as
+     * `gpuVramBytes`.
+     */
+    gpuAddressableBytes?: number | null;
 }
 /**
  * Resolve the memory a host can give resident local engines, per pool.

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

@@ -67,6 +67,13 @@ const VRAM_USABLE_FRACTION = 0.95;
  * bytes, so those hosts take the unified curve instead.
  */
 const UNIFIED_VRAM_RATIO = 0.75;
+/**
+ * Held back from an integrated GPU's firmware carve-out (see
+ * {@link CapacityBudgetInput.reservedGpuBytes}) for the desktop it also
+ * drives. The discrete card's 5% margin is too thin here: on a 512 MiB
+ * carve-out it would leave the compositor 25 MiB.
+ */
+const CARVE_OUT_DISPLAY_RESERVE_BYTES = 512 * 1024 ** 2;
 /**
  * Last accelerator-memory figure `detectMemoryProfile` measured on this host,
  * or null when nothing has probed yet / no GPU memory figure was published.
@@ -81,6 +88,8 @@ const UNIFIED_VRAM_RATIO = 0.75;
  */
 let detectedGpuVramBytes = null;
 let detectedGpuUnifiedMemory;
+let detectedGpuReservedBytes = null;
+let detectedGpuAddressableBytes = null;
 /**
  * Publish the measured accelerator pool. Called by `detectMemoryProfile`.
  *
@@ -88,10 +97,26 @@ let detectedGpuUnifiedMemory;
  * VRAM and RAM are common on small discrete-GPU machines, so their ratio is
  * not enough to tell a GeForce from a genuinely shared GB10/iGPU pool.
  */
-export function setDetectedGpuVramBytes(bytes, unifiedMemory) {
-    detectedGpuVramBytes =
-        typeof bytes === 'number' && Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+export function setDetectedGpuVramBytes(bytes, unifiedMemory, reservedGpuBytes, gpuAddressableBytes) {
+    detectedGpuVramBytes = positiveOrNull(bytes);
     detectedGpuUnifiedMemory = unifiedMemory;
+    detectedGpuReservedBytes = positiveOrNull(reservedGpuBytes);
+    detectedGpuAddressableBytes = positiveOrNull(gpuAddressableBytes);
+}
+function positiveOrNull(bytes) {
+    return typeof bytes === 'number' && Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+}
+/**
+ * What engines may hold of memory an integrated GPU owns or can reach — its
+ * carve-out, or carve-out plus GTT — after the share the desktop it also
+ * drives needs.
+ */
+export function usableReservedGpuBytes(reservedGpuBytes) {
+    const reserved = positiveOrNull(reservedGpuBytes);
+    if (reserved === null)
+        return 0;
+    const display = Math.max(CARVE_OUT_DISPLAY_RESERVE_BYTES, Math.ceil(reserved * (1 - VRAM_USABLE_FRACTION)));
+    return Math.max(0, reserved - display);
 }
 /** The published accelerator-memory figure, or null when none was measured. */
 export function getDetectedGpuVramBytes() {
@@ -144,6 +169,16 @@ export function computeCapacityBudget(input = {}) {
     const sharedPool = hasCard && measuredVram >= systemRamBytes * UNIFIED_VRAM_RATIO;
     const unified = measuredUnifiedMemory ?? (isUnifiedMemoryHost() || sharedPool);
     const discrete = hasCard && !unified;
+    const reservedGpuBytes = input.reservedGpuBytes !== undefined
+        ? input.reservedGpuBytes
+        : input.unifiedMemory === undefined && input.gpuVramBytes === undefined
+            ? detectedGpuReservedBytes
+            : null;
+    const gpuAddressableBytes = input.gpuAddressableBytes !== undefined
+        ? input.gpuAddressableBytes
+        : input.unifiedMemory === undefined && input.gpuVramBytes === undefined
+            ? detectedGpuAddressableBytes
+            : null;
     const highMemory = systemRamBytes >= HIGH_MEMORY_THRESHOLD_BYTES;
     // Whichever bound leaves the host MORE memory wins between the fraction and
     // the capped reserve, then the 4 GiB floor reserve caps them both. Written
@@ -153,7 +188,11 @@ export function computeCapacityBudget(input = {}) {
     const unifiedShare = Math.max(0, Math.min(Math.max(unifiedFractionShare, systemRamBytes - UNIFIED_OS_RESERVE_MAX_BYTES), systemRamBytes - UNIFIED_OS_RESERVE_BYTES));
     const nonUnifiedShare = Math.min(Math.floor(systemRamBytes * (highMemory ? 0.8 : 0.6)), BUDGET_CAP_BYTES);
     const ramShareBytes = unified ? unifiedShare : nonUnifiedShare;
-    const vramBytes = discrete ? Math.floor(measuredVram * VRAM_USABLE_FRACTION) : 0;
+    const vramBytes = discrete
+        ? Math.floor(measuredVram * VRAM_USABLE_FRACTION)
+        : unified
+            ? usableReservedGpuBytes(reservedGpuBytes)
+            : 0;
     // The pre-cap curve, retained for slot sizing only.
     const concurrencyRamShare = unified
         ? Math.max(0, Math.min(unifiedFractionShare, systemRamBytes - UNIFIED_OS_RESERVE_BYTES, BUDGET_CAP_BYTES))
@@ -175,7 +214,12 @@ export function computeCapacityBudget(input = {}) {
             overriddenByEnv: true,
         };
     }
-    const fastBytes = discrete ? vramBytes : auto;
+    const addressable = positiveOrNull(gpuAddressableBytes);
+    const fastBytes = discrete
+        ? vramBytes
+        : unified && addressable !== null
+            ? Math.min(auto, usableReservedGpuBytes(addressable))
+            : auto;
     return {
         budgetBytes: auto,
         fastBytes,

package/dist/providers/native/device-capacity.d.ts

@@ -73,7 +73,7 @@ export declare function configuredEngineMemoryBytes(config: {
  * download pages hide is exactly one the launch path refuses. Omit
  * `configuredBytes` for the machine's automatic ceilings.
  */
-export declare function staticCapacityCeilings(budget: Pick<CapacityBudget, 'budgetBytes' | 'fastBytes' | 'kind'>, ramBytes: number, configuredBytes?: number): {
+export declare function staticCapacityCeilings(budget: Pick<CapacityBudget, 'budgetBytes' | 'fastBytes' | 'kind' | 'vramBytes'>, ramBytes: number, configuredBytes?: number, platform?: NodeJS.Platform): {
     budgetBytes: number;
     gpuBudgetBytes: number;
 };