@bendyline/gezel-service 1.1.1 → 1.1.2

package/dist/handboek-content/technical/building-connected-apps-with-gezel-app-sdk.md

@@ -19,6 +19,8 @@ If the experience should live inside a Gezel project as a custom crew, dashboard
 
 The [Connected apps](../conceptual/connected-apps.md) article explains what the user sees. This article covers the developer side.
 
+This article teaches the SDK. For what is promised rather than how to use it — which exports are stable, what cancellation guarantees, and what a store build must do differently — see the [App SDK surface](../../app-sdk-surface.md) contract.
+
 ## Install and connect
 
 The Node entry requires Node.js 24 or newer:
@@ -139,6 +141,82 @@ This pairing is the supported route for a rich integration: the app SDK owns dis
 
 Ordinary third-party apps should ask the user to start Gezel when discovery reports `daemon_not_running`. The optional start-if-missing path is only for native integrations that deliberately bundle the matching `gezeld` package.
 
+## Host Gezel inside your app
+
+The flow above needs a Gezel the person already runs. An application that must
+work either way can host one itself: `@bendyline/gezel-app-sdk/host` connects to
+their Gezel when it is running, and otherwise starts a daemon inside your own
+process. Application code is the same afterwards.
+
+```ts
+import { connectOrHost } from '@bendyline/gezel-app-sdk/host';
+
+const gezel = await connectOrHost({
+  appId: 'acme.travel',
+  appName: 'Acme Travel',
+  host: { nodePath: bundledNodePath },
+});
+
+await gezel.ensureModel({ model: 'gemma4-e2b-q4' });
+const project = await gezel.ensureProject({ package: shippedGezapp, folder: travelFolder });
+const chat = await project.openChat({ role: 'travel-guide' });
+```
+
+`Gezel` is the central object — the connection, the models, the projects. Most
+work happens in the `GezelProject` it hands back, because chats and tools are
+both project-scoped, and an application that has the project never has to pass
+its id back in. `gezel.openProject(id)` reaches a project that already exists.
+
+A hosted daemon keeps its state under `~/.gezel/apps/<appId>/`, so the projects
+and gezels an application creates for itself never appear in the person's own
+workshop, and the two daemons never contend for one runtime directory. Models
+the person already installed are read from their home rather than downloaded
+again.
+
+Both `ensureModel` and `ensureProject` are idempotent and meant to run on every
+launch. `ensureModel` uses an installed model first, then a `.gezmodel` bundle
+the application ships, and only then the network — so a first run can work
+offline. `ensureProject` keeps the person's edits to seeded files and reuses the
+crew already on the roster.
+
+Hosting requires `@bendyline/gezel-service` beside the SDK; it is an optional
+peer dependency, so applications that only connect never download it. Under
+Electron, pass a real Node binary as `host.nodePath`: Gezel runs its tool server
+as a child process, and an Electron binary cannot stand in for Node.
+
+## Tools your application runs
+
+An application can offer its own tools to the gezels in its project. The model
+sees them beside Gezel's built-in tools; when one is called, the handler runs in
+the application's process and what it returns becomes the tool's output.
+
+```ts
+await project.registerTools({
+  tools: [
+    {
+      name: 'add_travel_points',
+      description: 'Award travel points to the traveller.',
+      inputSchema: {
+        type: 'object',
+        properties: { points: { type: 'number' } },
+        required: ['points'],
+      },
+      handler: async ({ points }) => awardPoints(Number(points)),
+    },
+  ],
+});
+```
+
+The registration lives as long as the connection that made it. A brief
+disconnection is held open for a grace window and reconnects on its own; a
+closed application's tools are withdrawn, because a tool whose handler is gone
+would accept a call and never answer it. Arguments are checked against the
+declared schema before they leave the daemon, a handler that throws is reported
+to the model as an ordinary tool failure, and each call has a timeout the
+application sets. Tool calls appear in the transcript and the history log like
+any other tool. This needs the `product` scope, or a daemon the application
+hosts.
+
 ## TLS, browsers, and errors
 
 The local daemon uses a per-launch self-signed certificate. The Node SDK reads the public certificate from Gezel's runtime directory and constructs a pinned `fetch`, so you should not disable TLS verification globally or replace the transport with an unpinned client.

