@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/perf/responsiveness.js

@@ -0,0 +1,560 @@
+import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { Session } from 'node:inspector/promises';
+import { join } from 'node:path';
+import { createHistogram } from 'node:perf_hooks';
+import { Worker } from 'node:worker_threads';
+import { createLogger, } from '@bendyline/gezel';
+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"
+ * 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
+ * update, 2026-09-30).
+ *
+ * Detection is a heartbeat on the main thread that notices its own gaps, with
+ * a watchdog worker as the witness: if the worker's timer stayed on schedule
+ * through the gap, the main thread was blocked; if the worker was late too, the
+ * whole process or host was paused, which is the suspend clock's business.
+ * `eventLoopUtilization()` cannot make that call: Electron's main process
+ * reports it as all zeros.
+ *
+ * Every tick here wakes an otherwise idle process, and the machine service is
+ * idle almost all of the time. A 20 ms event-loop-delay histogram plus 100 ms
+ * ticks on both threads took an idle daemon from 13 to 59 context switches a
+ * second (v1.26275.85), so the beat doubles as the delay sampler and both
+ * threads tick at the coarsest period that still measures a recordable stall.
+ */
+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`
+ * needs to rule the main thread out.
+ */
+export const BEAT_MS = 250;
+export const WATCHDOG_TICK_MS = 250;
+/** Shorter blocks are ordinary GC and JSON work; not worth a record. */
+export const STALL_RECORD_MS = 500;
+const STALL_LOG_MS = 1_000;
+/** Windows marks an unresponsive window "Not Responding" after 5 s. */
+const STALL_WARN_MS = 5_000;
+const SLOW_REQUEST_RECORD_MS = 250;
+const SLOW_REQUEST_LOG_MS = 1_000;
+const RING_SIZE = 50;
+/** Finished work is kept this long so a stall can name what ran through it. */
+const FINISHED_WORK_KEEP_MS = 120_000;
+const FINISHED_WORK_MIN_MS = 50;
+const FINISHED_WORK_CAP = 500;
+const DELAY_WINDOW_MS = 5 * 60_000;
+const PROFILE_WINDOW_MS = 60_000;
+const PROFILE_SAMPLING_US = 5_000;
+const PROFILE_KEEP = 20;
+const LABEL_MAX = 200;
+/**
+ * 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.
+ *
+ * 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
+ * for this. The main thread posts the question and then flips `asked` to wake
+ * it early. Ticks are settled before questions, so a late tick at a resume is
+ * always on record by the time the question about that gap is answered.
+ */
+const WATCHDOG_SOURCE = `
+const { parentPort, receiveMessageOnPort, workerData } = require('node:worker_threads');
+const tickMs = workerData.tickMs;
+const asked = new Int32Array(workerData.asked);
+const lateTicks = [];
+let lastTick = Date.now();
+for (;;) {
+  Atomics.wait(asked, 0, 0, Math.max(0, lastTick + tickMs - Date.now()));
+  const now = Date.now();
+  if (now - lastTick >= tickMs) {
+    const lateMs = now - lastTick - tickMs;
+    lastTick = now;
+    if (lateMs >= tickMs) {
+      lateTicks.push({ at: now, lateMs });
+      if (lateTicks.length > 32) lateTicks.shift();
+    }
+  }
+  Atomics.store(asked, 0, 0);
+  for (let m = receiveMessageOnPort(parentPort); m; m = receiveMessageOnPort(parentPort)) {
+    const gap = m.message;
+    let lateMs = 0;
+    for (const tick of lateTicks) {
+      if (tick.at > gap.startedAt && tick.lateMs > lateMs) lateMs = tick.lateMs;
+    }
+    parentPort.postMessage({ startedAt: gap.startedAt, durationMs: gap.durationMs, watchdogLateMs: lateMs });
+  }
+}
+`;
+/**
+ * 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.
+ */
+export function isMainThreadBlock(report) {
+    return report.watchdogLateMs < report.durationMs / 2;
+}
+/**
+ * Work that overlapped `[start, end]`, most suspicious first. Running work
+ * counts to `now`; a request that blocked the thread finishes the instant the
+ * block ends, so finished work has to be searched too. Ranking is by overlap
+ * with the block, then by the tightest fit: a 10 s request inside a 10 s block
+ * outranks a 90 s long-poll that merely spanned it.
+ */
+export function workDuring(start, end, active, finished, now, limit = 6) {
+    const hits = [];
+    const consider = (w, until) => {
+        const overlap = Math.min(until, end) - Math.max(w.startedAt, start);
+        if (overlap > 0)
+            hits.push({ label: w.label, durationMs: until - w.startedAt, overlap });
+    };
+    for (const w of active)
+        consider(w, now);
+    for (const w of finished)
+        consider(w, w.endedAt);
+    hits.sort((a, b) => b.overlap - a.overlap || a.durationMs - b.durationMs);
+    return hits.slice(0, limit).map(({ label, durationMs }) => ({ label, durationMs }));
+}
+export function formatPerfMs(ms) {
+    if (ms < 1_000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1_000).toFixed(1)}s`;
+    const m = Math.floor(ms / 60_000);
+    return `${m}m${Math.round((ms % 60_000) / 1_000)}s`;
+}
+function pushRing(ring, item) {
+    ring.push(item);
+    if (ring.length > RING_SIZE)
+        ring.splice(0, ring.length - RING_SIZE);
+}
+function clip(label) {
+    return label.length > LABEL_MAX ? `${label.slice(0, LABEL_MAX - 1)}…` : label;
+}
+/**
+ * Rolling CPU profile of the main thread, kept only when a window contains a
+ * stall. The V8 sampler runs on its own thread, so samples land inside a
+ * synchronous block, native calls included — which is what makes the saved
+ * profile a verdict rather than a suspect list.
+ */
+class StallProfiler {
+    dir;
+    wanted;
+    session = null;
+    running = false;
+    disabled = false;
+    chain = Promise.resolve();
+    /** When the current profile began, so a capture can tell if it covers a block. */
+    profileStartedAt = 0;
+    constructor(dir, wanted) {
+        this.dir = dir;
+        this.wanted = wanted;
+    }
+    get active() {
+        return this.running;
+    }
+    /**
+     * Start or stop to match `wanted()` without restarting a running profile.
+     * Boot calls this the moment debug mode is known: waiting for the first
+     * window roll left every boot block unprofiled (2026-10-08).
+     */
+    sync() {
+        this.enqueue(async () => {
+            const want = this.wantNow();
+            if (want && !this.running)
+                await this.begin();
+            else if (!want && this.running)
+                await this.end();
+        });
+    }
+    /** Called every window: start, stop, or roll the profile per `wanted()`. */
+    roll() {
+        this.enqueue(async () => {
+            const want = this.wantNow();
+            if (want && !this.running)
+                await this.begin();
+            else if (!want && this.running)
+                await this.end();
+            else if (this.running) {
+                await this.end();
+                await this.begin();
+            }
+        });
+    }
+    /**
+     * Save the current window's profile. Resolves to the file name, or null.
+     * A profile that began after the block did is not saved: it holds only the
+     * tail, and a 263 ms profile filed as "the 2.7s block" sent the reader after
+     * the profiler's own startup cost.
+     */
+    capture(at, durationMs) {
+        return this.enqueue(async () => {
+            if (!this.running || !this.session)
+                return null;
+            // `at` is the last beat before the block, up to a beat ahead of it.
+            if (this.profileStartedAt > at + BEAT_MS)
+                return null;
+            const { profile } = await this.session.post('Profiler.stop');
+            this.running = false;
+            const stamp = new Date(at).toISOString().replace(/[:.]/g, '-');
+            const name = `stall-${stamp}-${Math.round(durationMs)}ms.cpuprofile`;
+            await mkdir(this.dir, { recursive: true });
+            await writeFile(join(this.dir, name), JSON.stringify(profile));
+            await this.prune();
+            if (this.wantNow())
+                await this.begin();
+            return name;
+        });
+    }
+    dispose() {
+        return this.enqueue(async () => {
+            await this.end();
+            this.session?.disconnect();
+            this.session = null;
+        }).then(() => undefined);
+    }
+    wantNow() {
+        if (this.disabled)
+            return false;
+        try {
+            return this.wanted();
+        }
+        catch {
+            return false;
+        }
+    }
+    async begin() {
+        if (!this.session) {
+            const session = new Session();
+            session.connect();
+            this.session = session;
+        }
+        await this.session.post('Profiler.enable');
+        await this.session.post('Profiler.setSamplingInterval', { interval: PROFILE_SAMPLING_US });
+        const startedAt = Date.now();
+        await this.session.post('Profiler.start');
+        this.profileStartedAt = startedAt;
+        this.running = true;
+    }
+    async end() {
+        if (!this.running || !this.session)
+            return;
+        this.running = false;
+        await this.session.post('Profiler.stop');
+    }
+    async prune() {
+        const names = (await readdir(this.dir))
+            .filter((n) => n.startsWith('stall-') && n.endsWith('.cpuprofile'))
+            .sort();
+        for (const old of names.slice(0, Math.max(0, names.length - PROFILE_KEEP))) {
+            await rm(join(this.dir, old), { force: true });
+        }
+    }
+    enqueue(op) {
+        const next = this.chain.then(op).catch((err) => {
+            // Another inspector client (a debugger attached with --inspect) can own
+            // the profiler. Losing profiles must never cost the daemon anything else.
+            this.disabled = true;
+            this.running = false;
+            log.warn(`CPU profiling for stalls is off for this run: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        });
+        this.chain = next;
+        return next;
+    }
+}
+class ResponsivenessMonitor {
+    startedAt = Date.now();
+    active = new Map();
+    finished = [];
+    stalls = [];
+    slowRequests = [];
+    clientReports = [];
+    nextId = 1;
+    lastBeatAt = Date.now();
+    beatTimer;
+    windowTimer;
+    /** Beat lateness in nanoseconds, the unit `monitorEventLoopDelay` used. */
+    delay = createHistogram();
+    delayWindowStartedAt = Date.now();
+    watchdogAsked = new Int32Array(new SharedArrayBuffer(4));
+    watchdog = null;
+    profiler;
+    /**
+     * Gaps sent to the watchdog and not yet answered. The window timer comes due
+     * during a long block and fires in the same tick as the beat that reports
+     * it, so rolling then discarded the very profile the answer would save.
+     */
+    awaitingVerdicts = 0;
+    rollDeferred = false;
+    constructor(opts) {
+        this.beatTimer = setInterval(() => this.beat(), BEAT_MS);
+        this.beatTimer.unref?.();
+        this.profiler = new StallProfiler(join(opts.logsDir, 'perf'), opts.profileWhen ?? (() => false));
+        this.windowTimer = setInterval(() => {
+            this.rollProfile();
+            if (Date.now() - this.delayWindowStartedAt >= DELAY_WINDOW_MS) {
+                this.delay.reset();
+                this.delayWindowStartedAt = Date.now();
+            }
+        }, opts.profileWindowMs ?? PROFILE_WINDOW_MS);
+        this.windowTimer.unref?.();
+        this.profiler.roll();
+        this.startWatchdog();
+    }
+    /** Match profiling to the current debug setting now, not at the next window. */
+    syncProfiling() {
+        this.profiler.sync();
+    }
+    rollProfile() {
+        // A stale beat is a gap about to be reported: the window timer can fire
+        // ahead of the beat that reports it.
+        if (this.awaitingVerdicts > 0 || Date.now() - this.lastBeatAt >= STALL_RECORD_MS) {
+            this.rollDeferred = true;
+            return;
+        }
+        this.rollDeferred = false;
+        this.profiler.roll();
+    }
+    begin(label) {
+        const id = this.nextId++;
+        const work = { label: clip(redactPathSecrets(label)), startedAt: Date.now() };
+        this.active.set(id, work);
+        return (outcome) => {
+            if (!this.active.delete(id))
+                return;
+            const endedAt = Date.now();
+            const durationMs = endedAt - work.startedAt;
+            if (durationMs >= FINISHED_WORK_MIN_MS)
+                this.remember({ ...work, endedAt });
+            if (outcome?.method && outcome.path && durationMs >= SLOW_REQUEST_RECORD_MS) {
+                const status = outcome.status ?? 0;
+                pushRing(this.slowRequests, {
+                    at: new Date(work.startedAt).toISOString(),
+                    method: outcome.method,
+                    path: clip(redactPathSecrets(outcome.path)),
+                    status,
+                    durationMs,
+                });
+                if (durationMs >= SLOW_REQUEST_LOG_MS) {
+                    log.info(`slow request ${work.label} ${formatPerfMs(durationMs)} (${status})`);
+                }
+            }
+        };
+    }
+    recordClient(received) {
+        const report = redactClientReport(received);
+        pushRing(this.clientReports, { receivedAt: new Date().toISOString(), report });
+        log.info(`ui: ${describeClientReport(report)}`);
+    }
+    snapshot() {
+        const now = Date.now();
+        const count = this.delay.count;
+        return {
+            running: true,
+            startedAt: new Date(this.startedAt).toISOString(),
+            profiling: this.profiler.active,
+            eventLoopDelay: count > 0
+                ? {
+                    windowStartedAt: new Date(this.delayWindowStartedAt).toISOString(),
+                    p50Ms: this.delay.percentile(50) / 1e6,
+                    p99Ms: this.delay.percentile(99) / 1e6,
+                    maxMs: this.delay.max / 1e6,
+                }
+                : null,
+            stalls: [...this.stalls],
+            slowRequests: [...this.slowRequests],
+            inflight: [...this.active.values()]
+                .map((w) => ({ label: w.label, durationMs: now - w.startedAt }))
+                .sort((a, b) => b.durationMs - a.durationMs),
+            clientReports: [...this.clientReports],
+        };
+    }
+    async dispose() {
+        clearInterval(this.beatTimer);
+        clearInterval(this.windowTimer);
+        const watchdog = this.watchdog;
+        this.watchdog = null;
+        await Promise.all([watchdog?.terminate(), this.profiler.dispose()]);
+    }
+    /**
+     * A gap is reported from the last beat, the last moment the thread was seen
+     * alive, so it overstates the block by less than one beat rather than
+     * missing one of a recordable size.
+     */
+    beat() {
+        const now = Date.now();
+        const startedAt = this.lastBeatAt;
+        this.lastBeatAt = now;
+        const gapMs = now - startedAt;
+        this.delay.record(Math.max(1, Math.round((gapMs - BEAT_MS) * 1e6)));
+        if (gapMs < STALL_RECORD_MS || !this.watchdog) {
+            if (this.rollDeferred && this.awaitingVerdicts === 0)
+                this.rollProfile();
+            return;
+        }
+        this.awaitingVerdicts += 1;
+        this.watchdog.postMessage({ startedAt, durationMs: gapMs });
+        Atomics.store(this.watchdogAsked, 0, 1);
+        Atomics.notify(this.watchdogAsked, 0);
+    }
+    remember(work) {
+        const cutoff = work.endedAt - FINISHED_WORK_KEEP_MS;
+        const oldest = this.finished[0];
+        if (this.finished.length >= FINISHED_WORK_CAP || (oldest && oldest.endedAt < cutoff)) {
+            this.finished = this.finished
+                .filter((w) => w.endedAt >= cutoff)
+                .slice(-(FINISHED_WORK_CAP - 1));
+        }
+        this.finished.push(work);
+    }
+    startWatchdog() {
+        try {
+            const worker = new Worker(WATCHDOG_SOURCE, {
+                eval: true,
+                workerData: { tickMs: WATCHDOG_TICK_MS, asked: this.watchdogAsked.buffer },
+            });
+            worker.on('message', (report) => this.onWatchdogReport(report));
+            worker.on('error', (err) => {
+                log.warn(`stall watchdog stopped: ${err instanceof Error ? err.message : String(err)}`);
+            });
+            worker.unref();
+            this.watchdog = worker;
+        }
+        catch (err) {
+            log.warn(`stall watchdog unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    onWatchdogReport(report) {
+        this.awaitingVerdicts = Math.max(0, this.awaitingVerdicts - 1);
+        this.handleReport(report);
+        if (this.awaitingVerdicts === 0 && this.rollDeferred)
+            this.rollProfile();
+    }
+    handleReport(report) {
+        if (!isMainThreadBlock(report))
+            return;
+        const now = Date.now();
+        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),
+        };
+        pushRing(this.stalls, stall);
+        if (report.durationMs < STALL_LOG_MS)
+            return;
+        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}`;
+        if (report.durationMs >= STALL_WARN_MS)
+            log.warn(line);
+        else
+            log.info(line);
+        void this.profiler.capture(report.startedAt, report.durationMs).then((name) => {
+            if (!name)
+                return;
+            stall.profile = name;
+            log.info(`CPU profile of the ${formatPerfMs(report.durationMs)} block: logs/perf/${name}`);
+        });
+    }
+}
+/**
+ * The renderer reports the paths it timed, so they are scrubbed like the
+ * daemon's own. Never longer than what arrived: `GET /perf` validates the
+ * stored report again against the same length caps.
+ */
+export function redactClientReport(report) {
+    const scrub = (text) => redactPathSecrets(text).slice(0, text.length);
+    if (report.kind === 'long-task') {
+        return {
+            ...report,
+            view: scrub(report.view),
+            ...(report.source !== undefined ? { source: scrub(report.source) } : {}),
+        };
+    }
+    return {
+        ...report,
+        view: scrub(report.view),
+        slowest: report.slowest.map((request) => ({ ...request, path: scrub(request.path) })),
+    };
+}
+export function describeClientReport(report) {
+    if (report.kind === 'long-task') {
+        return `renderer blocked for ${formatPerfMs(report.durationMs)} on ${report.view}${report.source ? ` in ${report.source}` : ''}`;
+    }
+    const slowest = report.slowest[0];
+    const parts = [
+        `opened ${report.view} in ${formatPerfMs(report.settledMs)}${report.unsettled ? ' (still loading)' : ''}`,
+        `first frame ${formatPerfMs(report.firstFrameMs)}`,
+        `${report.requests} request${report.requests === 1 ? '' : 's'}`,
+    ];
+    if (slowest) {
+        parts.push(`slowest ${slowest.method} ${slowest.path} ${formatPerfMs(slowest.ms)}${slowest.serverMs !== undefined ? ` (daemon ${formatPerfMs(slowest.serverMs)})` : ''}`);
+    }
+    if (report.longTasks.count > 0) {
+        parts.push(`renderer busy ${report.longTasks.count}× (max ${formatPerfMs(report.longTasks.maxMs)})`);
+    }
+    return parts.join(', ');
+}
+let monitor = null;
+const noop = () => { };
+/**
+ * Start watching the main thread. A second start replaces the first; the
+ * returned stopper only ever stops the monitor it started.
+ */
+export function startResponsivenessMonitor(opts) {
+    if (monitor)
+        void monitor.dispose();
+    const mine = new ResponsivenessMonitor(opts);
+    monitor = mine;
+    return async () => {
+        if (monitor === mine)
+            monitor = null;
+        await mine.dispose();
+    };
+}
+/** Start or stop the stall profiler to match its condition now. */
+export function syncPerfProfiling() {
+    monitor?.syncProfiling();
+}
+/**
+ * Mark a stretch of background work so a stall that happens during it can
+ * name it. Returns the function that ends the stretch; free when no monitor runs.
+ */
+export function beginPerfWork(label) {
+    if (!monitor)
+        return noop;
+    const end = monitor.begin(label);
+    return () => end();
+}
+/** Time one HTTP request. The returned function takes the response status. */
+export function beginPerfRequest(method, path) {
+    if (!monitor)
+        return noop;
+    const end = monitor.begin(`${method} ${path}`);
+    return (status) => end({ status, method, path });
+}
+export function recordClientPerfReport(report) {
+    monitor?.recordClient(report);
+}
+export function perfSnapshot() {
+    return (monitor?.snapshot() ?? {
+        running: false,
+        startedAt: null,
+        profiling: false,
+        eventLoopDelay: null,
+        stalls: [],
+        slowRequests: [],
+        inflight: [],
+        clientReports: [],
+    });
+}

package/dist/providers/active-install-message.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The sentence a chat turn shows when no local model is installed yet.
+ *
+ * A first run pins a recommended model and the user starts a multi-gigabyte
+ * download — then, quite reasonably, tries to chat while they wait. The turn
+ * fails, because there is genuinely nothing to answer with. What it used to
+ * say was "Download a model from the list above", which is written for the
+ * Settings model list and is wrong twice over in a chat: there is no list
+ * above, and the download they are being told to start is already running.
+ *
+ * Given the live install snapshot, say the true thing instead.
+ */
+export interface ActiveInstallLike {
+    catalogId: string;
+    bytesWritten: number;
+    totalBytes: number;
+    phase: 'downloading' | 'verifying' | 'extracting-metadata';
+}
+/** Whole-percent progress, or null when the total size isn't known yet. */
+export declare function installPercent(install: ActiveInstallLike): number | null;
+/**
+ * The Settings tab that lists this machine's models, named the way the UI's
+ * `deviceLabel` names it. llama.cpp runs everywhere, so its errors must not
+ * send a Windows owner to a "This Mac" tab that does not exist.
+ */
+export declare function localDeviceSettingsLabel(platform?: NodeJS.Platform): string;
+/**
+ * Why an on-device chat can't answer yet. Not a fault: the person is waiting
+ * on a download, so the turn's failure card offers the fix and no bug report.
+ * `describeTurnError` copies the code into the turn's error detail.
+ */
+export type NotReadyCode = 'model-not-ready' | 'engine-not-ready';
+/** An actionable error for a chat that can't answer yet. */
+export declare function notReadyError(message: string, code: NotReadyCode): Error;
+/**
+ * Compose the user-facing message for a chat turn that found no model.
+ *
+ * `active` is whichever install is in flight for this engine, or null. The
+ * caller supplies `engineLabel` ("Local model", "Apple MLX") so the message
+ * keeps the prefix the rest of that provider's errors use.
+ */
+export declare function noModelYetMessage(engineLabel: string, active: ActiveInstallLike | null): string;

package/dist/providers/active-install-message.js

@@ -0,0 +1,49 @@
+/** Whole-percent progress, or null when the total size isn't known yet. */
+export function installPercent(install) {
+    if (!Number.isFinite(install.totalBytes) || install.totalBytes <= 0)
+        return null;
+    const pct = (install.bytesWritten / install.totalBytes) * 100;
+    if (!Number.isFinite(pct))
+        return null;
+    // Never round up to 100 while bytes are still arriving — "100% downloaded"
+    // next to a turn that just failed reads as a contradiction.
+    return Math.max(0, Math.min(99, Math.floor(pct)));
+}
+/**
+ * The Settings tab that lists this machine's models, named the way the UI's
+ * `deviceLabel` names it. llama.cpp runs everywhere, so its errors must not
+ * send a Windows owner to a "This Mac" tab that does not exist.
+ */
+export function localDeviceSettingsLabel(platform = process.platform) {
+    if (platform === 'darwin')
+        return 'This Mac';
+    if (platform === 'win32')
+        return 'This PC';
+    return 'This Device';
+}
+/** An actionable error for a chat that can't answer yet. */
+export function notReadyError(message, code) {
+    const err = new Error(message);
+    err.isActionable = true;
+    err.code = code;
+    return err;
+}
+/**
+ * Compose the user-facing message for a chat turn that found no model.
+ *
+ * `active` is whichever install is in flight for this engine, or null. The
+ * caller supplies `engineLabel` ("Local model", "Apple MLX") so the message
+ * keeps the prefix the rest of that provider's errors use.
+ */
+export function noModelYetMessage(engineLabel, active) {
+    if (!active) {
+        return `${engineLabel}: no model is installed yet. Download one from Settings → Artificial Intelligence, then try again.`;
+    }
+    if (active.phase !== 'downloading') {
+        const verb = active.phase === 'verifying' ? 'being verified' : 'being prepared';
+        return `${engineLabel}: your model is ${verb} — hang tight, this message will work as soon as it finishes.`;
+    }
+    const pct = installPercent(active);
+    const progress = pct === null ? 'still downloading' : `${pct}% downloaded`;
+    return `${engineLabel}: your model is ${progress} — hang tight. Send this again once it finishes and it will go through.`;
+}

package/dist/providers/apple-foundation-models/binary.d.ts

@@ -0,0 +1,4 @@
+/** Both Electron and headless CLI startup can publish the verified native root. */
+export declare function appleFmBinaryPath(env?: NodeJS.ProcessEnv): string | undefined;
+/** Passive picker presence. Only an explicit helper probe can establish readiness. */
+export declare function appleFoundationModelsInstalled(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, arch?: string): boolean;

package/dist/providers/apple-foundation-models/binary.js

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Both Electron and headless CLI startup can publish the verified native root. */
+export function appleFmBinaryPath(env = process.env) {
+    if (env.GEZEL_APPLE_FM_BIN)
+        return env.GEZEL_APPLE_FM_BIN;
+    if (env.GEZEL_NATIVE_BIN_DIR) {
+        const binary = join(env.GEZEL_NATIVE_BIN_DIR, 'darwin-arm64', 'gezel-apple-fm');
+        if (existsSync(binary))
+            return binary;
+    }
+    return undefined;
+}
+/** Passive picker presence. Only an explicit helper probe can establish readiness. */
+export function appleFoundationModelsInstalled(env = process.env, platform = process.platform, arch = process.arch) {
+    const bin = appleFmBinaryPath(env);
+    return platform === 'darwin' && arch === 'arm64' && !!bin && existsSync(bin);
+}