@bendyline/gezel-inference 1.0.1 → 1.0.3

package/dist/perf/responsiveness.js

@@ -8,9 +8,10 @@ import { redactPathSecrets } from './redact-path.js';
 /**
  * Main-thread responsiveness monitor.
  *
- * The daemon runs on one event loop. In embedded mode (`pnpm app`, and the
- * packaged fallback) that loop is Electron's main thread, so a synchronous
- * block here freezes the window itself, and Windows labels it "Not Responding"
+ * The daemon runs on one event loop. With an in-process embedded service (the
+ * packaged fallback, E2E, `GEZEL_SERVICE_HOST=in-process`) that loop is
+ * Electron's main thread, so a synchronous block here freezes the window
+ * itself, and Windows labels it "Not Responding"
  * after 5 s. Before this existed a block under the suspend monitor's 10 s floor
  * left no trace, and a longer one was logged as "host resumed after Ns
  * suspended": sleep that never happened (two of them during one catalog
@@ -33,7 +34,7 @@ const log = createLogger('perf');
 /**
  * A gap is measured to within one beat, so this has to stay well inside
  * `STALL_RECORD_MS`. At the same period, a pause long enough to log leaves the
- * watchdog late by more than half the gap, which is what `isMainThreadBlock`
+ * watchdog late by more than half the heartbeat's lateness, which is what `isMainThreadBlock`
  * needs to rule the main thread out.
  */
 export const BEAT_MS = 250;
@@ -55,10 +56,17 @@ const PROFILE_WINDOW_MS = 60_000;
 const PROFILE_SAMPLING_US = 5_000;
 const PROFILE_KEEP = 20;
 const LABEL_MAX = 200;
