@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/secrets/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SecretStore — the one place secrets (API tokens, webhook keys, OAuth
+ * access tokens) live at rest. Three implementations ship:
+ *
+ *   - KeyringSecretStore: native OS keychain (macOS Keychain / Windows
+ *     Credential Manager / Linux Secret Service). Preferred.
+ *   - FileSecretStore:    AES-256-GCM encrypted file with a 0600 key.
+ *     Fallback when the OS keyring is unavailable (headless CI, locked
+ *     session, missing libsecret on bare Linux, etc).
+ *   - MemorySecretStore:  process memory only, nothing at rest. (The
+ *     inference-only profile opens no secret store at all.)
+ *
+ * Toolset secrets are keyed globally by `(toolsetId, fieldId)` — there's
+ * one config per toolset regardless of which scope uses it. Per-scope
+ * overrides can add a `scope` axis to SecretKey later without breaking
+ * existing callers.
+ */
+export type SecretKey = {
+    kind: 'toolset';
+    toolsetId: string;
+    fieldId: string;
+} | {
+    kind: 'providerCredential';
+    name: ProviderCredentialName;
+} | {
+    kind: 'deviceIdentity';
+    scope?: string;
+};
+export type ProviderCredentialName = 'githubToken' | 'openaiApiKey' | 'openaiOrganization' | 'anthropicApiKey' | 'googleAiApiKey' | 'webhookBearerToken' | 'webhookBasicAuth' | 'braveSearchApiKey' | 'tavilyApiKey';
+export interface SecretStore {
+    get(key: SecretKey): Promise<string | null>;
+    set(key: SecretKey, value: string): Promise<void>;
+    delete(key: SecretKey): Promise<void>;
+    has(key: SecretKey): Promise<boolean>;
+    /** Field ids with a stored value for the given toolset. */
+    listForToolset(toolsetId: string): Promise<string[]>;
+    /** Short label identifying which backend is in use (for logs + UI banner). */
+    readonly backend: SecretStoreBackend;
+}
+export type SecretStoreBackend = 'keyring' | 'file' | 'memory';
+/** A backend outage must never be mistaken for an absent credential. */
+export declare class SecretBackendUnavailableError extends Error {
+    readonly backend: SecretStoreBackend;
+    constructor(backend: SecretStoreBackend, message: string, options?: ErrorOptions);
+}
+export declare class SecretStoreCorruptError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Canonical string form of a SecretKey, used as an account name in the
+ * keyring backend and as a map key in the file backend. Callers should
+ * treat this as opaque. */
+export declare function stringifySecretKey(key: SecretKey): string;
+/** Account name of the legacy un-namespaced device identity entry. Only
+ *  the migration path in remotes/identity.ts may address it. */
+export declare const LEGACY_DEVICE_IDENTITY_ACCOUNT = "deviceIdentity";
+/**
+ * Stable, opaque namespace for one GEZEL_HOME's private identity. The same
+ * path resolves to the same account after a home is deleted and recreated,
+ * while two intentional homes under one OS login do not share a key.
+ */
+export declare function deviceIdentityScope(home: string): string;
+/** Prefix used by listForToolset to match a toolset's entries. */
+export declare function toolsetKeyPrefix(toolsetId: string): string;

package/dist/secrets/types.js

