@4fu/arbor-interfaces 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4fuu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# arbor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+arbor is a framework for an agent without sessions: many context windows run
+at once over one shared record, so work moves in parallel, replies come fast,
+and every window can find everything that was ever done.
+
+A deployment composes the pieces it wants and registers plugins for the domains
+it serves. The framework guarantees what an agent cannot guarantee for itself -
+the record, isolation, exactly-once effects, the checks, dispatch - and leaves
+everything that takes judgment, such as git, merges and conflicts, to the agent.
+
+## Core ideas
+
+- **No sessions to manage.** Work runs in disposable context windows. Any
+  number run at the same time; none of them owns anything, and a window that
+  ends loses nothing. The model looks up what it needs instead of carrying it.
+- **One record, shared live.** Every input, tool call, result, send and note
+  revision goes into one journal and is visible to every window as
+  soon as it is written. Records never merge and are never lost.
+- **Dispatch by a judge.** A judge (Jev by default, replaceable) decides which
+  live window takes a new input, or opens a new one. There is no router session
+  and no main line.
+- **Current without locks.** Windows run in parallel. New events on a
+  conversation a window is in are steered into it as they arrive; only a note
+  write is checked against the revision the window read.
+- **Mechanisms in the framework, policy in the agent.** The framework
+  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 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.
+- **Minimal limits.** The framework sets no policy. Permissions, privacy
+  review, budgets and approvals belong to deployments built on it, through
+  hooks.
+- **Direct tools plus code mode.** Decisions are direct tools; everything else
+  is a module called from `code_exec`. There is no CLI.
+- **Every module is replaceable.** The agent backend (pi by default), the
+  journal, notes, workspaces, the judge, channels and the rest are interfaces
+  ([docs/architecture.md](docs/architecture.md#interfaces)).
+
+## Install
+
+Node 24 or newer. Every package is published separately, so a deployment
+installs the core and the defaults it wants:
+
+```sh
+npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
+  @4fu/arbor-environment-dir @4fu/arbor-supervisor-process @4fu/arbor-agent-pi \
+  @4fu/arbor-workspace-dir
+```
+
+`@4fu/arbor-plugin-http` is optional; it is the example plugin below.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+
+## A minimal host
+
+The smallest host needs a journal and a backend. Adding the defaults and one
+plugin is what a deployment usually starts from:
+
+```js
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Arbor } from "@4fu/arbor-core";
+import { DirectoryEnvironment } from "@4fu/arbor-environment-dir";
+import { SqliteJournal } from "@4fu/arbor-journal-sqlite";
+import { SqliteNoteStore } from "@4fu/arbor-notes-sqlite";
+import { ProcessSupervisor } from "@4fu/arbor-supervisor-process";
+import { DirectoryWorkspace } from "@4fu/arbor-workspace-dir";
+import { PiAgentBackend } from "@4fu/arbor-agent-pi";
+import { HttpChannel, httpPlugin } from "@4fu/arbor-plugin-http";
+
+const root = await mkdtemp(join(tmpdir(), "arbor-"));
+
+// Every module below is a default implementation of an interface. Replace any
+// one by passing your own; the host does not change.
+const journal = new SqliteJournal({ path: join(root, "journal.sqlite") });
+const notes = new SqliteNoteStore({ path: join(root, "notes.sqlite"), journal });
+const supervisor = new ProcessSupervisor({ root: join(root, "services") });
+const environment = new DirectoryEnvironment({ root: join(root, "env"), supervisor });
+const workspace = new DirectoryWorkspace({ root: join(root, "workspaces") });
+
+// A plugin adds; it never patches the core. This one is a chat channel: a
+// webhook in, a window's sends out, and a page that drives the whole host.
+let arbor;
+const channel = new HttpChannel({ host: "127.0.0.1", port: 8787, board: () => arbor.boardLines() });
+arbor = new Arbor({
+  journal,
+  notes,
+  backend: new PiAgentBackend(),
+  workspace,
+  environment,
+  supervisor,
+  plugins: [httpPlugin({ channel })],
+});
+
+await arbor.start();
+await channel.listen();
+```
+
+`arbor.open(task)` dispatches one task, and the journal is where everything that
+happened can be read back ([docs/journal.md](docs/journal.md)). The workspace a
+window gets, and how a continuation keeps working in it, are in
+[docs/workspaces.md](docs/workspaces.md).
+
+## Packages
+
+| Package | What it is |
+| --- | --- |
+| [`@4fu/arbor-interfaces`](packages/interfaces) | every replaceable interface, plus the core's own shapes. Types only. |
+| [`@4fu/arbor-errors`](packages/errors) | the error shape every refusal uses: the rule and the next action |
+| [`@4fu/arbor-prompt`](packages/prompt) | typed blocks, the one deterministic renderer and the replaceable text table |
+| [`@4fu/arbor-tools`](packages/tools) | the entry points: direct tools, code mode modules, the host API |
+| [`@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-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 |
+| [`@4fu/arbor-agent-pi`](packages/agent-pi) | the default `AgentBackend`: pi-agent-core in process |
+| [`@4fu/arbor-plugin-http`](packages/plugin-http) | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| [`@4fu/arbor-core`](packages/core) | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects and schedules |
+
+### Defaults are examples
+
+Every default above is a reference implementation of its interface, written to
+be read and replaced. A real deployment is expected to swap out the ones that do
+not fit: the SQLite journal and notes, the directory workspace, the process
+supervisor, the environment directory, the HTTP test plugin and the Jev judge
+are all examples of what an interface can be satisfied by, not commitments.
+What a deployment keeps is its own choice, and the interfaces are the contract
+([docs/architecture.md](docs/architecture.md#interfaces)).
+
+Each package's own documentation holds the limits of that default, so a
+deployment can see what it would be taking on before it adopts one.
+
+## Documents
+
+| Page | Contents |
+| --- | --- |
+| [docs/overview.md](docs/overview.md) | goals, concepts, principles, routes considered |
+| [docs/architecture.md](docs/architecture.md) | layers, interfaces, stack, models, plugins, hooks, data placement |
+| [docs/journal.md](docs/journal.md) | events and their order, targets, watermarks, external ids, refs, tracing, media, redaction |
+| [docs/windows.md](docs/windows.md) | window lifecycle, prompt layout, reminders, continuation |
+| [docs/dispatch.md](docs/dispatch.md) | task sources, judge decisions, insertion timing, backpressure, scheduled tasks |
+| [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/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 |
+
+## Repository layout
+
+`pnpm check` typechecks and tests every package on its TypeScript sources.
+`pnpm build` emits the `dist` publishing needs, and `pnpm pack` shows what each
+tarball would contain ([docs/release.md](docs/release.md)).
+
+| Path | Layer |
+| --- | --- |
+| `packages/interfaces` | the interfaces layer: every replaceable interface, plus the core's own shapes. Types only. |
+| `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/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 |
+| `packages/environment-dir` | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
+| `packages/supervisor-process` | the default `Supervisor`: one host process per service, restart with backoff, logs |
+| `packages/plugin-http` | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| `packages/prompt` | typed blocks, the one deterministic renderer and the replaceable text table |
+| `packages/agent-pi` | the default `AgentBackend`: pi-agent-core in process |
+| `packages/tools` | the entry points: direct tools, code mode modules, the host API |
+| `packages/core` | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects, schedules and the snapshot epochs |
+
+`mise.toml` pins the toolchain - Node and pnpm - installed under
+`~/.local/share/mise`, and `.agents/setup` prepares a machine from it. A machine
+without mise is expected to carry Node 24 or newer and pnpm 12 already.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/agent.d.ts

@@ -0,0 +1,202 @@
+/**
+ * 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).
+ *
+ * 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 { TaskRef, Ref, WindowRef } from "./refs.ts";
+import type { Handoff, TokenUsage, WindowState } from "./windows.ts";
+import type { RateLimitState } from "./scheduler.ts";
+/** One model the backend can run. Only models that take images are offered. */
+export interface ModelInfo {
+    id: string;
+    provider: string;
+    /** The tier settings map this model to, when the backend knows one. */
+    tier?: string;
+    name?: string;
+    images: boolean;
+}
+export type LoginState = "logged-in" | "logged-out" | "failed";
+export interface LoginRequest {
+    provider: string;
+    /** The name of a secret; a configuration never holds a secret's value. */
+    secret?: string;
+}
+export interface LoginResult {
+    provider: string;
+    state: LoginState;
+    models: ModelInfo[];
+    error?: string;
+}
+/** The prompt a window is opened with: the frozen prefix of its epoch. */
+export interface RenderedPrompt {
+    /** `<identity>`, `<agent>`, `<tools>`, `<modules>`, `<env>`, plugin sections. */
+    system: string;
+    /** The active notes, by summary. */
+    memory: string;
+    /** The environment revision the prompt was rendered against. */
+    envRevision: string;
+}
+/** What a window is opened for. */
+export interface OpenWindowRequest {
+    window: WindowRef;
+    task: TaskRef;
+    prompt: RenderedPrompt;
+    tools: readonly DirectToolSpec[];
+    modules: readonly ModuleSpec[];
+    /** The model the tier maps to, resolved from the backend's catalog. */
+    model: string;
+    /**
+     * The first input, already rendered by the host's one renderer: the task,
+     * the board lines related to it and, for a continuation, the previous
+     * window's ref and handoff (docs/prompting.md#layers).
+     */
+    firstInput?: string;
+    /** The workspace mounted for this window, when it has one. */
+    workspace?: string;
+    limits: WindowLimits;
+    continuation?: ContinuationInfo;
+}
+export interface WindowLimits {
+    /** The context window's token budget. */
+    contextTokens: number;
+    /** Tokens held back from the model, for the final reminder. */
+    reserveTokens: number;
+    /** How long an ended run stays open for a related input, in seconds. */
+    idleSeconds: number;
+}
+/** A continuation's first input carries these. */
+export interface ContinuationInfo {
+    previous: WindowRef;
+    handoff?: Handoff;
+    /** 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. */
+export interface Delivery {
+    kind: "inserted_task" | "conversation_update" | "notice" | "broadcast" | "window_message" | "environment_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. */
+    from?: WindowRef;
+    refs: readonly Ref[];
+    time: number;
+    content: readonly Block[];
+}
+/** One running window, owned by the backend. */
+export interface WindowSession {
+    readonly window: WindowRef;
+    readonly state: WindowState;
+    /** Insert at the next tool-call boundary, through the backend's steering. */
+    steer(delivery: Delivery): Promise<void>;
+    /** Queue for after the run ends. */
+    followUp(delivery: Delivery): Promise<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. */
+    events(): AsyncIterable<WindowEvent>;
+    /** Resolves when the window ends, with why. */
+    outcome(): Promise<WindowOutcome>;
+}
+/** What a backend streams while a window runs. */
+export type WindowEvent = {
+    kind: "tool_call";
+    call: ToolCall;
+} | {
+    kind: "tool_result";
+    call: ToolCall;
+    result: ToolResult;
+} | {
+    kind: "appended";
+    event: string;
+} | {
+    kind: "steered";
+    delivery: Delivery;
+} | {
+    kind: "usage";
+    usage: TokenUsage;
+}
+/** The run ended. The window stays open for a related input (docs/windows.md#lifecycle). */
+ | {
+    kind: "run_ended";
+    outcome: WindowOutcome;
+} | {
+    kind: "ended";
+    outcome: WindowOutcome;
+};
+export type WindowEndReason = "model_ended" | "idle_timeout" | "hard_limit" | "host_restart" | "paused" | "failed";
+export interface WindowOutcome {
+    window: WindowRef;
+    reason: WindowEndReason;
+    handoff?: Handoff;
+    usage: TokenUsage;
+    error?: string;
+}
+export interface AgentBackend {
+    readonly name: string;
+    /** The catalog the backend can run. Only models that take images are offered. */
+    models(): Promise<ModelInfo[]>;
+    login(request: LoginRequest): Promise<LoginResult>;
+    /**
+     * The backend's rate limits, when it reports any. There is no cap on windows;
+     * how many run at once is bounded by the backend, so new windows wait in a
+     * queue while it is limited (docs/dispatch.md#backpressure). A backend that
+     * reports nothing is never limited.
+     */
+    rateLimits?(): Promise<RateLimitState> | RateLimitState;
+    /** Open one window and start its first turn. */
+    open(request: OpenWindowRequest): Promise<WindowSession>;
+}
+/** Declared to the model and called in the turn (docs/tools.md#direct-tools). */
+export interface DirectToolSpec {
+    name: string;
+    /** What it does and when to use it; side effects. 1 to 4 sentences. */
+    description: string;
+    parameters: Record<string, ParameterSpec>;
+}
+/** Called from a script in `code_exec` (docs/tools.md#modules). */
+export interface ModuleSpec {
+    name: string;
+    /** What the module can do, never a function name. */
+    description: string;
+    functions: readonly FunctionSpec[];
+}
+export interface FunctionSpec {
+    /** `module.function`. */
+    name: string;
+    signature: string;
+    description: string;
+}
+export interface ParameterSpec {
+    type: "string" | "number" | "boolean" | "ref" | "refs" | "blocks" | "object" | "array";
+    description: string;
+    required?: boolean;
+    default?: unknown;
+}
+/** One direct tool or module call, as the backend reports it. */
+export interface ToolCall {
+    name: string;
+    args: Record<string, unknown>;
+    callId: string;
+}
+export interface ToolResult {
+    callId: string;
+    ok: boolean;
+    /** Stable fields, bounded, in the core's error shape when it failed. */
+    content: string;
+    error?: {
+        rule: string;
+        message: string;
+        nextAction?: string;
+        refs?: readonly Ref[];
+    };
+}

package/agent.js

@@ -0,0 +1,11 @@
+/**
+ * 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).
+ *
+ * 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).
+ */
+export {};

package/blocks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed blocks and the text table (docs/prompting.md).
+ *
+ * No component writes prompt text. Everything that reaches a model - a system
+ * prompt section, a delivery, a reminder, a note, a result, an error - is a
+ * typed block: a kind and its fields. One renderer, owned by the host, turns
+ * blocks into text by fixed rules, so the same blocks always give the same
+ * bytes. A plugin registers kinds of its own and hands the host blocks, never
+ * finished text.
+ */
+import type { Ref } from "./refs.ts";
+/** A field value inside a block. */
+export type BlockValue = string | number | boolean | Ref | readonly Ref[] | readonly string[] | readonly Block[];
+/** One typed block. */
+export interface Block<K extends string = string> {
+    kind: K;
+    fields: Record<string, BlockValue>;
+}
+/** Built-in block kinds. Plugins add their own through `BlockKindSpec`. */
+export type BlockKind = "task" | "board_line" | "handoff" | "note" | "note_summary" | "reminder" | "tool_result" | "error" | "data" | "outside_message" | (string & {});
+/** Declares one field of a block kind. */
+export interface BlockFieldSpec {
+    name: string;
+    type: "string" | "strings" | "number" | "boolean" | "ref" | "refs" | "blocks";
+    required?: boolean;
+}
+/**
+ * A plugin's registration of a block kind: its fields, the tag the renderer
+ * wraps it in, and the fixed lines the renderer writes before its fields. The
+ * mapping is declarative so rendering stays deterministic and in one place.
+ */
+export interface BlockKindSpec {
+    kind: string;
+    /**
+     * A kind this one extends, built-in or another plugin's. Its tag, fields,
+     * lines and data mark are kept, and this spec's are added to them, so a
+     * plugin adds its own fields to a block the core builds - a note, an outside
+     * message - and the one renderer still renders it
+     * (docs/prompting.md#blocks-and-the-renderer).
+     */
+    extends?: string;
+    /** XML tag the renderer wraps one block in; omitted for an untagged block. */
+    tag?: string;
+    fields: readonly BlockFieldSpec[];
+    /** Fixed lines written before the fields, by key into the text table. */
+    lines?: readonly string[];
+    /** Outside content is data, never instructions, and is marked where delivered. */
+    data?: boolean;
+}
+/**
+ * One text table entry per fixed string the framework writes: section
+ * headings, delivery lines, reminders, descriptions, errors. A deployment
+ * replaces the table to change the language or the wording; no fixed text is
+ * written anywhere else. Identifiers stay as they are.
+ */
+export type TextTable = Record<string, string>;

package/blocks.js

@@ -0,0 +1,11 @@
+/**
+ * Typed blocks and the text table (docs/prompting.md).
+ *
+ * No component writes prompt text. Everything that reaches a model - a system
+ * prompt section, a delivery, a reminder, a note, a result, an error - is a
+ * typed block: a kind and its fields. One renderer, owned by the host, turns
+ * blocks into text by fixed rules, so the same blocks always give the same
+ * bytes. A plugin registers kinds of its own and hands the host blocks, never
+ * finished text.
+ */
+export {};

package/channel.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The `Channel` interface: an outside source and sink - look up a message by
+ * its native id, list what is connected, report online state
+ * (docs/architecture.md#interfaces).
+ *
+ * An outside message keeps its native id, with a short channel prefix:
+ * `qq:12345`. No second id is made up for it. When the channel is offline the
+ * lookup returns the stored copy and says the channel is offline; a channel
+ * plugged back in matches the same ids.
+ */
+import type { Block } from "./blocks.ts";
+import type { ExternalRef, Ref, Target } from "./refs.ts";
+/** One event from outside, before a task source turns it into a task. */
+export interface OutsideEvent {
+    /** The channel or service it came from: `qq`, `svc:crawler`. */
+    source: string;
+    /** Its native id, with the channel prefix: `qq:12345`. */
+    external?: ExternalRef;
+    /** What it touches: the conversation, the issue, the service. */
+    target: Target;
+    time: number;
+    content: readonly Block[];
+    /** The outside message it answers, when it is a reply. */
+    replyTo?: ExternalRef;
+    refs?: readonly Ref[];
+}
+/** What a channel lookup returns: the stored copy, plus the channel's state. */
+export interface OutsideMessage extends OutsideEvent {
+    external: ExternalRef;
+    /** True when the copy came from the journal rather than the live channel. */
+    stored: boolean;
+}
+export interface ChannelConnection {
+    id: string;
+    online: boolean;
+    detail?: string;
+}
+export interface SendRequest {
+    channel: string;
+    /** The conversation or item it goes to. */
+    target: Target;
+    content: readonly Block[];
+    /** The outside message it answers, by native id. */
+    replyTo?: ExternalRef;
+}
+export interface SendResult {
+    external: ExternalRef;
+    time: number;
+}
+export type Unsubscribe = () => void | Promise<void>;
+export interface Channel {
+    readonly id: string;
+    /** What is connected, and whether each connection is online. */
+    connections(): Promise<readonly ChannelConnection[]>;
+    /** Look up a message by its native id. Returns the stored copy when offline. */
+    get(nativeId: ExternalRef): Promise<OutsideMessage | null>;
+    /** The sink: send out. Used by an effect executor, never by a window directly. */
+    send?(request: SendRequest): Promise<SendResult>;
+    /** Push source. A host that prefers polling may ignore this. */
+    subscribe?(handler: (events: readonly OutsideEvent[]) => void | Promise<void>): Unsubscribe;
+}

package/channel.js

@@ -0,0 +1,11 @@
+/**
+ * The `Channel` interface: an outside source and sink - look up a message by
+ * its native id, list what is connected, report online state
+ * (docs/architecture.md#interfaces).
+ *
+ * An outside message keeps its native id, with a short channel prefix:
+ * `qq:12345`. No second id is made up for it. When the channel is offline the
+ * lookup returns the stored copy and says the channel is offline; a channel
+ * plugged back in matches the same ids.
+ */
+export {};

package/effects.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `EffectExecutor` interface and the effect queue's shapes
+ * (docs/architecture.md#interfaces, docs/coordination.md#effects).
+ *
+ * An effect takes place when it is made and cannot be rolled back. So every
+ * effect goes through one queue per host, which paces effects and executes
+ * each exactly once, in the order made; effects on one target are serial. Each
+ * effect is recorded as an event, so continuations and restarts never repeat
+ * it.
+ */
+import type { Block } from "./blocks.ts";
+import type { ExternalRef, Ref, Target, WindowRef } from "./refs.ts";
+import type { ArborErrorInfo } from "@4fu/arbor-errors";
+export type EffectKind = "send" | (string & {});
+/** One queued effect, as the host hands it to an executor. */
+export interface Effect {
+    /** The event that recorded it, so a continuation never repeats it. */
+    event: Ref;
+    kind: EffectKind;
+    target: Target;
+    /** The outside address, for a send. */
+    to?: string;
+    content: readonly Block[];
+    /** The outside message it answers. */
+    replyTo?: ExternalRef;
+    cites?: readonly Ref[];
+    madeBy: WindowRef;
+    time: number;
+}
+export interface EffectResult {
+    ok: boolean;
+    /** The native id the outside world gave it, for the event's `external`. */
+    external?: ExternalRef;
+    error?: ArborErrorInfo;
+}
+export interface EffectExecutor {
+    readonly id: string;
+    /** Whether this executor owns the effect. One that does not refuses it. */
+    can(effect: Effect): boolean;
+    /** Carry the effect out. Called once per effect, by the queue. */
+    run(effect: Effect): Promise<EffectResult>;
+}

package/effects.js

@@ -0,0 +1,11 @@
+/**
+ * The `EffectExecutor` interface and the effect queue's shapes
+ * (docs/architecture.md#interfaces, docs/coordination.md#effects).
+ *
+ * An effect takes place when it is made and cannot be rolled back. So every
+ * effect goes through one queue per host, which paces effects and executes
+ * each exactly once, in the order made; effects on one target are serial. Each
+ * effect is recorded as an event, so continuations and restarts never repeat
+ * it.
+ */
+export {};