package/dist/handboek-content/whats-new/{1.26250.md → 1.26251.md}

@@ -1,14 +1,14 @@
 ---
-id: whats-new/1.26250
-title: 1.26250 — 7 September 2026
-order: -26250
+id: whats-new/1.26251
+title: 1.26251 — 8 September 2026
+order: -26251
 summary: Engines that reserve memory instead of colliding, llama.cpp v0.4 loading controls, GLM 5.3 on DwarfStar, and catalogs built from a folder of Markdown.
 ogHeadline: Engines stop fighting over memory
 ---
 
-# 1.26250 — 7 September 2026
+# 1.26251 — 8 September 2026
 
-Three days after **1.26247**, and this one lives mostly under the floor. The visible half is a set of new controls over how a local model loads; the invisible half is the reason those controls are now safe to use.
+Four days after **1.26247**, and this one lives mostly under the floor. The visible half is a set of new controls over how a local model loads; the invisible half is the reason those controls are now safe to use.
 
 If you read only one thing: when two things on your machine both want the memory, they now take turns instead of colliding.
 

package/dist/index-store/static-index-worker.js

@@ -4,7 +4,7 @@
 import { parentPort } from "worker_threads";
 
 // src/index-store/content-indexer.ts
-import { readFile as readFile3, readdir as readdir2, rm as rm4, stat as stat3 } from "fs/promises";
+import { readFile as readFile3, readdir as readdir2, rm as rm5, stat as stat4 } from "fs/promises";
 import { extname as extname3, join as join10 } from "path";
 import { createLogger as createLogger6, nowIso as nowIso2 } from "@bendyline/gezel";
 import { PROJECT_SHADOW_DIR_NAME as PROJECT_SHADOW_DIR_NAME2, projectLocalIndexDbFile } from "@bendyline/gezel/paths";