+/**
+ * A watchdog tick later than this is kept. Half the smallest recordable
+ * lateness: a shorter one cannot rule the main thread out. The floor was a
+ * whole period, which threw away the witness's own evidence of a sub-second
+ * pause of the whole process, so such pauses were filed as main-thread blocks
+ * (idle processes on a swapping machine collected dozens a minute).
+ */
+const WATCHDOG_KEEP_LATE_MS = (STALL_RECORD_MS - BEAT_MS) / 2;
 /**
  * The witness. It keeps its own late ticks and, asked about a gap, answers
- * with the worst one since the gap began. A tick late by less than a period is
- * not kept: it cannot reach half of a recordable gap.
+ * with the worst one since the gap began.
  *
  * It sleeps on a futex instead of running an event loop: a worker woken by its
  * own timer cost about 1.6 context switches per tick on Windows, against 1.0
@@ -69,6 +77,7 @@ const LABEL_MAX = 200;
 const WATCHDOG_SOURCE = `
 const { parentPort, receiveMessageOnPort, workerData } = require('node:worker_threads');
 const tickMs = workerData.tickMs;
+const keepLateMs = workerData.keepLateMs;
 const asked = new Int32Array(workerData.asked);
 const lateTicks = [];
 let lastTick = Date.now();
@@ -78,7 +87,7 @@ for (;;) {
   if (now - lastTick >= tickMs) {
     const lateMs = now - lastTick - tickMs;
     lastTick = now;
-    if (lateMs >= tickMs) {
+    if (lateMs >= keepLateMs) {
       lateTicks.push({ at: now, lateMs });
       if (lateTicks.length > 32) lateTicks.shift();
     }
@@ -98,9 +107,52 @@ for (;;) {
  * A stale heartbeat is a main-thread block only when the watchdog itself kept
  * time. When the watchdog was late by a comparable amount, the process or the
  * host was paused, and blaming whatever was in flight would be a false lead.
+ *
+ * Lateness against lateness: both threads sleep a beat between checks, so a
+ * pause delays each by about its length. Comparing the watchdog's lateness
+ * with the whole gap, beat included, filed short pauses as blocks.
  */
 export function isMainThreadBlock(report) {
-    return report.watchdogLateMs < report.durationMs / 2;
+    return report.watchdogLateMs < (report.durationMs - BEAT_MS) / 2;
+}
+/** Fewer page faults than this in a stall is ordinary; more, with the thread idle, is swap. */
+const PAGING_MIN_FAULTS = 10;
+/**
+ * Read at every beat. Both are single syscalls and add no wakeups. A stall's
+ * duration alone cannot say whether code ran: on a memory-starved machine most
+ * logged stalls were the thread waiting for its own pages to come back from
+ * swap, and their CPU profiles held no samples at all.
+ */
+function readStallCounters() {
+    const threadCpuUsage = process.threadCpuUsage;
+    const cpu = typeof threadCpuUsage === 'function' ? threadCpuUsage() : null;
+    return {
+        cpuMs: cpu ? (cpu.user + cpu.system) / 1_000 : null,
+        pageFaults: process.resourceUsage().majorPageFault,
+    };
+}
+function stallCostBetween(before, after) {
+    return {
+        cpuMs: before.cpuMs !== null && after.cpuMs !== null
+            ? Math.max(0, Math.round(after.cpuMs - before.cpuMs))
+            : null,
+        pageFaults: Math.max(0, after.pageFaults - before.pageFaults),
+    };
+}
+/** Running code when it used at least half the stall; otherwise paging or waiting on something. */
+export function stallVerdict(durationMs, cost) {
+    if (cost.cpuMs === null)
+        return undefined;
+    if (cost.cpuMs >= durationMs / 2)
+        return 'running code';
+    return cost.pageFaults >= PAGING_MIN_FAULTS ? 'paging' : 'blocked waiting';
+}
+export function describeStallCost(durationMs, cost) {
+    const faults = `${cost.pageFaults} page fault${cost.pageFaults === 1 ? '' : 's'}`;
+    const verdict = stallVerdict(durationMs, cost);
+    if (cost.cpuMs === null)
+        return faults;
+    return `cpu ${formatPerfMs(cost.cpuMs)}, ${faults}${verdict ? `: ${verdict}` : ''}`;
 }
 /**
  * Work that overlapped `[start, end]`, most suspicious first. Running work
@@ -295,6 +347,10 @@ class ResponsivenessMonitor {
      */
     awaitingVerdicts = 0;
     rollDeferred = false;
