@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/providers/native/device-capacity.d.ts

@@ -0,0 +1,84 @@
+import { type NativeCapacityCommand, type NativeCapacityReply } from '@bendyline/gezel';
+import type { CapacityBudget } from './capacity-budget.js';
+import { DeviceCapacityLedger, type DeviceCapacitySample } from './device-capacity-ledger.js';
+import type { NativeEngineLaunch } from './supervisor.js';
+export interface BrokerVersionSkew {
+    /** What the installed machine engine reports, or `'unknown'` if it reports none. */
+    brokerVersion: string;
+    localVersion: string;
+    /**
+     * Take the LOCAL ledger instead of deferring. True only for an unstamped
+     * dev build facing a broker that is not the same build.
+     */
+    takeLocalAuthority: boolean;
+}
+/**
+ * Decide who arbitrates this machine's memory when an installed machine engine
+ * is present.
+ *
+ * Hosting mode does not answer this. An embedded dev daemon still shares the
+ * physical RAM of the box with whatever the installed app loads, so deferring
+ * to one machine-wide ledger is right in production and right for two builds
+ * of the same version. What it is NOT right for is a dev loop: on 2026-09-08 a
+ * patched dev build planned an 8.6 GB launch against its own corrected
+ * availability reading, handed the request to an installed 1.26251.69 broker
+ * whose formula saw 5.9 GB, and waited out the full five-minute admission
+ * budget — the fix under test could not run, because the process that decides
+ * was a different, older one. Nothing in either log said so.
+ *
+ * Ordering is deliberately not the test. `isUnstampedDevBuild` is: a checkout
+ * carries code no release has, while `0.0.0` sorts below every stamped version
+ * — so `compareGezelVersions` would conclude the exact opposite of the truth.
+ */
+export declare function assessBrokerVersionSkew(brokerVersion: string | undefined, localVersion?: string): BrokerVersionSkew | null;
+export interface NativeMemoryRequirement {
+    bytes: number;
+    gpuBytes?: number;
+    exclusive?: boolean;
+}
+export interface NativeCapacityLease {
+    bind(pid: number): Promise<void>;
+    ready(): Promise<void>;
+    release(): Promise<void>;
+    shouldYield(): Promise<boolean>;
+}
+export interface NativeCapacityOptions {
+    home: string;
+    exclusive?: boolean;
+    priority?: () => 'interactive' | 'background';
+    /** Evaluated after resolveLaunch, so context/offload recovery is priced anew. */
+    requirement?: () => NativeMemoryRequirement | undefined | Promise<NativeMemoryRequirement | undefined>;
+    execute?: (command: NativeCapacityCommand) => Promise<NativeCapacityReply>;
+}
+export declare function nativeCapacityDirectory(home: string): string;
+/**
+ * Free graphics memory as device admission counts it: every card's reported
+ * free memory, less a driver reserve. Undefined when no card reports usage.
+ *
+ * The llama.cpp context planner sizes adaptive growth against this same
+ * reading. It used to size against 95% of the card's TOTAL memory while
+ * admission compared against this, so on a 32 GB card with ~4.5 GB held by
+ * the desktop and browsers, gemma4-31b grew to a 96K window, planned a
+ * 28.3 GB launch, and was refused against 27.2 GB free — a launch that fit
+ * comfortably at the 64K it would otherwise have used (2026-09-23).
+ */
+export declare function measureAvailableGpuBytes(): Promise<number | undefined>;
+/** The engine memory limit the person set in Settings, in bytes, when they set one. */
+export declare function configuredEngineMemoryBytes(config: {
+    localEngineMemoryGb?: number | null | undefined;
+}): number | undefined;
+/**
+ * The ledger's static ceilings: a request above either is refused at acquire,
+ * whatever else is running. Shared with the media fit check so a model the
+ * download pages hide is exactly one the launch path refuses. Omit
+ * `configuredBytes` for the machine's automatic ceilings.
+ */
+export declare function staticCapacityCeilings(budget: Pick<CapacityBudget, 'budgetBytes' | 'fastBytes' | 'kind'>, ramBytes: number, configuredBytes?: number): {
+    budgetBytes: number;
+    gpuBudgetBytes: number;
+};
+export declare function sampleDeviceCapacity(home?: string): Promise<DeviceCapacitySample>;
+export declare function localDeviceCapacity(home: string): DeviceCapacityLedger;
+/** Conservative fallback for media engines that do not expose a launch planner. */
+export declare function estimateNativeLaunchMemory(launch: NativeEngineLaunch): Promise<NativeMemoryRequirement>;
+export declare function acquireNativeCapacity(options: NativeCapacityOptions, launch: NativeEngineLaunch, signal: AbortSignal, onWait: (message: string) => void): Promise<NativeCapacityLease>;

