@bendyline/gezel-inference 1.0.0 → 1.0.1

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

@@ -502,6 +502,34 @@ 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 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.
+ *
+ * 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
@@ -747,6 +775,8 @@ export interface AdaptiveCtxGrowthInput {
      * growth's to spend.
      */
     allowSlotTrade?: boolean;
+    /** Test seam; defaults to {@link autoKvCacheMaxBytes}. */
+    maxKvCacheBytes?: number;
 }
 export interface AdaptiveCtxGrowthResult {
     perTurnCtxTokens: number;
@@ -787,6 +817,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

@@ -713,6 +713,38 @@ function envGrowthCeilingTokens() {
     const tokens = Number.parseInt(raw, 10);
     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.
+ *
+ * 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
@@ -948,6 +980,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 +1011,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 +1053,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 +1061,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 +1087,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}`,
     };
 }
 /**

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

@@ -1161,7 +1161,7 @@ export class LocalEngineRuntime {
         // 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 { defaultLocalEngineSlots, estimatePerSlotKvBytes, kvQuantScale, llamaCppSlotCeiling, planAdaptiveContextGrowth, planCtxTokensForMemory, plannedLocalEngineSlots, } = await import('./capacity-broker.js');
+        const { autoKvCacheMaxBytes, 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'];
@@ -1492,7 +1492,12 @@ export class LocalEngineRuntime {
                 // `requirement.minimumPerTurnCtxTokens`, so the windowed
                 // re-plan sheds slots or denies but never shortens the window.
                 const explicitSwaFull = config.llamaCppSwaFull ?? manifestEngineConfig?.swaFull;
-                const windowedCacheWillRun = (!admission.minimumSatisfied || admission.clamped || admission.slots < slots) &&
+                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 })));

package/dist/remotes/identity.d.ts

@@ -73,6 +73,7 @@ export declare const IdentityResponseSchema: z.ZodObject<{
         "machine-engine": "machine-engine";
         "legacy-full": "legacy-full";
     }>>;
+    pairingMethods: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type IdentityResponse = z.infer<typeof IdentityResponseSchema>;
 /** Hex SHA-256 of a PEM-encoded X.509 cert's DER bytes. */

package/dist/remotes/identity.js

@@ -70,6 +70,12 @@ export const IdentityResponseSchema = z.object({
     gezelVersion: z.string().optional(),
     protocolVersion: z.number().optional(),
     serviceRole: z.enum(['user', 'machine-engine', 'legacy-full']).optional(),
+    /**
+     * How a client may pair: `code` (a connect code shown on this device,
+     * SPAKE2 over `/v1/apps/pair/*`) and/or `approval` (`/v1/apps/register`,
+     * approved here). Absent → a server from before connect codes: approval only.
+     */
+    pairingMethods: z.array(z.string()).max(8).optional(),
 });
 /** Hex SHA-256 of a PEM-encoded X.509 cert's DER bytes. */
 export function certFingerprintFromPem(certPem) {

package/dist/remotes/pinned-fetch.d.ts

@@ -17,6 +17,8 @@ import type { PairedRemote, RemotesRegistry } from './types.js';
 export type ClosableFetch = typeof fetch & {
     close(): Promise<void>;
 };
+/** Connect timeout for a paired peer (see {@link createPinnedFetch}). */
+export declare const PINNED_CONNECT_TIMEOUT_MS = 5000;
 /**
  * Pin a single self-signed cert as the sole CA and skip hostname/SAN
  * verification. Long-call-friendly (no header/body timeouts) for streamed

package/dist/remotes/pinned-fetch.js

@@ -15,6 +15,29 @@
  */
 import { Agent, fetch as undiciFetch } from 'undici';
 import { IdentityResponseSchema, certFingerprintFromPem, fingerprintOfPublicKeyPem, verifyIdentitySignature, } from './identity.js';
+/** Connect timeout for a paired peer (see {@link createPinnedFetch}). */
+export const PINNED_CONNECT_TIMEOUT_MS = 5_000;
+/** Failures before any TLS handshake: no certificate was presented, so none can be stale. */
+const NO_HANDSHAKE_CODES = new Set([
+    'ECONNREFUSED',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'EHOSTDOWN',
+    'ENETDOWN',
+    'ETIMEDOUT',
+    'EADDRNOTAVAIL',
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+function failedBeforeHandshake(err) {
+    let current = err;
+    for (let depth = 0; depth < 6 && current && typeof current === 'object'; depth++) {
+        const code = current.code;
+        if (typeof code === 'string' && NO_HANDSHAKE_CODES.has(code))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
 async function closeFetch(fetchImpl) {
     const close = fetchImpl?.close;
     if (typeof close === 'function')
@@ -34,6 +57,10 @@ export function createPinnedFetch(certPem) {
             // IP; the cert identity itself is the pin, reinforced by the identity
             // signature verified at connect time.
             checkServerIdentity: () => undefined,
+            // A peer on the local network answers a connect within milliseconds.
+            // Waiting undici's default 10 s for one that left the network only
+            // delays the fallback; streamed replies keep their unlimited timeouts.
+            timeout: PINNED_CONNECT_TIMEOUT_MS,
         },
         allowH2: true,
         headersTimeout: 0,
@@ -100,7 +127,9 @@ export function createPairedRemoteFetch(remote, registry, deps = {}) {
             return await active(url, init);
         }
         catch (originalError) {
-            if (init?.signal?.aborted)
+            // A refresh re-dials the same address; when that address answered
+            // nothing at all it doubles the wait and fails the same way.
+            if (init?.signal?.aborted || failedBeforeHandshake(originalError))
                 throw originalError;
             refresh ??= refreshPairedCertificate(remote, registry, makeBootstrap).then((cert) => {
                 const previous = active;