@bendyline/gezel 0.1.0

package/dist/native/index.d.ts

@@ -0,0 +1,650 @@
+export { D as DEVICE_HARD_TEMPERATURE_C } from '../device-safety-DezzpNyR.js';
+
+/**
+ * Runtime backend detection for the bundled llama-server.
+ *
+ * Phase 2 ships multiple llama-server variants by platform and
+ * architecture — CUDA, Vulkan, CPU, or Metal — and this module picks
+ * which one to launch on a given host. The probe is pure filesystem /
+ * linker inspection; it does NOT spawn a GPU workload. Binary
+ * availability fallback is handled by `resolveAvailableLlamaBinary`;
+ * failures after a selected binary starts are surfaced by the native
+ * engine supervisor.
+ *
+ * Usage from the Electron supervisor:
+ *
+ *   import { detectLlamaBackend } from './llama-backend.js';
+ *   import { resolveNativeBinaryPath } from './native-bin.js';
+ *
+ *   const probe = detectLlamaBackend({
+ *     engineVersion: 'b9843',
+ *     home: gezelHome,
+ *   });
+ *   const bin = resolveNativeBinaryPath('llama-server', import.meta.url, probe.backend);
+ *
+ * Caching: the result is memoized at
+ * `<home>/engines/llama-cpp/backend.json` so subsequent launches
+ * skip the probe. Cache invalidates whenever `engineVersion`
+ * changes — bumping the llama.cpp pin may prefer a different
+ * backend.
+ */
+type LlamaBackend = 'cuda' | 'vulkan' | 'metal' | 'cpu';
+/**
+ * Which GPU vendor the host *primarily* has, independent of which
+ * llama-server backend was picked. Used to label the running engine
+ * in the UI: a Radeon user on the Vulkan backend should see "AMD GPU"
+ * not just "GPU." `cuda` already implies NVIDIA, so the vendor field
+ * is most useful for disambiguating Vulkan and CPU fallbacks.
+ *
+ * Detection is best-effort and pure filesystem inspection — no shell-out
+ * to wmic / lspci. `undefined` means we couldn't tell; the UI should
+ * fall back to a generic label.
+ */
+type GpuVendorHint = 'amd' | 'nvidia' | 'intel';
+interface DetectInput {
+    /** Engine pin from native/engines/llama-cpp/VERSION (e.g. 'b9843'). Bumps invalidate the cache. */
+    engineVersion: string;
+    /** GEZEL_HOME — backend cache lives at `<home>/engines/llama-cpp/backend.json`. */
+    home: string;
+    /**
+     * User-pinned backend (from `config.llamaCppBackendOverride`). When
+     * set to a concrete backend (`cuda` / `vulkan` / `metal` / `cpu`),
+     * the auto-probe is skipped and the chosen backend is returned
+     * verbatim — even if the OS doesn't have the corresponding driver.
+     * `resolveNativeBinaryPath` will then fail to find the binary and
+     * the supervisor surfaces an actionable error (which is the right
+     * behavior — the user picked an unavailable backend, we tell them).
+     *
+     * `'auto'` or `undefined` keeps the existing CUDA → Vulkan → CPU
+     * (or Metal on Mac) probe behavior.
+     *
+     * Cache bypass: when an override is in effect we don't read OR write
+     * the cache file. The override is the source of truth; we don't want
+     * a future `'auto'` to come back and re-use what was actually a
+     * forced choice.
+     */
+    override?: 'auto' | 'cuda' | 'vulkan' | 'metal' | 'cpu';
+    /** Optional injection points for tests. */
+    probe?: {
+        fileExists?: (path: string) => boolean;
+        commandOk?: (cmd: string) => boolean;
+        /**
+         * Read a small text file (no size limit checks — the caller only
+         * uses this on tiny sysfs files like
+         * `/sys/class/drm/card0/device/vendor`). Returns `undefined` for
+         * any failure mode (missing, EACCES, etc.) — the caller treats
+         * that the same as "vendor unknown."
+         */
+        readFileText?: (path: string) => string | undefined;
+        /**
+         * List a directory's entries. Used to enumerate `/sys/class/drm/`
+         * for `card*` devices. Returns `[]` for any failure mode
+         * (directory missing on non-Linux containers, permission denied).
+         */
+        readDir?: (path: string) => string[];
+        platform?: NodeJS.Platform;
+        arch?: NodeJS.Architecture;
+    };
+}
+interface DetectResult {
+    /**
+     * What the supervisor should use for this launch. When the user pinned
+     * `config.llamaCppBackendOverride`, this is the override; otherwise it's
+     * the hardware-probe result (same as `detectedBackend`).
+     */
+    backend: LlamaBackend;
+    /**
+     * What the hardware probe found, independent of any override. The
+     * Settings UI uses this to populate the dropdown so a `cpu` pin on a
+     * CUDA machine still shows CUDA / Vulkan as switchable options.
+     *
+     * Equal to `backend` when no override is in effect.
+     */
+    detectedBackend: LlamaBackend;
+    cached: boolean;
+    /** Human-readable explanation of why this backend was chosen. */
+    reason: string;
+    /** ISO 8601 timestamp of when the underlying probe ran (cache hits show the cached value). */
+    probedAt: string;
+    /**
+     * Best-effort guess of the host's primary GPU vendor. Independent of
+     * the backend pick — a Radeon user on the Vulkan backend reports
+     * `vendorHint='amd'` so the UI can label the engine "AMD GPU"
+     * instead of the generic "GPU." `undefined` when no GPU could be
+     * identified (e.g. headless container, macOS where the field is
+     * meaningless because Apple Silicon is unified memory).
+     */
+    vendorHint?: GpuVendorHint;
+}
+interface ResolvedLlamaBinary {
+    /** Backend the selected binary was built for. */
+    backend: LlamaBackend;
+    /** Absolute path returned by the caller's binary resolver. */
+    path: string;
+    /**
+     * Present when automatic backend selection had to use the CPU build
+     * because the detected GPU variant was not bundled for this platform.
+     */
+    fallbackFrom?: LlamaBackend;
+    /**
+     * Backends passed over because `isUsable` rejected them — a build that
+     * is present but known to crash on this machine. Distinct from
+     * `fallbackFrom`, which covers a variant that simply isn't bundled:
+     * this one shipped, exists on disk, and does not run here. Callers
+     * surface it so the demotion is visible instead of silent.
+     */
+    skippedUnusable?: LlamaBackend[];
+}
+/**
+ * Resolve the preferred llama-server build, with optional lower-tier
+ * fallbacks.
+ *
+ * Detection and packaging support are deliberately separate: a machine can
+ * expose a Vulkan loader even when the release does not ship a Vulkan build
+ * for its architecture (for example Linux ARM64 under Parallels). In auto
+ * mode, that should still produce a working on-device engine by selecting the
+ * next bundled build in CUDA → Vulkan → CPU order. Explicit user overrides
+ * pass `allowFallbacks=false`
+ * so a missing pinned backend remains an actionable configuration error.
+ *
+ * Returning the backend together with the path prevents callers from launching
+ * a CPU binary while incorrectly advertising it as Vulkan or CUDA.
+ */
+declare function resolveAvailableLlamaBinary(preferredBackend: LlamaBackend, resolveBinary: (backend: LlamaBackend) => string | null, allowFallbacks: boolean, 
+/**
+ * Optional veto on a binary that exists. Returning false continues down
+ * the fallback chain as if the build were absent — the quarantine hook
+ * (see `llama-quarantine.ts`) uses this to route around a variant that
+ * crashed before it was ever ready.
+ *
+ * Only consulted while fallbacks are allowed. With an explicit user
+ * pin there is nowhere to demote TO, and silently refusing the pinned
+ * backend would replace one confusing failure with a stranger one.
+ */
+isUsable?: (backend: LlamaBackend, path: string) => boolean): ResolvedLlamaBinary | null;
+declare function detectLlamaBackend(input: DetectInput): DetectResult;
+
+/**
+ * Per-machine record of llama-server builds that cannot run here.
+ *
+ * `resolveAvailableLlamaBinary` picks a backend by asking whether the
+ * binary EXISTS, never whether it RUNS. When the preferred variant is
+ * present but dies the instant it is spawned, nothing in the chain
+ * notices: the engine supervisor just relaunches the same binary on the
+ * next request, forever, while a working lower-tier build sits unused in
+ * the same directory.
+ *
+ * That is not hypothetical. A CUDA build shipped in native-v0.1.29 died
+ * with SIGILL before binding its port on a Haswell CPU, and the user's
+ * only route out was to hand-pin Vulkan in Settings — after the crash had
+ * been misdiagnosed several times, because the error surfaced as a bare
+ * signal name with no attribution.
+ *
+ * So: when a variant crashes before it is ever ready, write it down here,
+ * and let backend resolution route around it on the next launch.
+ *
+ * ## Why the fingerprint, and not a version string
+ *
+ * An entry pins the exact bytes that crashed — `<size>:<mtimeMs>` of the
+ * binary — rather than an engine or release version. A quarantine has to
+ * expire the moment the offending build is replaced, and a version key
+ * cannot promise that: the fix for the SIGILL above was a compiler-flag
+ * change at an UNCHANGED llama.cpp pin. Keying on `LLAMA_ENGINE_VERSION`
+ * would have left every affected machine demoted to Vulkan permanently,
+ * with the repaired CUDA build sitting right there. Fingerprinting the
+ * file means an upgrade re-enables the backend on its own, and a machine
+ * that is genuinely too old re-quarantines after one cheap crash.
+ *
+ * Deliberately NOT consulted when the user has pinned a backend
+ * explicitly: an override is a decision, and silently overriding the
+ * override would be worse than the failure it avoids. The pin stands, the
+ * crash still reports.
+ */
+
+interface LlamaQuarantineEntry {
+    backend: LlamaBackend;
+    /** `<size>:<mtimeMs>` of the binary that crashed — see the module docstring. */
+    fingerprint: string;
+    /** Signal that killed it (`SIGILL`), or `exit:<code>` when it exited normally. */
+    signal: string;
+    /** Human-readable explanation, surfaced in the backend-resolution reason. */
+    reason: string;
+    /** ISO 8601 timestamp of the crash that created this entry. */
+    at: string;
+}
+/** Injection seam — tests supply fakes, production uses `node:fs`. */
+interface QuarantineIo {
+    readFile?: (path: string) => string;
+    writeFile?: (path: string, data: string) => void;
+    statFile?: (path: string) => {
+        size: number;
+        mtimeMs: number;
+    };
+    mkdir?: (path: string) => void;
+    now?: () => Date;
+}
+declare function llamaQuarantinePath(home: string): string;
+/**
+ * Identity of the bytes at `path`, or null when it cannot be stat'd.
+ *
+ * Size alone is nearly sufficient — a rebuilt engine is essentially never
+ * byte-identical in length — but mtime costs nothing extra from the same
+ * stat call and closes the gap.
+ */
+declare function binaryFingerprint(path: string, io?: QuarantineIo): string | null;
+declare function readLlamaQuarantine(home: string, io?: QuarantineIo): LlamaQuarantineEntry[];
+/**
+ * True when `backend`'s binary at `binaryPath` is the same file that
+ * crashed before. A fingerprint mismatch means the build was replaced, so
+ * the entry no longer applies and the backend gets another chance.
+ */
+declare function isBinaryQuarantined(entries: readonly LlamaQuarantineEntry[], backend: LlamaBackend, binaryPath: string, io?: QuarantineIo): boolean;
+/**
+ * Record that `backend`'s binary crashed. Replaces any existing entry for
+ * the same backend and drops entries whose binary no longer matches, so
+ * the file stays small and self-pruning.
+ *
+ * Returns the entry written, or null when the binary could not be
+ * fingerprinted (it vanished mid-crash) — there is nothing meaningful to
+ * pin the quarantine to in that case, and a stale-forever entry is worse
+ * than none.
+ */
+declare function recordLlamaQuarantine(home: string, input: {
+    backend: LlamaBackend;
+    binaryPath: string;
+    signal: string;
+    reason: string;
+}, io?: QuarantineIo): LlamaQuarantineEntry | null;
+
+/**
+ * Service-side native-binary discovery.
+ *
+ * The Electron supervisor runs its own discovery in
+ * `packages/app/src/supervisor/index.ts#connectOrStart` before spawning
+ * the service, so embedded / dev / packaged-spawn launches already
+ * have `GEZEL_LLAMA_SERVER_BIN`, `GEZEL_SD_SERVER_BIN`,
+ * `GEZEL_WHISPER_SERVER_BIN`, `GEZEL_UV_BIN`, and
+ * `GEZEL_DEVICE_HEALTH_BIN` in their env. The OS
+ * system services (Windows NSSM `GezelService`, macOS LaunchDaemon
+ * `com.bendyline.gezeld`, Linux `gezeld.service` systemd unit) do NOT
+ * — they're started directly by the OS with a clean environment, so
+ * the supervisor's env-stamping never reaches them. Without this
+ * module, chat against the on-device provider fails with
+ * "no local engine is available on this machine" on every packaged
+ * install.
+ *
+ * Discovery rules per binary:
+ *
+ *   - `GEZEL_*_BIN` already set → no-op (supervisor or operator wins).
+ *   - `GEZEL_NATIVE_BIN_DIR` unset → no-op (no source of binaries to
+ *     probe). System-service installers stamp this var; bare CLI runs
+ *     without it just get the existing actionable error on first chat.
+ *   - llama-server: needs a backend probe (CUDA / Vulkan / Metal / CPU).
+ *     Results are cached at `<home>/engines/llama-cpp/backend.json` —
+ *     same file the supervisor writes, so the two share state.
+ *   - sd-server / whisper-server / uv: variant-less, resolved directly
+ *     under `<dir>/<platform>/<binary>`.
+ *
+ * Cross-platform note: same code on Windows, macOS, and Linux. The
+ * `resolvePlatformKey` helper handles the per-OS subdirectory naming
+ * (`win32-x64`, `darwin-arm64`, `linux-x64`, `linux-arm64`).
+ */
+
+type NativeBinaryName = 'llama-server' | 'ds4-server' | 'sd-server' | 'whisper-server' | 'device-health' | 'uv';
+interface DiscoverInput {
+    /** GEZEL_HOME — backend cache file lives at `<home>/engines/llama-cpp/`. */
+    home: string;
+    /**
+     * Optional user-pinned backend override (from `GezelConfig.
+     * llamaCppBackendOverride`). Forwarded to the probe unchanged. The
+     * supervisor reads this from config.json directly; the service has
+     * already loaded config by the time discovery runs, so the caller
+     * can pass the resolved value in.
+     */
+    llamaCppBackendOverride?: 'auto' | LlamaBackend;
+    /**
+     * Override the native-bin root (test-only). Production callers leave
+     * this unset and let the function read `GEZEL_NATIVE_BIN_DIR`.
+     */
+    nativeBinDirOverride?: string;
+    /** Test seam — production callers default to `process.platform` / `process.arch`. */
+    platform?: NodeJS.Platform;
+    arch?: string;
+    /** Test seam for existence checks; defaults to `node:fs.existsSync`. */
+    fileExists?: (p: string) => boolean;
+    /**
+     * Test seam — forwarded to `detectLlamaBackend` so tests can fake
+     * driver presence (`libcuda.so.1`, `nvcuda.dll`, vendor sysfs).
+     * Production callers leave this unset and the probe uses real fs.
+     */
+    llamaProbeOverride?: DetectInput['probe'];
+    /**
+     * Test seam — pre-read quarantine entries. Production callers leave
+     * this unset and the list is read from `<home>/engines/llama-cpp/`.
+     */
+    quarantine?: readonly LlamaQuarantineEntry[];
+    /** Optional logger; the service passes its own to thread service-style logs. */
+    logger?: {
+        info?: (m: string) => void;
+        warn?: (m: string) => void;
+    };
+}
+interface DiscoverResult {
+    /** One entry per binary the discovery attempted. */
+    binaries: Array<{
+        name: NativeBinaryName;
+        /** `'pre-set'` — env var was already populated, discovery skipped. */
+        source: 'pre-set' | 'discovered' | 'no-native-bin-dir' | 'no-platform-key' | 'not-found';
+        /** Resolved path when `source` is `'pre-set'` or `'discovered'`. */
+        path?: string;
+        /**
+         * For llama-server, the picked backend (so logs can record
+         * "discovered cuda variant"). Undefined for variant-less binaries.
+         */
+        variant?: LlamaBackend;
+    }>;
+    /** Backend probe result, present when llama-server discovery ran. */
+    llamaBackend?: {
+        backend: LlamaBackend;
+        detectedBackend: LlamaBackend;
+        reason: string;
+        cached: boolean;
+        vendorHint?: GpuVendorHint;
+        /**
+         * Backends skipped because they crashed on this machine. Present so
+         * the UI can say the GPU engine was demoted rather than leaving the
+         * user to infer it from a slow session.
+         */
+        quarantined?: LlamaBackend[];
+    };
+}
+/**
+ * Resolve a single bundled binary under `<root>/<subdir>/<file>`. The
+ * `subdir` is `<platform>[-<variant>]`; the file is `<name>[.exe]`.
+ *
+ * Returns `null` when the file isn't on disk. Caller decides whether
+ * to fall through to a variant-less subdir or surface "not found."
+ */
+declare function resolveNativeBinaryUnder(root: string, name: NativeBinaryName, subdir: string, platform?: NodeJS.Platform, fileExists?: (p: string) => boolean): string | null;
+/**
+ * Discover bundled native binaries and stamp the matching env vars on
+ * `process.env`. Idempotent: a second call after the env is set is a
+ * no-op. Tolerant of partial bundling — a missing binary just leaves
+ * its env var unset; the dependent provider then surfaces its own
+ * actionable error on first use.
+ */
+declare function discoverNativeBinaries(input: DiscoverInput): DiscoverResult;
+
+/**
+ * Windows console-allocation policy for spawned native children.
+ *
+ * Console-subsystem executables (llama-server, ds4-server, bundled Node) get
+ * a console allocated by the loader unless the creator says otherwise. Under
+ * the machine-wide service there is nothing to allocate one from: the daemon
+ * runs in non-interactive Session 0, where — as
+ * `native/helpers/service-host/src/main.cpp` records — `AllocConsole` fails
+ * with error 317. `DETACHED_PROCESS`, which Node exposes as `detached: true`,
+ * asks for no console at all.
+ *
+ * `windowsHide` is NOT that flag. It maps to `CREATE_NO_WINDOW`, which still
+ * allocates a console and only withholds the window.
+ *
+ * `detached` is deliberately scoped to win32. On POSIX the same option means
+ * `setsid()`, which changes process-group and signal semantics that callers
+ * may depend on; there is no console problem to solve there.
+ *
+ * ## What this does not fix
+ *
+ * This helper was introduced in v1.26215.31 believing it fixed the
+ * `spawn EPERM` that killed every native-engine launch under the machine
+ * service. It did not. That release shipped the flag and the failure
+ * continued, on two machines, with the daemon's own log showing the engine,
+ * the bundled device-health helper, `nvidia-smi`, `amd-smi` and `rocm-smi`
+ * all denied at once. The cause was the service token: `sc sidtype ...
+ * restricted` write-restricts it, and libuv creates a named pipe per piped
+ * stdio handle before every `CreateProcess`, which that token cannot do. The
+ * installer now assigns `unrestricted` (see
+ * `packages/app/installer/nsis-hooks.nsh`), and `probeChildProcessSpawn` in
+ * the service catches a recurrence at boot.
+ *
+ * The flag is still correct and still used — a console the service cannot
+ * allocate is one Windows should not be asked for — but it is a tidiness
+ * measure, not a fix for a permission error. If `spawn EPERM` appears again,
+ * do not reach for spawn flags: look at the token.
+ */
+declare function windowsDetachedSpawnOptions(platform?: NodeJS.Platform): {
+    detached: true;
+} | Record<string, never>;
+
+/**
+ * Cache-bust key for the llama-cpp backend probe.
+ *
+ * Bumped alongside `native/engines/llama-cpp/VERSION`. Both the Electron
+ * supervisor (pre-spawn discovery) and the service (system-service-side
+ * discovery) write/read the same cache file at
+ * `<home>/engines/llama-cpp/backend.json`. A mismatch between the two
+ * would cause cache thrash; keep them in one constant.
+ */
+declare const LLAMA_ENGINE_VERSION = "b10353";
+
+/**
+ * Map a (platform, arch) pair to the subdirectory name used under
+ * the bundled `native-bin/` tree (e.g. `win32-x64`, `darwin-arm64`,
+ * `linux-arm64`). Returns `null` on platforms we don't ship engine
+ * binaries for; callers should treat that as "no bundled engine
+ * available" and avoid further probing.
+ *
+ * Mirrors `packages/app/src/supervisor/native-bin.ts` — kept in sync
+ * because both the supervisor (pre-spawn) and the service (system
+ * service launches) resolve the same per-platform subtree.
+ */
+declare function resolvePlatformKey(platform?: NodeJS.Platform, arch?: string): string | null;
+
+/**
+ * Device-agnostic accelerator admission and health probing.
+ *
+ * Policy is deliberately independent of CUDA/Vulkan/ROCm/Metal. Optional
+ * command adapters translate vendor telemetry into one small reading shape;
+ * the gate then applies the same temperature, thermal-margin, throttle, and
+ * telemetry-failure rules everywhere. Unsupported devices remain usable by
+ * default (`onTelemetryFailure: allow`) while unattended safety-sensitive
+ * runs can fail closed.
+ */
+
+type DeviceSafetyMode = 'off' | 'observe' | 'guard';
+type DeviceTelemetryFailurePolicy = 'allow' | 'block';
+type DeviceVendor = 'nvidia' | 'amd' | 'apple' | 'generic';
+interface DeviceSafetyPolicyInput {
+    mode?: DeviceSafetyMode;
+    maxStartTemperatureC?: number;
+    resumeTemperatureC?: number;
+    minThermalMarginC?: number;
+    pollIntervalMs?: number;
+    maxWaitMs?: number;
+    consecutiveHealthySamples?: number;
+    onTelemetryFailure?: DeviceTelemetryFailurePolicy;
+}
+interface ResolvedDeviceSafetyPolicy {
+    mode: DeviceSafetyMode;
+    maxStartTemperatureC: number;
+    resumeTemperatureC: number;
+    minThermalMarginC: number;
+    pollIntervalMs: number;
+    maxWaitMs: number;
+    consecutiveHealthySamples: number;
+    onTelemetryFailure: DeviceTelemetryFailurePolicy;
+}
+declare const DEFAULT_DEVICE_SAFETY_POLICY: ResolvedDeviceSafetyPolicy;
+interface DeviceHealthReading {
+    vendor: DeviceVendor;
+    deviceId: string;
+    name?: string;
+    temperatureC?: number;
+    /** Degrees remaining before the device's thermal limit, when exposed. */
+    thermalMarginC?: number;
+    utilizationPercent?: number;
+    memoryUsedMb?: number;
+    memoryTotalMb?: number;
+    thermalSlowdown?: boolean;
+    powerBrake?: boolean;
+}
+type DeviceGpuProcessOwner = 'machine-engine' | 'app-engine' | 'development-engine' | 'gezel-engine' | 'external';
+interface DeviceGpuProcess {
+    pid: number;
+    name?: string;
+    dedicatedBytes: number;
+    owner: DeviceGpuProcessOwner;
+}
+interface DeviceHealthSample {
+    sampledAt: string;
+    sources: string[];
+    readings: DeviceHealthReading[];
+    /** Dedicated GPU-memory owners when the platform exposes process counters. */
+    processes?: DeviceGpuProcess[];
+    errors: string[];
+}
+interface DeviceHealthDecision {
+    admissible: boolean;
+    /** True when a reading crossed the non-optional emergency temperature cutoff. */
+    hardBlocked: boolean;
+    telemetryAvailable: boolean;
+    reasons: string[];
+    summary: string;
+}
+type DeviceHealthState = 'off' | 'healthy' | 'warm' | 'cooling' | 'blocked' | 'unavailable';
+/** Authenticated service/UI snapshot; contains no device identifiers beyond display names. */
+interface DeviceHealthStatusSnapshot {
+    state: DeviceHealthState;
+    mode: DeviceSafetyMode;
+    sampledAt: string | null;
+    sources: string[];
+    readings: DeviceHealthReading[];
+    processes?: DeviceGpuProcess[];
+    reasons: string[];
+    summary: string;
+}
+interface DeviceHealthProbe {
+    sample(): Promise<DeviceHealthSample>;
+}
+interface CommandResult {
+    stdout: string;
+    stderr: string;
+}
+type DeviceHealthCommandRunner = (command: string, args: string[], timeoutMs: number) => Promise<CommandResult>;
+interface SystemDeviceHealthProbeOptions {
+    preferredVendor?: 'nvidia' | 'amd';
+    commandRunner?: DeviceHealthCommandRunner;
+    timeoutMs?: number;
+    /**
+     * Bundled native helper. `undefined` reads GEZEL_DEVICE_HEALTH_BIN;
+     * `null` disables the helper (primarily useful in tests/operators).
+     */
+    helperPath?: string | null;
+}
+interface DeviceHealthGateOptions {
+    probe: DeviceHealthProbe;
+    policy?: DeviceSafetyPolicyInput;
+    log?: (message: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+declare function resolveDeviceSafetyPolicy(input: DeviceSafetyPolicyInput | undefined, env?: NodeJS.ProcessEnv): ResolvedDeviceSafetyPolicy;
+/** Parse the stable CSV query emitted by NVIDIA SMI. Exported for tests. */
+declare function parseNvidiaSmiCsv(stdout: string): DeviceHealthReading[];
+/**
+ * Parse AMD SMI or ROCm SMI JSON without pinning to one release's field
+ * spelling. Both CLIs have changed nesting and labels over time, while their
+ * semantic keys consistently contain temperature/use/memory/throttle terms.
+ */
+declare function parseAmdSmiJson(stdout: string, source?: string): DeviceHealthReading[];
+/**
+ * Create a best-effort multi-vendor probe. The bundled helper gets first
+ * chance, then optional host SMI CLIs preserve compatibility with custom and
+ * older installations.
+ */
+declare function createSystemDeviceHealthProbe(opts?: SystemDeviceHealthProbeOptions): DeviceHealthProbe;
+declare function evaluateDeviceHealth(sample: DeviceHealthSample, policy: ResolvedDeviceSafetyPolicy, cooling?: boolean): DeviceHealthDecision;
+/**
+ * Stateful admission gate with cooling hysteresis. A device that crosses a
+ * start threshold must satisfy the lower resume threshold for consecutive
+ * samples before work restarts, preventing hot start/stop oscillation.
+ */
+declare class DeviceHealthGate {
+    private policy;
+    private readonly probe;
+    private readonly log;
+    private readonly sleep;
+    private readonly now;
+    private cooling;
+    private pendingAdmission?;
+    private pendingSample?;
+    private lastSample?;
+    private lastSampleAt;
+    private admissionBlocked;
+    private lastUnavailableDiagnostic;
+    constructor(opts: DeviceHealthGateOptions);
+    setPolicy(policy: DeviceSafetyPolicyInput): void;
+    getPolicy(): ResolvedDeviceSafetyPolicy;
+    /**
+     * Return a cached-or-fresh normalized snapshot for status surfaces. The
+     * cache keeps a UI polling every few seconds from spawning overlapping SMI
+     * processes, while admission can still force a fresh sample after it ages.
+     */
+    status(maxAgeMs?: number): Promise<DeviceHealthStatusSnapshot>;
+    admit(context: string): Promise<DeviceHealthDecision>;
+    private runAdmission;
+    private sampleDevice;
+}
+
+/**
+ * macOS GPU kernel-panic detection.
+ *
+ * Heavy Metal workloads on Apple Silicon can trip a latent Apple GPU *driver*
+ * bug: a kernel panic in `IOGPUMemory.cpp` ("completeMemory() prepare count
+ * underflow", driver family `AGXAcceleratorG16X`). Wild-caught on
+ * an M4 Max running local MLX models — an identical panic hit two days
+ * running. It is NOT out-of-memory and NOT gezel/MLX code: a userspace
+ * process can't panic the kernel; only a driver bug can. Our GPU
+ * allocate/free churn (loading/unloading models, KV cache) merely *triggers*
+ * it.
+ *
+ * No thermal/memory telemetry threshold catches a driver refcount underflow,
+ * so the one thing gezel can do is DETECT that a panic happened (macOS writes
+ * a `.panic` report on the next boot) and stop re-triggering the loop —
+ * refuse to auto-spawn a fresh local GPU engine right after a panic until the
+ * operator acknowledges. This module is the pure detector; consumers (the
+ * service's engine-spawn guard, the eval harness) decide policy.
+ *
+ * Node built-ins only, so it lives in core native alongside device-health.
+ * No-op off macOS.
+ */
+/**
+ * Panic strings that implicate the GPU / Metal kernel driver — the class
+ * Metal churn triggers. Broad across Apple GPU driver families (AGX = Apple
+ * GPU) and the IOAccelerator/IOGPU memory paths so a slightly different
+ * underflow site or a newer SoC's accelerator name still matches.
+ */
+declare const GPU_PANIC_RE: RegExp;
+interface GpuPanicRecord {
+    /** Absolute path to the `.panic`/`.ips` report. */
+    file: string;
+    /** Report file mtime — when macOS wrote it (≈ the reboot after the panic). */
+    when: Date;
+    /** The matched driver signature, for the operator message. */
+    signature: string;
+}
+interface FindGpuPanicOptions {
+    /** Only report panics newer than this many ms ago. Default 24h. */
+    withinMs?: number;
+    /** Injected for tests: current time. Defaults to `Date.now()`. */
+    now?: number;
+    /** Injected for tests: directories to scan. Defaults to the macOS report dirs. */
+    dirs?: string[];
+}
+/**
+ * Return GPU-driver kernel panics recorded within the window, newest first.
+ * Empty on non-macOS (no report dirs) or when nothing matches.
+ */
+declare function findRecentGpuPanics(opts?: FindGpuPanicOptions): GpuPanicRecord[];
+
+export { type CommandResult, DEFAULT_DEVICE_SAFETY_POLICY, type DetectInput, type DetectResult, type DeviceHealthCommandRunner, type DeviceHealthDecision, DeviceHealthGate, type DeviceHealthGateOptions, type DeviceHealthProbe, type DeviceHealthReading, type DeviceHealthSample, type DeviceHealthState, type DeviceHealthStatusSnapshot, type DeviceSafetyMode, type DeviceSafetyPolicyInput, type DeviceTelemetryFailurePolicy, type DeviceVendor, type DiscoverInput, type DiscoverResult, type FindGpuPanicOptions, GPU_PANIC_RE, type GpuPanicRecord, type GpuVendorHint, LLAMA_ENGINE_VERSION, type LlamaBackend, type LlamaQuarantineEntry, type NativeBinaryName, type QuarantineIo, type ResolvedDeviceSafetyPolicy, type ResolvedLlamaBinary, type SystemDeviceHealthProbeOptions, binaryFingerprint, createSystemDeviceHealthProbe, detectLlamaBackend, discoverNativeBinaries, evaluateDeviceHealth, findRecentGpuPanics, isBinaryQuarantined, llamaQuarantinePath, parseAmdSmiJson, parseNvidiaSmiCsv, readLlamaQuarantine, recordLlamaQuarantine, resolveAvailableLlamaBinary, resolveDeviceSafetyPolicy, resolveNativeBinaryUnder, resolvePlatformKey, windowsDetachedSpawnOptions };