package/dist/providers/native/device-capacity.js

@@ -0,0 +1,431 @@
+import { randomUUID } from 'node:crypto';
+import { readdir, stat } from 'node:fs/promises';
+import { homedir, totalmem } from 'node:os';
+import { join } from 'node:path';
+import { GEZEL_VERSION, NativeCapacityCommandSchema, NativeCapacityReplySchema, awakeNow, createLogger, isUnstampedDevBuild, } from '@bendyline/gezel';
+import { readSystemServiceRuntime, systemServiceHome } from '@bendyline/gezel-client/node';
+import { ConfigStore } from '../../fs/config-store.js';
+import { createPinnedFetch } from '../../remotes/pinned-fetch.js';
+import { CapacityDeniedError, availableSystemRamBytes, liveRamOsReserveBytes, } from './capacity-broker.js';
+import { DeviceCapacityLedger } from './device-capacity-ledger.js';
+import { measuredCapacityBudget } from './measured-budget.js';
+const GIB = 1024 ** 3;
+const POLL_MS = 500;
+/**
+ * Ceiling for the case where the ledger reports `externalShortfall` — the
+ * request leads the queue and fits the budget, and nothing this protocol
+ * governs is holding the memory. Engine work can legitimately take longer
+ * than five minutes, so governed contention stays queued until it can run or
+ * the caller cancels. Queueing behind the user's browser is different: a
+ * request that needs 9.7 GB on a host with 4.3 GB free should report the
+ * shortfall promptly.
+ * Short rather than zero because a just-released engine's pages take a moment
+ * to come back, and makeRoom's retry deserves to see them.
+ */
+const EXTERNAL_SHORTFALL_WAIT_MS = 20_000;
+// Once an installed broker owns this process's reservations, its disappearance
+// is an outage, never permission to create a competing local ledger.
+const observedMachineAuthorities = new Set();
+const log = createLogger('native-capacity');
+/** Skew is announced once per (broker home, version) — acquire runs per launch. */
+const announcedSkew = new Set();
+/**
+ * Installed brokers, by (home, version), that answered 404 for the capacity
+ * route: they predate memory coordination and never will coordinate, so later
+ * launches skip straight to the local ledger until Gezel is updated.
+ */
+const outdatedBrokers = new Set();
+/**
+ * Decide who arbitrates this machine's memory when an installed machine engine
+ * is present.
+ *
+ * Hosting mode does not answer this. An embedded dev daemon still shares the
+ * physical RAM of the box with whatever the installed app loads, so deferring
+ * to one machine-wide ledger is right in production and right for two builds
+ * of the same version. What it is NOT right for is a dev loop: on 2026-09-08 a
+ * patched dev build planned an 8.6 GB launch against its own corrected
+ * availability reading, handed the request to an installed 1.26251.69 broker
+ * whose formula saw 5.9 GB, and waited out the full five-minute admission
+ * budget — the fix under test could not run, because the process that decides
+ * was a different, older one. Nothing in either log said so.
+ *
+ * Ordering is deliberately not the test. `isUnstampedDevBuild` is: a checkout
+ * carries code no release has, while `0.0.0` sorts below every stamped version
+ * — so `compareGezelVersions` would conclude the exact opposite of the truth.
+ */
+export function assessBrokerVersionSkew(brokerVersion, localVersion = GEZEL_VERSION) {
+    if (brokerVersion !== undefined && brokerVersion === localVersion)
+        return null;
+    return {
+        brokerVersion: brokerVersion ?? 'unknown',
+        localVersion,
+        // A broker that reports no version cannot be shown to be this build, and a
+        // dev loop that silently tests someone else's code is the failure here.
+        takeLocalAuthority: isUnstampedDevBuild(localVersion),
+    };
+}
+function announceSkew(machineHome, skew) {
+    const key = `${machineHome}\u0000${skew.brokerVersion}\u0000${String(skew.takeLocalAuthority)}`;
+    if (announcedSkew.has(key))
+        return;
+    announcedSkew.add(key);
+    if (skew.takeLocalAuthority) {
+        log.warn([
+            `dev build (unstamped) differs from the installed machine engine (${skew.brokerVersion}); `,
+            'using the LOCAL admission ledger so this build’s own memory decisions are the ones under ',
+            'test. Engines started by the installed app are NOT coordinated with — quit it before ',
+            'loading large models on a memory-tight host. Set ',
+            'GEZEL_NATIVE_CAPACITY_AUTHORITY=machine to defer anyway.',
+        ].join(''));
+        return;
+    }
+    log.info([
+        `this build (${skew.localVersion}) and the installed machine engine (${skew.brokerVersion}) `,
+        'are different versions; deferring to the machine engine as the memory authority, so ',
+        'admission decisions come from the installed service rather than from this build.',
+    ].join(''));
+}
+export function nativeCapacityDirectory(home) {
+    return (process.env.GEZEL_NATIVE_CAPACITY_DIR ??
+        (home === systemServiceHome()
+            ? join(home, 'native-capacity')
+            : join(homedir(), '.gezel', 'runtime', 'native-capacity')));
+}
+/**
+ * Free graphics memory as device admission counts it: every card's reported
+ * free memory, less a driver reserve. Undefined when no card reports usage.
+ *
+ * The llama.cpp context planner sizes adaptive growth against this same
+ * reading. It used to size against 95% of the card's TOTAL memory while
+ * admission compared against this, so on a 32 GB card with ~4.5 GB held by
+ * the desktop and browsers, gemma4-31b grew to a 96K window, planned a
+ * 28.3 GB launch, and was refused against 27.2 GB free — a launch that fit
+ * comfortably at the 64K it would otherwise have used (2026-09-23).
+ */
+export async function measureAvailableGpuBytes() {
+    const { createSystemDeviceHealthProbe } = await import('@bendyline/gezel/native');
+    const probe = await createSystemDeviceHealthProbe({
+        helperPath: process.env.GEZEL_DEVICE_HEALTH_BIN,
+    }).sample();
+    const readings = probe.readings.filter((r) => r.memoryTotalMb !== undefined && r.memoryUsedMb !== undefined);
+    if (readings.length === 0)
+        return undefined;
+    return Math.max(0, readings.reduce((sum, r) => sum + r.memoryTotalMb - r.memoryUsedMb, 0) * 1024 ** 2 -
+        256 * 1024 ** 2);
+}
+/** The engine memory limit the person set in Settings, in bytes, when they set one. */
+export function configuredEngineMemoryBytes(config) {
+    return typeof config.localEngineMemoryGb === 'number' && config.localEngineMemoryGb > 0
+        ? config.localEngineMemoryGb * GIB
+        : undefined;
+}
+/**
+ * The ledger's static ceilings: a request above either is refused at acquire,
+ * whatever else is running. Shared with the media fit check so a model the
+ * download pages hide is exactly one the launch path refuses. Omit
+ * `configuredBytes` for the machine's automatic ceilings.
+ */
+export function staticCapacityCeilings(budget, ramBytes, configuredBytes) {
+    const budgetBytes = configuredBytes === undefined
+        ? budget.budgetBytes
+        : Math.min(configuredBytes, budget.budgetBytes);
+    return {
+        budgetBytes,
+        // Keep non-reclaimable accelerator commitments on the conservative curve;
+        // a larger RAM budget is not permission to wire the whole machine.
+        gpuBudgetBytes: Math.min(budgetBytes, budget.kind === 'unified' ? Math.min(budget.fastBytes, ramBytes * 0.75) : budget.fastBytes),
+    };
+}
+export async function sampleDeviceCapacity(home) {
+    const budget = await measuredCapacityBudget();
+    const ram = totalmem();
+    const config = home ? await new ConfigStore(home).readConfig() : {};
+    const ceilings = staticCapacityCeilings(budget, ram, configuredEngineMemoryBytes(config));
+    // The ledger's RAM ceiling and the OS's currently reclaimable RAM answer
+    // different questions. Checking both catches tenants outside this protocol.
+    //
+    // This MUST be the same reading the context planner sized the launch
+    // against — see liveRamOsReserveBytes. It used to be a darwin-only sample
+    // that counted neither inactive nor speculative pages, which made admission
+    // roughly 5 GiB stricter than planning on a 16 GiB Mac and refused launches
+    // the host could serve.
+    const availableRamBytes = Math.max(0, availableSystemRamBytes() - liveRamOsReserveBytes(ram));
+    const availableBytes = availableRamBytes + budget.vramBytes;
+    const discrete = budget.kind === 'discrete-gpu';
+    const availableGpuBytes = discrete ? await measureAvailableGpuBytes() : undefined;
+    return {
+        ...ceilings,
+        availableBytes,
+        ...(availableGpuBytes !== undefined ? { availableGpuBytes } : {}),
+        // A discrete card's claims say how much of them lives on the card, so
+        // their RAM need is the rest. Against RAM plus the whole card, a MoE
+        // that keeps only its residue on the GPU would be credited with graphics
+        // memory it never uses.
+        ...(discrete ? { availableRamBytes } : {}),
+        serializeLoads: process.platform === 'darwin',
+    };
+}
+export function localDeviceCapacity(home) {
+    return new DeviceCapacityLedger({
+        directory: nativeCapacityDirectory(home),
+        sample: () => sampleDeviceCapacity(home),
+    });
+}
+/** Routes reservations to the installed broker even when eval inference is isolated. */
+async function capacityExecutor(home) {
+    // Set only after an explicit desktop-startup choice (or deliberately by an
+    // operator). This is not tied to GEZEL_DISABLE_MACHINE_ENGINE: isolated
+    // inference normally still shares the installed broker's admission ledger.
+    const authority = process.env.GEZEL_NATIVE_CAPACITY_AUTHORITY;
+    if (authority === 'local') {
+        const ledger = localDeviceCapacity(home);
+        return (command) => ledger.execute(command);
+    }
+    const machineHome = systemServiceHome();
+    if (machineHome && machineHome !== home) {
+        const runtime = await readSystemServiceRuntime(machineHome);
+        if (runtime?.serviceRole === 'machine-engine') {
+            const { inspectMachineRuntime } = await import('../../machine-engine/inspect-runtime.js');
+            let identity;
+            try {
+                identity = await inspectMachineRuntime(runtime);
+            }
+            catch (error) {
+                // Seeing the role at all is enough to refuse a competing ledger. A
+                // broker that is merely unreachable is an outage, never permission to
+                // double-book the machine — so claim the authority before rethrowing.
+                observedMachineAuthorities.add(machineHome);
+                throw error;
+            }
+            const skew = assessBrokerVersionSkew(identity.gezelVersion);
+            if (skew)
+                announceSkew(machineHome, skew);
+            // `machine` is the explicit opt-back-in for a dev build that wants the
+            // installed broker's arbitration anyway (two engines, one tight host).
+            if (skew?.takeLocalAuthority && authority !== 'machine') {
+                const ledger = localDeviceCapacity(home);
+                return (command) => ledger.execute(command);
+            }
+            const outdatedKey = `${machineHome}\u0000${identity.gezelVersion ?? 'unknown'}`;
+            if (outdatedBrokers.has(outdatedKey) && authority !== 'machine') {
+                const ledger = localDeviceCapacity(home);
+                return (command) => ledger.execute(command);
+            }
+            observedMachineAuthorities.add(machineHome);
+            let verifiedCert = runtime.cert;
+            let brokerAccepted = false;
+            let local = null;
+            return async (command) => {
+                if (local)
+                    return local.execute(command);
+                // Re-read discovery on each operation: broker restarts rotate both the
+                // token and TLS certificate. Never switch a live lease to another ledger.
+                const current = await readSystemServiceRuntime(machineHome);
+                if (!current || current.serviceRole !== 'machine-engine' || !current.cert) {
+                    throw new CapacityDeniedError('Waiting for the machine engine to restore memory coordination.');
+                }
+                if (current.cert !== verifiedCert) {
+                    const refreshed = await inspectMachineRuntime(current);
+                    if (refreshed.pinnedIdentityFingerprint !== identity.pinnedIdentityFingerprint)
+                        throw new CapacityDeniedError('The machine memory coordinator identity changed.');
+                    verifiedCert = current.cert;
+                }
+                const fetchImpl = createPinnedFetch(current.cert);
+                try {
+                    const response = await fetchImpl(`${current.baseUrl}/v1/remote/manage/native-capacity`, {
+                        method: 'POST',
+                        headers: {
+                            authorization: `Bearer ${current.token}`,
+                            'content-type': 'application/json',
+                        },
+                        body: JSON.stringify(command),
+                        signal: AbortSignal.timeout(5_000),
+                    });
+                    if (response.ok) {
+                        brokerAccepted = true;
+                        return NativeCapacityReplySchema.parse(await response.json());
+                    }
+                    // Once the broker has accepted a command it holds this lease, and a
+                    // 404 is no longer evidence that it predates coordination.
+                    if (response.status !== 404 || brokerAccepted || authority === 'machine') {
+                        const detail = response.status === 409
+                            ? (await response.json().catch(() => null))
+                            : null;
+                        throw new CapacityDeniedError(response.status === 404
+                            ? 'The installed machine engine needs an update before isolated local engines can share memory safely.'
+                            : (detail?.error ??
+                                `Machine memory coordination unavailable (HTTP ${response.status}).`));
+                    }
+                }
+                finally {
+                    await fetchImpl.close();
+                }
+                // The installed broker predates memory coordination: it neither sees
+                // nor limits this build's engines, and refusing would leave an embedded
+                // Gezel unable to run its own models until the person updates an app
+                // they may not use. Admit through this build's ledger instead; it still
+                // checks the RAM the OS reports free, so the older app's resident
+                // engines count against every launch.
+                outdatedBrokers.add(outdatedKey);
+                observedMachineAuthorities.delete(machineHome);
+                // Diagnostics only: the person is never asked to resolve version skew.
+                log.info([
+                    `the installed machine engine (${identity.gezelVersion ?? 'unknown'}) predates memory `,
+                    'coordination; admitting this build’s engines through its own ledger.',
+                ].join(''));
+                local = localDeviceCapacity(home);
+                return local.execute(command);
+            };
+        }
+        if (observedMachineAuthorities.has(machineHome))
+            throw new CapacityDeniedError('Waiting for the machine engine to restore memory coordination.');
+    }
+    const ledger = localDeviceCapacity(home);
+    return (command) => ledger.execute(command);
+}
+/** Conservative fallback for media engines that do not expose a launch planner. */
+export async function estimateNativeLaunchMemory(launch) {
+    const paths = new Set();
+    for (let i = 0; i < launch.args.length - 1; i++) {
+        if ([
+            '--model',
+            '-m',
+            '--mmproj',
+            '--diffusion-model',
+            '--vae',
+            '--clip_l',
+            '--clip_g',
+            '--t5xxl',
+            '--llm',
+            '--model-draft',
+        ].includes(launch.args[i])) {
+            paths.add(launch.args[i + 1]);
+        }
+    }
+    const weightBytes = async (path, depth = 0) => {
+        const info = await stat(path);
+        if (info.isFile())
+            return info.size;
+        if (!info.isDirectory() || depth > 6)
+            return 0;
+        const entries = await readdir(path, { withFileTypes: true });
+        let bytes = 0;
+        for (const entry of entries) {
+            if (entry.isDirectory() ||
+                (entry.isFile() && /\.(gguf|safetensors|bin|pt|pth)$/i.test(entry.name))) {
+                bytes += await weightBytes(join(path, entry.name), depth + 1);
+            }
+        }
+        return bytes;
+    };
+    let bytes = 0;
+    for (const path of paths)
+        bytes += await weightBytes(path);
+    if (bytes <= 0)
+        throw new CapacityDeniedError('Cannot determine the native model working set before starting it.');
+    const cpu = launch.args.includes('--cpu') ||
+        launch.args.includes('--no-gpu') ||
+        launch.args.some((arg, i) => arg === '--accelerator' && launch.args[i + 1] === 'cpu') ||
+        launch.args.some((arg, i) => ['--n-gpu-layers', '--gpu-layers', '-ngl'].includes(arg) && launch.args[i + 1] === '0');
+    const reservation = Math.ceil(bytes * 1.5 + GIB);
+    return { bytes: reservation, ...(cpu ? { gpuBytes: 0 } : {}) };
+}
+/**
+ * The refusal a person can act on: which two numbers disagreed, and that the
+ * memory is held by their other applications rather than by Gezel. The old
+ * wording ("current engine work is still protected") described a queue that,
+ * in this branch, has nothing in it.
+ */
+function formatHostMemoryShortfall(reply) {
+    const gb = (bytes) => `${(bytes / GIB).toFixed(1)} GB`;
+    if (reply.requiredBytes === undefined || reply.availableBytes === undefined)
+        return 'Not enough free memory on this device to start this model right now. Close some applications and retry, or choose a smaller model.';
+    return [
+        'Not enough free memory on this device to start this model: it needs about ',
+        `${gb(reply.requiredBytes)}, and ${gb(reply.availableBytes)} is available right now. `,
+        'The rest is in use by other applications, not by Gezel — closing some and retrying ',
+        'will help, as will choosing a smaller model.',
+    ].join('');
+}
+export async function acquireNativeCapacity(options, launch, signal, onWait) {
+    const execute = options.execute ?? (await capacityExecutor(options.home));
+    const requirement = (await options.requirement?.()) ?? (await estimateNativeLaunchMemory(launch));
+    const budget = await measuredCapacityBudget();
+    const id = randomUUID();
+    const request = NativeCapacityCommandSchema.parse({
+        action: 'acquire',
+        id,
+        ownerPid: process.pid,
+        label: 'native model',
+        bytes: Math.ceil(requirement.bytes),
+        gpuBytes: Math.ceil(requirement.gpuBytes ??
+            (budget.kind === 'system-ram'
+                ? 0
+                : budget.kind === 'discrete-gpu'
+                    ? Math.min(requirement.bytes, budget.fastBytes)
+                    : requirement.bytes)),
+        exclusive: requirement.exclusive ?? options.exclusive ?? false,
+    });
+    let lastReport = Number.NEGATIVE_INFINITY;
+    let externalSince;
+    try {
+        for (;;) {
+            signal.throwIfAborted();
+            if (request.action === 'acquire')
+                request.priority = options.priority?.() ?? 'interactive';
+            const reply = await execute(request);
+            signal.throwIfAborted();
+            if (reply.state === 'granted')
+                break;
+            if (reply.externalShortfall) {
+                externalSince ??= awakeNow();
+                if (awakeNow() - externalSince >= EXTERNAL_SHORTFALL_WAIT_MS)
+                    throw new CapacityDeniedError(formatHostMemoryShortfall(reply));
+            }
+            else {
+                externalSince = undefined;
+            }
+            if (awakeNow() - lastReport >= 15_000) {
+                onWait(reply.reason ?? 'Waiting for memory.');
+                lastReport = awakeNow();
+            }
+            await new Promise((resolve, reject) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    signal.removeEventListener('abort', abort);
+                    resolve();
+                };
+                const abort = () => {
+                    clearTimeout(timer);
+                    signal.removeEventListener('abort', abort);
+                    reject(signal.reason);
+                };
+                const timer = setTimeout(done, POLL_MS);
+                signal.addEventListener('abort', abort, { once: true });
+                if (signal.aborted)
+                    abort();
+            });
+        }
+    }
+    catch (error) {
+        await execute({ action: 'release', id }).catch(() => { });
+        throw error;
+    }
+    return {
+        bind: async (childPid) => {
+            if ((await execute({ action: 'bind', id, childPid })).state !== 'granted')
+                throw new CapacityDeniedError('The engine memory reservation was lost before startup.');
+        },
+        ready: async () => {
+            if ((await execute({ action: 'ready', id })).state !== 'granted')
+                throw new CapacityDeniedError('The engine memory reservation was lost during startup.');
+        },
+        release: async () => {
+            await execute({ action: 'release', id });
+        },
+        shouldYield: async () => {
+            const reply = await execute({ action: 'status', id });
+            return reply.state !== 'granted' || reply.releaseRequested;
+        },
+    };
+}

