@4fu/arbor-tools 2026.1106.1 → 2026.1107.0

package/README.md

@@ -56,7 +56,9 @@ npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
 ```
 
 `@4fu/arbor-plugin-http` is optional; it is the example plugin below.
-`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the lexical package, and
+`@4fu/arbor-search-zvec` an optional peer of the journal: absent either one, the
+journal searches lexically and nothing else changes.
 
 ## A minimal host
 
@@ -120,6 +122,8 @@ window gets, and how a continuation keeps working in it, are in
 | [`@4fu/arbor-journal-sqlite`](packages/journal-sqlite) | the default `Journal` and `BlobStore` on SQLite |
 | [`@4fu/arbor-notes-sqlite`](packages/notes-sqlite) | the default `NoteStore` on SQLite, beside the journal |
 | [`@4fu/arbor-segmenter-jieba`](packages/segmenter-jieba) | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| [`@4fu/arbor-lexical`](packages/lexical) | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
+| [`@4fu/arbor-search-zvec`](packages/search-zvec) | the optional semantic channel: event text embedded and searched by meaning with zvec |
 | [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the fallback `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
 | [`@4fu/arbor-workspace-ovnfs`](packages/workspace-ovnfs) | the default `Workspace` when ovnfs is installed: one shared folder, per-window copy-on-write checkouts the model opens and applies back |
 | [`@4fu/arbor-environment-dir`](packages/environment-dir) | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
@@ -171,6 +175,7 @@ tarball would contain ([docs/release.md](docs/release.md)).
 | `packages/errors` | the error shape every refusal uses: the rule and the next action |
 | `packages/journal-sqlite` | the default `Journal` and `BlobStore` on SQLite |
 | `packages/segmenter-jieba` | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| `packages/lexical` | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
 | `packages/notes-sqlite` | the default `NoteStore` on SQLite, beside the journal |
 | `packages/judge-jev` | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
 | `packages/workspace-dir` | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place, and the lookup of another window's directory it contributes to the catalog |

package/catalog.d.ts

@@ -49,9 +49,22 @@ export declare class ToolCatalog implements ToolGroup, ScriptCatalog {
     private readonly services;
     /** The groups the core declares itself, which no external tool may shadow. */
     private readonly own;
-    /** Every group, the core's own first, then what a deployment registered. */
-    private readonly groups;
+    /**
+     * The groups a deployment registered - the core's own, what the workspace
+     * implementation contributes, and a plugin's own groups - which no external
+     * tool may shadow either.
+     */
+    private readonly base;
+    /**
+     * One group per source that declared external tools, the source's name as the
+     * key. A refresh replaces the group its source declared before, so a tool the
+     * source dropped is no longer declared and no longer callable
+     * (docs/tools.md#external-tools-that-change).
+     */
+    private readonly externalGroups;
     constructor(options: ToolCatalogOptions);
+    /** Every group: the base, then one per source that declared external tools. */
+    private get groups();
     /**
      * Register direct tools declared from outside the core - a plugin's own, or a
      * backend's injection of the tools an outside harness registered
@@ -60,7 +73,12 @@ export declare class ToolCatalog implements ToolGroup, ScriptCatalog {
      * A name the model already has is not registered: a core tool always wins,
      * and so does the external tool that arrived first. The collisions come back
      * with the rule that refused them, so the host records them for the operator
-     * instead of throwing.
+     * instead of throwing. The rule runs on every call, so every refresh of the
+     * set is checked the same way.
+     *
+     * What this source declared before is replaced, so a refresh that drops a
+     * tool leaves it undeclared and uncallable - and a tool the source declares
+     * again is not a collision with itself.
      */
     external(tools: readonly ExternalTool[], source: string): readonly ExternalToolRefusal[];
     /** Every direct tool, one line each in the prompt. */

package/catalog.js

@@ -13,7 +13,7 @@
  * moment it is an ordinary direct tool: same declaration, same routing, same
  * result cut (docs/tools.md#external-tools).
  */
-import { textOf } from "@4fu/arbor-prompt";
+import { textOf, toolLine } from "@4fu/arbor-prompt";
 import { directToolIn, runScript } from "./code-exec.js";
 import { boundResult } from "./bound.js";
 import { CoreToolGroup } from "./groups/core.js";
@@ -29,8 +29,19 @@ export class ToolCatalog {
     services;
     /** The groups the core declares itself, which no external tool may shadow. */
     own;
-    /** Every group, the core's own first, then what a deployment registered. */
-    groups;
+    /**
+     * The groups a deployment registered - the core's own, what the workspace
+     * implementation contributes, and a plugin's own groups - which no external
+     * tool may shadow either.
+     */
+    base;
+    /**
+     * One group per source that declared external tools, the source's name as the
+     * key. A refresh replaces the group its source declared before, so a tool the
+     * source dropped is no longer declared and no longer callable
+     * (docs/tools.md#external-tools-that-change).
+     */
+    externalGroups = new Map();
     constructor(options) {
         this.services = options.services;
         this.own = [
@@ -48,7 +59,7 @@ export class ToolCatalog {
             new EnvToolGroup(options.services),
             new EnvModuleGroup(options.services),
         ];
-        this.groups = [
+        this.base = [
             ...this.own,
             // What the workspace implementation contributes: a capability the core
             // does not name, such as showing another window's directory.
@@ -56,6 +67,10 @@ export class ToolCatalog {
             ...(options.groups ?? []),
         ];
     }
+    /** Every group: the base, then one per source that declared external tools. */
+    get groups() {
+        return [...this.base, ...this.externalGroups.values()];
+    }
     /**
      * Register direct tools declared from outside the core - a plugin's own, or a
      * backend's injection of the tools an outside harness registered
@@ -64,10 +79,19 @@ export class ToolCatalog {
      * A name the model already has is not registered: a core tool always wins,
      * and so does the external tool that arrived first. The collisions come back
      * with the rule that refused them, so the host records them for the operator
-     * instead of throwing.
+     * instead of throwing. The rule runs on every call, so every refresh of the
+     * set is checked the same way.
+     *
+     * What this source declared before is replaced, so a refresh that drops a
+     * tool leaves it undeclared and uncallable - and a tool the source declares
+     * again is not a collision with itself.
      */
     external(tools, source) {
-        const taken = new Set([...this.tools().map((tool) => tool.name), ...this.modules().map((module) => module.name)]);
+        const others = [...this.base, ...[...this.externalGroups].filter(([name]) => name !== source).map(([, group]) => group)];
+        const taken = new Set([
+            ...others.flatMap((group) => group.tools()).map((tool) => tool.name),
+            ...others.flatMap((group) => group.modules()).map((module) => module.name),
+        ]);
         const refused = [];
         const declared = [];
         for (const tool of tools) {
@@ -78,8 +102,7 @@ export class ToolCatalog {
             taken.add(tool.name);
             declared.push(tool);
         }
-        if (declared.length > 0)
-            this.groups.push(new ExternalToolGroup(declared, source, this.services));
+        this.externalGroups.set(source, new ExternalToolGroup(declared, source, this.services));
         return refused;
     }
     /** Every direct tool, one line each in the prompt. */
@@ -290,6 +313,7 @@ export class ToolCatalog {
             lines.push(textOf(table, "result.tool_search.modules", { names: found.modules.join(", ") }));
         }
         for (const tool of found.tools) {
+            // The renderer's own rule, so the lookup and the prompt never disagree.
             lines.push(toolLine(table, tool));
         }
         for (const name of found.functions) {
@@ -327,15 +351,6 @@ function stringArg(args, name) {
     const value = args[name];
     return typeof value === "string" ? value : "";
 }
-/**
- * One tool's line, the same one the tools list writes: a tool declared from
- * outside the core says where it comes from, so the model knows whose it is
- * wherever it meets the name (docs/tools.md#external-tools).
- */
-function toolLine(table, tool) {
-    const key = tool.source === undefined ? "system.tool" : "system.tool.source";
-    return lookup(table, key, { name: tool.name, description: tool.description, source: tool.source ?? "" });
-}
 /**
  * The matches, strongest first: an exact name, then a name that starts with
  * the query, then a description that holds it. Ties keep the order the catalog

package/groups/external.d.ts

@@ -9,7 +9,9 @@
  * every direct tool.
  *
  * The `source` rides on each spec, so the tools list the model reads says where
- * a tool comes from and `tool_search` answers with the same line.
+ * a tool comes from and `tool_search` answers with the same line. So does the
+ * JSON Schema the outside harness declared, carried through untouched
+ * (docs/tools.md#external-tools).
  */
 import type { CallContext, DirectToolSpec, ExternalTool, ToolCall, ToolGroup, ToolResult } from "@4fu/arbor-interfaces";
 import { type ToolServices } from "../host.ts";

package/groups/external.js

@@ -9,7 +9,9 @@
  * every direct tool.
  *
  * The `source` rides on each spec, so the tools list the model reads says where
- * a tool comes from and `tool_search` answers with the same line.
+ * a tool comes from and `tool_search` answers with the same line. So does the
+ * JSON Schema the outside harness declared, carried through untouched
+ * (docs/tools.md#external-tools).
  */
 import { refused } from "../host.js";
 export class ExternalToolGroup {
@@ -27,7 +29,11 @@ export class ExternalToolGroup {
         return this.declared.map((tool) => ({
             name: tool.name,
             description: tool.description,
-            parameters: tool.parameters,
+            // A tool that declares a JSON Schema of its own needs no restatement of
+            // it in arbor's shape: the schema is the declaration
+            // (docs/tools.md#external-tools).
+            parameters: tool.parameters ?? {},
+            ...(tool.schema === undefined ? {} : { schema: tool.schema }),
             source: this.source,
         }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4fu/arbor-tools",
-  "version": "2026.1106.1",
+  "version": "2026.1107.0",
   "type": "module",
   "description": "The entry points: direct tools, code mode modules and the one tool catalog that routes both through the service layer.",
   "exports": {
@@ -54,8 +54,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@4fu/arbor-errors": "2026.1106.1",
-    "@4fu/arbor-interfaces": "2026.1106.1",
-    "@4fu/arbor-prompt": "2026.1106.1"
+    "@4fu/arbor-errors": "2026.1107.0",
+    "@4fu/arbor-interfaces": "2026.1107.0",
+    "@4fu/arbor-prompt": "2026.1107.0"
   }
 }