@@ -0,0 +1,64 @@
+/**
+ * SecretStore — the one place secrets (API tokens, webhook keys, OAuth
+ * access tokens) live at rest. Three implementations ship:
+ *
+ *   - KeyringSecretStore: native OS keychain (macOS Keychain / Windows
+ *     Credential Manager / Linux Secret Service). Preferred.
+ *   - FileSecretStore:    AES-256-GCM encrypted file with a 0600 key.
+ *     Fallback when the OS keyring is unavailable (headless CI, locked
+ *     session, missing libsecret on bare Linux, etc).
+ *   - MemorySecretStore:  process memory only, nothing at rest. (The
+ *     inference-only profile opens no secret store at all.)
+ *
+ * Toolset secrets are keyed globally by `(toolsetId, fieldId)` — there's
+ * one config per toolset regardless of which scope uses it. Per-scope
+ * overrides can add a `scope` axis to SecretKey later without breaking
+ * existing callers.
+ */
+import { createHash } from 'node:crypto';
+import { resolve as resolvePath } from 'node:path';
+/** A backend outage must never be mistaken for an absent credential. */
+export class SecretBackendUnavailableError extends Error {
+    backend;
+    constructor(backend, message, options) {
+        super(message, options);
+        this.backend = backend;
+        this.name = 'SecretBackendUnavailableError';
+    }
+}
+export class SecretStoreCorruptError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SecretStoreCorruptError';
+    }
+}
+/** Canonical string form of a SecretKey, used as an account name in the
+ * keyring backend and as a map key in the file backend. Callers should
+ * treat this as opaque. */
+export function stringifySecretKey(key) {
+    switch (key.kind) {
+        case 'toolset':
+            return `toolset:${key.toolsetId}:${key.fieldId}`;
+        case 'providerCredential':
+            return `providerCredential:${key.name}`;
+        case 'deviceIdentity':
+            return key.scope === undefined
+                ? LEGACY_DEVICE_IDENTITY_ACCOUNT
+                : `deviceIdentity:${key.scope}`;
+    }
+}
+/** Account name of the legacy un-namespaced device identity entry. Only
+ *  the migration path in remotes/identity.ts may address it. */
+export const LEGACY_DEVICE_IDENTITY_ACCOUNT = 'deviceIdentity';
+/**
+ * Stable, opaque namespace for one GEZEL_HOME's private identity. The same
+ * path resolves to the same account after a home is deleted and recreated,
+ * while two intentional homes under one OS login do not share a key.
+ */
+export function deviceIdentityScope(home) {
+    return createHash('sha256').update(resolvePath(home)).digest('hex').slice(0, 16);
+}
+/** Prefix used by listForToolset to match a toolset's entries. */
+export function toolsetKeyPrefix(toolsetId) {
+    return `toolset:${toolsetId}:`;
+}

package/dist/speech.d.ts

@@ -0,0 +1 @@
+export { KokoroFrontend, findKokoroLexiconDir, type KokoroFrontendOptions, type KokoroUtterance, } from './providers/audio/kokoro-frontend.js';

package/dist/speech.js

@@ -0,0 +1 @@
+export { KokoroFrontend, findKokoroLexiconDir, } from './providers/audio/kokoro-frontend.js';

package/dist/system/darwin-memory.d.ts

@@ -0,0 +1,26 @@
+export interface DarwinSystemMemorySnapshot {
+    /** RAM occupied by app, wired, and compressed memory. */
+    usedBytes: number;
+    /** Reclaimable file-backed and purgeable pages (Activity Monitor "Cached Files"). */
+    cachedBytes: number;
+    /** Completely unused physical pages. */
+    freeBytes: number;
+}
+export type DarwinMemoryCommandRunner = (command: string, args: string[]) => Promise<string>;
+/**
+ * Convert `vm_stat`'s Mach page counters into the same top-level buckets
+ * Activity Monitor presents. File-backed and purgeable pages are cached,
+ * reclaimable capacity; treating only `Pages free` as available makes a
+ * healthy Mac appear completely full.
+ */
+export declare function parseDarwinVmStat(stdout: string, totalBytes: number): DarwinSystemMemorySnapshot | null;
+export declare function sampleDarwinSystemMemory(opts: {
+    totalBytes: number;
+    platform?: NodeJS.Platform;
+    run?: DarwinMemoryCommandRunner;
+}): Promise<DarwinSystemMemorySnapshot | null>;
+/** Coalesce the engine popover's one-second polling into a cheap live sample. */
+export declare function sampleDarwinSystemMemoryCached(opts: {
+    totalBytes: number;
+    maxAgeMs?: number;
+}): Promise<DarwinSystemMemorySnapshot | null>;

package/dist/system/darwin-memory.js

