@bendyline/gezel-inference 1.0.2 → 1.0.4

package/dist/providers/provider-lifecycle.d.ts

@@ -0,0 +1,21 @@
+interface Provider {
+    shutdown?(): Promise<void>;
+}
+/**
+ * Owns one lazy provider generation. Reset and broker retirement close admission
+ * before waiting for an in-flight build and admitted work. A failed shutdown
+ * retains its generation for retry; no replacement can leak past it.
+ */
+export declare class ProviderLifecycle<T extends Provider> {
+    private readonly operations;
+    private generation?;
+    private transition?;
+    private brokerRetired;
+    constructor(operations: ReadonlySet<PropertyKey>);
+    current(build: () => Promise<T>, retireWithBroker?: boolean): Promise<T>;
+    reset(): Promise<void>;
+    /** Permanent for native generations; user-owned cloud providers remain usable. */
+    retireForMachineBroker(): Promise<void>;
+    private drain;
+}
+export {};

package/dist/providers/provider-lifecycle.js

@@ -0,0 +1,83 @@
+import { ProviderRetirementGate, trackProviderOperations } from './retirement-gate.js';
+/**
+ * Owns one lazy provider generation. Reset and broker retirement close admission
+ * before waiting for an in-flight build and admitted work. A failed shutdown
+ * retains its generation for retry; no replacement can leak past it.
+ */
+export class ProviderLifecycle {
+    operations;
+    generation;
+    transition;
+    brokerRetired = false;
+    constructor(operations) {
+        this.operations = operations;
+    }
+    async current(build, retireWithBroker = true) {
+        if (retireWithBroker && this.brokerRetired)
+            throw new Error('local provider retired after machine engine adoption');
+        if (this.transition) {
+            await this.transition;
+            return this.current(build, retireWithBroker);
+        }
+        if (this.generation?.closed) {
+            await this.reset();
+            return this.current(build, retireWithBroker);
+        }
+        if (this.generation)
+            return this.generation.build;
+        const gate = new ProviderRetirementGate();
+        const generation = {
+            gate,
+            closed: false,
+            retireWithBroker,
+            build: Promise.resolve()
+                .then(build)
+                .then((provider) => {
+                generation.provider = provider;
+                return trackProviderOperations(provider, gate, this.operations);
+            })
+                .catch((error) => {
+                if (this.generation === generation)
+                    this.generation = undefined;
+                throw error;
+            }),
+        };
+        this.generation = generation;
+        return generation.build;
+    }
+    reset() {
+        return this.drain('local provider retired during reset; obtain the current provider');
+    }
+    /** Permanent for native generations; user-owned cloud providers remain usable. */
+    retireForMachineBroker() {
+        this.brokerRetired = true;
+        if (this.generation && !this.generation.retireWithBroker)
+            return Promise.resolve();
+        return this.drain();
+    }
+    drain(message) {
+        if (this.transition)
+            return this.transition;
+        const generation = this.generation;
+        if (!generation)
+            return Promise.resolve();
+        generation.closed = true;
+        generation.gate.beginRetirement(message);
+        const run = (async () => {
+            // A failed build produced no provider to shut down. Its caller still
+            // receives the build error, while retirement can finish successfully.
+            await generation.build.catch(() => { });
+            await generation.gate.waitForIdle();
+            await generation.provider?.shutdown?.();
+            if (this.generation === generation)
+                this.generation = undefined;
+        })();
+        this.transition = run;
+        const clear = () => {
+            if (this.transition === run)
+                this.transition = undefined;
+        };
+        void run.then(clear, clear);
+        return run;
+    }
+}

package/dist/providers/queue.d.ts

@@ -5,11 +5,18 @@
  * service's import point and keeps the one piece that reads the process
  * environment.
  */
-export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
-export type { EnqueueRequest, Lane, ProviderQueueOptions, QueueSnapshot, QueueWaitOpts, } from '@bendyline/gezel/runtime';
+export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, DEFAULT_LOCAL_YIELD_QUANTUM_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
+export type { EnqueueRequest, Lane, ProviderQueueOptions, QueueLease, QueueSnapshot, QueueWaitOpts, } from '@bendyline/gezel/runtime';
 /**
  * Ambient quiet window for local engine queues. Override with
  * `GEZEL_AMBIENT_QUIET_MS` (milliseconds; `0` disables ambient gating
  * entirely).
  */
 export declare function defaultAmbientQuietMs(): number;
+/**
+ * How long a local turn holds its queue slot before it hands the slot to
+ * another conversation that is waiting. Override with
+ * `GEZEL_QUEUE_YIELD_QUANTUM_MS` (milliseconds; `0` keeps a slot for the
+ * whole turn).
+ */
+export declare function defaultQueueYieldQuantumMs(): number;

package/dist/providers/queue.js

@@ -5,8 +5,8 @@
  * service's import point and keeps the one piece that reads the process
  * environment.
  */
