@4fu/arbor-agent-pi 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/backend.js

@@ -96,6 +96,11 @@ export class PiAgentBackend {
             });
         }
         const results = new Map();
+        // The tools the window declares, built once here: the backend owns the call
+        // path, so it is the one that wires a spec to the host's catalog. A refresh
+        // while the window runs builds them again and replaces them on the agent's
+        // own state (docs/tools.md#external-tools-that-change).
+        const declareTools = (tools) => tools.map((tool) => piTool(tool, (args, callId) => this.callTool(request.window, tool.name, args, callId, results), this.renderer));
         const agent = new Agent({
             streamFn: (piModel, context, options) => this.runtime.streamSimple(piModel, context, options),
             getApiKey: async (provider) => {
@@ -105,7 +110,7 @@ export class PiAgentBackend {
             initialState: {
                 systemPrompt: systemPromptOf(request),
                 model,
-                tools: request.tools.map((tool) => piTool(tool, (args, callId) => this.callTool(request.window, tool.name, args, callId, results), this.renderer)),
+                tools: declareTools(request.tools),
             },
             steeringMode: "all",
             followUpMode: "all",
@@ -122,6 +127,9 @@ export class PiAgentBackend {
             limits: { limit: request.limits.contextTokens, reserve: request.limits.reserveTokens },
             results,
             run,
+            refreshTools: (tools) => {
+                agent.state.tools = declareTools(tools);
+            },
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4fu/arbor-agent-pi",
-  "version": "2026.1106.1",
+  "version": "2026.1107.0",
   "type": "module",
   "description": "The default AgentBackend: pi-agent-core in process, with its own system prompt and no pi type crossing the interface.",
   "exports": {
@@ -42,9 +42,9 @@
     "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",
     "@earendil-works/pi-agent-core": "1.5.0",
     "@earendil-works/pi-ai": "1.5.0"
   }

package/session.d.ts

@@ -13,7 +13,7 @@
  * even complete (docs/windows.md#streaming).
  */
 import type { Agent } from "@earendil-works/pi-agent-core";
-import type { Delivery, Handoff, TokenUsage, ToolResult, WindowEndReason, WindowEvent, WindowOutcome, WindowRef, WindowSession, WindowState } from "@4fu/arbor-interfaces";
+import type { Delivery, DirectToolSpec, Handoff, TokenUsage, ToolResult, WindowEndReason, WindowEvent, WindowOutcome, WindowRef, WindowSession, WindowState } from "@4fu/arbor-interfaces";
 import type { Renderer } from "@4fu/arbor-prompt";
 export interface PiSessionOptions {
     agent: Agent;
@@ -27,6 +27,12 @@ export interface PiSessionOptions {
     results?: Map<string, ToolResult>;
     /** The first turn, already started by the backend. */
     run: Promise<void>;
+    /**
+     * Replace the tools this window declares, when the host's set changed while
+     * the window runs. The backend owns the call path, so it builds them
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refreshTools?: (tools: readonly DirectToolSpec[]) => void;
 }
 export declare class PiWindowSession implements WindowSession {
     readonly window: WindowRef;
@@ -46,10 +52,24 @@ export declare class PiWindowSession implements WindowSession {
      * JSON yet, so they are read with pi's own tolerant parser.
      */
     private readonly writing;
+    /**
+     * How this window's declared tools are replaced when the host's set changes.
+     * The backend owns the call path, so it builds them
+     * (docs/tools.md#external-tools-that-change).
+     */
+    private readonly refresh;
     constructor(options: PiSessionOptions);
     get state(): WindowState;
     steer(delivery: Delivery): Promise<void>;
     followUp(delivery: Delivery): Promise<void>;
+    /**
+     * The tools this window may call changed. pi keeps its declaration on the
+     * agent's own state, which may be replaced while the window runs, so a tool
+     * that appeared is callable from the next model request and one that was
+     * removed is not - and the window's prefix is never rebuilt for it
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refreshTools(tools: readonly DirectToolSpec[]): void;
     end(handoff?: Handoff, reason?: WindowEndReason): Promise<void>;
     pause(): Promise<void>;
     resume(): Promise<void>;

package/session.js

@@ -64,9 +64,16 @@ export class PiWindowSession {
      * JSON yet, so they are read with pi's own tolerant parser.
      */
     writing = new Map();
+    /**
+     * How this window's declared tools are replaced when the host's set changes.
+     * The backend owns the call path, so it builds them
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refresh;
     constructor(options) {
         this.window = options.window;
         this.agent = options.agent;
+        this.refresh = options.refreshTools;
         this.renderer = options.renderer;
         this.results = options.results ?? new Map();
         this.current = { used: 0, limit: options.limits.limit, reserve: options.limits.reserve };
@@ -104,6 +111,18 @@ export class PiWindowSession {
             return;
         this.enqueue(delivery, "followUp");
     }
+    /**
+     * The tools this window may call changed. pi keeps its declaration on the
+     * agent's own state, which may be replaced while the window runs, so a tool
+     * that appeared is callable from the next model request and one that was
+     * removed is not - and the window's prefix is never rebuilt for it
+     * (docs/tools.md#external-tools-that-change).
+     */
+    refreshTools(tools) {
+        if (this.ended)
+            return;
+        this.refresh?.(tools);
+    }
     async end(handoff, reason = "model_ended") {
         if (this.ended)
             return;

package/tools.d.ts

@@ -10,12 +10,21 @@
  * error block - the rule and the next action, one line.
  */
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { ParameterSpec, ToolResult } from "@4fu/arbor-interfaces";
+import type { JSONSchema, ParameterSpec, ToolResult } from "@4fu/arbor-interfaces";
 import type { Renderer } from "@4fu/arbor-prompt";
 /** One parameter's JSON Schema, from its `ParameterSpec`. */
 export declare function parameterSchema(parameter: ParameterSpec): Record<string, unknown>;
-/** The JSON Schema one tool declares to pi. */
-export declare function toolParameters(parameters: Record<string, ParameterSpec>): Record<string, unknown>;
+/**
+ * The JSON Schema one tool declares to pi.
+ *
+ * A tool declared from outside the core hands over the JSON Schema its own
+ * harness declared, and that is what pi sends: `enum`, `items`, `oneOf`, a
+ * nested object's own properties, all of it, because the model calls the tool
+ * with the schema it was given and a summary of it would only drop what it says
+ * (docs/tools.md#external-tools). A tool that declares none - arbor's own - is
+ * built from its `ParameterSpec`s, which is the declaration for those.
+ */
+export declare function toolParameters(parameters: Record<string, ParameterSpec>, schema?: JSONSchema): Record<string, unknown>;
 /**
  * What the model reads of one result. A successful result is rendered as the
  * `tool_result` block, so it is escaped and marked as data like every other
@@ -31,4 +40,5 @@ export declare function piTool(spec: {
     name: string;
     description: string;
     parameters: Record<string, ParameterSpec>;
+    schema?: JSONSchema;
 }, call: (args: Record<string, unknown>, callId: string) => Promise<ToolResult>, renderer: Renderer): AgentTool<Record<string, unknown>>;

package/tools.js

@@ -44,8 +44,19 @@ function jsonType(type) {
             return "string";
     }
 }
-/** The JSON Schema one tool declares to pi. */
-export function toolParameters(parameters) {
+/**
+ * The JSON Schema one tool declares to pi.
+ *
+ * A tool declared from outside the core hands over the JSON Schema its own
+ * harness declared, and that is what pi sends: `enum`, `items`, `oneOf`, a
+ * nested object's own properties, all of it, because the model calls the tool
+ * with the schema it was given and a summary of it would only drop what it says
+ * (docs/tools.md#external-tools). A tool that declares none - arbor's own - is
+ * built from its `ParameterSpec`s, which is the declaration for those.
+ */
+export function toolParameters(parameters, schema) {
+    if (schema !== undefined)
+        return schema;
     const properties = {};
     const required = [];
     for (const [name, parameter] of Object.entries(parameters)) {
@@ -94,7 +105,7 @@ export function piTool(spec, call, renderer) {
         name: spec.name,
         label: spec.name,
         description: spec.description,
-        parameters: toolParameters(spec.parameters),
+        parameters: toolParameters(spec.parameters, spec.schema),
         execute: async (callId, params) => {
             const result = await call((params ?? {}), callId);
             return toolResultOf(result, renderer);