@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/utils/xet.js

@@ -0,0 +1,201 @@
+/**
+ * Pure decoders for HuggingFace's Xet content-addressed storage format.
+ *
+ * HF migrated model hosting to Xet (content-defined chunking + dedup). A
+ * `/resolve/<rev>/<file>` request for a Xet-backed file no longer 302s to a
+ * plain CDN blob — it redirects into a CAS bridge that a naive "follow the
+ * redirect and GET" client can't read (it 403s). The supported path is the
+ * reconstruction protocol:
+ *
+ *   1. resolve (redirect: manual) → the 302 carries `X-Xet-Hash` + a `link`
+ *      header with rel="xet-auth" (token mint) and rel="xet-reconstruction-info".
+ *   2. GET the xet-auth endpoint → { casUrl, accessToken, exp } (anonymous
+ *      works for public repos).
+ *   3. GET `${casUrl}/v1/reconstructions/${xetHash}` (Bearer token) → an
+ *      ordered `terms[]` (each = a xorb hash + a chunk-index range) plus
+ *      `fetch_info` (per-xorb presigned `transfer.xethub.hf.co` URLs with the
+ *      byte range to fetch for a given chunk range).
+ *   4. For each term, fetch its xorb byte range, walk the chunks, decompress,
+ *      and concatenate in term order (dropping `offset_into_first_range` bytes
+ *      at the very start). sha256 of the result matches the manifest pin.
+ *
+ * This file is the PURE half: no network, no fs. It parses chunk headers and
+ * decompresses the three schemes Xet emits. The I/O driver lives in
+ * `xet-download.ts`. Every decoder here was validated against real e2b files
+ * (tokenizer.json = 100% LZ4, model.safetensors = None+LZ4+bg4) by full-file
+ * sha256 before this shipped — do not "simplify" the LZ4 frame handling
+ * without re-checking against a bg4 file.
+ *
+ * Chunk header (8 bytes, little-endian):
+ *   [version:u8][compressedLen:u24][scheme:u8][uncompressedLen:u24]
+ * Compression schemes:
+ *   0 None · 1 LZ4 (frame) · 2 ByteGroupingLZ4 (bg4: 4 byte-planes, LZ4 frame)
+ *
+ * NB: scheme 1/2 payloads are LZ4 *frame* format (magic 0x184D2204), NOT raw
+ * blocks — the block decoder runs once per frame block.
+ */
+export const XET_CHUNK_HEADER_BYTES = 8;
+const LZ4_FRAME_MAGIC = 0x184d2204;
+const SCHEME_NONE = 0;
+const SCHEME_LZ4 = 1;
+const SCHEME_BG4 = 2;
+/**
+ * Decompress one raw LZ4 block (input-terminated) into `dst` at `dStart`.
+ * Returns the number of bytes written. The block length is known exactly from
+ * the enclosing frame, so there is no trailing padding and input exhaustion is
+ * the correct terminator.
+ */
+function lz4BlockInto(src, dst, dStart) {
+    let s = 0;
+    let d = dStart;
+    while (s < src.length) {
+        const token = src[s++];
+        let litLen = token >> 4;
+        if (litLen === 15) {
+            let b;
+            do {
+                b = src[s++];
+                litLen += b;
+            } while (b === 255);
+        }
+        src.copy(dst, d, s, s + litLen);
+        s += litLen;
+        d += litLen;
+        if (s >= src.length)
+            break; // final sequence: literals only
+        const offset = src[s] | (src[s + 1] << 8);
+        s += 2;
+        let matchLen = token & 0x0f;
+        if (matchLen === 15) {
+            let b;
+            do {
+                b = src[s++];
+                matchLen += b;
+            } while (b === 255);
+        }
+        matchLen += 4; // MINMATCH
+        let m = d - offset;
+        for (let i = 0; i < matchLen; i++)
+            dst[d++] = dst[m++];
+    }
+    return d - dStart;
+}
+/** Decompress an LZ4 frame to exactly `destSize` bytes. */
+export function lz4DecompressFrame(src, destSize) {
+    let s = 0;
+    if (src.length < 7 || src.readUInt32LE(0) !== LZ4_FRAME_MAGIC) {
+        throw new Error('xet: payload is not an LZ4 frame');
+    }
+    s += 4;
+    const flg = src[s++];
+    s++; // BD (block-max-size descriptor) — unused; output is sized by destSize
+    const contentSizePresent = (flg >> 3) & 1;
+    const dictIdPresent = flg & 1;
+    const blockChecksum = (flg >> 4) & 1;
+    const contentChecksum = (flg >> 2) & 1;
+    if (contentSizePresent)
+        s += 8;
+    if (dictIdPresent)
+        s += 4;
+    s += 1; // HC header checksum
+    const dst = Buffer.allocUnsafe(destSize);
+    let d = 0;
+    while (s + 4 <= src.length) {
+        const blockSize = src.readUInt32LE(s);
+        s += 4;
+        if (blockSize === 0)
+            break; // end mark
+        const uncompressed = (blockSize & 0x80000000) !== 0;
+        const size = blockSize & 0x7fffffff;
+        const block = src.subarray(s, s + size);
+        s += size;
+        if (uncompressed) {
+            block.copy(dst, d);
+            d += size;
+        }
+        else {
+            d += lz4BlockInto(block, dst, d);
+        }
+        if (blockChecksum)
+            s += 4;
+    }
+    if (contentChecksum)
+        s += 4;
+    if (d !== destSize) {
+        throw new Error(`xet: LZ4 frame produced ${d} bytes, expected ${destSize}`);
+    }
+    return dst;
+}
+/**
+ * Undo bg4 byte-plane regrouping. The original data was split into 4 planes by
+ * index % 4 (plane sizes floor((len - k + 3) / 4)), the planes concatenated,
+ * then LZ4-compressed. We're given the already-decompressed regrouped buffer.
+ */
+export function bg4Unregroup(regrouped, len) {
+    const out = Buffer.allocUnsafe(len);
+    const s0 = Math.floor((len + 3) / 4);
+    const s1 = Math.floor((len + 2) / 4);
+    const s2 = Math.floor((len + 1) / 4);
+    let c0 = 0;
+    let c1 = s0;
+    let c2 = s0 + s1;
+    let c3 = s0 + s1 + s2;
+    for (let i = 0; i < len; i++) {
+        const plane = i & 3;
+        const src = plane === 0 ? c0++ : plane === 1 ? c1++ : plane === 2 ? c2++ : c3++;
+        out[i] = regrouped[src];
+    }
+    return out;
+}
+/** Decode a single chunk at `buf[off]`. */
+export function decodeChunk(buf, off) {
+    const version = buf[off];
+    if (version !== 0)
+        throw new Error(`xet: unsupported chunk version ${version}`);
+    const compLen = buf[off + 1] | (buf[off + 2] << 8) | (buf[off + 3] << 16);
+    const scheme = buf[off + 4];
+    const uncompLen = buf[off + 5] | (buf[off + 6] << 8) | (buf[off + 7] << 16);
+    const payload = buf.subarray(off + XET_CHUNK_HEADER_BYTES, off + XET_CHUNK_HEADER_BYTES + compLen);
+    let data;
+    if (scheme === SCHEME_NONE) {
+        data = Buffer.from(payload);
+    }
+    else if (scheme === SCHEME_LZ4) {
+        data = lz4DecompressFrame(payload, uncompLen);
+    }
+    else if (scheme === SCHEME_BG4) {
+        data = bg4Unregroup(lz4DecompressFrame(payload, uncompLen), uncompLen);
+    }
+    else {
+        throw new Error(`xet: unknown compression scheme ${scheme}`);
+    }
+    return { data, next: off + XET_CHUNK_HEADER_BYTES + compLen };
+}
+/**
+ * Decode every chunk in a fetched xorb byte segment → one decoded buffer per
+ * chunk, in order. `expectedChunks` (segment chunk-range width) guards against
+ * a short/over-read.
+ */
+export function decodeSegmentChunks(buf, expectedChunks) {
+    const chunks = [];
+    let off = 0;
+    while (off + XET_CHUNK_HEADER_BYTES <= buf.length && chunks.length < expectedChunks) {
+        const { data, next } = decodeChunk(buf, off);
+        chunks.push(data);
+        off = next;
+    }
+    if (chunks.length !== expectedChunks) {
+        throw new Error(`xet: segment decoded ${chunks.length} chunks, expected ${expectedChunks}`);
+    }
+    return chunks;
+}
+/** Parse the `link` header from a resolve 302 into a rel → url map. */
+export function parseLinkHeader(header) {
+    if (!header)
+        return {};
+    const out = {};
+    for (const m of header.matchAll(/<([^>]+)>;\s*rel="([^"]+)"/g)) {
+        out[m[2]] = m[1];
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,106 @@
 {
   "name": "@bendyline/gezel-inference",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Shared on-device inference, model management and knowledge runtime for Gezel hosts.",
+  "license": "MIT",
+  "keywords": [
+    "gezel",
+    "ai",
+    "agents",
+    "local-first",
+    "daemon",
+    "server",
+    "llm"
+  ],
+  "homepage": "https://github.com/bendyline/gezel",
+  "bugs": {
+    "url": "https://github.com/bendyline/gezel/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bendyline/gezel.git",
+    "directory": "packages/inference"
+  },
+  "author": {
+    "name": "Bendyline",
+    "email": "support@bendyline.com"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./native-release": {
+      "types": "./dist/native-release-entry.d.ts",
+      "import": "./dist/native-release-entry.js"
+    },
+    "./speech": {
+      "types": "./dist/speech.d.ts",
+      "import": "./dist/speech.js"
+    },
+    "./internal/*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    },
+    "./package.json": "./package.json",
+    "./packaging": {
+      "types": "./scripts/embedding-packaging.d.cts",
+      "default": "./scripts/embedding-packaging.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts/embedding-packaging.cjs",
+    "scripts/embedding-packaging.d.cts",
+    "!dist/**/*.map",
+    "!dist/**/*_test.py",
+    "!dist/**/*_modeltest.py",
+    "!dist/**/__pycache__"
+  ],
+  "dependencies": {
+    "hono": "4.13.9",
+    "tar": "7.5.21",
+    "undici": "8.11.2",
+    "yauzl": "^3.4.0",
+    "yazl": "^3.3.1",
+    "zod": "^4.4.3",
+    "@bendyline/gezel-client": "1.2.4",
+    "@bendyline/gezel-catalog": "1.2.4",
+    "@bendyline/gezel": "1.2.4",
+    "@bendyline/gezel-knowledge": "1.2.4"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/yauzl": "^3.4.0",
+    "@types/yazl": "^3.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@huggingface/transformers": "^4.3.1"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json && node scripts/stage-assets.mjs",
+    "dev": "node scripts/stage-assets.mjs && tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
 }

package/scripts/embedding-packaging.cjs

@@ -0,0 +1,264 @@
+/**
+ * electron-builder beforePack hook. The installed service, never "latest",
+ * supplies the native release and archive SHA-256 pins. Downloads happen only
+ * on the build machine; runtime checks the service's per-file pins as well.
+ */
+const { createHash } = require('node:crypto');
+const { createReadStream, createWriteStream } = require('node:fs');
+const {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rename,
+  rm,
+  stat,
+  symlink,
+  writeFile,
+} = require('node:fs/promises');
+const { createRequire } = require('node:module');
+const path = require('node:path');
+const { Readable, Transform } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+
+const MAX_ARCHIVE_BYTES = 2 * 1024 ** 3;
+const MAX_EXTRACTED_BYTES = 8 * 1024 ** 3;
+const MAX_ENTRIES = 10000;
+
+function selectArchives(pins, platform, arch) {
+  if (!/^\d+\.\d+\.\d+$/.test(pins.NATIVE_ENGINE_RELEASE)) {
+    throw new Error('Gezel must pin an exact native release.');
+  }
+  const prefix = `gezel-native-${pins.NATIVE_ENGINE_RELEASE}-${platform}-${arch}`;
+  const extension = platform === 'win32' ? '.zip' : '.tar.gz';
+  return Object.entries(pins.NATIVE_ENGINE_ARCHIVE_SHA256)
+    .filter(
+      ([name]) =>
+        name === `${prefix}${extension}` ||
+        (name.startsWith(`${prefix}-`) && name.endsWith(extension)),
+    )
+    .map(([name, sha256]) => {
+      if (!/^[a-z\d.-]+$/.test(name) || !/^[a-f\d]{64}$/i.test(sha256) || /^0{64}$/.test(sha256)) {
+        throw new Error(`Invalid Gezel native archive pin: ${name}`);
+      }
+      return {
+        name,
+        sha256: sha256.toLowerCase(),
+        platformKey: name.slice(
+          `gezel-native-${pins.NATIVE_ENGINE_RELEASE}-`.length,
+          -extension.length,
+        ),
+      };
+    });
+}
+
+async function hashFile(file) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function verifiedArchive(file, pin, fetchImpl) {
+  try {
+    if ((await stat(file)).size <= MAX_ARCHIVE_BYTES && (await hashFile(file)) === pin.sha256)
+      return;
+    throw new Error(`Cached Gezel archive failed SHA-256 verification: ${pin.name}`);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const temporary = `${file}.partial`;
+  const { createAwakeTimeout, acquireSuspendMonitor } = await import('@bendyline/gezel');
+  const releaseMonitor = acquireSuspendMonitor();
+  const timeout = createAwakeTimeout(10 * 60 * 1000);
+  try {
+    const version = pin.name.match(/^gezel-native-(\d+\.\d+\.\d+)-/)[1];
+    const response = await fetchImpl(
+      `https://github.com/bendyline/gezel/releases/download/native-v${version}/${pin.name}`,
+      { signal: timeout.signal },
+    );
+    if (!response.ok || !response.body)
+      throw new Error(`Could not download ${pin.name}: HTTP ${response.status}`);
+    let bytes = 0;
+    const hash = createHash('sha256');
+    const guard = new Transform({
+      transform(chunk, _encoding, callback) {
+        bytes += chunk.length;
+        if (bytes > MAX_ARCHIVE_BYTES)
+          return callback(new Error(`Gezel archive too large: ${pin.name}`));
+        hash.update(chunk);
+        callback(null, chunk);
+      },
+    });
+    await pipeline(
+      Readable.fromWeb(response.body),
+      guard,
+      createWriteStream(temporary, { flags: 'wx' }),
+    );
+    if (hash.digest('hex') !== pin.sha256)
+      throw new Error(`Gezel archive SHA-256 mismatch: ${pin.name}`);
+    await rename(temporary, file);
+  } finally {
+    timeout.dispose();
+    releaseMonitor();
+    await rm(temporary, { force: true });
+  }
+}
+
+function checkEntry(name, size, budget) {
+  const parts = name.replace(/^\.\//, '').replace(/\/$/, '').split('/');
+  if (
+    name !== './' &&
+    name !== '.' &&
+    parts.some((part) => !part || part === '..' || part === '.' || unsafeSegment(part))
+  ) {
+    throw new Error(`Unsafe Gezel archive path: ${name}`);
+  }
+  budget.entries += 1;
+  budget.bytes += size;
+  if (
+    !Number.isSafeInteger(size) ||
+    size < 0 ||
+    budget.entries > MAX_ENTRIES ||
+    budget.bytes > MAX_EXTRACTED_BYTES
+  ) {
+    throw new Error('Gezel archive exceeds extraction limits.');
+  }
+}
+
+function unsafeSegment(value) {
+  return /[\\:]/.test(value) || [...value].some((character) => character.charCodeAt(0) < 32);
+}
+
+async function extractArchive(file, target, serviceRequire) {
+  await mkdir(target, { recursive: true });
+  const budget = { entries: 0, bytes: 0 };
+  if (file.endsWith('.zip')) {
+    const AdmZip = serviceRequire('adm-zip');
+    const zip = new AdmZip(file);
+    for (const entry of zip.getEntries()) {
+      checkEntry(entry.entryName, entry.header.size, budget);
+      if (((entry.header.attr >>> 16) & 0o170000) === 0o120000) {
+        throw new Error('Symlinks are not supported in Windows Gezel archives.');
+      }
+    }
+    zip.extractAllTo(target, false);
+  } else {
+    const tar = serviceRequire('tar');
+    const links = new Map();
+    const files = new Set();
+    // Inspect the complete verified archive before writing any of its entries.
+    await tar.t({
+      file,
+      strict: true,
+      onReadEntry(entry) {
+        checkEntry(entry.path, entry.size, budget);
+        if (!['File', 'Directory', 'SymbolicLink'].includes(entry.type)) {
+          throw new Error(`Unsupported Gezel archive entry: ${entry.type}`);
+        }
+        if (
+          entry.type === 'SymbolicLink' &&
+          (!entry.linkpath ||
+            entry.linkpath.split('/').some((part) => !part || part === '..' || unsafeSegment(part)))
+        ) {
+          throw new Error(`Unsafe Gezel archive symlink: ${entry.path}`);
+        }
+        const name = entry.path.replace(/^\.\//, '');
+        if (entry.type === 'File') files.add(name);
+        if (entry.type === 'SymbolicLink') links.set(name, entry.linkpath);
+      },
+    });
+    // Extract regular files first so no archive entry can be written through
+    // a previously created link. Then restore the release's SONAME chains.
+    await tar.x({
+      file,
+      cwd: target,
+      strict: true,
+      preservePaths: false,
+      filter: (_name, entry) => entry.type !== 'SymbolicLink',
+    });
+    for (const [name, linkTarget] of links) {
+      let resolved = name;
+      const seen = new Set();
+      while (links.has(resolved)) {
+        if (seen.has(resolved)) throw new Error(`Cyclic Gezel archive symlink: ${name}`);
+        seen.add(resolved);
+        resolved = path.posix.join(path.posix.dirname(resolved), links.get(resolved));
+      }
+      if (!files.has(resolved))
+        throw new Error(`Gezel archive symlink has no regular target: ${name}`);
+      await symlink(linkTarget, path.join(target, name), 'file');
+    }
+  }
+}
+
+async function stageNative({
+  pins,
+  platform,
+  arch,
+  destination,
+  cache,
+  serviceRequire,
+  fetchImpl = fetch,
+  allowUnavailable = false,
+}) {
+  const archives = selectArchives(pins, platform, arch);
+  if (!archives.length && !allowUnavailable) {
+    throw new Error(`The pinned Gezel release has no native archives for ${platform}/${arch}.`);
+  }
+  await mkdir(path.dirname(destination), { recursive: true });
+  await mkdir(cache, { recursive: true });
+  const staging = await mkdtemp(path.join(path.dirname(destination), '.gezel-staging-'));
+  try {
+    for (const pin of archives) {
+      process.stdout.write(
+        `Staging Gezel ${pin.platformKey} (native-v${pins.NATIVE_ENGINE_RELEASE})\n`,
+      );
+      const file = path.join(cache, pin.name);
+      await verifiedArchive(file, pin, fetchImpl);
+      await extractArchive(file, path.join(staging, pin.platformKey), serviceRequire);
+    }
+    if (platform === 'darwin' && archives.length && !pins.NATIVE_ENGINE_MACOS_NOTARIZED) {
+      throw new Error('The pinned Gezel macOS native release must be notarized.');
+    }
+    await writeFile(
+      path.join(staging, 'release.json'),
+      `${JSON.stringify(
+        {
+          release: pins.NATIVE_ENGINE_RELEASE,
+          platform,
+          arch,
+          archives: archives.map(({ name, sha256 }) => ({ name, sha256 })),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    // Keep the prior payload recoverable if promotion fails.
+    const previous = `${staging}.previous`;
+    let moved = false;
+    try {
+      await rename(destination, previous);
+      moved = true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    try {
+      await rename(staging, destination);
+    } catch (error) {
+      if (moved) await rename(previous, destination);
+      throw error;
+    }
+    if (moved) await rm(previous, { recursive: true, force: true });
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+  return archives;
+}
+
+/** Stage the installed service's exact native release; no app-relative module resolution. */
+exports.stageElectronNative = async function stageElectronNative(options) {
+  const pins = await import('../dist/native-release-entry.js');
+  return stageNative({ ...options, pins, serviceRequire: createRequire(__filename) });
+};
+exports.selectArchives = selectArchives;
+exports.stageNative = stageNative;
+exports.checkEntry = checkEntry;

package/scripts/embedding-packaging.d.cts

@@ -0,0 +1,16 @@
+export interface ElectronNativeStageOptions {
+  platform: NodeJS.Platform;
+  arch: string;
+  destination: string;
+  cache: string;
+  fetchImpl?: typeof fetch;
+  allowUnavailable?: boolean;
+}
+export interface NativeArchivePin {
+  name: string;
+  sha256: string;
+  platformKey: string;
+}
+export function stageElectronNative(
+  options: ElectronNativeStageOptions,
+): Promise<NativeArchivePin[]>;