-import { DEFAULT_AMBIENT_QUIET_MS } from '@bendyline/gezel/runtime';
-export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
+import { DEFAULT_AMBIENT_QUIET_MS, DEFAULT_LOCAL_YIELD_QUANTUM_MS } from '@bendyline/gezel/runtime';
+export { AbortedWhileQueuedError, DEFAULT_AMBIENT_QUIET_MS, DEFAULT_LOCAL_YIELD_QUANTUM_MS, ProviderQueue, QUEUE_WAIT_NOTICE_DELAY_MS, QUEUE_WAIT_NOTICE_REPEAT_MS, backgroundLaneCap, runInQueue, } from '@bendyline/gezel/runtime';
 /**
  * Ambient quiet window for local engine queues. Override with
  * `GEZEL_AMBIENT_QUIET_MS` (milliseconds; `0` disables ambient gating
@@ -21,3 +21,18 @@ export function defaultAmbientQuietMs() {
     }
     return DEFAULT_AMBIENT_QUIET_MS;
 }
+/**
+ * How long a local turn holds its queue slot before it hands the slot to
+ * another conversation that is waiting. Override with
+ * `GEZEL_QUEUE_YIELD_QUANTUM_MS` (milliseconds; `0` keeps a slot for the
+ * whole turn).
+ */
+export function defaultQueueYieldQuantumMs() {
+    const raw = process.env.GEZEL_QUEUE_YIELD_QUANTUM_MS;
+    if (raw !== undefined) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return DEFAULT_LOCAL_YIELD_QUANTUM_MS;
+}

package/dist/providers/retirement-gate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tracks long-running provider operations while a machine-engine adoption is
+ * retiring the user daemon's local provider. The gate closes before draining:
+ * callers that already hold a provider reference cannot start a second local
+ * operation after the broker has become authoritative.
+ */
+export declare class ProviderRetirementGate {
+    private retiring;
+    private retirementMessage;
+    private active;
+    private readonly idleWaiters;
+    beginRetirement(message?: string): void;
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    waitForIdle(): Promise<void>;
+}
+/**
+ * Wrap only the operations which can own a native engine. Management calls
+ * remain direct, and shutdown is deliberately not counted as user work.
+ */
+export declare function trackProviderOperations<T extends object>(provider: T, gate: ProviderRetirementGate, operationNames: ReadonlySet<PropertyKey>): T;

package/dist/providers/retirement-gate.js

@@ -0,0 +1,55 @@
+/**
+ * Tracks long-running provider operations while a machine-engine adoption is
+ * retiring the user daemon's local provider. The gate closes before draining:
+ * callers that already hold a provider reference cannot start a second local
+ * operation after the broker has become authoritative.
+ */
+export class ProviderRetirementGate {
+    retiring = false;
+    retirementMessage = 'local provider retired after machine engine adoption';
+    active = 0;
+    idleWaiters = new Set();
+    beginRetirement(message) {
+        this.retiring = true;
+        if (message)
+            this.retirementMessage = message;
+    }
+    async run(operation) {
+        if (this.retiring) {
+            throw new Error(this.retirementMessage);
+        }
+        this.active += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            this.active -= 1;
+            if (this.active === 0) {
+                for (const resolve of this.idleWaiters)
+                    resolve();
+                this.idleWaiters.clear();
+            }
+        }
+    }
+    async waitForIdle() {
+        if (this.active === 0)
+            return;
+        await new Promise((resolve) => this.idleWaiters.add(resolve));
+    }
+}
+/**
+ * Wrap only the operations which can own a native engine. Management calls
+ * remain direct, and shutdown is deliberately not counted as user work.
+ */
+export function trackProviderOperations(provider, gate, operationNames) {
+    return new Proxy(provider, {
+        get(target, property) {
+            const value = Reflect.get(target, property, target);
+            if (typeof value !== 'function')
+                return value;
+            if (!operationNames.has(property))
+                return value.bind(target);
+            return (...args) => gate.run(() => Promise.resolve(Reflect.apply(value, target, args)));
+        },
+    });
+}

package/dist/providers/session-hooks.d.ts

@@ -22,5 +22,8 @@ export interface ToolGroundingHooks {
         kind: 'allow';
         args: Record<string, unknown>;
     } | null;
-    labelEvidence(toolName: string, args: Record<string, unknown>, text: string): string | null;
+    /** `source.thirdParty` is true for a tool served by any server but gezel's own. */
+    labelEvidence(toolName: string, args: Record<string, unknown>, text: string, source?: {
+        thirdParty: boolean;
+    }): string | null;
 }

package/dist/system/memory.js

@@ -541,6 +541,12 @@ export function parseNvidiaMemoryProbe(stdout, systemRamBytes = totalmem()) {
         deviceNames: devices.map((device) => device.name),
     };
 }
