@bendyline/gezel-inference 1.0.0 → 1.0.2

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

@@ -96,8 +96,15 @@ class SafeToolGrammarProcessor:
     salvage layer is still there as the post-hoc safety net.
     """
 
-    def __init__(self, inner: Any) -> None:
+    def __init__(
+        self,
+        inner: Any,
+        label: str = "tool-grammar",
+        fallback: str = "unconstrained + TS salvage",
+    ) -> None:
         self._inner = inner
+        self._label = label
+        self._fallback = fallback
         self.disabled = False
 
     def __call__(self, input_ids: Any, logits: Any) -> Any:
@@ -107,8 +114,8 @@ class SafeToolGrammarProcessor:
             return self._inner(input_ids, logits)
         except Exception as exc:  # noqa: BLE001 - defensive: any matcher fault
             print(
-                f"[tool-grammar] matcher error; disabling grammar for the rest of "
-                f"this turn (falling back to unconstrained + TS salvage): {exc}",
+                f"[{self._label}] matcher error; disabling grammar for the rest of "
+                f"this turn (falling back to {self._fallback}): {exc}",
                 flush=True,
             )
             self.disabled = True
@@ -698,6 +705,58 @@ def build_grammar_string(
     return None
 
 
+# What each format's own grammar opens with, and how its reasoning block
+# reads, for splicing an answer branch in front of the format's call rules.
+_FORMAT_HEADS = {"hermes": _HERMES_HEAD, "gemma": _GEMMA_HEAD, "glm": _GLM_HEAD}
+_THINK_BLOCKS = {
+    "hermes": "<think> TEXT </think>",
+    "glm": "<think> TEXT </think>",
+    "gemma": "<|channel> TEXT <channel|>",
+}
+
+
+def build_answer_or_calls_grammar(
+    tools: Optional[List[Dict[str, Any]]],
+    hint: Dict[str, Any],
+    answer_schema: Dict[str, Any],
+    allow_think: bool = True,
+) -> Optional[str]:
+    """One grammar for a request with both tools and a response format.
+
+    OpenAI's contract: the model may call tools, and when it answers, the
+    answer follows the schema. So the reply is optional reasoning, then
+    either one or more calls in the format's own syntax (with this module's
+    name and key constraints) or a JSON value matching `answer_schema`.
+    Stacking the plain JSON grammar on the tool grammar instead left only
+    their intersection, JSON, which no call can satisfy. Prose outside the
+    reasoning is ruled out, as it is for a plain response format.
+
+    None when the format has no grammar here; the caller then keeps tool
+    calls free and leaves the answer unconstrained, as before.
+
+    `allow_think` False drops the reasoning block for a request that turned
+    thinking off: with prose masked, Gemma took the open `<|channel>` as its
+    way out and reasoned until max_tokens (2026-10-14).
+    """
+    fmt = str((hint or {}).get("format") or "").strip()
+    head = _FORMAT_HEADS.get(fmt)
+    base = build_grammar_string(tools, hint)
+    if head is None or base is None or not base.startswith(head):
+        return None
+    schema = dict(answer_schema)
+    # Whitespace stays free inside the answer; see response_format.py.
+    schema["x-guidance"] = {**schema.get("x-guidance", {}), "whitespace_flexible": True}
+    return (
+        "%llguidance {}\n"
+        + ("start: think? WS? (calls | answer) WS?\n" if allow_think else "start: WS? (calls | answer) WS?\n")
+        + (f"think: {_THINK_BLOCKS[fmt]}\n" if allow_think else "")
+        + "calls: tool_call (WS? tool_call)*\n"
+        + f"answer: %json {json.dumps(schema)}\n"
+        + "WS: /[ \\t\\r\\n]+/\n"
+        + "TEXT: /(.|\\n)*/\n"
+    ) + base[len(head) :]
+
+
 def build_tool_grammar_processor(
     tokenizer: Any,
     tools: Optional[List[Dict[str, Any]]],

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

@@ -1,3 +1,13 @@
+/** Response header in which the sidecar reports the rendered prompt's state. */
+export declare const REASONING_OPEN_HEADER = "x-gezel-reasoning-open";
+/**
+ * Whether the engine says this turn's prompt left the model inside a reasoning
+ * block. The sidecar reads the rendered prompt, so this beats anything derived
+ * from the template text: Qwen 3.5's small models open `<think>` only when
+ * `enable_thinking` is explicitly true, and Gemma 4 opens its thought channel
+ * only after a tool response. Undefined when the header is absent.
+ */
+export declare function engineOpensReasoning(header: string | null | undefined): boolean | undefined;
 /**
  * How a chat template's generation prompt leaves the model inside a reasoning
  * block:
@@ -11,7 +21,9 @@ export type TemplateReasoningOpen = 'always' | 'unless-thinking-off';
 /**
  * Whether the model's chat template opens a reasoning block as the last thing
  * it emits before the model starts generating, and whether that depends on
- * `enable_thinking`.
+ * `enable_thinking`. A fallback for a sidecar that does not report
+ * {@link REASONING_OPEN_HEADER}: a template guess cannot see which branch the
+ * request takes.
  *
  * Qwen-family templates end their generation prompt with a bare `<think>`, so
  * the model's output begins *inside* reasoning and the only tag that ever
@@ -66,6 +78,11 @@ export interface ReasoningSplitChunk {
 export declare class StreamingReasoningSplit {
     private buffer;
     private inReasoning;
+    /** A channel opener names its channel (`thought`) before the reasoning starts. */
+    private channelNamePending;
+    /** The blank lines a model leaves after closing its reasoning are not reply. */
+    private afterClose;
+    private sawVisible;
     private readonly enabled;
     constructor(opts: {
         opensInReasoning: boolean;
@@ -79,7 +96,8 @@ export declare class StreamingReasoningSplit {
      */
     flush(): ReasoningSplitChunk;
     private drain;
-    private firstCloseMarker;
+    private out;
+    private firstMarker;
     /** Length of the trailing fragment that could still be a partial marker. */
     private holdBackLength;
 }

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

@@ -3,17 +3,39 @@ import { join } from 'node:path';
 import { createLogger } from '@bendyline/gezel';
 const log = createLogger('mlx');
 /**
- * Closing markers that end a reasoning block the chat template opened for the
- * model. Kept in sync with the paired forms `extractReasoning` strips at end of
- * turn — this is the streaming half of the same knowledge.
+ * Markers that open and close a reasoning block. Kept in sync with the paired
+ * forms `extractReasoning` strips at end of turn — this is the streaming half
+ * of the same knowledge. Gemma 4 opens a named channel (`<|channel>thought\n`,
+ * sometimes without the leading pipe) and closes it with `<channel|>`.
  */
-const CLOSE_MARKERS = ['</think>', '</reasoning>', '[/THINK]', '<|end|>'];
-/** The longest close marker, so `push` knows how much tail to hold back. */
-const MAX_MARKER_LENGTH = Math.max(...CLOSE_MARKERS.map((marker) => marker.length));
+const OPEN_MARKERS = ['<think>', '<reasoning>', '[THINK]', '<|channel>', '<channel>'];
+const CLOSE_MARKERS = ['</think>', '</reasoning>', '[/THINK]', '<|end|>', '<channel|>'];
+const OPEN_PATTERN = /<think>|<reasoning>|\[THINK\]|<\|?channel>/i;
+const CHANNEL_NAME = /^[A-Za-z_][\w-]*/;
+/** The longest marker, so `push` knows how much tail to hold back. */
+const MAX_MARKER_LENGTH = Math.max(...[...OPEN_MARKERS, ...CLOSE_MARKERS].map((marker) => marker.length));
+/** Response header in which the sidecar reports the rendered prompt's state. */
+export const REASONING_OPEN_HEADER = 'x-gezel-reasoning-open';
+/**
+ * Whether the engine says this turn's prompt left the model inside a reasoning
+ * block. The sidecar reads the rendered prompt, so this beats anything derived
+ * from the template text: Qwen 3.5's small models open `<think>` only when
+ * `enable_thinking` is explicitly true, and Gemma 4 opens its thought channel
+ * only after a tool response. Undefined when the header is absent.
+ */
+export function engineOpensReasoning(header) {
+    if (header === '1')
+        return true;
+    if (header === '0')
+        return false;
+    return undefined;
+}
 /**
  * Whether the model's chat template opens a reasoning block as the last thing
  * it emits before the model starts generating, and whether that depends on
- * `enable_thinking`.
+ * `enable_thinking`. A fallback for a sidecar that does not report
+ * {@link REASONING_OPEN_HEADER}: a template guess cannot see which branch the
+ * request takes.
  *
  * Qwen-family templates end their generation prompt with a bare `<think>`, so
  * the model's output begins *inside* reasoning and the only tag that ever
@@ -108,6 +130,11 @@ export function requestOpensReasoning(templateOpen, body) {
 export class StreamingReasoningSplit {
     buffer = '';
     inReasoning;
+    /** A channel opener names its channel (`thought`) before the reasoning starts. */
+    channelNamePending = false;
+    /** The blank lines a model leaves after closing its reasoning are not reply. */
+    afterClose = false;
+    sawVisible = false;
     enabled;
     constructor(opts) {
         this.enabled = opts.enabled ?? true;
@@ -134,20 +161,48 @@ export class StreamingReasoningSplit {
         let reasoning = '';
         while (this.buffer.length > 0) {
             if (this.inReasoning) {
-                const close = this.firstCloseMarker();
+                if (this.channelNamePending) {
+                    const name = CHANNEL_NAME.exec(this.buffer)?.[0] ?? '';
+                    if (!final && name.length === this.buffer.length)
+                        break;
+                    this.buffer = this.buffer.slice(name.length).replace(/^[ \t]*\r?\n/, '');
+                    this.channelNamePending = false;
+                    continue;
+                }
+                const close = this.firstMarker(CLOSE_MARKERS);
                 if (!close)
                     break;
                 reasoning += this.buffer.slice(0, close.index);
                 this.buffer = this.buffer.slice(close.index + close.marker.length);
                 this.inReasoning = false;
+                this.afterClose = true;
+                continue;
+            }
+            if (this.afterClose) {
+                if (!this.sawVisible && visible.trim() === '') {
+                    visible = '';
+                    this.buffer = this.buffer.replace(/^\s+/, '');
+                    if (this.buffer.length === 0)
+                        break;
+                }
+                this.afterClose = false;
+            }
+            const open = OPEN_PATTERN.exec(this.buffer);
+            // A closer with no opener is a template-opened block the engine did not
+            // report; the text before it has already streamed, but the tag need not.
+            const stray = this.firstMarker(CLOSE_MARKERS);
+            if (stray && (!open || stray.index < open.index)) {
+                visible += this.buffer.slice(0, stray.index);
+                this.buffer = this.buffer.slice(stray.index + stray.marker.length);
+                this.afterClose = true;
                 continue;
             }
-            const open = /<think>|<reasoning>|\[THINK\]/i.exec(this.buffer);
             if (!open)
                 break;
             visible += this.buffer.slice(0, open.index);
             this.buffer = this.buffer.slice(open.index + open[0].length);
             this.inReasoning = true;
+            this.channelNamePending = /channel/i.test(open[0]);
         }
         if (final) {
             if (this.inReasoning)
@@ -155,8 +210,10 @@ export class StreamingReasoningSplit {
             else
                 visible += this.buffer;
             this.buffer = '';
-            return { visible, reasoning };
+            return this.out(visible, reasoning);
         }
+        if (this.channelNamePending)
+            return this.out(visible, reasoning);
         // Hold back a tail that could still grow into a marker; release the rest.
         const safeLength = this.buffer.length - this.holdBackLength();
         if (safeLength > 0) {
@@ -167,12 +224,18 @@ export class StreamingReasoningSplit {
             else
                 visible += released;
         }
+        return this.out(visible, reasoning);
+    }
+    out(visible, reasoning) {
+        if (visible.trim() !== '')
+            this.sawVisible = true;
         return { visible, reasoning };
     }
-    firstCloseMarker() {
+    firstMarker(markers) {
+        const haystack = this.buffer.toLowerCase();
         let best = null;
-        for (const marker of CLOSE_MARKERS) {
-            const index = this.buffer.toLowerCase().indexOf(marker.toLowerCase());
+        for (const marker of markers) {
+            const index = haystack.indexOf(marker.toLowerCase());
             if (index === -1)
                 continue;
             if (!best || index < best.index)
@@ -182,12 +245,10 @@ export class StreamingReasoningSplit {
     }
     /** Length of the trailing fragment that could still be a partial marker. */
     holdBackLength() {
+        const candidates = (this.inReasoning ? CLOSE_MARKERS : [...OPEN_MARKERS, ...CLOSE_MARKERS]).map((marker) => marker.toLowerCase());
         const maxTail = Math.min(MAX_MARKER_LENGTH - 1, this.buffer.length);
         for (let length = maxTail; length > 0; length -= 1) {
             const tail = this.buffer.slice(this.buffer.length - length).toLowerCase();
-            const candidates = this.inReasoning
-                ? CLOSE_MARKERS.map((marker) => marker.toLowerCase())
-                : ['<think>', '<reasoning>', '[think]'];
             if (candidates.some((marker) => marker.startsWith(tail)))
                 return length;
         }

package/dist/providers/mlx/runtime-diagnostics.d.ts

@@ -1,5 +1,21 @@
 /** Read a process's resident-set size (bytes) via `ps` for engine telemetry. */
 export declare function readProcessRssBytes(pid: number): Promise<number | null>;
+/**
+ * The engine refused the request as the caller's to fix: a `response_format`
+ * schema its JSON grammar cannot enforce. Routes answer it with a 400
+ * `invalid_request_error`. Reported as a 500 `server_error`, it was retried
+ * by OpenAI SDKs although no retry could succeed.
+ */
+export declare class UnsupportedResponseFormatError extends Error {
+    readonly code = "unsupported_response_format";
+    constructor(message: string);
+}
+/**
+ * The error a failed engine response becomes. The sidecar answers 422 with a
+ * `response_format` detail only for a schema it refused (response_format.py);
+ * its other 422s are about images, and stay engine errors.
+ */
+export declare function mlxHttpError(status: number, statusText: string, body: string): Error;
 /** Translate known mlx_vlm response shapes into user-actionable errors. */
 export declare function translateMlxHttpError(status: number, statusText: string, body: string): string;
 /** Detect an engine-side HTTP response stream closing mid-flight. */

package/dist/providers/mlx/runtime-diagnostics.js

@@ -27,6 +27,33 @@ export async function readProcessRssBytes(pid) {
         }
     });
 }
+/**
+ * The engine refused the request as the caller's to fix: a `response_format`
+ * schema its JSON grammar cannot enforce. Routes answer it with a 400
+ * `invalid_request_error`. Reported as a 500 `server_error`, it was retried
+ * by OpenAI SDKs although no retry could succeed.
+ */
+export class UnsupportedResponseFormatError extends Error {
+    code = 'unsupported_response_format';
+    constructor(message) {
+        super(message);
+        this.name = 'UnsupportedResponseFormatError';
+    }
+}
+/**
+ * The error a failed engine response becomes. The sidecar answers 422 with a
+ * `response_format` detail only for a schema it refused (response_format.py);
+ * its other 422s are about images, and stay engine errors.
+ */
+export function mlxHttpError(status, statusText, body) {
+    if (status === 422) {
+        const detail = tryParseJsonDetail(body, 1_000);
+        if (detail && /response[ _]format/i.test(detail)) {
+            return new UnsupportedResponseFormatError(detail);
+        }
+    }
+    return new Error(translateMlxHttpError(status, statusText, body));
+}
 /** Translate known mlx_vlm response shapes into user-actionable errors. */
 export function translateMlxHttpError(status, statusText, body) {
     if (/Repository Not Found for url/i.test(body) || /401 Client Error/i.test(body)) {
@@ -148,11 +175,11 @@ export function computePreFirstByteBudgetMs(approxPromptTokens) {
     const scaled = PRE_FIRST_BYTE_BASE_MS + (over / 1000) * PRE_FIRST_BYTE_MS_PER_1K_TOKENS;
     return Math.min(PRE_FIRST_BYTE_CAP_MS, Math.round(scaled));
 }
-function tryParseJsonDetail(body) {
+function tryParseJsonDetail(body, maxChars = 200) {
     try {
         const obj = JSON.parse(body);
         if (obj && typeof obj === 'object' && 'detail' in obj && typeof obj.detail === 'string') {
-            return obj.detail.slice(0, 200);
+            return obj.detail.slice(0, maxChars);
         }
     }
     catch {

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);
@@ -502,6 +512,32 @@ export declare function liveLaunchCapBytes(input: {
 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 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
+ * defers compaction. Across the 2026-10-12 scorecard (DGX Spark, n=3 per
+ * scenario) gemma4-31b never passed 41.7K tokens of an 82,944-token window
+ * it held as a 69.6 GB `--swa-full` cache, and qwen3.8-27b peaked at 94.8K,
+ * about 6 GB of its KV. That memory is worth more as a second resident
+ * model, and the same week two daemons each grew into one unified pool and
+ * hung the machine.
+ */
+export declare const AUTO_KV_CACHE_MAX_BYTES: number;
+/** {@link AUTO_KV_CACHE_MAX_BYTES}, unless `GEZEL_LLAMA_AUTO_KV_MAX_GB` overrides it. */
+export declare function autoKvCacheMaxBytes(): number;
+/**
+ * The share of a shared pool's live free memory, left after the un-grown
+ * launch, that adaptive growth may spend. The rest stays free for whatever
+ * starts next: the desktop's own apps, a second model, another daemon. The
+ * base grant already holds the practical window; growth is the extra, and an
+ * extra that takes everything down to the OS reserve leaves the next tenant
+ * to page the machine.
+ */
+export declare const ADAPTIVE_GROWTH_SHARED_FREE_SHARE = 0.5;
 /**
  * The context floor THIS host is held to. A 16 GB Mac or an 8 GB card cannot
  * back a 64K window next to the weights, and the admission ladder's only
@@ -622,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;
@@ -723,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
@@ -747,6 +783,8 @@ export interface AdaptiveCtxGrowthInput {
      * growth's to spend.
      */
     allowSlotTrade?: boolean;
+    /** Test seam; defaults to {@link autoKvCacheMaxBytes}. */
+    maxKvCacheBytes?: number;
 }
 export interface AdaptiveCtxGrowthResult {
     perTurnCtxTokens: number;
@@ -766,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
@@ -787,6 +823,11 @@ export interface AdaptiveCtxGrowthResult {
  * the inputs match the base clamp. Inherits `VRAM_USABLE_FRACTION` and
  * {@link LOCAL_ENGINE_COMPUTE_HEADROOM} through the shared clamp.
  *
+ * Ceiling: total KV never grows past {@link autoKvCacheMaxBytes}, and on a
+ * shared pool with a live reading, never past the base KV plus
+ * {@link ADAPTIVE_GROWTH_SHARED_FREE_SHARE} of what the base launch leaves
+ * free. Both only stop growth; neither shrinks the base grant.
+ *
  * MoE models never grow on a discrete card: `planMoeOffload` places routed
  * experts around the KV reserve, and a grown reserve would silently evict
  * experts from VRAM — trading decode speed for context behind the user's

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 }),
                 }),
         });
     }
@@ -713,6 +723,36 @@ function envGrowthCeilingTokens() {
     const tokens = Number.parseInt(raw, 10);
     return Number.isFinite(tokens) && tokens > 0 ? tokens : null;
 }
+/**
+ * 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
+ * defers compaction. Across the 2026-10-12 scorecard (DGX Spark, n=3 per
+ * scenario) gemma4-31b never passed 41.7K tokens of an 82,944-token window
+ * it held as a 69.6 GB `--swa-full` cache, and qwen3.8-27b peaked at 94.8K,
+ * about 6 GB of its KV. That memory is worth more as a second resident
+ * model, and the same week two daemons each grew into one unified pool and
+ * hung the machine.
+ */
+export const AUTO_KV_CACHE_MAX_BYTES = 32 * GIB;
+/** {@link AUTO_KV_CACHE_MAX_BYTES}, unless `GEZEL_LLAMA_AUTO_KV_MAX_GB` overrides it. */
+export function autoKvCacheMaxBytes() {
+    const raw = process.env.GEZEL_LLAMA_AUTO_KV_MAX_GB;
+    const gb = raw ? Number.parseFloat(raw) : Number.NaN;
+    return Number.isFinite(gb) && gb > 0 ? gb * GIB : AUTO_KV_CACHE_MAX_BYTES;
+}
+/**
+ * The share of a shared pool's live free memory, left after the un-grown
+ * launch, that adaptive growth may spend. The rest stays free for whatever
+ * starts next: the desktop's own apps, a second model, another daemon. The
+ * base grant already holds the practical window; growth is the extra, and an
+ * extra that takes everything down to the OS reserve leaves the next tenant
+ * to page the machine.
+ */
+export const ADAPTIVE_GROWTH_SHARED_FREE_SHARE = 0.5;
 /**
  * The context floor THIS host is held to. A 16 GB Mac or an 8 GB card cannot
  * back a 64K window next to the weights, and the admission ladder's only
@@ -927,11 +967,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
@@ -948,6 +986,11 @@ export const ADAPTIVE_GROWTH_TRADE_MIN_GAIN = 1.25;
  * the inputs match the base clamp. Inherits `VRAM_USABLE_FRACTION` and
  * {@link LOCAL_ENGINE_COMPUTE_HEADROOM} through the shared clamp.
  *
+ * Ceiling: total KV never grows past {@link autoKvCacheMaxBytes}, and on a
+ * shared pool with a live reading, never past the base KV plus
+ * {@link ADAPTIVE_GROWTH_SHARED_FREE_SHARE} of what the base launch leaves
+ * free. Both only stop growth; neither shrinks the base grant.
+ *
  * MoE models never grow on a discrete card: `planMoeOffload` places routed
  * experts around the KV reserve, and a grown reserve would silently evict
  * experts from VRAM — trading decode speed for context behind the user's
@@ -974,6 +1017,27 @@ export function planAdaptiveContextGrowth(input) {
         ? Math.max(0, input.measuredFreeVramBytes)
         : undefined;
     const cardBytes = measuredFreeVram !== undefined ? Math.min(input.vramBytes, measuredFreeVram) : input.vramBytes;
+    const kvTotalAt = (slots, ctx) => slots * (kvFixedPerSlot + ctx * input.kvBytesPerToken);
+    const baseKv = kvTotalAt(startSlots, base);
+    const capKv = Math.max(0, input.maxKvCacheBytes ?? autoKvCacheMaxBytes());
+    // Priced like the shared clamp (same OS reserve, same compute headroom) so
+    // "what the base launch leaves free" means the same thing to both.
+    const leftAfterBase = !discrete && input.freeSystemRamBytes !== undefined
+        ? Math.max(0, (input.freeSystemRamBytes -
+            liveRamOsReserveBytes() -
+            CTX_PLANNING_MARGIN_BYTES -
+            input.weightsResidentBytes) *
+            (1 - LOCAL_ENGINE_COMPUTE_HEADROOM) -
+            baseKv)
+        : undefined;
+    const shareKv = leftAfterBase !== undefined
+        ? baseKv + leftAfterBase * ADAPTIVE_GROWTH_SHARED_FREE_SHARE
+        : Number.POSITIVE_INFINITY;
+    const kvCeiling = Math.min(capKv, shareKv);
+    const ctxUnderCeiling = (slots) => {
+        const perSlot = kvCeiling / slots - kvFixedPerSlot;
+        return perSlot > 0 ? Math.floor(perSlot / input.kvBytesPerToken / 1024) * 1024 : 0;
+    };
     const safeAt = (slots) => {
         const safe = clampCtxTokensForMemory({
             requestedPerTurnCtxTokens: target,
@@ -995,7 +1059,7 @@ export function planAdaptiveContextGrowth(input) {
             vramBytes: discrete ? cardBytes : 0,
             minPerTurnCtxTokens: 1,
         });
-        return Math.min(target, safe.perTurnCtxTokens);
+        return Math.min(target, safe.perTurnCtxTokens, ctxUnderCeiling(slots));
     };
     // Walk the slot count down only while the target stays out of reach:
     // the first (largest) count that reaches it wins, else the floor count
@@ -1003,7 +1067,9 @@ export function planAdaptiveContextGrowth(input) {
     const floorSlots = input.allowSlotTrade
         ? Math.min(startSlots, ADAPTIVE_GROWTH_MIN_SLOTS)
         : startSlots;
-    const noTradeCtx = safeAt(startSlots);
+    // Floored at the base grant: when the base already sits above the KV
+    // ceiling, the ceiling must not make a lane trade look like a big gain.
+    const noTradeCtx = Math.max(base, safeAt(startSlots));
     let chosenSlots = startSlots;
     let chosenCtx = noTradeCtx;
     for (let slots = startSlots - 1; slots >= floorSlots && chosenCtx < target; slots -= 1) {
@@ -1027,14 +1093,19 @@ export function planAdaptiveContextGrowth(input) {
     const measuredNote = measuredFreeVram !== undefined && measuredFreeVram < Math.min(fastLeft, input.vramBytes)
         ? ` (capped at the ~${gb(measuredFreeVram)} of graphics memory other applications leave free)`
         : '';
+    const ceilingNote = grownTo < target && ctxUnderCeiling(chosenSlots) <= grownTo
+        ? kvCeiling === capKv
+            ? `; stopped at the ~${gb(capKv)} automatic KV ceiling`
+            : `; stopped to keep ~${gb((leftAfterBase ?? 0) * (1 - ADAPTIVE_GROWTH_SHARED_FREE_SHARE))} free for other work`
+        : '';
     return {
         perTurnCtxTokens: grownTo,
         slots: chosenSlots,
         grown: true,
         reason: `growing context ${base} → ${grownTo} tokens/turn at ${chosenSlots} slot${chosenSlots === 1 ? '' : 's'}${slotNote} ` +
             `(target ${target}): weights ~${gb(input.weightsResidentBytes)} + grown KV ` +
-            `~${gb(chosenSlots * (kvFixedPerSlot + grownTo * input.kvBytesPerToken))} fits fast memory ` +
-            `~${gb(fastLeft)}${measuredNote}`,
+            `~${gb(kvTotalAt(chosenSlots, grownTo))} fits fast memory ` +
+            `~${gb(fastLeft)}${measuredNote}${ceilingNote}`,
     };
 }
 /**