@@ -0,0 +1,81 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+let cached = null;
+let pending = null;
+function pageCount(stdout, label) {
+    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = stdout.match(new RegExp(`^${escaped}:\\s*(\\d+)\\.?\\s*$`, 'im'));
+    if (!match)
+        return null;
+    const count = Number.parseInt(match[1], 10);
+    return Number.isFinite(count) && count >= 0 ? count : null;
+}
+/**
+ * Convert `vm_stat`'s Mach page counters into the same top-level buckets
+ * Activity Monitor presents. File-backed and purgeable pages are cached,
+ * reclaimable capacity; treating only `Pages free` as available makes a
+ * healthy Mac appear completely full.
+ */
+export function parseDarwinVmStat(stdout, totalBytes) {
+    const pageSizeMatch = stdout.match(/page size of\s+(\d+)\s+bytes/i);
+    if (!pageSizeMatch || !Number.isFinite(totalBytes) || totalBytes <= 0)
+        return null;
+    const pageSize = Number.parseInt(pageSizeMatch[1], 10);
+    const freePages = pageCount(stdout, 'Pages free');
+    const fileBackedPages = pageCount(stdout, 'File-backed pages');
+    const purgeablePages = pageCount(stdout, 'Pages purgeable');
+    if (!Number.isFinite(pageSize) ||
+        pageSize <= 0 ||
+        freePages === null ||
+        fileBackedPages === null ||
+        purgeablePages === null) {
+        return null;
+    }
+    const freeBytes = clamp(freePages * pageSize, 0, totalBytes);
+    const cachedBytes = clamp((fileBackedPages + purgeablePages) * pageSize, 0, totalBytes - freeBytes);
+    const usedBytes = Math.max(0, totalBytes - freeBytes - cachedBytes);
+    return { usedBytes, cachedBytes, freeBytes };
+}
+export async function sampleDarwinSystemMemory(opts) {
+    if ((opts.platform ?? process.platform) !== 'darwin')
+        return null;
+    const run = opts.run ?? runCommand;
+    try {
+        return parseDarwinVmStat(await run('/usr/bin/vm_stat', []), opts.totalBytes);
+    }
+    catch {
+        return null;
+    }
+}
+/** Coalesce the engine popover's one-second polling into a cheap live sample. */
+export async function sampleDarwinSystemMemoryCached(opts) {
+    if (process.platform !== 'darwin')
+        return null;
+    const now = Date.now();
+    const maxAgeMs = opts.maxAgeMs ?? 3_000;
+    if (cached && now - cached.at <= maxAgeMs)
+        return cached.value;
+    if (pending)
+        return pending;
+    pending = sampleDarwinSystemMemory({ totalBytes: opts.totalBytes })
+        .then((value) => {
+        cached = { at: Date.now(), value };
+        return value;
+    })
+        .finally(() => {
+        pending = null;
+    });
+    return pending;
+}
+async function runCommand(command, args) {
+    const { stdout } = await exec(command, args, {
+        encoding: 'utf8',
+        timeout: 3_000,
+        maxBuffer: 1024 * 1024,
+    });
+    return String(stdout);
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}

package/dist/system/gezel-process-memory.d.ts