+    /** Counters at the last beat, so a gap's cost is the difference at the next one. */
+    lastBeatCost = readStallCounters();
+    /** What each gap awaiting a verdict cost, keyed by its start. */
+    gapCosts = new Map();
     constructor(opts) {
         this.beatTimer = setInterval(() => this.beat(), BEAT_MS);
         this.beatTimer.unref?.();
@@ -396,11 +452,15 @@ class ResponsivenessMonitor {
         this.lastBeatAt = now;
         const gapMs = now - startedAt;
         this.delay.record(Math.max(1, Math.round((gapMs - BEAT_MS) * 1e6)));
+        const counters = readStallCounters();
+        const before = this.lastBeatCost;
+        this.lastBeatCost = counters;
         if (gapMs < STALL_RECORD_MS || !this.watchdog) {
             if (this.rollDeferred && this.awaitingVerdicts === 0)
                 this.rollProfile();
             return;
         }
+        this.gapCosts.set(startedAt, stallCostBetween(before, counters));
         this.awaitingVerdicts += 1;
         this.watchdog.postMessage({ startedAt, durationMs: gapMs });
         Atomics.store(this.watchdogAsked, 0, 1);
@@ -420,7 +480,11 @@ class ResponsivenessMonitor {
         try {
             const worker = new Worker(WATCHDOG_SOURCE, {
                 eval: true,
-                workerData: { tickMs: WATCHDOG_TICK_MS, asked: this.watchdogAsked.buffer },
+                workerData: {
+                    tickMs: WATCHDOG_TICK_MS,
+                    keepLateMs: WATCHDOG_KEEP_LATE_MS,
+                    asked: this.watchdogAsked.buffer,
+                },
             });
             worker.on('message', (report) => this.onWatchdogReport(report));
             worker.on('error', (err) => {
@@ -440,13 +504,19 @@ class ResponsivenessMonitor {
             this.rollProfile();
     }
     handleReport(report) {
+        const cost = this.gapCosts.get(report.startedAt);
+        this.gapCosts.delete(report.startedAt);
         if (!isMainThreadBlock(report))
             return;
         const now = Date.now();
+        const verdict = cost ? stallVerdict(report.durationMs, cost) : undefined;
         const stall = {
             at: new Date(report.startedAt).toISOString(),
             durationMs: report.durationMs,
             during: workDuring(report.startedAt, report.startedAt + report.durationMs, this.active.values(), this.finished, now),
+            ...(cost?.cpuMs != null ? { cpuMs: cost.cpuMs } : {}),
+            ...(cost ? { pageFaults: cost.pageFaults } : {}),
+            ...(verdict ? { verdict } : {}),
         };
         pushRing(this.stalls, stall);
         if (report.durationMs < STALL_LOG_MS)
@@ -454,7 +524,8 @@ class ResponsivenessMonitor {
         const running = stall.during.length > 0
             ? stall.during.map((w) => `${w.label} (${formatPerfMs(w.durationMs)})`).join(', ')
             : 'nothing tracked';
-        const line = `main thread blocked for ${formatPerfMs(report.durationMs)} — running: ${running}`;
+        const costText = cost ? ` (${describeStallCost(report.durationMs, cost)})` : '';
+        const line = `main thread blocked for ${formatPerfMs(report.durationMs)}${costText} — running: ${running}`;
         if (report.durationMs >= STALL_WARN_MS)
             log.warn(line);
         else

package/dist/providers/audio/kokoro-frontend.js

@@ -75,7 +75,7 @@ export class KokoroFrontend {
                 // put it back, because a packaging slip is the likely cause.
                 throw new Error(`Kokoro pronunciation dictionary is missing at ${file}; rebuild the service (node scripts/build-kokoro-lexicon.mjs stages it).`, { cause });
             }
-            return parseKokoroLexicon(gunzipSync(packed).toString('utf8'));
+            return parseKokoroLexicon(gunzipSync(packed).toString('utf8'), { language });
         })();
         // A failed read must not be cached as a permanent failure.
         void pending.catch(() => this.loaded.delete(language));

package/dist/providers/ds4/build-provider.js

@@ -526,12 +526,18 @@ export async function buildDs4Provider(opts) {
             return { command: binary, args, baseUrl: `http://127.0.0.1:${port}`, cwd: ds4BundleDir };
         },
     });
+    // Sessions budget prompts, `max_tokens`, and compaction against this window,
+    // so it must be the `--ctx` ds4 actually launches with. Left unset, it fell
+    // back to the 64K llama default: GLM 5.3 (launched at 32K) overflowed with
+    // `context_length_exceeded` long before compaction triggered, and DeepSeek
+    // (launched at 128K) compacted at a third of its window.
     const ds4Inner = new LlamaCppProvider({
         supervisor,
         logFile: ds4LogFile,
         disableThinkingRequestShape: 'deepseek',
         classifyLine: classifyDs4Line,
         visionEnabled: vision.enabled,
+        numCtx,
         ...baseProviderOpts,
     });
     ds4ProviderHolder.current = ds4Inner;

package/dist/providers/llama-cpp/backend-health.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Whether llama-server is getting the hardware this machine has, as the
+ * engine process sees it: the CUDA build discovery passed over for the
+ * driver (`GEZEL_LLAMA_CUDA_BLOCKER`), a GPU build that started without its
+ * GPU (gpu-startup-watch.ts), and Linux's out-of-memory killer stopping the
+ * engine. Each is invisible otherwise — the engine keeps answering, slower,
+ * or a chat fails with a crash that reads like any other.
+ *
+ * Process-wide like the backend env it sits beside: every llama provider in
+ * this process launches the same build.
+ */
+import type { LlamaCppBackendHealthResponse } from '@bendyline/gezel';
+import type { GpuUnused } from './gpu-startup-watch.js';
+/** Record what the latest start of a build found; null clears it. */
+export declare function noteGpuStartup(verdict: GpuUnused | null, now?: Date): void;
+export declare function noteHostOutOfMemory(input: {
+    model?: string | undefined;
+    whileStarting: boolean;
+}, now?: Date): void;
+declare const BACKENDS: readonly ["cuda", "vulkan", "metal", "cpu"];
+/**
+ * The backend this process's on-device llama-server runs, for catalog
+ * backend exclusions: the build discovery resolved, else what the probe
+ * found, else the only build macOS ships. Undefined when an external server
+ * is configured through the environment — its backend is not ours to know.
+ */
+export declare function currentLlamaCppBackend(): (typeof BACKENDS)[number] | undefined;
+export declare function llamaBackendHealthView(): LlamaCppBackendHealthResponse;
+export declare function __resetLlamaBackendHealthForTest(): void;
+export {};

package/dist/providers/llama-cpp/backend-health.js

@@ -0,0 +1,64 @@
+/**
+ * Whether llama-server is getting the hardware this machine has, as the
+ * engine process sees it: the CUDA build discovery passed over for the
+ * driver (`GEZEL_LLAMA_CUDA_BLOCKER`), a GPU build that started without its
+ * GPU (gpu-startup-watch.ts), and Linux's out-of-memory killer stopping the
+ * engine. Each is invisible otherwise — the engine keeps answering, slower,
+ * or a chat fails with a crash that reads like any other.
+ *
+ * Process-wide like the backend env it sits beside: every llama provider in
+ * this process launches the same build.
+ */
+import { readLlamaCudaBlocker } from '@bendyline/gezel/native';
+let gpuUnused = null;
+let outOfMemory = null;
+/** Record what the latest start of a build found; null clears it. */
+export function noteGpuStartup(verdict, now = new Date()) {
+    gpuUnused = verdict ? { ...verdict, at: now.toISOString() } : null;
+}
+export function noteHostOutOfMemory(input, now = new Date()) {
+    outOfMemory = {
+        count: (outOfMemory?.count ?? 0) + 1,
+        at: now.toISOString(),
+        ...(input.model ? { model: input.model } : {}),
+        whileStarting: input.whileStarting,
+    };
+}
+const BACKENDS = ['cuda', 'vulkan', 'metal', 'cpu'];
+/**
+ * The backend this process's on-device llama-server runs, for catalog
+ * backend exclusions: the build discovery resolved, else what the probe
+ * found, else the only build macOS ships. Undefined when an external server
+ * is configured through the environment — its backend is not ours to know.
+ */
+export function currentLlamaCppBackend() {
+    if (process.env.GEZEL_LLAMA_SERVER_URL)
+        return undefined;
+    for (const raw of [
+        process.env.GEZEL_LLAMA_SERVER_BACKEND,
+        process.env.GEZEL_LLAMA_DETECTED_BACKEND,
+    ]) {
+        const backend = BACKENDS.find((b) => b === raw);
+        if (backend)
+            return backend;
+    }
+    return process.platform === 'darwin' ? 'metal' : undefined;
+}
+export function llamaBackendHealthView() {
+    const runningRaw = process.env.GEZEL_LLAMA_SERVER_BACKEND;
+    const running = BACKENDS.find((backend) => backend === runningRaw);
+    const cudaBlocker = readLlamaCudaBlocker();
+    // A verdict about a build the process has since moved off (a quarantine
+    // fallback, a lifted quarantine) no longer describes what runs.
+    const unused = gpuUnused && gpuUnused.backend === running ? gpuUnused : null;
+    return {
+        ...(running ? { running } : {}),
+        ...(cudaBlocker ? { cudaBlocker } : {}),
+        ...(unused ? { gpuUnused: unused } : {}),
+        ...(outOfMemory ? { outOfMemory } : {}),
+    };
+}
+export function __resetLlamaBackendHealthForTest() {
+    gpuUnused = null;
+    outOfMemory = null;
+}

package/dist/providers/llama-cpp/backend-quarantine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The engine process's side of the llama-server quarantine
+ * (`llama-quarantine.ts` in `@bendyline/gezel/native`): which build this
+ * process launches, kept in the env discovery stamps at startup
+ * (`GEZEL_LLAMA_SERVER_BIN`, `GEZEL_LLAMA_SERVER_BACKEND`,
+ * `GEZEL_LLAMA_QUARANTINED`), and the view and undo behind the engine's
+ * Settings tab.
+ *
+ * Discovery reads the quarantine only at startup. These move the env inside
+ * a running process, so a quarantine and its undo both take effect on the
+ * next engine launch instead of the next app start.
+ */
+import type { LlamaCppQuarantineResponse } from '@bendyline/gezel';
+import { type LlamaBackend, type ResolvedLlamaBinary } from '@bendyline/gezel/native';
+export declare function isLlamaBackend(value: string): value is LlamaBackend;
+/**
+ * Point this process at the build that replaces `backend`'s, just
+ * quarantined, so the pool's rebuild of the failed engine launches it. Null,
+ * env untouched, when nothing usable is bundled beside `binary`.
+ */
+export declare function adoptLlamaFallback(home: string, binary: string, backend: LlamaBackend): ResolvedLlamaBinary | null;
+/**
+ * The quarantined builds that still apply. An entry pins its binary's bytes,
+ * so one whose build an update replaced is left out — discovery ignores it
+ * too. Without a resolved build to measure from, entries are shown as written.
+ */
+export declare function llamaQuarantineView(home: string): LlamaCppQuarantineResponse;
+/**
+ * Lift `backend`'s quarantine at a person's request. Unless they pinned a
+ * backend, also point this process back at the best build the hardware
+ * supports, so the next engine launch tries it; `restored` is that build when
+ * the env moved. A pinned backend is launched as pinned and was never routed
+ * around, so there is nothing to move back.
+ */
+export declare function liftLlamaQuarantine(home: string, backend: LlamaBackend, opts: {
+    pinned: boolean;
+}): {
+    cleared: boolean;
+    restored: ResolvedLlamaBinary | null;
+};

package/dist/providers/llama-cpp/backend-quarantine.js

@@ -0,0 +1,100 @@
+/**
+ * The engine process's side of the llama-server quarantine
+ * (`llama-quarantine.ts` in `@bendyline/gezel/native`): which build this
+ * process launches, kept in the env discovery stamps at startup
+ * (`GEZEL_LLAMA_SERVER_BIN`, `GEZEL_LLAMA_SERVER_BACKEND`,
+ * `GEZEL_LLAMA_QUARANTINED`), and the view and undo behind the engine's
+ * Settings tab.
+ *
+ * Discovery reads the quarantine only at startup. These move the env inside
+ * a running process, so a quarantine and its undo both take effect on the
+ * next engine launch instead of the next app start.
+ */
+import { LLAMA_QUARANTINE_STRIKES, clearLlamaQuarantine, createLlamaBuildCheck, isBinaryQuarantined, llamaVariantBinaryPath, publishLlamaCudaBlocker, readLlamaQuarantine, resolveLlamaFallbackBinary, resolveLlamaVariantBinary, } from '@bendyline/gezel/native';
+const BACKENDS = ['cuda', 'vulkan', 'metal', 'cpu'];
+export function isLlamaBackend(value) {
+    return BACKENDS.some((backend) => backend === value);
+}
+function envBackend(name) {
+    const raw = process.env[name];
+    return raw !== undefined && isLlamaBackend(raw) ? raw : undefined;
+}
+function updateQuarantinedEnv(update) {
+    const backends = new Set(process.env.GEZEL_LLAMA_QUARANTINED?.split(',').filter(Boolean));
+    update(backends);
+    if (backends.size > 0)
+        process.env.GEZEL_LLAMA_QUARANTINED = [...backends].join(',');
+    else
+        delete process.env.GEZEL_LLAMA_QUARANTINED;
+}
+/**
+ * Point this process at the build that replaces `backend`'s, just
+ * quarantined, so the pool's rebuild of the failed engine launches it. Null,
+ * env untouched, when nothing usable is bundled beside `binary`.
+ */
+export function adoptLlamaFallback(home, binary, backend) {
+    const quarantine = readLlamaQuarantine(home);
+    const fallback = resolveLlamaFallbackBinary(binary, backend, (candidate, path) => !isBinaryQuarantined(quarantine, candidate, path));
+    if (!fallback)
+        return null;
+    process.env.GEZEL_LLAMA_SERVER_BIN = fallback.path;
+    process.env.GEZEL_LLAMA_SERVER_BACKEND = fallback.backend;
+    updateQuarantinedEnv((backends) => backends.add(backend));
+    return fallback;
+}
+/**
+ * The quarantined builds that still apply. An entry pins its binary's bytes,
+ * so one whose build an update replaced is left out — discovery ignores it
+ * too. Without a resolved build to measure from, entries are shown as written.
+ */
+export function llamaQuarantineView(home) {
+    const binary = process.env.GEZEL_LLAMA_SERVER_BIN;
+    const running = envBackend('GEZEL_LLAMA_SERVER_BACKEND');
+    const entries = readLlamaQuarantine(home).filter((entry) => {
+        if (!isLlamaBackend(entry.backend))
+            return false;
+        if (!binary || !running)
+            return true;
+        const path = llamaVariantBinaryPath(binary, running, entry.backend);
+        return path === null || isBinaryQuarantined([entry], entry.backend, path);
+    });
+    return {
+        entries: entries.map(({ backend, signal, reason, at, crashes }) => ({
+            backend,
+            signal,
+            reason,
+            at,
+            ...(crashes !== undefined ? { crashes } : {}),
+        })),
+        strikeThreshold: LLAMA_QUARANTINE_STRIKES,
+        ...(running ? { running } : {}),
+    };
+}
+/**
+ * Lift `backend`'s quarantine at a person's request. Unless they pinned a
+ * backend, also point this process back at the best build the hardware
+ * supports, so the next engine launch tries it; `restored` is that build when
+ * the env moved. A pinned backend is launched as pinned and was never routed
+ * around, so there is nothing to move back.
+ */
+export function liftLlamaQuarantine(home, backend, opts) {
+    const cleared = clearLlamaQuarantine(home, backend);
+    updateQuarantinedEnv((backends) => backends.delete(backend));
+    const binary = process.env.GEZEL_LLAMA_SERVER_BIN;
+    const running = envBackend('GEZEL_LLAMA_SERVER_BACKEND');
+    if (opts.pinned || !binary || !running)
+        return { cleared, restored: null };
+    // Discovery's own check: a CUDA build the driver cannot run stays passed
+    // over, whatever else was lifted.
+    const check = createLlamaBuildCheck({
+        quarantine: readLlamaQuarantine(home),
+        platform: process.platform,
+    });
+    const best = resolveLlamaVariantBinary(binary, running, envBackend('GEZEL_LLAMA_DETECTED_BACKEND') ?? backend, check.isUsable);
+    publishLlamaCudaBlocker(check.cudaBlocker());
+    if (!best || best.backend === running)
+        return { cleared, restored: null };
+    process.env.GEZEL_LLAMA_SERVER_BIN = best.path;
+    process.env.GEZEL_LLAMA_SERVER_BACKEND = best.backend;
+    return { cleared, restored: best };
+}