@@ -343,7 +343,7 @@ async function runGit(args, opts = {}) {
     "credential.interactive=false",
     ...cleanedArgs
   ];
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const hasStdinPayload = opts.stdin !== void 0;
     const child = hasStdinPayload ? spawn("git", gitArgs, {
       cwd: opts.cwd,
@@ -398,11 +398,11 @@ async function runGit(args, opts = {}) {
         return;
       }
       if (code === 0) {
-        resolve3({ stdout, stderr });
+        resolve4({ stdout, stderr });
         return;
       }
       if (code !== null && opts.acceptExitCodes?.includes(code)) {
-        resolve3({ stdout, stderr, code });
+        resolve4({ stdout, stderr, code });
         return;
       }
       reject(
@@ -1205,7 +1205,7 @@ async function resolveNodePermissionFlag(nodeBin) {
   }
 }
 async function readNodeHelp(nodeBin) {
-  return await new Promise((resolve3, reject) => {
+  return await new Promise((resolve4, reject) => {
     const child = spawn2(nodeBin, ["--help"], {
       stdio: ["ignore", "pipe", "pipe"],
       env: sandboxEnv(process.env),
@@ -1223,13 +1223,13 @@ async function readNodeHelp(nodeBin) {
     });
     child.once("error", reject);
     child.once("close", (code) => {
-      if (code === 0) resolve3(stdout);
+      if (code === 0) resolve4(stdout);
       else reject(new Error(`failed to inspect Node permission support (${code}): ${stderr}`));
     });
   });
 }
 async function runSandboxChild(command, args, opts) {
-  return await new Promise((resolve3) => {
+  return await new Promise((resolve4) => {
     const child = spawn2(command, args, {
       cwd: opts.cwd,
       stdio: opts.rpcChannel ? ["pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
@@ -1307,7 +1307,7 @@ async function runSandboxChild(command, args, opts) {
       if (timer) clearTimeout(timer);
       const signalSuffix = code === null && signal ? `[process closed by signal ${signal}]
 ` : "";
-      resolve3({
+      resolve4({
         exitCode: code ?? -1,
         signal,
         stdout,
@@ -1438,12 +1438,12 @@ async function wrapForPlatform(command, args, ctx) {
 }
 var macSandboxProbe;
 function canApplyMacSandbox() {
-  macSandboxProbe ??= new Promise((resolve3) => {
+  macSandboxProbe ??= new Promise((resolve4) => {
     let settled = false;
     const finish = (ok) => {
       if (settled) return;
       settled = true;
-      resolve3(ok);
+      resolve4(ok);
     };
     const child = spawn2("sandbox-exec", ["-p", "(version 1)\n(allow default)", "/usr/bin/true"], {
       stdio: ["ignore", "ignore", "ignore"],
@@ -1465,12 +1465,12 @@ function canApplyMacSandbox() {
 var linuxSystemdSandboxProbe;
 function canApplyLinuxSystemdSandbox() {
   if (process.platform !== "linux") return Promise.resolve(false);
-  linuxSystemdSandboxProbe ??= new Promise((resolve3) => {
+  linuxSystemdSandboxProbe ??= new Promise((resolve4) => {
     let settled = false;
     const finish = (ok) => {
       if (settled) return;
       settled = true;
-      resolve3(ok);
+      resolve4(ok);
     };
     const probe = "const net=require('node:net');const s=net.connect({host:'127.0.0.1',port:9});s.once('connect',()=>process.exit(9));s.once('error',e=>process.exit(['EAFNOSUPPORT','EPERM','EACCES'].includes(e.code)?0:2));setTimeout(()=>process.exit(3),1000);";
     const child = spawn2(
@@ -2193,7 +2193,7 @@ import {
 } from "@bendyline/gezel";
 
 // src/memory/embed-core.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { createLogger as createLogger3 } from "@bendyline/gezel";
 import {
   EmbedderUnavailableError,
@@ -2204,10 +2204,13 @@ import {
 } from "@bendyline/gezel-knowledge";
 
 // src/transformers-cache.ts
-import { mkdir as mkdir3 } from "fs/promises";
-import { join as join8 } from "path";
+import { createHash as createHash3 } from "crypto";
+import { mkdir as mkdir3, rm as rm4, stat as stat3, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname6, join as join8, resolve as resolve3 } from "path";
 import { createLogger as createLogger2 } from "@bendyline/gezel";
 var log2 = createLogger2("service");
+var DEFAULT_MODEL_LOCK_TIMEOUT_MS = 10 * 60 * 1e3;
+var DEFAULT_MODEL_LOCK_STALE_MS = 2 * 60 * 60 * 1e3;
 
 // src/memory/embed-core.ts
 var log3 = createLogger3("memory");
@@ -2229,7 +2232,7 @@ function passageInstruction() {
   return "";
 }
 function embedProfileId() {
-  const sha8 = (s) => createHash3("sha256").update(s, "utf8").digest("hex").slice(0, 8);
+  const sha8 = (s) => createHash4("sha256").update(s, "utf8").digest("hex").slice(0, 8);
   const dim = Number(process.env.GEZEL_EMBED_DIM) || 384;
   return `${embedModelId()}|d${dim}|mean|norm|q:${sha8(queryInstruction())}|p:${sha8(passageInstruction())}`;
 }
@@ -2256,6 +2259,138 @@ function imageEmbedModelId() {
   return process.env.GEZEL_IMAGE_EMBED_MODEL || DEFAULT_IMAGE_EMBED_MODEL;
 }
 
+// src/index-store/query-terms.ts
+var QUERY_STOP_WORDS = /* @__PURE__ */ new Set([
+  // articles + determiners
+  "a",
+  "an",
+  "the",
+  "this",
+  "that",
+  "these",
+  "those",
+  "some",
+  "any",
+  "all",
+  "each",
+  "both",
+  "every",
+  "other",
+  "another",
+  "same",
+  "such",
+  // pronouns
+  "i",
+  "me",
+  "my",
+  "we",
+  "us",
+  "our",
+  "you",
+  "your",
+  "it",
+  "its",
+  "he",
+  "him",
+  "his",
+  "she",
+  "her",
+  "they",
+  "them",
+  "their",
+  // be / have / do
+  "am",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "done",
+  // modals
+  "can",
+  "could",
+  "will",
+  "would",
+  "shall",
+  "should",
+  "may",
+  "might",
+  "must",
+  // question words
+  "how",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "whom",
+  "why",
+  // prepositions + conjunctions
+  "about",
+  "and",
+  "as",
+  "at",
+  "but",
+  "by",
+  "for",
+  "from",
+  "if",
+  "in",
+  "into",
+  "of",
+  "on",
+  "or",
+  "so",
+  "than",
+  "then",
+  "there",
+  "to",
+  "with",
+  // request scaffolding + degree words
+  "please",
+  "help",
+  "let",
+  "tell",
+  "want",
+  "need",
+  "create",
+  "make",
+  "give",
+  "get",
+  "got",
+  "use",
+  "using",
+  "just",
+  "like",
+  "also",
+  "very",
+  "only",
+  "new",
+  "more",
+  "most",
+  "much",
+  "many",
+  "few",
+  "own"
+]);
+var MAX_QUERY_TERMS = 16;
+function tokenizeText(text) {
+  return text.normalize("NFKC").toLocaleLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
+}
+function queryTerms(text) {
+  const unique = [...new Set(tokenizeText(text))].slice(0, MAX_QUERY_TERMS);
+  const meaningful = unique.filter((token) => !QUERY_STOP_WORDS.has(token));
+  return meaningful.length > 0 ? meaningful : unique;
+}
+
 // src/index-store/review-claims.ts
 var TRUNCATION_CLAIM_RES = [
   /truncat/i,
@@ -2790,7 +2925,7 @@ function applySchema(db, opts = {}) {
 // src/index-store/sqlite-driver.ts
 import { mkdir as mkdir4, rename as rename2 } from "fs/promises";
 import { createRequire as createRequire3 } from "module";
-import { dirname as dirname6 } from "path";
+import { dirname as dirname7 } from "path";
 import { createLogger as createLogger5 } from "@bendyline/gezel";
 var nodeRequire = createRequire3(import.meta.url);
 var log5 = createLogger5("sqlite");
@@ -2813,7 +2948,7 @@ async function openIndexDatabase(dbPath) {
   }
   if (dbPath !== ":memory:") {
     try {
-      await mkdir4(dirname6(dbPath), { recursive: true });
+      await mkdir4(dirname7(dbPath), { recursive: true });
     } catch (error) {
       if (isUnavailableIndexError(error)) return null;
       throw error;
@@ -2927,29 +3062,6 @@ var VECTOR_ARM_MIN_SIMILARITY = 0.55;
 function symbolId(filePath, name) {
   return `${filePath}#${name}`;
 }
-var FTS_STOP_WORDS = /* @__PURE__ */ new Set([
-  "a",
-  "an",
-  "and",
-  "are",
-  "for",
-  "how",
-  "in",
-  "is",
-  "me",
-  "my",
-  "of",
-  "on",
-  "or",
-  "our",
-  "please",
-  "the",
-  "to",
-  "we",
-  "with",
-  "you",
-  "your"
-]);
 function ftsPhrase(query) {
   const normalized = query.normalize("NFKC");
   const explicitlyQuoted = normalized.match(/^\s*"([^"]+)"\s*$/u);
@@ -2957,10 +3069,7 @@ function ftsPhrase(query) {
     const phrase = explicitlyQuoted[1]?.match(/[\p{L}\p{N}_]+/gu)?.join(" ") ?? "";
     return phrase ? `"${phrase.replace(/"/g, '""')}"` : '"__gezel_no_match__"';
   }
-  const raw = normalized.match(/[\p{L}\p{N}_]+/gu) ?? [];
-  const unique = [...new Set(raw.map((token) => token.toLocaleLowerCase()))].slice(0, 16);
-  const meaningful = unique.filter((token) => !FTS_STOP_WORDS.has(token));
-  const tokens = meaningful.length > 0 ? meaningful : unique;
+  const tokens = queryTerms(normalized);
   if (tokens.length === 0) return '"__gezel_no_match__"';
   return tokens.map((token) => `"${token.replace(/"/g, '""')}"${token.length >= 3 ? "*" : ""}`).join(" OR ");
 }
@@ -5296,7 +5405,7 @@ function parseBindings(raw) {
 
 // src/index-store/symbols.ts
 import { createRequire as createRequire4 } from "module";
-import { dirname as dirname7, join as join9 } from "path";
+import { dirname as dirname8, join as join9 } from "path";
 var nodeRequire2 = createRequire4(import.meta.url);
 var SIG_CAP = 160;
 var GRAMMAR_FILE = {
@@ -5369,7 +5478,7 @@ async function ensureInit() {
   initPromise = (async () => {
     try {
       const mod = nodeRequire2("web-tree-sitter");
-      const wtsDir = dirname7(nodeRequire2.resolve("web-tree-sitter"));
+      const wtsDir = dirname8(nodeRequire2.resolve("web-tree-sitter"));
       await mod.Parser.init({ locateFile: (f) => join9(wtsDir, f) });
       ParserCtor = mod.Parser;
       LanguageMod = mod.Language;
@@ -5381,7 +5490,7 @@ async function ensureInit() {
   return initPromise;
 }
 function grammarDir() {
-  return join9(dirname7(nodeRequire2.resolve("tree-sitter-wasms/package.json")), "out");
+  return join9(dirname8(nodeRequire2.resolve("tree-sitter-wasms/package.json")), "out");
 }
 async function loadLanguage(langId) {
   const file = GRAMMAR_FILE[langId];
@@ -5832,7 +5941,7 @@ async function indexWorkspaceContent(store, workspaceDir, artifactsDir, opts = {
         store.upsertFile(record);
         if (!convertible) continue;
         const paths = shadowDocFilesPaths(artifactsDir, file.path);
-        const sidecarPresent = paths ? await stat3(paths.mdPath).then(
+        const sidecarPresent = paths ? await stat4(paths.mdPath).then(
           (s) => s.isFile(),
           () => false
         ) : true;
@@ -5951,7 +6060,7 @@ async function indexWorkspaceContent(store, workspaceDir, artifactsDir, opts = {
         stats.removed++;
         if (isConvertibleDoc(extname3(f.path))) {
           const paths = shadowDocFilesPaths(artifactsDir, f.path);
-          if (paths) await rm4(paths.dir, { recursive: true, force: true }).catch(() => {
+          if (paths) await rm5(paths.dir, { recursive: true, force: true }).catch(() => {
           });
         }
       }
@@ -5981,7 +6090,7 @@ async function sweepShadowOrphans(artifactsDir, seen) {
       if (e.name.endsWith("_files")) {
         const sourceRel = childRel.slice(0, -"_files".length);
         if (!seen.has(sourceRel)) {
-          await rm4(join10(shadowRoot, childRel), { recursive: true, force: true }).catch(() => {
+          await rm5(join10(shadowRoot, childRel), { recursive: true, force: true }).catch(() => {
           });
         }
       } else {