@@ -0,0 +1,55 @@
+export interface ProcessListEntry {
+    pid: number;
+    ppid: number;
+    command: string;
+}
+export interface GezelProcessMemorySnapshot {
+    /** Combined macOS physical footprint for gezeld plus same-home engines. */
+    bytes: number;
+    engineProcessCount: number;
+    orphanedEngineProcessCount: number;
+}
+export type ProcessMemoryCommandRunner = (command: string, args: string[]) => Promise<string>;
+/** Parse `ps -axo pid=,ppid=,command=` without truncating the command tail. */
+export declare function parseProcessList(stdout: string): ProcessListEntry[];
+/**
+ * Identify engine processes launched for this Gezel home. The executable or
+ * script marker proves it is one of our engines; the home path prevents a dev
+ * daemon from claiming an isolated eval or another local installation.
+ */
+export declare function findGezelEngineProcesses(entries: ProcessListEntry[], home: string, platform?: NodeJS.Platform): ProcessListEntry[];
+/** Parse the byte-form summary emitted by `/usr/bin/footprint`. */
+export declare function parseFootprintBytes(stdout: string): number | null;
+/**
+ * Observe the same physical-footprint metric Activity Monitor uses on macOS.
+ * Unlike RSS, this includes Metal-backed unified-memory allocations (the
+ * difference is tens of GiB for MLX and DS4).
+ */
+export declare function sampleDarwinGezelProcessMemory(opts: {
+    home: string;
+    platform?: NodeJS.Platform;
+    servicePid?: number;
+    run?: ProcessMemoryCommandRunner;
+}): Promise<GezelProcessMemorySnapshot | null>;
+/**
+ * Physical footprint for ONE process, or null when it can't be measured.
+ *
+ * The per-engine counterpart of {@link sampleDarwinGezelProcessMemory}, for
+ * "how much is this engine holding". RSS is the wrong answer on macOS and
+ * wrong by a lot: an MLX 27B showed 30 GB resident while its footprint was
+ * ~103 GB, because Metal's unified-memory allocations don't land in RSS.
+ * Callers keep an RSS fallback for hosts where `footprint` is unavailable.
+ */
+export declare function sampleDarwinProcessFootprintBytes(opts: {
+    pid: number;
+    platform?: NodeJS.Platform;
+    run?: ProcessMemoryCommandRunner;
+}): Promise<number | null>;
+/**
+ * The UI polls once a second; process discovery + footprint are cheap but not
+ * free. Coalesce concurrent requests and refresh at a human-live cadence.
+ */
+export declare function sampleDarwinGezelProcessMemoryCached(opts: {
+    home: string;
+    maxAgeMs?: number;
+}): Promise<GezelProcessMemorySnapshot | null>;

package/dist/system/gezel-process-memory.js

