@4fu/arbor-interfaces 0.1.0 → 2026.1106.1

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.
@@ -118,7 +120,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-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-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 +154,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 |

package/agent.d.ts

@@ -1,14 +1,15 @@
 /**
  * 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";
@@ -80,6 +81,12 @@ export interface ContinuationInfo {
 /** What the host inserts into a running window at a tool-call boundary. */
 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"
     /** 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. */
@@ -102,13 +109,40 @@ export interface WindowSession {
     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 +187,14 @@ 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. Read once, before the first window
+     * opens.
+     */
+    externalTools?(): readonly ExternalTool[] | Promise<readonly ExternalTool[]>;
     /** Open one window and start its first turn. */
     open(request: OpenWindowRequest): Promise<WindowSession>;
 }
@@ -162,6 +204,12 @@ export interface DirectToolSpec {
     /** What it does and when to use it; side effects. 1 to 4 sentences. */
     description: string;
     parameters: Record<string, ParameterSpec>;
+    /**
+     * 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 +241,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

@@ -151,7 +151,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

@@ -12,18 +12,18 @@ export type { BlockValue, Block, BlockKind, BlockFieldSpec, BlockKindSpec, TextT
 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 { 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 { 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 } 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/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": "0.1.0",
+  "version": "2026.1106.1",
   "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": "0.1.0"
+    "@4fu/arbor-errors": "2026.1106.1"
   }
 }

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 } 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,13 @@ 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.
+     */
+    tools?: readonly ExternalTool[];
     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/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,8 +4,9 @@
  *
  * 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 { EventRef, WindowRef } from "./refs.ts";
@@ -31,3 +32,22 @@ 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;
+    readonly parameters: Record<string, ParameterSpec>;
+    /** Run one call. The same path a core tool takes. */
+    execute(request: ToolCall, context: CallContext): Promise<ToolResult>;
+}

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;
+    }[];
 }