@4fu/arbor-interfaces 2026.1106.0 → 2026.1107.0

package/README.md

@@ -27,9 +27,11 @@ everything that takes judgment, such as git, merges and conflicts, to the agent.
   guarantees what an agent cannot guarantee for itself - the record, isolation,
   exactly-once effects, the checks, dispatch. Everything that takes judgment,
   such as git, merges and conflicts, is the agent's.
-- **A directory per window.** Each window gets its own directory, and a
-  continuation keeps working in its predecessor's directory in place. It is not
-  bound to a repository; the agent clones and pushes what it needs.
+- **A shared workspace with per-window checkouts.** The default workspace is
+  ovnfs: one shared folder every window reads, and a window opens its own
+  copy-on-write checkout of the project it needs, works there and merges back
+  with `apply`. It falls back to a plain directory per window when ovnfs is not
+  installed. It is not a sandbox: ovnfs isolates files, not processes.
 - **A self-changing environment.** The model adds and changes skills, MCP
   servers and resident services itself; a `reload` validates the change and
   broadcasts it to every live window as a delta of names and descriptions.
@@ -54,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
 
@@ -118,7 +122,10 @@ 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-workspace-dir`](packages/workspace-dir) | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@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 |
 | [`@4fu/arbor-supervisor-process`](packages/supervisor-process) | the default `Supervisor`: one host process per service, restart with backoff, logs |
 | [`@4fu/arbor-judge-jev`](packages/judge-jev) | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
@@ -151,7 +158,7 @@ deployment can see what it would be taking on before it adopts one.
 | [docs/coordination.md](docs/coordination.md) | the board, expectations, deliveries and broadcasts, staying current, effects |
 | [docs/environment.md](docs/environment.md) | skills, MCP servers and services: using, changing, reload, built-in skills, deltas |
 | [docs/memory.md](docs/memory.md) | notes, the active set, anchors, links |
-| [docs/workspaces.md](docs/workspaces.md) | per-window directories: isolation, continuity, what the agent does |
+| [docs/workspaces.md](docs/workspaces.md) | the shared folder and per-window checkouts: isolation, continuity, what the agent does |
 | [docs/tools.md](docs/tools.md) | direct tools and code mode modules |
 | [docs/prompting.md](docs/prompting.md) | how every model-facing text is written: layers, notes, deliveries, errors, judge questions, terms |
 | [docs/release.md](docs/release.md) | calendar versioning, the manual release steps, how a package is published |
@@ -168,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

@@ -1,17 +1,29 @@
 /**
  * The `AgentBackend` interface: run one window - send the prompt and the tools
- * to a model, stream tool calls, accept inputs inserted once a turn's tool
- * calls finish, report token usage, list the models it can run and log in to
- * their providers (docs/architecture.md#interfaces).
+ * to a model, stream tool calls and what the model is writing, accept inputs
+ * inserted once a turn's tool calls finish, report token usage, list the models
+ * it can run and log in to their providers (docs/architecture.md#interfaces).
  *
  * arbor uses pi-agent-core's `Agent` with its own system prompt: pi's default
  * coding prompt, context files and skills never reach the model
  * (docs/prompting.md#no-built-in-pi-prompt).
  */
 import type { Block } from "./blocks.ts";
+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;
@@ -77,9 +89,47 @@ 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"
+    /**
+     * A plugin's prompt section changed since this window's prefix was built:
+     * the lines that changed, and nothing that did not
+     * (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. */
@@ -92,23 +142,106 @@ 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. */
     pause(): Promise<void>;
     resume(): Promise<void>;
     usage(): TokenUsage;
-    /** Tool calls, results and appends as they happen. */
+    /** Tool calls, results and what the model is writing, as they happen. */
     events(): AsyncIterable<WindowEvent>;
     /** Resolves when the window ends, with why. */
     outcome(): Promise<WindowOutcome>;
 }
+/**
+ * What a window is writing while it runs, one delta at a time
+ * (docs/windows.md#streaming).
+ *
+ * Streams are best-effort and ephemeral: they are not journaled, and the
+ * journal's durable events stay the only record. A backend that cannot report
+ * deltas never emits them, and a consumer that misses one keeps going - the
+ * next delta carries what stands so far.
+ */
+export type StreamEvent = 
+/** Assistant text, as the model writes it. */
+{
+    kind: "text_delta";
+    delta: string;
+}
+/**
+ * One tool call's arguments, as the model writes them. `call.args` is what
+ * has been decoded so far and is best-effort: a call still being written is
+ * not valid JSON yet, so a string argument holds the characters written so
+ * far - which is what makes `send`'s content visible while the model is
+ * still writing it (docs/tools.md#direct-tools). The durable `tool_call`
+ * event carries the complete arguments, once.
+ */
+ | {
+    kind: "tool_call_delta";
+    call: ToolCall;
+};
 /** What a backend streams while a window runs. */
-export type WindowEvent = {
+export type WindowEvent = StreamEvent | {
     kind: "tool_call";
     call: ToolCall;
 } | {
@@ -153,6 +286,20 @@ export interface AgentBackend {
      * reports nothing is never limited.
      */
     rateLimits?(): Promise<RateLimitState> | RateLimitState;
+    /**
+     * 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.
+     *
+     * 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. */
     open(request: OpenWindowRequest): Promise<WindowSession>;
 }
@@ -161,7 +308,23 @@ 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
+     * knows whose it is (docs/tools.md#external-tools).
+     */
+    source?: string;
 }
 /** Called from a script in `code_exec` (docs/tools.md#modules). */
 export interface ModuleSpec {
@@ -193,6 +356,12 @@ export interface ToolResult {
     ok: boolean;
     /** Stable fields, bounded, in the core's error shape when it failed. */
     content: string;
+    /**
+     * The tool that was called, as the prompt names it. A refusal carries it so
+     * the error line starts with the tool name; the catalog fills it on the way
+     * out, so a group that leaves it out still names the call.
+     */
+    tool?: string;
     error?: {
         rule: string;
         message: string;

package/agent.js

@@ -1,8 +1,8 @@
 /**
  * The `AgentBackend` interface: run one window - send the prompt and the tools
- * to a model, stream tool calls, accept inputs inserted once a turn's tool
- * calls finish, report token usage, list the models it can run and log in to
- * their providers (docs/architecture.md#interfaces).
+ * to a model, stream tool calls and what the model is writing, accept inputs
+ * inserted once a turn's tool calls finish, report token usage, list the models
+ * it can run and log in to their providers (docs/architecture.md#interfaces).
  *
  * arbor uses pi-agent-core's `Agent` with its own system prompt: pi's default
  * coding prompt, context files and skills never reach the model

package/blocks.d.ts

@@ -23,6 +23,12 @@ export interface BlockFieldSpec {
     name: string;
     type: "string" | "strings" | "number" | "boolean" | "ref" | "refs" | "blocks";
     required?: boolean;
+    /**
+     * True when the field names the block's own XML tag rather than content: the
+     * renderer writes it as the tag and never as a line of its own
+     * (docs/prompting.md#blocks-and-the-renderer).
+     */
+    tag?: boolean;
 }
 /**
  * A plugin's registration of a block kind: its fields, the tag the renderer
@@ -41,6 +47,12 @@ export interface BlockKindSpec {
     extends?: string;
     /** XML tag the renderer wraps one block in; omitted for an untagged block. */
     tag?: string;
+    /**
+     * The field whose value is this block's XML tag, for a kind whose tag is
+     * chosen per instance - a plugin prompt section's delta, which renders in the
+     * tag the plugin named. Omitted for a kind whose tag is fixed.
+     */
+    tagField?: string;
     fields: readonly BlockFieldSpec[];
     /** Fixed lines written before the fields, by key into the text table. */
     lines?: readonly string[];

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;
@@ -151,7 +155,7 @@ export interface TraceNode {
 /** A target a window is behind on. */
 export interface TargetGap {
     target: Target;
-    /** The newest event on the target. */
+    /** The newest event on the target another window wrote after this one opened. */
     latest: number;
     /** The newest event on the target the window has seen. */
     watermark: number;

package/hooks.d.ts

@@ -8,7 +8,7 @@
  * built from these.
  */
 import type { ArborErrorInfo } from "@4fu/arbor-errors";
-import type { Delivery, RenderedPrompt, ToolCall, ToolResult } from "./agent.ts";
+import type { Delivery, RenderedPrompt, StreamEvent, ToolCall, ToolResult } from "./agent.ts";
 import type { Block } from "./blocks.ts";
 import type { Event, EventInput } from "./events.ts";
 import type { Effect } from "./effects.ts";
@@ -27,6 +27,11 @@ export type HookOutcome<T> = {
     allow: false;
     error: ArborErrorInfo;
 };
+/**
+ * What an after hook answers with: the outcome of what it observed, or nothing
+ * at all. An after hook that observes only answers with nothing.
+ */
+export type AfterHookOutcome<T> = HookOutcome<T> | void;
 export interface AppendContext {
     input: EventInput;
     event?: Event;
@@ -67,12 +72,28 @@ export interface WindowContinueContext {
 export interface ModelRequestContext {
     window: WindowRef;
     prompt: RenderedPrompt;
+    /**
+     * The blocks the window's first input is rendered from, and what a hook
+     * changes is what the window opens with: the host renders what comes back.
+     * The hook runs once per window, before the first turn
+     * (docs/windows.md#prompt-layout).
+     */
     inputs: readonly Block[];
 }
 export interface DeliveryContext {
     window: WindowRef;
     delivery: Delivery;
 }
+/**
+ * One delta of a window's live output, as the model writes it. What a window
+ * says to the outside is the `content` argument of the `send` direct tool, so a
+ * surface that shows a window's output live reads `tool_call_delta`
+ * (docs/windows.md#streaming).
+ */
+export interface WindowStreamContext {
+    window: WindowRef;
+    event: StreamEvent;
+}
 export interface ToolCallContext {
     window: WindowRef;
     call: ToolCall;
@@ -127,8 +148,21 @@ export interface Hooks {
     windowContinue?(context: WindowContinueContext): Promise<HookOutcome<WindowContinueContext>> | HookOutcome<WindowContinueContext>;
     beforeModelRequest?(context: ModelRequestContext): Promise<HookOutcome<ModelRequestContext>> | HookOutcome<ModelRequestContext>;
     beforeDelivery?(context: DeliveryContext): Promise<HookOutcome<DeliveryContext>> | HookOutcome<DeliveryContext>;
+    /**
+     * One delta of a window's live output. Observation only, and best-effort: it
+     * can neither change nor refuse anything, it is not waited for, and a hook
+     * that throws or is slow loses its deltas rather than the window
+     * (docs/windows.md#streaming).
+     */
+    windowStream?(context: WindowStreamContext): Promise<void> | void;
     beforeToolCall?(context: ToolCallContext): Promise<HookOutcome<ToolCallContext>> | HookOutcome<ToolCallContext>;
-    afterToolCall?(context: ToolCallContext): Promise<void> | void;
+    /**
+     * After one call has run. The call is already made, so a refusal cannot undo
+     * it: it stops the hooks after it and leaves the result as it stands. What it
+     * answers with is used - a hook that returns a different `result` replaces
+     * what is recorded and what the model reads (docs/architecture.md#hooks).
+     */
+    afterToolCall?(context: ToolCallContext): Promise<AfterHookOutcome<ToolCallContext>> | AfterHookOutcome<ToolCallContext>;
     beforeEffect?(context: EffectContext): Promise<EffectOutcome> | EffectOutcome;
     beforeNoteWrite?(context: NoteWriteContext): Promise<HookOutcome<NoteWriteContext>> | HookOutcome<NoteWriteContext>;
     afterNoteWrite?(context: NoteWriteContext): Promise<void> | void;

package/index.d.ts

@@ -11,19 +11,19 @@ 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, 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, WorkspaceMount, WorkspaceQuota, Workspace, } from "./workspace.ts";
+export type { ExecResult, StagedFile, OpenWorkItem, WorkspaceCheckout, WorkspaceKeep, WorkspaceMount, WorkspaceQuota, Workspace, } from "./workspace.ts";
 export type { JudgeMode, JudgeDecisionKind, CandidateWindow, JudgeTask, FilterState, RouteState, ModelTierState, NoticeState, BroadcastState, ActiveSetState, FilterRequest, RouteRequest, ModelTierRequest, NoticeRequest, BroadcastRequest, ActiveSetRequest, JudgeRequest, FilterAnswer, RouteScore, RouteAnswer, ModelTierAnswer, WindowDecision, NoticeAnswer, BroadcastAnswer, ActiveSetAnswer, JudgeAnswer, Judge, JudgeCriteria, } from "./judge.ts";
 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 } 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, ScheduledTaskInput, ScheduledTask, ScheduledTaskUpdate, Scheduler, } from "./scheduler.ts";
-export type { HookOutcome, AppendContext, DispatchContext, JudgeContext, WindowStartContext, WindowEndContext, WindowContinueContext, ModelRequestContext, DeliveryContext, ToolCallContext, EffectOutcome, EffectHold, EffectContext, NoteWriteContext, ReloadContext, ServiceStateContext, Hooks, HeldEffect, } from "./hooks.ts";
+export type { QueuedInput, InsertionRequest, InsertionPlan, RateLimitState, AdmissionRequest, AdmissionPlan, SkipPeriod, DailyRepeat, EveryRepeat, RepeatBounds, RepeatRule, WeeklyRepeat, ScheduledTaskInput, ScheduledTask, ScheduledTaskUpdate, Scheduler, } from "./scheduler.ts";
+export type { AfterHookOutcome, HookOutcome, AppendContext, DispatchContext, JudgeContext, WindowStartContext, WindowEndContext, WindowContinueContext, ModelRequestContext, DeliveryContext, WindowStreamContext, ToolCallContext, EffectOutcome, EffectHold, EffectContext, NoteWriteContext, ReloadContext, ServiceStateContext, Hooks, HeldEffect, } from "./hooks.ts";
 export type { PluginAdapters, PromptSection, Plugin, } from "./plugin.ts";
 export type { Settings } from "./settings.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/notes.d.ts

@@ -155,6 +155,8 @@ export interface NotesSnapshot {
     limit: number;
     nextCall: string;
     budget: ActiveSetBudget;
+    /** What the active notes cost against `budget.tokens`, estimated. */
+    tokens: number;
 }
 /** What changed since an epoch: the notes written after it. */
 export interface NoteDelta {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4fu/arbor-interfaces",
-  "version": "2026.1106.0",
+  "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.0"
+    "@4fu/arbor-errors": "2026.1107.0"
   }
 }

package/plugin.d.ts

@@ -5,10 +5,10 @@
  * below; every part is optional, so a plugin can be only a hook, only a skill,
  * or a whole domain such as a chat channel or a code host.
  *
- * Capabilities are MCP servers, not tools: a plugin adds no direct tool or
- * module of its own. What the model can do with it is an MCP server and skills
- * in `/env`, which the model reads, changes and reinstalls with `reload` like
- * any item.
+ * Capabilities the model reads, changes and reinstalls itself are MCP servers
+ * and skills in `/env`. A tool whose behaviour is the plugin's own code rather
+ * than an item in `/env` is declared as an `ExternalTool` and reaches the model
+ * under its own name (docs/tools.md#external-tools).
  */
 import type { Block, BlockKindSpec, TextTable } from "./blocks.ts";
 import type { Channel } from "./channel.ts";
@@ -17,6 +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, ExternalToolSource } from "./tools.ts";
 /** Connections to the outside world. */
 export interface PluginAdapters {
     channels?: readonly Channel[];
@@ -37,6 +38,23 @@ export interface PromptSection {
      * blocks carry data, and the table carries the words.
      */
     text?: TextTable;
+    /**
+     * The section's revision, which the plugin raises when its content changes.
+     * The host asks for it as a window runs - one cheap call per step - and
+     * renders the section again only when it moved, so a section that changes
+     * reaches a live window as a delta carrying the changed lines
+     * (docs/prompting.md#plugin-sections-that-change). Absent for a section that
+     * never changes once the host has rendered it.
+     */
+    revision?(): string | number | Promise<string | number>;
+    /**
+     * True when the section is material from outside the framework - a third
+     * party's prompt text, such as the sections a DeepSeek Harness plugin
+     * contributes. It is marked as data, carries a lead line saying what it is,
+     * and the `<agent>` rules state that the framework's own prompt wins on
+     * conflict (docs/prompting.md#data-and-instructions).
+     */
+    outside?: boolean;
 }
 export interface Plugin {
     readonly name: string;
@@ -45,6 +63,18 @@ export interface Plugin {
     mcpServers?: readonly EnvDraft[];
     /** Skills, installed into `/env/skills` under the plugin's name. */
     skills?: readonly EnvDraft[];
+    /**
+     * Direct tools of its own: declared to the model under the names it gives
+     * 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[] | ExternalToolSource;
     hooks?: Hooks;
     promptSection?: PromptSection;
     /** Extra criteria or decisions for its own inputs. */

package/plugin.js

@@ -5,9 +5,9 @@
  * below; every part is optional, so a plugin can be only a hook, only a skill,
  * or a whole domain such as a chat channel or a code host.
  *
- * Capabilities are MCP servers, not tools: a plugin adds no direct tool or
- * module of its own. What the model can do with it is an MCP server and skills
- * in `/env`, which the model reads, changes and reinstalls with `reload` like
- * any item.
+ * Capabilities the model reads, changes and reinstalls itself are MCP servers
+ * and skills in `/env`. A tool whose behaviour is the plugin's own code rather
+ * than an item in `/env` is declared as an `ExternalTool` and reaches the model
+ * under its own name (docs/tools.md#external-tools).
  */
 export {};

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/scheduler.d.ts

@@ -73,15 +73,33 @@ export interface SkipPeriod {
     from: string;
     to: string;
 }
+/** How a repeating schedule stops: how often it fires, and until when. */
+export interface RepeatBounds {
+    /** How many more times it fires after the first one. */
+    times?: number;
+    /** The last moment it may fire at, in epoch milliseconds. */
+    until?: number;
+}
+/** A period in milliseconds. */
+export interface EveryRepeat extends RepeatBounds {
+    everyMs: number;
+}
+/** A clock time a firing repeats at daily. */
+export interface DailyRepeat extends RepeatBounds {
+    dailyAt: string;
+}
+/** Days of the week, 0 for Sunday, and the clock time it fires at on them. */
+export interface WeeklyRepeat extends RepeatBounds {
+    weekdays: readonly number[];
+    at: string;
+}
+/** How a scheduled task repeats. */
+export type RepeatRule = EveryRepeat | DailyRepeat | WeeklyRepeat;
 export interface ScheduledTaskInput {
     name?: string;
     /** The first firing, in epoch milliseconds. */
     firstAt: number;
-    repeat?: {
-        everyMs: number;
-    } | {
-        dailyAt: string;
-    };
+    repeat?: RepeatRule;
     skipDaily?: readonly SkipPeriod[];
     targets?: readonly Target[];
     task: Omit<TaskInput, "kind">;
@@ -92,11 +110,9 @@ export interface ScheduledTask {
     firstAt: number;
     nextAt: number;
     lastAt?: number;
-    repeat?: {
-        everyMs: number;
-    } | {
-        dailyAt: string;
-    };
+    /** How many times it has fired, so `repeat.times` survives a restart. */
+    fired?: number;
+    repeat?: RepeatRule;
     skipDaily?: readonly SkipPeriod[];
     targets: readonly Target[];
     paused: boolean;

package/settings.d.ts

@@ -58,6 +58,21 @@ export interface Settings {
     workspaces?: {
         /** How long a chain's directory is kept after its last window ended, before the host reclaims it. */
         retentionMs?: number;
+        /**
+         * The shared folder every window works in, for the ovnfs workspace: it can
+         * hold several projects and repositories, and it is read-only by convention.
+         * Absent leaves the plain-directory workspace's own root in place.
+         */
+        shared?: string;
+        /** The ovnfs daemon's paths, under the host's data directory by default. */
+        ovnfs?: {
+            /** Where the daemon keeps its state. */
+            state?: string;
+            /** Where checkouts appear. */
+            mount?: string;
+            /** The ovnfs binary to run; `ovnfs` on PATH by default. */
+            bin?: string;
+        };
     };
     /** The names of the secrets a configuration may use. Never their values. */
     secrets?: readonly string[];

package/task.d.ts

@@ -6,6 +6,12 @@
  * or a service event. Batching is the source's business - a chat source
  * debounces per conversation, so several messages sent in a row become one
  * task. The host makes no tasks of its own for maintenance.
+ *
+ * A source claims the outside events of the source it names: the host hands it
+ * every event whose `OutsideEvent.source` is this source's `id`, and dispatches
+ * the tasks it makes of them as they stand. The host groups nothing of its own
+ * for a source's events, and never debounces on its behalf - a source that
+ * debounces keeps its own buffer.
  */
 import type { Block } from "./blocks.ts";
 import type { OutsideEvent, Unsubscribe } from "./channel.ts";
@@ -41,6 +47,9 @@ export interface TaskSource {
     readonly id: string;
     /** Turn outside events into tasks, batched the way this source batches. */
     toTasks(events: readonly OutsideEvent[]): readonly TaskInput[];
-    /** Push source. The host may poll instead. */
+    /**
+     * Push source. The host may poll instead. The host takes this one at `start`,
+     * the way it takes a channel's, and what it pushes goes through `ingest`.
+     */
     subscribe?(handler: (events: readonly OutsideEvent[]) => void | Promise<void>): Unsubscribe;
 }

package/task.js

@@ -6,5 +6,11 @@
  * or a service event. Batching is the source's business - a chat source
  * debounces per conversation, so several messages sent in a row become one
  * task. The host makes no tasks of its own for maintenance.
+ *
+ * A source claims the outside events of the source it names: the host hands it
+ * every event whose `OutsideEvent.source` is this source's `id`, and dispatches
+ * the tasks it makes of them as they stand. The host groups nothing of its own
+ * for a source's events, and never debounces on its behalf - a source that
+ * debounces keeps its own buffer.
  */
 export {};

package/tools.d.ts

@@ -4,10 +4,12 @@
  *
  * Decisions and plain commands are direct tools, declared to the model and
  * called in the turn. Everything else is a module function, called from a
- * script in `code_exec`. Plugins add no tools of their own; what the model can
- * do with a plugin is an MCP server and skills in `/env`.
+ * script in `code_exec`. A plugin declares its own direct tools as
+ * `ExternalTool`s, which the host registers as a group of their own; what the
+ * 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. */
@@ -31,3 +33,50 @@ export interface ToolGroup {
     call(request: ToolCall, context: CallContext): Promise<ToolResult>;
 }
 export type { DirectToolSpec, FunctionSpec, ModuleSpec, ParameterSpec, ToolCall, ToolResult };
+/**
+ * One direct tool declared from outside the core: a plugin's own, or a
+ * backend's injection of the tools an outside harness registered
+ * (docs/tools.md#external-tools).
+ *
+ * One shape for both, so a plugin and a backend share one path instead of two:
+ * the host registers what it is handed, and from there the tool is a direct
+ * tool like any other - declared to the model under its own name, and called
+ * through the same hooks, journaling, scrub and result cut as the core's own.
+ * Nothing about it is special-cased after registration.
+ */
+export interface ExternalTool {
+    readonly name: string;
+    /** What it does and when to use it; side effects. 1 to 4 sentences. */
+    readonly description: string;
+    /**
+     * 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;
+}

package/tools.js

@@ -4,7 +4,8 @@
  *
  * Decisions and plain commands are direct tools, declared to the model and
  * called in the turn. Everything else is a module function, called from a
- * script in `code_exec`. Plugins add no tools of their own; what the model can
- * do with a plugin is an MCP server and skills in `/env`.
+ * script in `code_exec`. A plugin declares its own direct tools as
+ * `ExternalTool`s, which the host registers as a group of their own; what the
+ * model can otherwise do with a plugin is an MCP server and skills in `/env`.
  */
 export {};

package/windows.d.ts

@@ -57,6 +57,11 @@ export interface BoardLine {
     expects: readonly Expectation[];
     state: WindowState;
     usage: TokenUsage;
+    /**
+     * The work this window still has open in its workspace, each item as the
+     * model reads it (docs/workspaces.md#open-work). Empty when it has none.
+     */
+    openWork?: readonly string[];
 }
 /**
  * What a window expects to arrive, so the input reaches it instead of a new

package/workspace.d.ts

@@ -8,6 +8,7 @@
  */
 import type { TextTable } from "./blocks.ts";
 import type { WindowRef, WorkspaceRef } from "./refs.ts";
+import type { PromptSection } from "./plugin.ts";
 import type { ToolGroup } from "./tools.ts";
 /** The result of one command run in a mounted workspace. */
 export interface ExecResult {
@@ -79,6 +80,46 @@ export interface WorkspaceQuota {
     used: number;
     files: number;
 }
+/**
+ * One checkout a window's chain has open, for an implementation that gives a
+ * window a copy-on-write checkout rather than working in place (the ovnfs
+ * workspace, docs/workspaces.md). `dirty` is true when the checkout holds
+ * changes not yet applied back, which counts as open work at `end`.
+ */
+export interface WorkspaceCheckout {
+    /** The checkout's name, which begins with the window ref that opened it. */
+    name: string;
+    /** The checkout's path on the host, where a command works in it. */
+    path: string;
+    /** The checkout holds changes not yet applied back to the shared folder. */
+    dirty: boolean;
+}
+/**
+ * One persistent directory an implementation keeps beyond a window's own
+ * folder: a named place whose content outlives the window that made it, the
+ * retention period and a host restart, and which a later window finds by name
+ * and uses. The plain directory workspace keeps them under one root beside the
+ * windows' own directories (docs/workspaces.md#persistent-directories).
+ */
+export interface WorkspaceKeep {
+    /** The name the model gave it, which is how a later window names it. */
+    name: string;
+    /** The directory's path on the host, where a command works in it. */
+    path: string;
+}
+/**
+ * One piece of work a window still has open in its workspace: something it
+ * started and has not finished. The ovnfs workspace answers with its unapplied
+ * checkouts; an implementation whose work is finished in place - the plain
+ * directory workspace, which a continuation keeps working in - answers nothing
+ * (docs/workspaces.md#open-work).
+ */
+export interface OpenWorkItem {
+    /** The name the implementation knows it by, which is how a later window names it. */
+    name: string;
+    /** What is open about it, in the implementation's own words, when it has any. */
+    detail?: string;
+}
 export interface Workspace {
     /**
      * Create the window's own directory, on first use. A window that never
@@ -110,4 +151,54 @@ export interface Workspace {
      * about it (docs/workspaces.md, docs/architecture.md#plugins).
      */
     groups?: (table: TextTable) => readonly ToolGroup[];
+    /**
+     * The open checkouts of a window's chain, for `end`'s open-work check, for
+     * `workspace.list` and `workspace.path`, and as the gate reclaim uses. Absent
+     * for an implementation that keeps no checkouts of its own.
+     */
+    checkouts?(window: WindowRef): Promise<readonly WorkspaceCheckout[]>;
+    /**
+     * The work a window still has open: what it started and has not finished.
+     * The host asks for it where a window's own state is not enough - the
+     * reminder tiers name the open items, the board shows them, `end` refuses
+     * without a handoff while any are open, and a continuation's first input
+     * names the ones its predecessor left (docs/windows.md#usage-reminders,
+     * docs/workspaces.md#open-work). Absent for an implementation that keeps
+     * nothing open.
+     */
+    openWork?(window: WindowRef): Promise<readonly OpenWorkItem[]>;
+    /**
+     * The persistent directories a window's chain created, or every one of them
+     * when no window is named - the places whose content outlives the window, the
+     * retention period and a host restart, which a later window finds by name and
+     * uses (docs/workspaces.md#persistent-directories). Absent for an
+     * implementation that keeps none. The host asks for a chain's to name them in
+     * a continuation's first input; a window asks for all of them through the
+     * implementation's own module function.
+     */
+    keeps?(window?: WindowRef): Promise<readonly WorkspaceKeep[]>;
+    /**
+     * The prompt section this implementation contributes, or none. It carries the
+     * method the model follows - how this implementation wants files changed -
+     * rendered in its own tag, so each implementation owns its own prompt text and
+     * a host that fell back to another implementation shows that one's instead.
+     */
+    promptSection?(table: TextTable): PromptSection;
+    /**
+     * The environment a bash command in this window runs with, beyond the host's
+     * own, or none. The ovnfs workspace sets `ARBOR_WINDOW` and the git hook path
+     * that stamps `Arbor-Window` onto commits made in a checkout
+     * (docs/workspaces.md). Set on the command's own process, never on the host,
+     * so it does not reach an MCP server or a service.
+     */
+    bashEnv?(window: WindowRef): Record<string, string>;
+    /**
+     * The built-in skills this implementation seeds into the environment, read
+     * only, or none. The ovnfs workspace seeds the `ovnfs` skill that documents
+     * the full CLI method.
+     */
+    builtinSkills?(): readonly {
+        name: string;
+        source: string;
+    }[];
 }