@@ -0,0 +1,156 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { isGezelEngineCommand } from '@bendyline/gezel-client/node';
+const exec = promisify(execFile);
+const cachedByHome = new Map();
+const pendingByHome = new Map();
+/** Parse `ps -axo pid=,ppid=,command=` without truncating the command tail. */
+export function parseProcessList(stdout) {
+    const entries = [];
+    for (const rawLine of stdout.split(/\r?\n/)) {
+        const match = rawLine.trimStart().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!match)
+            continue;
+        const pid = Number.parseInt(match[1], 10);
+        const ppid = Number.parseInt(match[2], 10);
+        if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+            continue;
+        entries.push({ pid, ppid, command: match[3] });
+    }
+    return entries;
+}
+/**
+ * Identify engine processes launched for this Gezel home. The executable or
+ * script marker proves it is one of our engines; the home path prevents a dev
+ * daemon from claiming an isolated eval or another local installation.
+ */
+export function findGezelEngineProcesses(entries, home, platform = process.platform) {
+    const separator = platform === 'win32' ? '\\' : '/';
+    const normalizedHome = normalizeProcessCommand(home, platform).replace(/[\\/]+$/, '');
+    const homeAnchor = `${normalizedHome}${separator}`;
+    return entries.filter(({ command }) => {
+        const normalizedCommand = normalizeProcessCommand(command, platform);
+        return normalizedCommand.includes(homeAnchor) && isGezelEngineCommand(command);
+    });
+}
+function normalizeProcessCommand(value, platform) {
+    return platform === 'win32' ? value.replaceAll('/', '\\').toLowerCase() : value;
+}
+/** Parse the byte-form summary emitted by `/usr/bin/footprint`. */
+export function parseFootprintBytes(stdout) {
+    const summary = stdout.match(/Summary Footprint:\s*(\d+)\s+B/i);
+    if (summary) {
+        const bytes = Number.parseInt(summary[1], 10);
+        return Number.isFinite(bytes) && bytes >= 0 ? bytes : null;
+    }
+    // A target can disappear between ps and footprint. Some macOS releases
+    // still emit the surviving targets without a final summary, so retain the
+    // useful measurements instead of dropping the whole sample.
+    let total = 0;
+    let found = false;
+    for (const match of stdout.matchAll(/^\s*phys_footprint:\s*(\d+)\s+B/gim)) {
+        const bytes = Number.parseInt(match[1], 10);
+        if (!Number.isFinite(bytes) || bytes < 0)
+            continue;
+        total += bytes;
+        found = true;
+    }
+    return found ? total : null;
+}
+/**
+ * Observe the same physical-footprint metric Activity Monitor uses on macOS.
+ * Unlike RSS, this includes Metal-backed unified-memory allocations (the
+ * difference is tens of GiB for MLX and DS4).
+ */
+export async function sampleDarwinGezelProcessMemory(opts) {
+    if ((opts.platform ?? process.platform) !== 'darwin')
+        return null;
+    const run = opts.run ?? runCommand;
+    const servicePid = opts.servicePid ?? process.pid;
+    try {
+        const processList = parseProcessList(await run('/bin/ps', ['-axo', 'pid=,ppid=,command=']));
+        const engines = findGezelEngineProcesses(processList, opts.home);
+        const pids = [...new Set([servicePid, ...engines.map(({ pid }) => pid)])];
+        const args = [
+            '--noCategories',
+            '--format',
+            'bytes',
+            ...pids.flatMap((pid) => ['--pid', String(pid)]),
+        ];
+        const bytes = parseFootprintBytes(await run('/usr/bin/footprint', args));
+        if (bytes === null)
+            return null;
+        return {
+            bytes,
+            engineProcessCount: engines.length,
+            orphanedEngineProcessCount: engines.filter(({ ppid }) => ppid === 1).length,
+        };
+    }
+    catch {
+        // Sandboxed/dev hosts may deny process inspection. The caller retains the
+        // portable reservation-based estimate as a fallback.
+        return null;
+    }
+}
+/**
+ * Physical footprint for ONE process, or null when it can't be measured.
+ *
+ * The per-engine counterpart of {@link sampleDarwinGezelProcessMemory}, for
+ * "how much is this engine holding". RSS is the wrong answer on macOS and
+ * wrong by a lot: an MLX 27B showed 30 GB resident while its footprint was
+ * ~103 GB, because Metal's unified-memory allocations don't land in RSS.
+ * Callers keep an RSS fallback for hosts where `footprint` is unavailable.
+ */
+export async function sampleDarwinProcessFootprintBytes(opts) {
+    if ((opts.platform ?? process.platform) !== 'darwin')
+        return null;
+    const run = opts.run ?? runCommand;
+    try {
+        const stdout = await run('/usr/bin/footprint', [
+            '--noCategories',
+            '--format',
+            'bytes',
+            '--pid',
+            String(opts.pid),
+        ]);
+        return parseFootprintBytes(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The UI polls once a second; process discovery + footprint are cheap but not
+ * free. Coalesce concurrent requests and refresh at a human-live cadence.
+ */
+export async function sampleDarwinGezelProcessMemoryCached(opts) {
+    if (process.platform !== 'darwin')
+        return null;
+    const key = `${opts.home}\0${process.pid}`;
+    const now = Date.now();
+    const maxAgeMs = opts.maxAgeMs ?? 3_000;
+    const cached = cachedByHome.get(key);
+    if (cached && now - cached.at <= maxAgeMs)
+        return cached.value;
+    const pending = pendingByHome.get(key);
+    if (pending)
+        return pending;
+    const sample = sampleDarwinGezelProcessMemory({ home: opts.home })
+        .then((value) => {
+        cachedByHome.set(key, { at: Date.now(), value });
+        return value;
+    })
+        .finally(() => {
+        pendingByHome.delete(key);
+    });
+    pendingByHome.set(key, sample);
+    return sample;
+}
+async function runCommand(command, args) {
+    const { stdout } = await exec(command, args, {
+        encoding: 'utf8',
+        timeout: 3_000,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return String(stdout);
+}

package/dist/system/memory.d.ts

@@ -0,0 +1,154 @@
+import type { LocalEngineLifecycle, MachineMemoryUsage, ResidentEngineModel } from '@bendyline/gezel';
+import { type DeviceHealthStatusSnapshot } from '@bendyline/gezel/native';
+import { type LlamaGpuMemoryKind, type GpuVendor as LlamaGpuVendor } from '../providers/llama-cpp/devices.js';
+import type { DarwinSystemMemorySnapshot } from './darwin-memory.js';
+import type { GezelProcessMemorySnapshot } from './gezel-process-memory.js';
+export type MemorySource = 'darwin-unified' | 'gpu-nvidia' | 'gpu-vulkan' | 'gpu-integrated' | 'system-ram-fallback';
+export type GpuVendor = 'amd' | 'nvidia' | 'intel';
+export type GpuMemoryKind = 'discrete' | 'integrated' | 'unified' | 'none' | 'unknown';
+export interface MemoryProfile {
+    platform: 'darwin' | 'win32' | 'linux' | string;
+    /** Total system RAM in bytes. Always populated. */
+    totalRamBytes: number;
+    /**
+     * GPU-addressable memory in bytes, when detected. For `gpu-integrated` this
+     * is a reported shared allocation inside `totalRamBytes`, not extra memory.
+     * Null on macOS and when no GPU tool responds.
+     */
+    gpuVramBytes: number | null;
+    /** Whether the reported GPU pool is separate from or shared with system RAM. */
+    gpuMemoryKind: GpuMemoryKind;
+    /** Where `usableBytes` comes from. Drives the UI's wording. */
+    source: MemorySource;
+    /**
+     * The conservative FAST-memory budget available to local engines: VRAM on
+     * a discrete card, a RAM fraction on unified / CPU-only hosts. A model
+     * within this runs entirely where the compute happens.
+     */
+    usableBytes: number;
+    /**
+     * What the capacity broker will actually admit — the same auto-derived
+     * ceiling {@link autoDetectBudgetBytes} gives it, summed across every pool
+     * a resident engine can use. On a discrete card that is VRAM PLUS a system-
+     * RAM share, because a MoE model streams its experts from RAM.
+     *
+     * Larger than {@link usableBytes} on a discrete card and equal to it on a
+     * Mac. Fit checks gate on this: anything above it is a model the broker
+     * refuses to load, so offering it as a download is a promise we break.
+     */
+    budgetBytes: number;
+    /** GPU vendor when a GPU backs the budget — lets the UI say "AMD GPU". */
+    gpuVendor?: GpuVendor;
+    /**
+     * Memory of the largest single NVIDIA card. `gpuVramBytes` sums every card,
+     * which is right for llama.cpp's layer split and wrong for an engine that
+     * runs on one device (the image and video engines).
+     */
+    gpuLargestDeviceBytes?: number;
+}
+/**
+ * Detect the memory available for local LLM inference. Platform-aware:
+ *
+ *   • macOS: unified memory — GPU and CPU share one pool. Use the same
+ *     capacity budget enforced by the native-engine broker: 60% on
+ *     ordinary machines, 80% on 96 GB+ machines, capped at 96 GiB.
+ *
+ *   • Linux / Windows: probe `nvidia-smi` for VRAM. If present, that's
+ *     the primary budget (dedicated GPU inference). If absent, probe the
+ *     bundled `llama-server --list-devices` for a non-NVIDIA GPU (AMD /
+ *     Intel / any Vulkan device) and use ITS VRAM as the budget. Only when
+ *     neither reports a GPU do we fall back to ~50% of system RAM (CPU
+ *     inference — works, but slower, with headroom left for the OS).
+ */
+export declare function detectMemoryProfile(): Promise<MemoryProfile>;
+/**
+ * Convert a llama.cpp Vulkan device into the service memory profile without
+ * double-counting an integrated adapter's shared allocation. Exported as the
+ * pure policy seam for regression tests and diagnostics tooling.
+ */
+export declare function memoryProfileForLlamaGpu(platform: string, totalRamBytes: number, gpu: {
+    vramBytes: number;
+    name: string;
+    vendor?: LlamaGpuVendor;
+    memoryKind: LlamaGpuMemoryKind;
+}): MemoryProfile;
+/**
+ * Capacity changes only on GPU hot-plug / VM reconfiguration, while the live
+ * strip may poll once a second. Keep the expensive nvidia-smi / llama device
+ * discovery out of that hot path and refresh the profile occasionally.
+ */
+export declare function detectMemoryProfileCached(maxAgeMs?: number): Promise<MemoryProfile>;
+export interface SampleMachineMemoryUsageOptions {
+    profile: MemoryProfile;
+    deviceHealth?: DeviceHealthStatusSnapshot;
+    /** Capacity broker reservation across resident Gezel local-engine replicas. */
+    engineCommittedBytes?: number;
+    /** The broker budget that reservation is measured against; spans pools. */
+    engineBudgetBytes?: number | null;
+    /** Resident replicas behind the reservation, aggregated per model. */
+    residentModels?: ResidentEngineModel[];
+    /** Running replicas and their idle/pressure release deadlines. */
+    engineLifecycles?: LocalEngineLifecycle[];
+    /** Installed parameter payloads for the resident replicas, when known. */
+    engineModelWeightsBytes?: number;
+    /** macOS physical footprint for gezeld + same-home engine processes. */
+    gezelProcessMemory?: GezelProcessMemorySnapshot | null;
+    /** macOS Activity Monitor-style used/cache/free counters. */
+    darwinSystemMemory?: DarwinSystemMemorySnapshot | null;
+    /**
+     * CPU inference deliberately uses main RAM even when a discrete GPU exists.
+     * The UI should describe the pool actually backing the selected backend.
+     */
+    forceMainMemory?: boolean;
+    /** Portable fallback test seams; macOS production uses darwinSystemMemory. */
+    freeRamBytes?: number;
+    serviceRssBytes?: number;
+    sampledAt?: string;
+}
+/**
+ * Combine stable capacity detection, cached accelerator health, and cheap OS
+ * RAM counters into the live memory strip's portable wire shape.
+ *
+ * Driver telemetry reliably gives aggregate GPU use. On Windows, the bundled
+ * helper also reads process memory (the OS GPU Process Memory counter on
+ * Windows, NVML on NVIDIA Linux) and classifies Gezel's supervised engine
+ * processes; on macOS, physical-footprint sampling observes gezeld and
+ * same-home engines, including Metal allocations. Other hosts fall back to
+ * the broker reservation + daemon RSS.
+ *
+ * A discrete card uses process accounting when available and otherwise keeps
+ * the older reservation estimate clearly approximate. The reservation itself
+ * still travels separately as `engineReservedBytes`: it spans VRAM and a
+ * system-RAM share and must never be presented as measured placement.
+ */
+export declare function sampleMachineMemoryUsage(opts: SampleMachineMemoryUsageOptions): MachineMemoryUsage;
+/**
+ * Collapse the engine pool's per-replica entries into one row per model,
+ * heaviest first. Clones of the same model share a row because a reader
+ * looking for "what is holding my memory" wants the model named once with
+ * its whole reservation, not N lines that differ only by replica index.
+ */
+export declare function summarizeResidentModels(entries: ReadonlyArray<{
+    provider: string;
+    modelId: string;
+    residentBytes: number;
+}>): ResidentEngineModel[];
+export interface NvidiaMemoryProbe {
+    vramBytes: number;
+    /** The largest single card: what a one-device engine can use. */
+    largestDeviceBytes: number;
+    memoryKind: 'discrete' | 'unified';
+    deviceNames: string[];
+}
+/**
+ * Parse the stable `name,memory.total` CSV emitted by nvidia-smi.
+ *
+ * A unified-memory device has no framebuffer of its own, and the GB10 / DGX
+ * Spark reports its memory as `[N/A]`. Its pool IS system RAM, so
+ * `systemRamBytes` stands in for it. Rejecting that line used to drop the
+ * Spark through to the Vulkan probe, which calls it discrete: the capacity
+ * budget then counted the same 128 GB twice (RAM share + "VRAM", 211 GiB) and
+ * held back only ~3 GiB for the OS, so a 95 GB chat model and a 10 GB image
+ * model were co-admitted and the image engine died with a CUDA OOM at init.
+ */
+export declare function parseNvidiaMemoryProbe(stdout: string, systemRamBytes?: number): NvidiaMemoryProbe | null;