package/dist/providers/native/engine-api-key.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A per-process bearer token for the loopback engine APIs we spawn.
+ *
+ * ── Why a local-only HTTP server still needs auth ────────────────────────
+ *
+ * A supervised engine binds `127.0.0.1:<ephemeral>`, which sounds closed but
+ * is not. Two callers can reach it that we do not want reaching it:
+ *
+ *  1. **Any web page in the user's browser.** llama.cpp defaults
+ *     `--cors-origins` to `*` with credentials enabled, so it echoes back
+ *     whatever `Origin` it is handed — measured directly against the pinned
+ *     build, a request carrying `Origin: https://evil.example` came back
+ *     `200` with `Access-Control-Allow-Origin: https://evil.example` and a
+ *     full chat completion. The response body also leaks the absolute model
+ *     path, which contains the account name. Passing `--cors-origins
+ *     localhost` removes the header entirely for a foreign origin and closes
+ *     this;`--no-webui` drops the built-in chat page nobody here uses.
+ *  2. **Any other local process.** CORS is a *browser* policy; it does
+ *     nothing about a native process that opens the port directly. Only a
+ *     credential does, which is what this module is for.
+ *
+ * ── Shape ────────────────────────────────────────────────────────────────
+ *
+ * One random token per daemon process, generated lazily and never persisted.
+ * Per-process rather than per-engine because the value it protects is
+ * identical across replicas (a local model server holds no per-engine
+ * secret), and one token keeps the wrapper below stateless.
+ *
+ * It is handed to the child through the **environment**, never `argv`:
+ * command lines are world-readable via `ps` on a shared machine, whereas
+ * `/proc/<pid>/environ` is owner-only and macOS requires root for `ps -E`.
+ *
+ * Engines this applies to are the ones we launch. An engine the user pointed
+ * us at through an external base URL is theirs, not ours — we neither set its
+ * flags nor assume a key, so the wrapper is applied only on the supervised
+ * path.
+ */
+/**
+ * The token for this daemon process. Generated on first use so a daemon that
+ * never starts an engine never mints one.
+ */
+export declare function engineApiKey(): string;
+/** Test seam — forget the token so a case can assert generation behaviour. */
+export declare function resetEngineApiKeyForTests(): void;
+/**
+ * Wrap a fetch so every request carries the engine bearer token.
+ *
+ * An existing `Authorization` header always wins: the wrapper is a default,
+ * not an override, so a caller that deliberately authenticates some other way
+ * is left alone.
+ *
+ * Note that the engine's readiness and health endpoints are deliberately
+ * *unauthenticated* upstream (`/health` answers 200 without a key while
+ * `/props`, `/slots` and `/v1/*` return 401), so the supervisor's readiness
+ * probe and health watch keep working whether or not they go through this.
+ */
+export declare function withEngineApiKey(fetchImpl: typeof fetch, key: string): typeof fetch;

