@bendyline/gezel-inference 1.0.7 → 1.0.8

package/dist/providers/mlx/tool-call-protocol.d.ts

@@ -39,9 +39,10 @@ export declare function applyCallableToolGrammar(body: Record<string, unknown>,
  *
  * This deliberately checks presence only. A present-but-wrongly-typed value
  * remains the MCP validator's job; the MLX Hermes grammar promises only that
- * every declared required key is emitted before the call can close. Seeing a
- * missing key is therefore evidence that the live constrained-decoding path
- * broke its own contract, not an ordinary model validation miss.
+ * every declared required key is emitted before a constrained call can close.
+ * A missing key alone does not establish a decoder fault: calls salvaged from
+ * ordinary prose were not subject to that grammar. The caller must preserve
+ * their origin when deciding whether to disable speculative decoding.
  */
 export declare function missingTopLevelRequiredToolArgs(schema: Record<string, unknown> | undefined, args: Record<string, unknown>): string[];
 export declare function hermesRequiredArgGrammarRequested(body: Record<string, unknown>): boolean;

package/dist/providers/mlx/tool-call-protocol.js

@@ -59,9 +59,10 @@ export function applyCallableToolGrammar(body, bridges) {
  *
  * This deliberately checks presence only. A present-but-wrongly-typed value
  * remains the MCP validator's job; the MLX Hermes grammar promises only that
- * every declared required key is emitted before the call can close. Seeing a
- * missing key is therefore evidence that the live constrained-decoding path
- * broke its own contract, not an ordinary model validation miss.
+ * every declared required key is emitted before a constrained call can close.
+ * A missing key alone does not establish a decoder fault: calls salvaged from
+ * ordinary prose were not subject to that grammar. The caller must preserve
+ * their origin when deciding whether to disable speculative decoding.
  */
 export function missingTopLevelRequiredToolArgs(schema, args) {
     const required = schema?.required;

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

@@ -1,5 +1,6 @@
 import type { NativeCapacityCommand, NativeCapacityReply } from '@bendyline/gezel';
-import { readProcessIdentities } from './process-identity.js';
+import { ProcessIdentityCache, processAlive, type readProcessIdentities } from './process-identity.js';
+export { processAlive };
 export interface DeviceCapacitySample {
     budgetBytes: number;
     gpuBudgetBytes: number;
@@ -14,7 +15,6 @@ export interface DeviceCapacitySample {
     availableRamBytes?: number;
     serializeLoads: boolean;
 }
-export declare function processAlive(pid: number): boolean;
 /**
  * SQLite's process lock makes check-and-reserve atomic across GEZEL_HOME values.
  * Reservations survive a broker restart. A dead parent does not free the memory
@@ -22,11 +22,13 @@ export declare function processAlive(pid: number): boolean;
  */
 export declare class DeviceCapacityLedger {
     private readonly options;
+    private readonly identityCache;
     constructor(options: {
         directory: string;
         sample: () => Promise<DeviceCapacitySample>;
         alive?: (pid: number) => boolean;
         identities?: typeof readProcessIdentities;
+        identityCache?: ProcessIdentityCache;
     });
     execute(command: NativeCapacityCommand): Promise<NativeCapacityReply>;
     private transact;

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

@@ -2,7 +2,8 @@ import { chmod, mkdir } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { CapacityDeniedError } from './capacity-broker.js';
-import { readProcessIdentities } from './process-identity.js';
+import { ProcessIdentityCache, processAlive, sharedProcessIdentities, } from './process-identity.js';
+export { processAlive };
 // Keep the newer builtin behind a runtime require. The current tsup/esbuild
 // target rewrites a static `node:sqlite` import to the nonexistent npm package
 // `sqlite`, making the daemon bundle fail before it can write runtime state.
@@ -11,15 +12,6 @@ const { DatabaseSync } = nodeRequire('node:sqlite');
 function gb(bytes) {
     return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
 }
-export function processAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code !== 'ESRCH';
-    }
-}
 /**
  * SQLite's process lock makes check-and-reserve atomic across GEZEL_HOME values.
  * Reservations survive a broker restart. A dead parent does not free the memory
@@ -27,8 +19,18 @@ export function processAlive(pid) {
  */
 export class DeviceCapacityLedger {
     options;
+    identityCache;
     constructor(options) {
         this.options = options;
+        // An injected reader still goes through a cache, so tests see the reads
+        // production makes. An injected `alive` alone checks liveness only.
+        this.identityCache =
+            options.identityCache ??
+                (options.identities
+                    ? new ProcessIdentityCache({ read: options.identities, alive: options.alive })
+                    : options.alive
+                        ? undefined
+                        : sharedProcessIdentities);
     }
     async execute(command) {
         const sample = await this.options.sample();
@@ -43,18 +45,31 @@ export class DeviceCapacityLedger {
                 .prepare('SELECT claim FROM claims')
                 .all()
                 .map((row) => JSON.parse(String(row.claim)));
-            const pids = snapshot.flatMap((claim) => [
-                claim.ownerPid,
-                ...(claim.childPid === undefined ? [] : [claim.childPid]),
-            ]);
-            if (command.action === 'acquire')
-                pids.push(command.ownerPid);
+            const record = [];
+            if (command.action === 'acquire' && !snapshot.some((claim) => claim.id === command.id))
+                record.push(command.ownerPid);
             if (command.action === 'bind')
-                pids.push(command.childPid);
+                record.push(command.childPid);
+            // Stamps only decide which reservations are stale, and a stale one costs
+            // someone only while a request waits for memory. With no request
+            // waiting, liveness alone prunes, so the status check that runs before
+            // every engine request reads no stamps.
+            const confirm = new Map();
+            const stamp = (pid, identity) => {
+                if (pid !== undefined && identity !== undefined)
+                    confirm.set(pid, [...(confirm.get(pid) ?? []), identity]);
+            };
+            if (command.action === 'acquire' || snapshot.some((claim) => claim.phase === 'waiting')) {
+                for (const claim of snapshot) {
+                    stamp(claim.childPid, claim.childIdentity);
+                    // An owner's stamp is only consulted while its claim is queued.
+                    if (claim.phase === 'waiting')
+                        stamp(claim.ownerPid, claim.ownerIdentity);
+                }
+            }
             // OS probes may spawn a helper. Never hold SQLite's writer lock while awaiting one.
-            const probe = this.options.identities ?? (this.options.alive ? undefined : readProcessIdentities);
-            const identities = command.action !== 'release' && probe
-                ? await probe(pids).catch(() => new Map())
+            const identities = command.action !== 'release' && this.identityCache
+                ? await this.identityCache.lookup(record, confirm).catch(() => new Map())
                 : new Map();
             db.exec('BEGIN IMMEDIATE');
             try {

package/dist/providers/native/process-identity.d.ts

@@ -1,2 +1,40 @@
+export declare function processAlive(pid: number): boolean;
 /** Birth stamps survive coordinator restarts and distinguish a reused PID. */
 export declare function readProcessIdentities(pids: readonly number[]): Promise<ReadonlyMap<number, string>>;
+/**
+ * How long a stamp read for a still-live PID is trusted. A PID can die and be
+ * reused between two liveness checks; this bounds how long such a dead
+ * engine's reservation outlives it. That is the safe direction: memory looks
+ * taken for a few seconds longer, never free twice.
+ */
+export declare const VERIFIED_IDENTITY_TTL_MS = 10000;
+export interface ProcessIdentityCacheOptions {
+    read?: (pids: readonly number[]) => Promise<ReadonlyMap<number, string>>;
+    alive?: (pid: number) => boolean;
+    now?: () => number;
+    ttlMs?: number;
+}
+/**
+ * Reading a birth stamp starts `ps`, or PowerShell on Windows. The capacity
+ * ledger used to read every PID it holds on each command, which ran before
+ * every engine request. A stamp read for a PID that is still alive is reused
+ * for a short while, and the PIDs that do need reading go in one batch.
+ *
+ * A cached stamp may only confirm the stamp a reservation already recorded.
+ * A stamp about to be recorded, or one that disagrees, is read again: another
+ * coordinator may have recorded a newer process at that PID, and trusting an
+ * older stamp there would free a live engine's memory.
+ */
+export declare class ProcessIdentityCache {
+    private readonly options;
+    private readonly verified;
+    constructor(options?: ProcessIdentityCacheOptions);
+    /**
+     * `record`: PIDs whose stamp is about to be written onto a reservation.
+     * `confirm`: each PID's stamps as reservations recorded them.
+     * PIDs that are dead, or whose stamp cannot be read, are left out.
+     */
+    lookup(record: Iterable<number>, confirm: ReadonlyMap<number, readonly string[]>): Promise<ReadonlyMap<number, string>>;
+}
+/** One cache per process: every ledger in it asks about the same OS processes. */
+export declare const sharedProcessIdentities: ProcessIdentityCache;

package/dist/providers/native/process-identity.js

@@ -11,6 +11,15 @@ const PROBE_PID_LIMIT = {
     darwin: 99_999,
     win32: 2_147_483_647,
 };
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
 /** Birth stamps survive coordinator restarts and distinguish a reused PID. */
 export async function readProcessIdentities(pids) {
     const limit = PROBE_PID_LIMIT[process.platform] ?? Number.MAX_SAFE_INTEGER;
@@ -68,3 +77,80 @@ export async function readProcessIdentities(pids) {
     }
     return identities;
 }
+/**
+ * How long a stamp read for a still-live PID is trusted. A PID can die and be
+ * reused between two liveness checks; this bounds how long such a dead
+ * engine's reservation outlives it. That is the safe direction: memory looks
+ * taken for a few seconds longer, never free twice.
+ */
+export const VERIFIED_IDENTITY_TTL_MS = 10_000;
+/**
+ * Reading a birth stamp starts `ps`, or PowerShell on Windows. The capacity
+ * ledger used to read every PID it holds on each command, which ran before
+ * every engine request. A stamp read for a PID that is still alive is reused
+ * for a short while, and the PIDs that do need reading go in one batch.
+ *
+ * A cached stamp may only confirm the stamp a reservation already recorded.
+ * A stamp about to be recorded, or one that disagrees, is read again: another
+ * coordinator may have recorded a newer process at that PID, and trusting an
+ * older stamp there would free a live engine's memory.
+ */
+export class ProcessIdentityCache {
+    options;
+    verified = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * `record`: PIDs whose stamp is about to be written onto a reservation.
+     * `confirm`: each PID's stamps as reservations recorded them.
+     * PIDs that are dead, or whose stamp cannot be read, are left out.
+     */
+    async lookup(record, confirm) {
+        const alive = this.options.alive ?? processAlive;
+        const ttl = this.options.ttlMs ?? VERIFIED_IDENTITY_TTL_MS;
+        const now = (this.options.now ?? (() => performance.now()))();
+        for (const [pid, entry] of this.verified) {
+            if (now - entry.at >= ttl)
+                this.verified.delete(pid);
+        }
+        const live = (pid) => {
+            if (alive(pid))
+                return true;
+            // Forget a PID seen dead, so whatever process takes it next is read.
+            this.verified.delete(pid);
+            return false;
+        };
+        const identities = new Map();
+        const unread = new Set();
+        for (const pid of record)
+            if (live(pid))
+                unread.add(pid);
+        for (const [pid, stamps] of confirm) {
+            if (unread.has(pid) || !live(pid))
+                continue;
+            const cached = this.verified.get(pid)?.identity;
+            if (cached !== undefined && stamps.every((stamp) => stamp === cached)) {
+                identities.set(pid, cached);
+            }
+            else {
+                unread.add(pid);
+            }
+        }
+        if (unread.size === 0)
+            return identities;
+        const read = await (this.options.read ?? readProcessIdentities)([...unread]).catch(() => new Map());
+        for (const pid of unread) {
+            const identity = read.get(pid);
+            if (identity === undefined) {
+                this.verified.delete(pid);
+                continue;
+            }
+            this.verified.set(pid, { identity, at: now });
+            identities.set(pid, identity);
+        }
+        return identities;
+    }
+}
+/** One cache per process: every ledger in it asks about the same OS processes. */
+export const sharedProcessIdentities = new ProcessIdentityCache();

package/dist/runtime-lock.d.ts

@@ -1,3 +1,6 @@
+import { type LockIdentity, currentLockIdentity, parseLockFile, procStartTicks, sharesPidNamespace } from '@bendyline/gezel/native';
+export type { LockIdentity };
+export { currentLockIdentity, parseLockFile, procStartTicks, sharesPidNamespace };
 /**
  * Thrown when a gezel home already has a live daemon. The CLI's `gezel
  * start` / the supervisor surface this as an actionable message rather
@@ -12,33 +15,6 @@ export declare class SingleInstanceError extends Error {
 export interface RuntimeLock {
     release(): Promise<void>;
 }
-/**
- * Who holds a lock. A pid alone identifies a process only inside one pid
- * namespace on one boot: two containers sharing a volume each see the
- * other's pid as dead (or as an unrelated process), which let a one-shot
- * `docker run … gezel do` reclaim a serving container's live lock. The
- * namespace, boot and host fields say when a pid check is meaningful; a
- * holder outside our namespace is judged by the lock file's heartbeat.
- */
-export interface LockIdentity {
-    pid: number;
-    hostname?: string;
-    bootId?: string;
-    pidNs?: string;
-    /** Process start time in clock ticks since boot (`/proc/<pid>/stat` field 22). */
-    startTicks?: string;
-    /** Random per-process id; tells our own heartbeat whether the lock is still ours. */
-    instance?: string;
-}
-export declare function procStartTicks(pid: number | 'self'): string | undefined;
-export declare function currentLockIdentity(): LockIdentity;
-export declare function parseLockFile(text: string): LockIdentity | null;
-/**
- * Whether a pid check against `holder` means anything here. Any field the
- * holder recorded must match ours; a legacy pid-only record is assumed to be
- * in our namespace, which is how it was judged before.
- */
-export declare function sharesPidNamespace(holder: LockIdentity, me: LockIdentity): boolean;
 /**
  * Acquire an exclusive single-instance lock for a gezel home so two daemons
  * can't share one `~/.gezel/` and race its on-disk state (config, sessions,

package/dist/runtime-lock.js

@@ -1,6 +1,6 @@
-import { readFileSync, readlinkSync } from 'node:fs';
 import { mkdir, open, readFile, rm, stat, utimes } from 'node:fs/promises';
-import { hostname as osHostname } from 'node:os';
+import { LOCK_HEARTBEAT_INTERVAL_MS, LOCK_STALE_AFTER_MS, currentLockIdentity, foreignHolderMessage, parseLockFile, procStartTicks, sharesPidNamespace, } from '@bendyline/gezel/native';
+export { currentLockIdentity, parseLockFile, procStartTicks, sharesPidNamespace };
 /**
  * Thrown when a gezel home already has a live daemon. The CLI's `gezel
  * start` / the supervisor surface this as an actionable message rather
@@ -12,7 +12,7 @@ export class SingleInstanceError extends Error {
     holderHost;
     constructor(holderPid, lockPath, holderHost) {
         super(holderHost !== undefined
-            ? `Another Gezel daemon (host "${holderHost}", pid ${holderPid}) is using this home. If it runs in a container, run commands inside that container with \`docker exec <container> gezel …\` instead of starting a second container on the same volume.`
+            ? foreignHolderMessage({ pid: holderPid, hostname: holderHost })
             : holderPid > 0
                 ? `Another gezel daemon is already running for this home (pid ${holderPid}). Stop it first with \`gezel stop\`, or use a different GEZEL_HOME.`
                 : `Could not acquire the single-instance lock at ${lockPath}.`);
@@ -22,8 +22,8 @@ export class SingleInstanceError extends Error {
         this.name = 'SingleInstanceError';
     }
 }
-const HEARTBEAT_INTERVAL_MS = 10_000;
-const STALE_AFTER_MS = 40_000;
+// A holder's identity (core's lock-identity.ts) is what let a one-shot
+// `docker run … gezel do` stop reclaiming a serving container's live lock.
 function defaultIsAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -35,45 +35,6 @@ function defaultIsAlive(pid) {
         return err.code === 'EPERM';
     }
 }
-function readTrimmed(path) {
-    try {
-        return readFileSync(path, 'utf8').trim() || undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-export function procStartTicks(pid) {
-    if (process.platform !== 'linux')
-        return undefined;
-    const stat = readTrimmed(`/proc/${pid}/stat`);
-    if (!stat)
-        return undefined;
-    // comm (field 2) may contain spaces and parentheses; fields resume after
-    // the last ')'. starttime is field 22 overall, the 20th after comm.
-    const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
-    return rest[19];
-}
-export function currentLockIdentity() {
-    const linux = process.platform === 'linux';
-    let pidNs;
-    if (linux) {
-        try {
-            pidNs = readlinkSync('/proc/self/ns/pid');
-        }
-        catch {
-            pidNs = undefined;
-        }
-    }
-    return {
-        pid: process.pid,
-        hostname: osHostname(),
-        bootId: linux ? readTrimmed('/proc/sys/kernel/random/boot_id') : undefined,
-        pidNs,
-        startTicks: procStartTicks('self'),
-        instance: `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
-    };
-}
 /**
  * The pid stays on the first line so a daemon from before the identity
  * record (which parses the leading integer) still reads it as held instead
@@ -82,29 +43,6 @@ export function currentLockIdentity() {
 function serializeIdentity(identity) {
     return `${identity.pid}\n${JSON.stringify({ v: 1, ...identity })}\n`;
 }
-export function parseLockFile(text) {
-    const [first, second] = text.split('\n');
-    const pid = Number.parseInt((first ?? '').trim(), 10);
-    if (!Number.isFinite(pid))
-        return null;
-    if (!second?.trim())
-        return { pid };
-    try {
-        const record = JSON.parse(second);
-        const text = (value) => (typeof value === 'string' && value ? value : undefined);
-        return {
-            pid,
-            hostname: text(record.hostname),
-            bootId: text(record.bootId),
-            pidNs: text(record.pidNs),
-            startTicks: text(record.startTicks),
-            instance: text(record.instance),
-        };
-    }
-    catch {
-        return { pid };
-    }
-}
 async function readHolder(lockPath) {
     try {
         return parseLockFile(await readFile(lockPath, 'utf8'));
@@ -113,17 +51,6 @@ async function readHolder(lockPath) {
         return null;
     }
 }
-/**
- * Whether a pid check against `holder` means anything here. Any field the
- * holder recorded must match ours; a legacy pid-only record is assumed to be
- * in our namespace, which is how it was judged before.
- */
-export function sharesPidNamespace(holder, me) {
-    const same = (a, b) => !a || !b || a === b;
-    return (same(holder.hostname, me.hostname) &&
-        same(holder.bootId, me.bootId) &&
-        same(holder.pidNs, me.pidNs));
-}
 async function lockMtimeMs(lockPath) {
     try {
         return (await stat(lockPath)).mtimeMs;
@@ -174,7 +101,7 @@ export async function acquireSingleInstanceLock(opts) {
     const startTicksOf = opts.startTicksOf ?? procStartTicks;
     const now = opts.now ?? Date.now;
     const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    const staleAfterMs = opts.staleAfterMs ?? STALE_AFTER_MS;
+    const staleAfterMs = opts.staleAfterMs ?? LOCK_STALE_AFTER_MS;
     await mkdir(opts.runtimeDir, { recursive: true });
     for (let attempt = 0; attempt < 3; attempt++) {
         try {
@@ -185,7 +112,7 @@ export async function acquireSingleInstanceLock(opts) {
             finally {
                 await handle.close();
             }
-            return holdLock(opts.lockPath, me, opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS);
+            return holdLock(opts.lockPath, me, opts.heartbeatIntervalMs ?? LOCK_HEARTBEAT_INTERVAL_MS);
         }
         catch (err) {
             if (err.code !== 'EEXIST')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/gezel-inference",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Gezel's on-device inference runtime: native engines, local model management, embeddings, knowledge search, and OpenAI-compatible routes.",
   "license": "MIT",
   "keywords": [
@@ -73,9 +73,9 @@
     "!dist/**/__pycache__"
   ],
   "dependencies": {
-    "@bendyline/gezel": "1.2.12",
-    "@bendyline/gezel-catalog": "1.2.12",
-    "@bendyline/gezel-client": "1.2.12",
+    "@bendyline/gezel": "1.2.13",
+    "@bendyline/gezel-catalog": "1.2.13",
+    "@bendyline/gezel-client": "1.2.13",
     "@bendyline/gezel-knowledge": "1.2.10",
     "hono": "4.13.14",
     "tar": "7.5.21",