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

package/judge.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The `Judge` interface: answer the host's decisions - filter, route, model
+ * tier, notice, broadcast, active set (docs/architecture.md#interfaces,
+ * docs/dispatch.md#judge-decisions).
+ *
+ * The judge decides whether, where and when. It never writes text; the model
+ * owns content. It is a classifier, not the main model.
+ *
+ * What is *not* here: the rule bounds and the fallbacks. Those live in code
+ * that never moves, in the service layer, so an unreachable judge changes
+ * nothing about the rules.
+ */
+import type { Block } from "./blocks.ts";
+import type { NoteRef, Ref, Target, TaskRef, WindowRef } from "./refs.ts";
+export type JudgeMode = "off" | "shadow" | "on";
+export type JudgeDecisionKind = "filter" | "route" | "model_tier" | "notice" | "broadcast" | "active_set";
+/** A window's profile, assembled by the host with no extra model call. */
+export interface CandidateWindow {
+    window: WindowRef;
+    /** Its board line. */
+    doing: string;
+    targets: readonly Target[];
+    expects: readonly string[];
+    state: "running" | "idle";
+    usage: {
+        used: number;
+        limit: number;
+    };
+    /** The tasks it has taken, newest first. */
+    tasks: readonly string[];
+    /** Its last inputs, by ref and opening words. */
+    lastInputs: ReadonlyArray<{
+        ref: Ref;
+        summary: string;
+    }>;
+    /** Whether it has had its final usage reminder. */
+    finalReminderSent: boolean;
+}
+/** A task as the judge sees it: its targets, its reason and its content. */
+export interface JudgeTask {
+    ref: TaskRef;
+    kind: "batch" | "scheduled" | "service";
+    reason: string;
+    targets: readonly Target[];
+    content: readonly Block[];
+    time: number;
+}
+export interface FilterState {
+    task: JudgeTask;
+    /** Explicit requests always pass. */
+    explicit: boolean;
+}
+export interface RouteState {
+    task: JudgeTask;
+    /** The live windows that share a target, describe an expectation, or worked recently. */
+    candidates: readonly CandidateWindow[];
+}
+export interface ModelTierState {
+    task: JudgeTask;
+    /** Only configured tiers. */
+    tiers: readonly string[];
+    /**
+     * What each tier is for, as the question reads it: one line per tier name,
+     * from `settings.judge.tierCriteria`. A tier named here with no text falls
+     * back to the judge's own description of it.
+     */
+    criteria?: Record<string, string>;
+}
+export interface NoticeState {
+    /** The event that touched the target. */
+    event: {
+        ref: Ref;
+        kind: string;
+        target: Target;
+        summary: string;
+    };
+    /** Only windows that touched the event's target. */
+    candidates: readonly CandidateWindow[];
+}
+export interface BroadcastState {
+    broadcast: {
+        from: WindowRef | null;
+        summary: string;
+        refs: readonly Ref[];
+    };
+    candidates: readonly CandidateWindow[];
+    /** Environment deltas are never filtered. */
+    unfiltered?: boolean;
+}
+export interface ActiveSetState {
+    notes: ReadonlyArray<{
+        ref: NoteRef;
+        summary: string;
+        score: number;
+    }>;
+    budget: {
+        count: number;
+        tokens: number;
+    };
+    /** The bounded share the judge may add, which never outweighs the rule score. */
+    judgeShare: number;
+}
+export interface FilterRequest {
+    decision: "filter";
+    mode: JudgeMode;
+    state: FilterState;
+    criteria?: readonly string[];
+}
+export interface RouteRequest {
+    decision: "route";
+    mode: JudgeMode;
+    state: RouteState;
+    criteria?: readonly string[];
+}
+export interface ModelTierRequest {
+    decision: "model_tier";
+    mode: JudgeMode;
+    state: ModelTierState;
+    criteria?: readonly string[];
+}
+export interface NoticeRequest {
+    decision: "notice";
+    mode: JudgeMode;
+    state: NoticeState;
+    criteria?: readonly string[];
+}
+export interface BroadcastRequest {
+    decision: "broadcast";
+    mode: JudgeMode;
+    state: BroadcastState;
+    criteria?: readonly string[];
+}
+export interface ActiveSetRequest {
+    decision: "active_set";
+    mode: JudgeMode;
+    state: ActiveSetState;
+    criteria?: readonly string[];
+}
+export type JudgeRequest = FilterRequest | RouteRequest | ModelTierRequest | NoticeRequest | BroadcastRequest | ActiveSetRequest;
+export interface FilterAnswer {
+    decision: "filter";
+    needsHandling: boolean;
+    /**
+     * The judge's own reading, on the question's own scale: a bool question's
+     * probability. The service layer owns the threshold and reads this when the
+     * answer carries one, so a judge that answers with a probability and one that
+     * answers with a bare boolean are read the same way.
+     */
+    score?: number;
+    reason?: string;
+}
+export interface RouteScore {
+    /** A window ref, or `new` for a new window. */
+    item: WindowRef | "new";
+    score: number;
+    reason?: string;
+}
+export interface RouteAnswer {
+    decision: "route";
+    scores: readonly RouteScore[];
+    best: WindowRef | "new";
+}
+export interface ModelTierAnswer {
+    decision: "model_tier";
+    tier: string;
+}
+export interface WindowDecision {
+    window: WindowRef;
+    needs: boolean;
+    /** The judge's own reading, for the service layer's threshold. */
+    score?: number;
+    reason?: string;
+}
+export interface NoticeAnswer {
+    decision: "notice";
+    windows: readonly WindowDecision[];
+}
+export interface BroadcastAnswer {
+    decision: "broadcast";
+    windows: readonly WindowDecision[];
+}
+export interface ActiveSetAnswer {
+    decision: "active_set";
+    keep: readonly NoteRef[];
+    drop: readonly NoteRef[];
+    /**
+     * Each candidate's level on the score question's own scale, for the service
+     * layer's own threshold. Absent from a judge that answers with the two lists
+     * alone.
+     */
+    scores?: readonly {
+        ref: NoteRef;
+        score: number;
+    }[];
+}
+export type JudgeAnswer = FilterAnswer | RouteAnswer | ModelTierAnswer | NoticeAnswer | BroadcastAnswer | ActiveSetAnswer;
+export interface Judge {
+    readonly name: string;
+    /** Answer one decision. One request per decision, with its questions batched. */
+    decide(request: JudgeRequest): Promise<JudgeAnswer>;
+}
+/** Extra criteria a plugin registers for its own inputs. */
+export interface JudgeCriteria {
+    decision: JudgeDecisionKind;
+    criteria: readonly string[];
+}

package/judge.js

@@ -0,0 +1,13 @@
+/**
+ * The `Judge` interface: answer the host's decisions - filter, route, model
+ * tier, notice, broadcast, active set (docs/architecture.md#interfaces,
+ * docs/dispatch.md#judge-decisions).
+ *
+ * The judge decides whether, where and when. It never writes text; the model
+ * owns content. It is a classifier, not the main model.
+ *
+ * What is *not* here: the rule bounds and the fallbacks. Those live in code
+ * that never moves, in the service layer, so an unreachable judge changes
+ * nothing about the rules.
+ */
+export {};

package/notes.d.ts

@@ -0,0 +1,215 @@
+/**
+ * The `NoteStore` interface: notes are the long-term memory, one copy shared by
+ * every window, written only through the note tools (docs/memory.md).
+ */
+import type { EventRef, NoteId, NoteRef, Ref, Target, WindowRef } from "./refs.ts";
+import type { Page } from "./events.ts";
+/**
+ * A note is `active` in the current epoch's active set, `archived` when it is
+ * not, and `deleted` once a delete wrote a tombstone: every revision and every
+ * ref to them keep resolving, but no list, search or active set returns it.
+ */
+export type NoteStatus = "active" | "archived" | "deleted";
+/** Where a revision happened. The host records it; the model never fills it in. */
+export interface Anchor {
+    window: WindowRef;
+    event: EventRef;
+    evidence?: readonly Ref[];
+    range?: string;
+}
+/** What a write carries. A write, replace or delete names the revision it read. */
+export interface NoteWriteInput {
+    /** Omit for a new note. */
+    id?: NoteId;
+    title: string;
+    /** At most 200 characters. */
+    summary?: string;
+    body: string;
+    /** The revision the writer read. A stale one is refused with what changed. */
+    expectedRevision?: number;
+    anchor?: Anchor;
+    refs?: readonly Ref[];
+    /** Replace the body, or delete the note. Both name the revision read. */
+    replace?: boolean;
+    delete?: boolean;
+}
+export interface Note {
+    ref: NoteRef;
+    id: NoteId;
+    title: string;
+    summary: string;
+    body: string | null;
+    status: NoteStatus;
+    revision: number;
+    anchor?: Anchor;
+    time: number;
+    window: WindowRef | null;
+}
+/** What a list shows: summaries, never bodies. */
+export interface NoteSummary {
+    ref: NoteRef;
+    id: NoteId;
+    title: string;
+    summary: string;
+    status: NoteStatus;
+    revision: number;
+    time: number;
+}
+/** A paged body. */
+export interface NoteBody {
+    ref: NoteRef;
+    revision: number;
+    body: string;
+    /** The whole body's length in characters, before the page cut. */
+    total: number;
+    nextCall: string;
+}
+export interface NoteRevision {
+    ref: NoteRef;
+    revision: number;
+    window: WindowRef | null;
+    time: number;
+    summary: string;
+    anchor?: Anchor;
+    refs: readonly Ref[];
+}
+/** What `notes.context(ref)` restores: the surroundings of a revision. */
+export interface NoteContext {
+    ref: NoteRef;
+    revision: number;
+    anchor?: Anchor;
+    /** The events around the one the anchor names. */
+    events: readonly string[];
+    evidence: readonly Ref[];
+}
+export interface NoteQuery {
+    query?: string;
+    status?: NoteStatus;
+    /** Notes about a target. */
+    about?: Target;
+    linked?: Ref;
+    limit?: number;
+    offset?: number;
+}
+/** What a refused write carries: what changed since the revision it read. */
+export interface NoteConflictInfo {
+    read: number;
+    current: number;
+    revisions: readonly NoteRevision[];
+}
+/** The active set's budget: a count and a token estimate (docs/memory.md). */
+export interface ActiveSetBudget {
+    count: number;
+    tokens: number;
+}
+/** One candidate for the active set, with its usage score. */
+export interface ActiveCandidate {
+    ref: NoteRef;
+    id: NoteId;
+    summary: string;
+    score: number;
+}
+/**
+ * What a use of a note carries. The host records it from the events it
+ * appends; the model never declares one (docs/memory.md#the-active-set).
+ */
+export type NoteUseKind = "cite" | "evidence" | "read";
+export interface NoteUseInput {
+    ref: NoteRef;
+    kind: NoteUseKind;
+    /** The window that used it. */
+    window?: WindowRef;
+    /** The event that used it, so one event is recorded once. */
+    event?: EventRef;
+    /** The link's weight; a bare cite is weaker than a declared one. */
+    weight?: number;
+    time?: number;
+}
+/** What `snapshot` takes. */
+export interface SnapshotOptions {
+    /** Rebuild at most this often, in ms. 10 minutes. */
+    minIntervalMs?: number;
+    /** The active set's budget. */
+    budget?: ActiveSetBudget;
+    /**
+     * The notes the judge keeps, within its bounded share. The share is
+     * additive: the judge adds notes the rule score did not pick and never drops
+     * one it did, because it never outweighs the model's own use.
+     */
+    judgeKeep?: readonly NoteRef[];
+    /** The share of the budget the judge may add. */
+    judgeShare?: number;
+}
+/**
+ * One frozen memory snapshot: the active notes of one epoch, with the epoch's
+ * version (docs/windows.md#prompt-layout). Every window opened in one epoch
+ * freezes the same bytes; what changed since is `delta`.
+ */
+export interface NotesSnapshot {
+    /** The epoch's version. */
+    epoch: number;
+    time: number;
+    /** The active notes, by summary, sorted by id. */
+    items: readonly NoteSummary[];
+    total: number;
+    limit: number;
+    nextCall: string;
+    budget: ActiveSetBudget;
+}
+/** What changed since an epoch: the notes written after it. */
+export interface NoteDelta {
+    /** The epoch asked about; `0` for every note. */
+    since: number;
+    /** The current epoch. */
+    epoch: number;
+    items: readonly NoteDeltaItem[];
+    total: number;
+    limit: number;
+    nextCall: string;
+}
+export interface NoteDeltaItem {
+    ref: NoteRef;
+    id: NoteId;
+    revision: number;
+    title: string;
+    summary: string;
+    change: "created" | "revised" | "deleted";
+    window: WindowRef | null;
+    time: number;
+}
+export interface NoteStore {
+    /** Create, replace or delete. Names the revision it read; a stale one is refused. */
+    write(input: NoteWriteInput): Promise<Note>;
+    /** The body, paged. `n012` alone means the latest revision. */
+    read(ref: NoteRef, options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<NoteBody | null>;
+    /** The note's revisions, oldest first. */
+    revisions(ref: NoteRef): Promise<Page<NoteRevision>>;
+    search(query?: NoteQuery): Promise<Page<NoteSummary>>;
+    /** The active set, by summary: the memory snapshot of every window. */
+    active(): Promise<Page<NoteSummary>>;
+    /**
+     * The memory snapshot of one epoch, with the epoch's version
+     * (docs/windows.md#prompt-layout). A new epoch is built at most every
+     * `minIntervalMs`, and only when a note was written since the last one or the
+     * budget changed, so every window opened in one epoch freezes the same bytes.
+     */
+    snapshot(options?: SnapshotOptions): Promise<NotesSnapshot>;
+    /** What changed since an epoch: the notes written after it. */
+    delta(since: number, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<NoteDelta>;
+    /** The active-set candidates with their usage scores, strongest first. */
+    score(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Page<ActiveCandidate>>;
+    /** Record that a window used a note: cited it, used it as evidence or read it. */
+    recordUse(input: NoteUseInput): Promise<void>;
+    /** Release the underlying store. */
+    close(): Promise<void>;
+    context(ref: NoteRef): Promise<NoteContext | null>;
+}

package/notes.js

@@ -0,0 +1,5 @@
+/**
+ * The `NoteStore` interface: notes are the long-term memory, one copy shared by
+ * every window, written only through the note tools (docs/memory.md).
+ */
+export {};

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@4fu/arbor-interfaces",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Every replaceable interface in arbor, and the core's own shapes.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "agent.d.ts",
+    "agent.js",
+    "blocks.d.ts",
+    "blocks.js",
+    "channel.d.ts",
+    "channel.js",
+    "effects.d.ts",
+    "effects.js",
+    "environment.d.ts",
+    "environment.js",
+    "events.d.ts",
+    "events.js",
+    "hooks.d.ts",
+    "hooks.js",
+    "index.d.ts",
+    "index.js",
+    "journal.d.ts",
+    "journal.js",
+    "judge.d.ts",
+    "judge.js",
+    "notes.d.ts",
+    "notes.js",
+    "plugin.d.ts",
+    "plugin.js",
+    "refs.d.ts",
+    "refs.js",
+    "scheduler.d.ts",
+    "scheduler.js",
+    "settings.d.ts",
+    "settings.js",
+    "supervisor.d.ts",
+    "supervisor.js",
+    "task.d.ts",
+    "task.js",
+    "tools.d.ts",
+    "tools.js",
+    "windows.d.ts",
+    "windows.js",
+    "workspace.d.ts",
+    "workspace.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/interfaces"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "0.1.0"
+  }
+}

package/plugin.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The plugin surface (docs/architecture.md#plugins).
+ *
+ * A plugin is the one unit that extends the host. It bundles any of the parts
+ * 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.
+ */
+import type { Block, BlockKindSpec, TextTable } from "./blocks.ts";
+import type { Channel } from "./channel.ts";
+import type { EffectExecutor } from "./effects.ts";
+import type { EnvDraft } from "./environment.ts";
+import type { JudgeCriteria } from "./judge.ts";
+import type { Hooks } from "./hooks.ts";
+import type { TaskSource } from "./task.ts";
+/** Connections to the outside world. */
+export interface PluginAdapters {
+    channels?: readonly Channel[];
+    taskSources?: readonly TaskSource[];
+    effectExecutors?: readonly EffectExecutor[];
+}
+/** One plugin section of the system prompt. */
+export interface PromptSection {
+    /** The XML tag it renders in, named after the plugin. */
+    tag: string;
+    /** The block kinds its inputs use, which the renderer maps to text. */
+    blocks: readonly BlockKindSpec[];
+    /** Its content, as blocks. The plugin hands blocks, never finished text. */
+    content(): readonly Block[] | Promise<readonly Block[]>;
+    /**
+     * The fixed strings its own blocks write, merged into the host's text table.
+     * A plugin names no secret here, and writes no prompt text of its own: its
+     * blocks carry data, and the table carries the words.
+     */
+    text?: TextTable;
+}
+export interface Plugin {
+    readonly name: string;
+    adapters?: PluginAdapters;
+    /** MCP servers, installed into `/env/mcp` under the plugin's name. */
+    mcpServers?: readonly EnvDraft[];
+    /** Skills, installed into `/env/skills` under the plugin's name. */
+    skills?: readonly EnvDraft[];
+    hooks?: Hooks;
+    promptSection?: PromptSection;
+    /** Extra criteria or decisions for its own inputs. */
+    judgeCriteria?: readonly JudgeCriteria[];
+}

package/plugin.js

@@ -0,0 +1,13 @@
+/**
+ * The plugin surface (docs/architecture.md#plugins).
+ *
+ * A plugin is the one unit that extends the host. It bundles any of the parts
+ * 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.
+ */
+export {};

package/refs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Refs: one reference format points at anything, in every tool argument and
+ * result (docs/journal.md#refs). A ref is a string; the prefixes below are the
+ * whole vocabulary. Nothing else in arbor is addressed by an opaque id.
+ */
+/** An event: `r902`. Its number is the event's place in the one global order. */
+export type EventRef = `r${number}`;
+/** A window: `c41`. */
+export type WindowRef = `c${number}`;
+/** A note: `n012`, or one of its revisions: `n012@3`. Bare `n012` means latest. */
+export type NoteId = `n${number}`;
+export type NoteRef = NoteId | `${NoteId}@${number}`;
+/** A task: `t9`. */
+export type TaskRef = `t${number}`;
+/** A message between windows: `m55`. */
+export type MessageRef = `m${number}`;
+/** A workspace: `ws3`. */
+export type WorkspaceRef = `ws${number}`;
+/** An environment revision: `e7`. */
+export type EnvRef = `e${number}`;
+/** A skill, MCP server, service or the settings, at a revision: `sk:deploy@4`, `set:settings@2`. */
+export type EnvItemRef = `${"sk" | "mcp" | "svc" | "set"}:${string}@${number}`;
+/**
+ * An item named without its revision, as `reload({ remove })` takes it:
+ * `skill:deploy`, `mcp:weather`, `service:crawler`, `set:settings`.
+ */
+export type EnvItemName = `${"skill" | "sk" | "mcp" | "service" | "svc" | "settings" | "set"}:${string}`;
+/** Media and files stored once by content beside the journal: `b7`. */
+export type BlobRef = `b${number}`;
+/** An outside message by its native id, with a short channel prefix: `qq:12345`. */
+export type ExternalRef = `${string}:${string}`;
+export type Ref = EventRef | WindowRef | NoteRef | TaskRef | MessageRef | WorkspaceRef | EnvRef | EnvItemRef | EnvItemName | BlobRef | ExternalRef;
+/**
+ * A target is anything two windows can collide on: a conversation
+ * (`qq:group:123`), a file path (`file:src/cart.ts`), a note (`n012`), an
+ * outside item (`gh:issue:42`) or a service (`svc:crawler`). The host fills
+ * targets in; the model never does.
+ */
+export type Target = string;
+/** Event kinds the core defines. Later stages and plugins add their own. */
+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";
+/** Page size default shared by every read that returns a page. */
+export declare const DEFAULT_PAGE_LIMIT = 20;
+/** Maximum page size any read returns. */
+export declare const MAX_PAGE_LIMIT = 200;

package/refs.js

@@ -0,0 +1,9 @@
+/**
+ * Refs: one reference format points at anything, in every tool argument and
+ * result (docs/journal.md#refs). A ref is a string; the prefixes below are the
+ * whole vocabulary. Nothing else in arbor is addressed by an opaque id.
+ */
+/** Page size default shared by every read that returns a page. */
+export const DEFAULT_PAGE_LIMIT = 20;
+/** Maximum page size any read returns. */
+export const MAX_PAGE_LIMIT = 200;