package/dist/providers/native/engine-api-key.js

@@ -0,0 +1,72 @@
+/**
+ * A per-process bearer token for the loopback engine APIs we spawn.
+ *
+ * ── Why a local-only HTTP server still needs auth ────────────────────────
+ *
+ * A supervised engine binds `127.0.0.1:<ephemeral>`, which sounds closed but
+ * is not. Two callers can reach it that we do not want reaching it:
+ *
+ *  1. **Any web page in the user's browser.** llama.cpp defaults
+ *     `--cors-origins` to `*` with credentials enabled, so it echoes back
+ *     whatever `Origin` it is handed — measured directly against the pinned
+ *     build, a request carrying `Origin: https://evil.example` came back
+ *     `200` with `Access-Control-Allow-Origin: https://evil.example` and a
+ *     full chat completion. The response body also leaks the absolute model
+ *     path, which contains the account name. Passing `--cors-origins
+ *     localhost` removes the header entirely for a foreign origin and closes
+ *     this;`--no-webui` drops the built-in chat page nobody here uses.
+ *  2. **Any other local process.** CORS is a *browser* policy; it does
+ *     nothing about a native process that opens the port directly. Only a
+ *     credential does, which is what this module is for.
+ *
+ * ── Shape ────────────────────────────────────────────────────────────────
+ *
+ * One random token per daemon process, generated lazily and never persisted.
+ * Per-process rather than per-engine because the value it protects is
+ * identical across replicas (a local model server holds no per-engine
+ * secret), and one token keeps the wrapper below stateless.
+ *
+ * It is handed to the child through the **environment**, never `argv`:
+ * command lines are world-readable via `ps` on a shared machine, whereas
+ * `/proc/<pid>/environ` is owner-only and macOS requires root for `ps -E`.
+ *
+ * Engines this applies to are the ones we launch. An engine the user pointed
+ * us at through an external base URL is theirs, not ours — we neither set its
+ * flags nor assume a key, so the wrapper is applied only on the supervised
+ * path.
+ */
+import { randomBytes } from 'node:crypto';
+let cached;
+/**
+ * The token for this daemon process. Generated on first use so a daemon that
+ * never starts an engine never mints one.
+ */
+export function engineApiKey() {
+    if (!cached)
+        cached = randomBytes(32).toString('hex');
+    return cached;
+}
+/** Test seam — forget the token so a case can assert generation behaviour. */
+export function resetEngineApiKeyForTests() {
+    cached = undefined;
+}
+/**
+ * Wrap a fetch so every request carries the engine bearer token.
+ *
+ * An existing `Authorization` header always wins: the wrapper is a default,
+ * not an override, so a caller that deliberately authenticates some other way
+ * is left alone.
+ *
+ * Note that the engine's readiness and health endpoints are deliberately
+ * *unauthenticated* upstream (`/health` answers 200 without a key while
+ * `/props`, `/slots` and `/v1/*` return 401), so the supervisor's readiness
+ * probe and health watch keep working whether or not they go through this.
+ */
+export function withEngineApiKey(fetchImpl, key) {
+    return ((input, init) => {
+        const headers = new Headers(init?.headers ?? {});
+        if (!headers.has('authorization'))
+            headers.set('authorization', `Bearer ${key}`);
+        return fetchImpl(input, { ...init, headers });
+    });
+}

package/dist/providers/native/engine-key.d.ts

@@ -0,0 +1,18 @@
+/**
+ * EngineKey — the string handle that identifies a local-engine
+ * instance in the ProviderPool. Composite: `${provider}:${modelId}:${replicaIdx}`.
+ *
+ * Cloud providers (copilot, openai, anthropic, anthropic-cli,
+ * codex-cli, ollama, mock) are NOT pool-managed — they keep the
+ * bare-provider-name keying ChatManager's `cloudProviders` map uses.
+ */
+export type LocalProviderName = 'llama-cpp' | 'mlx' | 'ds4';
+export declare const LOCAL_PROVIDERS: readonly LocalProviderName[];
+export declare function isLocalProvider(name: string): name is LocalProviderName;
+export interface ParsedEngineKey {
+    provider: LocalProviderName;
+    modelId: string;
+    replicaIdx: number;
+}
+export declare function makeEngineKey(provider: LocalProviderName, modelId: string, replicaIdx: number): string;
+export declare function parseEngineKey(key: string): ParsedEngineKey | null;