@4fu/arbor-interfaces 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/agent.d.ts

@@ -13,6 +13,17 @@ import type { ExternalTool } from "./tools.ts";
 import type { TaskRef, Ref, WindowRef } from "./refs.ts";
 import type { Handoff, TokenUsage, WindowState } from "./windows.ts";
 import type { RateLimitState } from "./scheduler.ts";
+/**
+ * One JSON Schema object, carried as it was declared.
+ *
+ * A tool declared from outside the core - a plugin's own, or a harness's
+ * through a backend - hands its parameters over in the JSON Schema that
+ * harness already speaks, and that schema is what the model reads, verbatim
+ * (docs/tools.md#external-tools). Deriving one from a summary would drop what
+ * the schema says and what the summary cannot: `enum`, `items`, `oneOf`,
+ * `additionalProperties`, a nested object's own properties.
+ */
+export type JSONSchema = Record<string, unknown>;
 /** One model the backend can run. Only models that take images are offered. */
 export interface ModelInfo {
     id: string;
@@ -78,7 +89,32 @@ export interface ContinuationInfo {
     /** Set after the hard limit: the window was reset mid-task. */
     midTaskReset?: boolean;
 }
-/** What the host inserts into a running window at a tool-call boundary. */
+/**
+ * What the host inserts into a running window at a tool-call boundary.
+ *
+ * ## What each kind expects from a backend
+ *
+ * Every delivery is one input block, and the host says when the model must
+ * read it by the call it hands the delivery to: `WindowSession.steer` for one
+ * that goes in at the next step boundary, `WindowSession.followUp` for one that
+ * becomes the input of the next turn. The rule is the same for every kind - the
+ * insertion rules decide, not the kind
+ * (docs/dispatch.md#insertion-timing) - with two things a backend can rely on:
+ *
+ * - **What a window can call is never held back.** A conversation update, an
+ *   environment delta, a prompt delta and a tools delta always come through
+ *   `steer`, in the protection period and after it, because they change what
+ *   the window would otherwise do next.
+ * - **A reminder is the kind the host times itself.** While the window runs it
+ *   is steered in at the next boundary; once the run has ended it is queued as
+ *   a follow-up, so it is the input of the window's next turn.
+ *
+ * A backend that is not pi maps the two calls onto whatever its own loop
+ * offers - DeepSeek Harness's `agent.inject` for a step boundary and its
+ * steering for the next turn - and the rest of the contract is the same: the
+ * block is one user-role input, in order, exactly once, and the turn the
+ * window is in is never ended by it.
+ */
 export interface Delivery {
     kind: "inserted_task" | "conversation_update" | "notice" | "broadcast" | "window_message" | "environment_delta"
     /**
@@ -87,6 +123,13 @@ export interface Delivery {
      * (docs/prompting.md#plugin-sections-that-change).
      */
      | "prompt_delta"
+    /**
+     * The direct tools declared from outside the core changed while this window
+     * runs: a harness registered one, or a plugin's set moved. The delta names
+     * what was added and what was removed, and the window may call the new ones
+     * from its next tool call on (docs/tools.md#external-tools-that-change).
+     */
+     | "tools_delta"
     /** A host usage reminder, appended to an input (docs/windows.md#usage-reminders). */
      | "reminder";
     /** The window it comes from, for a notice, a broadcast or a window message. */
@@ -99,10 +142,66 @@ export interface Delivery {
 export interface WindowSession {
     readonly window: WindowRef;
     readonly state: WindowState;
-    /** Insert at the next tool-call boundary, through the backend's steering. */
+    /**
+     * Insert at the next tool-call boundary, through the backend's steering.
+     *
+     * A **step boundary** is the moment every tool call of the current turn has
+     * finished and the next model request has not gone out yet. The delivery
+     * becomes one user-role input the model reads with that request. It is never
+     * a system message in the middle of a window - some providers fold those into
+     * the leading system prompt and that breaks the cached prefix
+     * (docs/prompting.md#no-built-in-pi-prompt) - and it never rewrites the
+     * window's prefix.
+     *
+     * What a backend must do:
+     *
+     * - deliver the block in the order the host handed its deliveries over, and
+     *   deliver each one exactly once;
+     * - keep the turn going: the model is not stopped, not asked to confirm, and
+     *   not told the input is special - it is one more input;
+     * - start a turn when the window is idle, because that is what a related
+     *   input wants (docs/dispatch.md#insertion-timing); the host only steers
+     *   into a window it has not ended and has not paused, so a delivery never
+     *   arrives for one of those;
+     * - resolve once the delivery is queued, not once the model has read it: the
+     *   host never waits for the model, and a slow model is not a slow steer.
+     *
+     * A window that has ended refuses in the core's error shape, rule
+     * `window.ended`; the host never steers into one.
+     */
     steer(delivery: Delivery): Promise<void>;
-    /** Queue for after the run ends. */
+    /**
+     * Queue for after the run ends: the delivery becomes the input of the
+     * window's next turn.
+     *
+     * What a backend must do:
+     *
+     * - hold it out of the turn the window is in - the model must not read it
+     *   mid-turn, which is what separates this call from `steer`;
+     * - deliver it as the input of the next turn, in order and exactly once, when
+     *   the window runs again;
+     * - keep it queued while the window sits idle, and drop it when the window
+     *   ends, because an ended window is never reopened
+     *   (docs/windows.md#lifecycle).
+     *
+     * The host uses this only for a delivery that belongs after the run: the
+     * reminder of a window whose run has already ended, and whatever a
+     * `Scheduler` places there (docs/dispatch.md#insertion-timing).
+     */
     followUp(delivery: Delivery): Promise<void>;
+    /**
+     * The direct tools this window may call changed: the host registered what a
+     * backend or a plugin declared since this window opened
+     * (docs/tools.md#external-tools-that-change).
+     *
+     * A backend that can change a running window's declared tools replaces them
+     * here, so a tool that appeared is callable in this window and one that was
+     * removed is not. A backend that cannot leaves the declaration it opened
+     * with: the window still learns the change from the `tools_delta` it is
+     * steered, and a call still runs through the host's catalog, which holds the
+     * current set. Optional; the host asks only of a session that has it.
+     */
+    refreshTools?(tools: readonly DirectToolSpec[]): Promise<void> | void;
     /** End the run. With a handoff the host opens a continuation. */
     end(handoff?: Handoff, reason?: WindowEndReason): Promise<void>;
     /** Pause insertion without ending the window. */
@@ -191,8 +290,14 @@ export interface AgentBackend {
      * Direct tools the backend injects from outside arbor: the tools an outside
      * harness registered, which a host embedded in that harness hands in here
      * (docs/tools.md#external-tools). They are declared to the model and called
-     * in the turn like any other direct tool. Read once, before the first window
-     * opens.
+     * in the turn like any other direct tool.
+     *
+     * The set is refreshable: the host reads it again before every window opens
+     * and at every step boundary, so a tool the harness registers - or drops -
+     * while the host runs reaches the model without a restart
+     * (docs/tools.md#external-tools-that-change). A backend that wants the change
+     * to land the moment it happens rather than at the next boundary calls
+     * `Arbor.refreshExternalTools` from its own signal.
      */
     externalTools?(): readonly ExternalTool[] | Promise<readonly ExternalTool[]>;
     /** Open one window and start its first turn. */
@@ -203,7 +308,17 @@ export interface DirectToolSpec {
     name: string;
     /** What it does and when to use it; side effects. 1 to 4 sentences. */
     description: string;
+    /** The parameters in arbor's own declaration shape. */
     parameters: Record<string, ParameterSpec>;
+    /**
+     * The parameters as the JSON Schema an outside harness declared them, carried
+     * verbatim: `enum`, `items`, `oneOf`, `additionalProperties`, a nested
+     * object's own properties, all of it. What the model reads when the tool has
+     * one, and what the `<tools>` line and `tool_search` show
+     * (docs/tools.md#external-tools). Arbor's own tools declare none: their
+     * `parameters` are the declaration.
+     */
+    schema?: JSONSchema;
     /**
      * Who declares it, when it is not the core's own: a plugin's name, or a
      * backend's. The tools list says where such a tool comes from, so the model

package/events.d.ts

@@ -108,7 +108,11 @@ export interface SearchHit {
     kind: EventKind;
     time: number;
     match: MatchKind;
-    /** Relevance in 0..1 within its index; higher is better. */
+    /**
+     * Relevance in 0..1 across the channels that found the hit; higher is better.
+     * Fused with reciprocal rank fusion, so a hit two channels found outranks one
+     * only one did.
+     */
     score: number;
     /** The event's opening words, for a one-line result. */
     summary: string;

package/index.d.ts

@@ -11,8 +11,8 @@ export type { BlockValue, Block, BlockKind, BlockFieldSpec, BlockKindSpec, TextT
 /** Page bounds every read reports (docs/prompting.md). */
 export { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from "./refs.ts";
 export type { EventInput, Link, LinkInput, Redaction, Event, ListOptions, Page, EventPage, AroundOptions, SearchOptions, SearchHit, SearchPage, LinksOptions, RelatedItem, LinkPage, TraceOptions, TraceNode, TargetGap, JournalError, } from "./events.ts";
-export type { BlobInput, BlobContent, BlobInfo, BlobStore, Segmenter, Journal, } from "./journal.ts";
-export type { ModelInfo, LoginState, LoginRequest, LoginResult, RenderedPrompt, OpenWindowRequest, WindowLimits, ContinuationInfo, Delivery, WindowSession, StreamEvent, WindowEvent, WindowEndReason, WindowOutcome, AgentBackend, DirectToolSpec, ModuleSpec, FunctionSpec, ParameterSpec, ToolCall, ToolResult, } from "./agent.ts";
+export type { BlobInput, BlobContent, BlobInfo, BlobStore, Segmenter, SemanticFilters, SemanticFields, Embedder, SemanticIndex, Journal, } from "./journal.ts";
+export type { ModelInfo, LoginState, LoginRequest, LoginResult, RenderedPrompt, OpenWindowRequest, WindowLimits, ContinuationInfo, Delivery, WindowSession, StreamEvent, WindowEvent, WindowEndReason, WindowOutcome, AgentBackend, DirectToolSpec, ModuleSpec, FunctionSpec, ParameterSpec, JSONSchema, ToolCall, ToolResult, } from "./agent.ts";
 export type { WindowState, WindowRuntimeState, TokenUsage, Handoff, BoardLine, Expectation, InputBlock, } from "./windows.ts";
 export type { NoteStatus, Anchor, NoteWriteInput, Note, NoteSummary, NoteBody, NoteRevision, NoteContext, NoteQuery, NoteConflictInfo, ActiveSetBudget, ActiveCandidate, NoteUseKind, NoteUseInput, SnapshotOptions, NotesSnapshot, NoteDelta, NoteDeltaItem, NoteStore, } from "./notes.ts";
 export type { ExecResult, StagedFile, OpenWorkItem, WorkspaceCheckout, WorkspaceKeep, WorkspaceMount, WorkspaceQuota, Workspace, } from "./workspace.ts";
@@ -20,7 +20,7 @@ export type { JudgeMode, JudgeDecisionKind, CandidateWindow, JudgeTask, FilterSt
 export type { OutsideEvent, OutsideMessage, ChannelConnection, SendRequest, SendResult, Unsubscribe, Channel, } from "./channel.ts";
 export type { TaskKind, TaskInput, Task, TaskSource } from "./task.ts";
 export type { EffectKind, Effect, EffectResult, EffectExecutor } from "./effects.ts";
-export type { CallContext, ToolGroup, ExternalTool } from "./tools.ts";
+export type { CallContext, ToolGroup, ExternalTool, ExternalToolSource, ExternalToolChange, } from "./tools.ts";
 export type { EnvItemKind, EnvItem, EnvDraft, EnvValidation, EnvRevision, EnvDelta, Environment, } from "./environment.ts";
 export type { ServiceState, ServiceSpec, ServiceHandle, ServiceStatus, LogOptions, LogPage, Supervisor, } from "./supervisor.ts";
 export type { QueuedInput, InsertionRequest, InsertionPlan, RateLimitState, AdmissionRequest, AdmissionPlan, SkipPeriod, DailyRepeat, EveryRepeat, RepeatBounds, RepeatRule, WeeklyRepeat, ScheduledTaskInput, ScheduledTask, ScheduledTaskUpdate, Scheduler, } from "./scheduler.ts";

package/journal.d.ts

@@ -52,6 +52,60 @@ export interface BlobStore {
 export interface Segmenter {
     segment(text: string): string[];
 }
+/** The filters a semantic search applies, as the journal's own read applies them. */
+export interface SemanticFilters {
+    kinds?: readonly string[];
+    window?: WindowRef | null;
+    afterSeq?: number;
+    beforeSeq?: number;
+}
+/** The scalar fields a semantic filter reads, beside an event's text. */
+export interface SemanticFields {
+    kind?: string;
+    window?: WindowRef | null;
+}
+/**
+ * Embedding text into vectors. The default is a small local model that needs no
+ * key (docs/journal.md#search); a deployment replaces it with its own, which is
+ * the only way text reaches anything outside the host.
+ */
+export interface Embedder {
+    /** The dimension every vector this embedder returns has. */
+    readonly dimension: number;
+    /** Embed each text, in the order given. */
+    embed(texts: readonly string[]): Promise<readonly number[][]>;
+}
+/**
+ * The semantic channel: text search by meaning, beside the lexical indexes
+ * (docs/journal.md#search, docs/memory.md#search).
+ *
+ * A store takes one as an optional peer, the way it takes a `Segmenter`.
+ * When none is registered - the package is not installed, its vector store will
+ * not open on the platform, or no embedding model is available - search is
+ * lexical and nothing else changes. A channel that is registered but not ready
+ * yet - the model is still downloading, or the download failed and is waiting to
+ * be retried - answers `ready()` with `false`, an empty `search`, and keeps
+ * what `add` handed it until it is.
+ *
+ * The ref is the store's own: an event ref for the journal, a note id for the
+ * note store, which holds one vector per note and replaces it when the note is
+ * revised. What the channel keeps beside a ref - the fields, and the order the
+ * ref's number carries - is whatever that store's reads filter on.
+ */
+export interface SemanticIndex {
+    /** Embed and store one item's text, replacing what is stored for it. */
+    add(ref: Ref, text: string, fields?: SemanticFields): Promise<void>;
+    /** Forget one item's text, as a redaction or a delete does. */
+    remove(ref: Ref): Promise<void>;
+    /** The refs nearest a query, best first, already filtered. Empty until ready. */
+    search(query: string, limit: number, filters: SemanticFilters): Promise<readonly Ref[]>;
+    /** Whether the channel can answer a query now. */
+    ready(): Promise<boolean>;
+    /** Every ref the channel holds, so a caller can index what it is missing. */
+    held(): Promise<ReadonlySet<Ref>>;
+    /** Release the underlying store. */
+    close(): Promise<void>;
+}
 export interface Journal {
     /** Append one event. Assigns `ref` and `seq`; a redelivered `external` id is stored once. */
     append(input: EventInput): Promise<Event>;
@@ -63,7 +117,11 @@ export interface Journal {
     list(options?: ListOptions): Promise<EventPage>;
     /** The events around one, in the global order. */
     around(ref: EventRef, options?: AroundOptions): Promise<Event[]>;
-    /** Lexical search: exact substring hits first, then word hits, each with its ref and window. */
+    /**
+     * Text search: exact substring hits first, then word hits and semantic hits
+     * fused by reciprocal rank, each with its ref and window
+     * (docs/journal.md#search).
+     */
     search(query: string, options?: SearchOptions): Promise<SearchPage>;
     /** Related items by weight, with the call that pages the rest. */
     links(ref: Ref, options?: LinksOptions): Promise<LinkPage>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4fu/arbor-interfaces",
-  "version": "2026.1106.1",
+  "version": "2026.1107.0",
   "type": "module",
   "description": "Every replaceable interface in arbor, and the core's own shapes.",
   "exports": {
@@ -66,6 +66,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@4fu/arbor-errors": "2026.1106.1"
+    "@4fu/arbor-errors": "2026.1107.0"
   }
 }

package/plugin.d.ts

@@ -17,7 +17,7 @@ import type { EnvDraft } from "./environment.ts";
 import type { JudgeCriteria } from "./judge.ts";
 import type { Hooks } from "./hooks.ts";
 import type { TaskSource } from "./task.ts";
-import type { ExternalTool } from "./tools.ts";
+import type { ExternalTool, ExternalToolSource } from "./tools.ts";
 /** Connections to the outside world. */
 export interface PluginAdapters {
     channels?: readonly Channel[];
@@ -68,8 +68,13 @@ export interface Plugin {
      * them, and called in the turn through the same path a core tool takes
      * (docs/tools.md#external-tools). A name a core tool or a module already
      * declares is not registered; the host records the collision with its rule.
+     *
+     * The set may be a list or a source the host calls again on every refresh, so
+     * a plugin whose tools change while the host runs - the tools a harness
+     * around the host registered - answers with what stands now
+     * (docs/tools.md#external-tools-that-change).
      */
-    tools?: readonly ExternalTool[];
+    tools?: readonly ExternalTool[] | ExternalToolSource;
     hooks?: Hooks;
     promptSection?: PromptSection;
     /** Extra criteria or decisions for its own inputs. */

package/refs.d.ts

@@ -41,8 +41,11 @@ export type Target = string;
 export type EventKind = "input" | "tool_call" | "tool_result" | "send" | "effect_result" | "note_revision" | "window_start" | "window_end" | "delivery" | "environment_revision" | "service_state" | "redaction" | "schedule" | (string & {});
 /** Link kinds between refs. The host records them; the model never declares one. */
 export type LinkKind = "cite" | "evidence" | "range" | "origin" | "revision" | "handoff" | "continuation" | "notice" | "reply" | (string & {});
-/** How a search hit matched: an exact substring, or a word. */
-export type MatchKind = "substring" | "word";
+/**
+ * How a search hit matched: an exact substring, a word, or meaning alone. A hit
+ * the semantic channel found and no lexical index did is `semantic`.
+ */
+export type MatchKind = "substring" | "word" | "semantic";
 /** Page size default shared by every read that returns a page. */
 export declare const DEFAULT_PAGE_LIMIT = 20;
 /** Maximum page size any read returns. */

package/tools.d.ts

@@ -9,6 +9,7 @@
  * model can otherwise do with a plugin is an MCP server and skills in `/env`.
  */
 import type { DirectToolSpec, FunctionSpec, ModuleSpec, ParameterSpec, ToolCall, ToolResult } from "./agent.ts";
+import type { JSONSchema } from "./agent.ts";
 import type { EventRef, WindowRef } from "./refs.ts";
 import type { WorkspaceMount } from "./workspace.ts";
 /** What a call is made in. The service layer fills it; a group never reaches past it. */
@@ -47,7 +48,35 @@ export interface ExternalTool {
     readonly name: string;
     /** What it does and when to use it; side effects. 1 to 4 sentences. */
     readonly description: string;
-    readonly parameters: Record<string, ParameterSpec>;
+    /**
+     * The parameters in arbor's own declaration shape. Optional for a tool that
+     * declares `schema` instead: an outside harness already has a JSON Schema for
+     * its tool, and restating it in this shape would only lose what the schema
+     * says.
+     */
+    readonly parameters?: Record<string, ParameterSpec>;
+    /**
+     * The parameters as the JSON Schema the outside harness declared them,
+     * carried verbatim (docs/tools.md#external-tools). What the model reads when
+     * the tool has one; `parameters` is the declaration for a tool that has none.
+     */
+    readonly schema?: JSONSchema;
     /** Run one call. The same path a core tool takes. */
     execute(request: ToolCall, context: CallContext): Promise<ToolResult>;
 }
+/**
+ * Where a plugin's external tools come from: a list, or a call that answers
+ * with the current one. The host reads the source again on every refresh, so a
+ * plugin whose tools change at runtime - the tools a harness around the host
+ * registered - answers with what stands now
+ * (docs/tools.md#external-tools-that-change).
+ */
+export type ExternalToolSource = () => readonly ExternalTool[] | Promise<readonly ExternalTool[]>;
+/** What one refresh of the external tools changed about one tool. */
+export interface ExternalToolChange {
+    change: "added" | "removed";
+    /** The tool's own name, as the model calls it. */
+    name: string;
+    /** Who declares it: the plugin's name, or the backend's. */
+    source: string;
+}