+/**
+ * RTX Spark (N1X) is GB10-class silicon but deliberately not in this list.
+ * Windows splits its memory at boot into a fixed GPU share and the OS's RAM
+ * (32 + 32 GB on a 64 GB machine, changed only by a reboot), so nvidia-smi's
+ * figure is a pool of its own and the card is budgeted as discrete.
+ */
 function isKnownUnifiedNvidiaDevice(name) {
     const normalized = name.toLowerCase();
     return /\bgb10\b/.test(normalized) || normalized.includes('dgx spark');

package/dist/utils/image-meta.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Image dimensions from the file header alone, with no image library: PNG,
+ * GIF, JPEG and WebP. The service's photo index and the image engines both
+ * read through this one parser, so a rendered image's reported size is the
+ * size its own header states.
+ */
+export interface ImageMeta {
+    format: 'png' | 'jpeg' | 'gif' | 'webp';
+    width: number;
+    height: number;
+}
+export declare function readImageMeta(buf: Buffer): ImageMeta | null;

package/dist/utils/image-meta.js

@@ -0,0 +1,77 @@
+/**
+ * Image dimensions from the file header alone, with no image library: PNG,
+ * GIF, JPEG and WebP. The service's photo index and the image engines both
+ * read through this one parser, so a rendered image's reported size is the
+ * size its own header states.
+ */
+export function readImageMeta(buf) {
+    if (buf.length < 24)
+        return null;
+    // PNG: 8-byte signature, then IHDR (width @16, height @20, big-endian).
+    if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+        return { format: 'png', width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    // GIF: "GIF87a"/"GIF89a", width/height little-endian @6/@8.
+    if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46) {
+        return { format: 'gif', width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+    }
+    // JPEG: scan segments for a Start-Of-Frame marker (0xFFC0–C3, C5–C7, C9–CB).
+    if (buf[0] === 0xff && buf[1] === 0xd8) {
+        let off = 2;
+        while (off + 9 < buf.length) {
+            if (buf[off] !== 0xff) {
+                off++;
+                continue;
+            }
+            const marker = buf[off + 1];
+            const isSof = (marker >= 0xc0 && marker <= 0xc3) ||
+                (marker >= 0xc5 && marker <= 0xc7) ||
+                (marker >= 0xc9 && marker <= 0xcb);
+            if (isSof) {
+                const height = buf.readUInt16BE(off + 5);
+                const width = buf.readUInt16BE(off + 7);
+                return { format: 'jpeg', width, height };
+            }
+            // Skip this segment using its length field.
+            const len = buf.readUInt16BE(off + 2);
+            if (len < 2)
+                break;
+            off += 2 + len;
+        }
+        return null;
+    }
+    // WebP: "RIFF"...."WEBP" then a VP8 / VP8L / VP8X chunk.
+    if (buf[0] === 0x52 &&
+        buf[1] === 0x49 &&
+        buf[2] === 0x46 &&
+        buf[3] === 0x46 &&
+        buf[8] === 0x57 &&
+        buf[9] === 0x45 &&
+        buf[10] === 0x42 &&
+        buf[11] === 0x50) {
+        const fourcc = buf.toString('ascii', 12, 16);
+        if (fourcc === 'VP8 ' && buf.length >= 30) {
+            // Lossy: dimensions are 14-bit at offset 26/28 (mask off the top bits).
+            const width = buf.readUInt16LE(26) & 0x3fff;
+            const height = buf.readUInt16LE(28) & 0x3fff;
+            return { format: 'webp', width, height };
+        }
+        if (fourcc === 'VP8L' && buf.length >= 25) {
+            // Lossless: 1 signature byte then 14+14 bits packed.
+            const b0 = buf[21];
+            const b1 = buf[22];
+            const b2 = buf[23];
+            const b3 = buf[24];
+            const width = 1 + (((b1 & 0x3f) << 8) | b0);
+            const height = 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6));
+            return { format: 'webp', width, height };
+        }
+        if (fourcc === 'VP8X' && buf.length >= 30) {
+            // Extended: 24-bit (value+1) at 24/27.
+            const width = 1 + (buf[24] | (buf[25] << 8) | (buf[26] << 16));
+            const height = 1 + (buf[27] | (buf[28] << 8) | (buf[29] << 16));
+            return { format: 'webp', width, height };
+        }
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/gezel-inference",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Gezel's on-device inference runtime: native engines, local model management, embeddings, knowledge search, and OpenAI-compatible routes.",
   "license": "MIT",
   "keywords": [
@@ -73,10 +73,10 @@
     "!dist/**/__pycache__"
   ],
   "dependencies": {
-    "@bendyline/gezel": "1.2.7",
-    "@bendyline/gezel-catalog": "1.2.7",
-    "@bendyline/gezel-client": "1.2.7",
-    "@bendyline/gezel-knowledge": "1.2.7",
+    "@bendyline/gezel": "1.2.9",
+    "@bendyline/gezel-catalog": "1.2.9",
+    "@bendyline/gezel-client": "1.2.9",
+    "@bendyline/gezel-knowledge": "1.2.9",
     "hono": "4.13.9",
     "tar": "7.5.21",
     "undici": "8.11.2",
@@ -105,6 +105,6 @@
     "dev": "node scripts/stage-assets.mjs && tsc -p tsconfig.build.json --watch --preserveWatchOutput",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "clean": "rm -rf dist"
+    "clean": "node scripts/clean.mjs"
   }
 }