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

package/host.d.ts

@@ -0,0 +1,199 @@
+/**
+ * The seam between the entry points and the service layer
+ * (docs/architecture.md#layers, docs/tools.md#rules).
+ *
+ * A direct tool and a code mode function are thin wrappers of one service
+ * call: same arguments, same behaviour, same errors. The host API calls the
+ * same layer. So a group never reaches past these interfaces, and the service
+ * layer implements them once.
+ */
+import type { BoardLine, CallContext, Channel, DirectToolSpec, Environment, EnvDraft, EnvItem, EnvItemName, EnvItemRef, EnvRef, Event, EventRef, Expectation, Handoff, Journal, MessageRef, ModuleSpec, Note, NoteStore, NoteWriteInput, Page, ParameterSpec, Ref, ScheduledTask, ScheduledTaskInput, ScheduledTaskUpdate, SearchHit, Supervisor, Target, TaskKind, TaskRef, TextTable, ToolResult, WindowRef, Workspace, WorkspaceMount } from "@4fu/arbor-interfaces";
+/** One window the host knows about, for `windows.list` and the board. */
+export interface LiveWindow {
+    window: WindowRef;
+    state: string;
+    startedAt: number;
+    task?: Ref;
+    targets: readonly string[];
+    doing: string;
+    expects: readonly Expectation[];
+    usage: {
+        used: number;
+        limit: number;
+        reserve: number;
+    };
+}
+/** One query over the journal, the notes and the board in one call. */
+export interface SearchOutcome {
+    query: string;
+    scope: readonly string[];
+    hits: readonly SearchHit[];
+    notes: readonly {
+        ref: Ref;
+        title: string;
+        summary: string;
+    }[];
+    windows: readonly {
+        window: WindowRef;
+        doing: string;
+    }[];
+    total: number;
+    nextCall: string;
+}
+/** A send, as the host records and queues it. */
+export interface SendOutcome {
+    event: EventRef;
+    /** Events on the conversation the window has not seen yet. */
+    behind: number;
+}
+/** One task as the host recorded it. */
+export interface TaskSummary {
+    ref: TaskRef;
+    kind: TaskKind;
+    /** Why it is a task, for the board and the judge. */
+    reason: string;
+    targets: readonly Target[];
+    time: number;
+    /** The source that made it, when one did. */
+    source?: string;
+}
+/** One task with the outside events it batched. */
+export interface TaskRecord extends TaskSummary {
+    /** The events the batch was made of, oldest first. */
+    events: readonly Event[];
+}
+/** What a group needs from the service layer. Each group takes what it uses. */
+export interface ToolServices {
+    readonly table: TextTable;
+    readonly journal: Journal;
+    readonly notes?: NoteStore;
+    readonly workspace?: Workspace;
+    /** The environment. Absent when a deployment has none. */
+    readonly environment?: Environment;
+    /** The service supervisor. Absent when no service may run. */
+    readonly supervisor?: Supervisor;
+    /** The window's own directory, created on first use. */
+    ensureWorkspace(window: WindowRef): Promise<WorkspaceMount | undefined>;
+    /** End the run, with a handoff when there is unfinished work. */
+    endWindow(window: WindowRef, handoff?: Handoff): Promise<ToolResult>;
+    /** True when the window still has work the host can see. */
+    hasOpenWork(window: WindowRef): Promise<boolean>;
+    /**
+     * One note write, with the anchor the host fills in: the window, the event
+     * and the evidence. The model never declares an anchor.
+     */
+    writeNote(window: WindowRef, input: NoteWriteInput): Promise<Note>;
+    /** One query over the journal, the notes and the board. */
+    search(window: WindowRef, query: string, scope?: readonly string[]): Promise<SearchOutcome>;
+    /** One send, through the effect queue. */
+    send(window: WindowRef, request: {
+        to: string;
+        content: string;
+        replyTo?: string;
+        cites?: readonly Ref[];
+    }): Promise<SendOutcome>;
+    /** The board. */
+    board(): Promise<Page<BoardLine>>;
+    setBoardLine(window: WindowRef, doing: string): Promise<void>;
+    expect(window: WindowRef, item?: string, description?: string): Promise<Expectation>;
+    unexpect(window: WindowRef, ref: Ref): Promise<void>;
+    /**
+     * The channels the plugins registered, in the order they registered. A host
+     * no plugin plugged a channel into has none, and the `channels` module is
+     * absent (docs/tools.md#modules).
+     */
+    channels(): readonly Channel[];
+    /** The live windows. */
+    windows(): Promise<readonly LiveWindow[]>;
+    /** A window's transcript, exactly as the model saw it. */
+    windowTranscript(window: WindowRef): Promise<readonly Event[]>;
+    /** A message to another live window. */
+    windowMessage(from: WindowRef, to: WindowRef, text: string, replyTo?: Ref): Promise<MessageRef>;
+    /** A message to every live window. */
+    broadcast(from: WindowRef, text: string): Promise<number>;
+    /** What is queued for this window and not inserted yet. */
+    inbox(window: WindowRef): Promise<readonly {
+        ref: Ref;
+        from: WindowRef;
+        text: string;
+    }[]>;
+    /** The tasks the host dispatched, newest first (docs/dispatch.md#tasks). */
+    tasks(limit?: number): Promise<readonly TaskSummary[]>;
+    /** The tasks the refs name, each with the outside events it batched. */
+    task(refs: readonly TaskRef[]): Promise<readonly TaskRecord[]>;
+    /** The scheduled tasks, soonest first (docs/dispatch.md#scheduled-tasks). */
+    schedules(): Promise<readonly ScheduledTask[]>;
+    /** Record one scheduled task; the ref it returns names it. */
+    schedule(input: ScheduledTaskInput): Promise<TaskRef>;
+    /** Change one scheduled task; null when the ref names none. */
+    updateSchedule(ref: TaskRef, changes: ScheduledTaskUpdate): Promise<ScheduledTask | null>;
+    /** Cancel one scheduled task. */
+    cancelSchedule(ref: TaskRef): Promise<void>;
+    /**
+     * The environment as the file tools read it: the prefix a window sees, and the
+     * directory the host reads it from. Undefined when none is configured.
+     */
+    envPaths(): {
+        prefix: string;
+        directory: string;
+    } | undefined;
+    /** The environment as the catalog reads it: items, the MCP servers' modules. */
+    envCatalog(): EnvCatalog;
+    /** The item a path under the mount belongs to, when it is one. */
+    envItemAt(path: string): Promise<EnvItem | undefined>;
+    /** Record that a window read an item, so `reload` knows what its draft is based on. */
+    envRead(window: WindowRef, item: EnvItem): void;
+    /**
+     * `reload`: install drafts from the window's workspace and remove items, as
+     * one environment revision. A refusal changes nothing.
+     */
+    reload(window: WindowRef, request: {
+        drafts: readonly EnvDraft[];
+        remove: readonly (EnvItemRef | EnvItemName)[];
+    }): Promise<ReloadOutcome>;
+    /** Call one function of an installed MCP server, from a script. */
+    callMcp(server: string, fn: string, args: Record<string, unknown>): Promise<string>;
+}
+/**
+ * The environment as the catalog reads it. The host keeps this in step with
+ * every change, so the modules a window was opened with plus every delta since
+ * are what `tool_search` and `tool_describe` answer
+ * (docs/environment.md#deltas-in-a-window).
+ */
+export interface EnvCatalog {
+    /** Every installed item: skills, servers, services and the settings. */
+    items: readonly EnvItem[];
+    /** One module per MCP server, declared with the functions it listed. */
+    modules: readonly ModuleSpec[];
+    /** Functions a delta removed, with the change that removed them. */
+    removed: readonly {
+        name: string;
+        ref: EnvRef;
+    }[];
+}
+/** What `reload` answers with: the revision it landed and what it changed. */
+export interface ReloadOutcome {
+    revision: EnvRef;
+    changes: readonly {
+        change: "added" | "changed" | "removed";
+        item: EnvItem;
+    }[];
+    /** How many live windows the delta reached. */
+    delivered: number;
+}
+/** The context one call is made in, filled by the service layer. */
+export declare function callContext(window: WindowRef, options?: {
+    task?: string;
+    workspace?: WorkspaceMount;
+    envRevision?: string;
+    call?: EventRef;
+}): CallContext;
+/** One refusal, in the core's error shape, as a tool result. */
+export declare function refused(rule: string, table: TextTable, key: string, args?: Record<string, string | number>, refs?: readonly Ref[]): ToolResult;
+/** A tool's spec, with its description taken from the table. */
+export declare function toolSpec(table: TextTable, name: string, parameters: Record<string, Omit<ParameterSpec, "description">>): DirectToolSpec;
+/** A module's spec, with its description taken from the table. */
+export declare function moduleSpec(table: TextTable, name: string, functions: readonly {
+    name: string;
+    signature: string;
+}[]): ModuleSpec;

package/host.js

@@ -0,0 +1,70 @@
+/**
+ * The seam between the entry points and the service layer
+ * (docs/architecture.md#layers, docs/tools.md#rules).
+ *
+ * A direct tool and a code mode function are thin wrappers of one service
+ * call: same arguments, same behaviour, same errors. The host API calls the
+ * same layer. So a group never reaches past these interfaces, and the service
+ * layer implements them once.
+ */
+/** The context one call is made in, filled by the service layer. */
+export function callContext(window, options = {}) {
+    return {
+        window,
+        ...(options.task === undefined ? {} : { task: options.task }),
+        ...(options.workspace === undefined ? {} : { workspace: options.workspace }),
+        ...(options.envRevision === undefined ? {} : { envRevision: options.envRevision }),
+        ...(options.call === undefined ? {} : { call: options.call }),
+    };
+}
+/** One refusal, in the core's error shape, as a tool result. */
+export function refused(rule, table, key, args = {}, refs) {
+    return {
+        callId: "",
+        ok: false,
+        content: "",
+        error: {
+            rule,
+            message: messageOf(table, key, args),
+            nextAction: nextActionOf(table, key, args),
+            ...(refs === undefined || refs.length === 0 ? {} : { refs }),
+        },
+    };
+}
+function messageOf(table, key, args) {
+    const message = lookup(table, `refused.${key}`, args);
+    return message === "" ? key : message;
+}
+function nextActionOf(table, key, args) {
+    const next = lookup(table, `next.${key}`, args);
+    return next === "" ? undefined : next;
+}
+function lookup(table, key, args) {
+    const template = table[key];
+    if (template === undefined)
+        return "";
+    return template.replace(/\{(\w+)\}/g, (match, name) => {
+        const value = args[name];
+        return value === undefined ? match : String(value);
+    });
+}
+/** A tool's spec, with its description taken from the table. */
+export function toolSpec(table, name, parameters) {
+    const described = {};
+    for (const [key, parameter] of Object.entries(parameters)) {
+        described[key] = { ...parameter, description: lookup(table, `param.${key}`, {}) };
+    }
+    return { name, description: lookup(table, `tool.${name}`, {}), parameters: described };
+}
+/** A module's spec, with its description taken from the table. */
+export function moduleSpec(table, name, functions) {
+    return {
+        name,
+        description: lookup(table, `module.${name}`, {}),
+        functions: functions.map((fn) => ({
+            name: fn.name,
+            signature: fn.signature,
+            description: lookup(table, `function.${fn.name}`, {}),
+        })),
+    };
+}

package/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @4fu/arbor-tools - the entry points: direct tools, code mode modules and the one
+ * catalog that routes both through the service layer (docs/tools.md).
+ *
+ * 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`. There is no CLI, and there is no second path around the
+ * service layer.
+ */
+export { ToolCatalog, type ToolCatalogOptions } from "./catalog.ts";
+export { SCRIPT_TIMEOUT_MS, directToolIn, runScript, type CodeExecContext, type ScriptCatalog, } from "./code-exec.ts";
+export { RESULT_LIMIT, boundResult, boundText, nextCall, type Bound } from "./bound.ts";
+export { callContext, moduleSpec, refused, toolSpec, type EnvCatalog, type LiveWindow, type ReloadOutcome, type SearchOutcome, type SendOutcome, type TaskRecord, type TaskSummary, type ToolServices, } from "./host.ts";
+export { CoreToolGroup, handoffOf } from "./groups/core.ts";
+export { EnvToolGroup } from "./groups/env.ts";
+export { NoteToolGroup } from "./groups/notes.ts";
+export { FileToolGroup } from "./groups/files.ts";
+export { BoardModuleGroup, ChannelsModuleGroup, JournalModuleGroup, NotesModuleGroup, ScheduleModuleGroup, TasksModuleGroup, WindowsModuleGroup, WorkspaceModuleGroup, } from "./modules/modules.ts";

package/index.js

@@ -0,0 +1,18 @@
+/**
+ * @4fu/arbor-tools - the entry points: direct tools, code mode modules and the one
+ * catalog that routes both through the service layer (docs/tools.md).
+ *
+ * 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`. There is no CLI, and there is no second path around the
+ * service layer.
+ */
+export { ToolCatalog } from "./catalog.js";
+export { SCRIPT_TIMEOUT_MS, directToolIn, runScript, } from "./code-exec.js";
+export { RESULT_LIMIT, boundResult, boundText, nextCall } from "./bound.js";
+export { callContext, moduleSpec, refused, toolSpec, } from "./host.js";
+export { CoreToolGroup, handoffOf } from "./groups/core.js";
+export { EnvToolGroup } from "./groups/env.js";
+export { NoteToolGroup } from "./groups/notes.js";
+export { FileToolGroup } from "./groups/files.js";
+export { BoardModuleGroup, ChannelsModuleGroup, JournalModuleGroup, NotesModuleGroup, ScheduleModuleGroup, TasksModuleGroup, WindowsModuleGroup, WorkspaceModuleGroup, } from "./modules/modules.js";

package/modules/env.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The environment modules: `env`, `services`, and one module per installed MCP
+ * server (docs/tools.md#modules, docs/environment.md).
+ *
+ * A module whose backing feature is not configured is absent, so `env` and
+ * `services` appear only when the host has an environment and a supervisor. A
+ * capability is never a direct tool: an MCP server arrives as a module of its
+ * own, declared with the functions it listed when it was validated, and reaches
+ * a live window through an environment delta.
+ */
+import type { CallContext, ModuleSpec, ToolCall, ToolGroup, ToolResult } from "@4fu/arbor-interfaces";
+import type { ToolServices } from "../host.ts";
+export declare class EnvModuleGroup implements ToolGroup {
+    readonly id = "modules.env";
+    private readonly services;
+    constructor(services: ToolServices);
+    tools(): readonly [];
+    /** The modules this group declares: `env`, `services` and every MCP server. */
+    modules(): readonly ModuleSpec[];
+    call(request: ToolCall, _context: CallContext): Promise<ToolResult>;
+    /** `env.list`: the items and their revisions, one line each. */
+    private list;
+    /** `env.history(item?)`: one item's revisions, or the environment's. */
+    private history;
+    /** `services.list`: the services and their state. */
+    private services_;
+    /** `services.status(name)`: one service's real numbers. */
+    private status;
+    /** `services.logs(name)`: the tail of a service's own output. */
+    private logs;
+    /**
+     * One call into an MCP server: `weather.forecast({ city })` from a script.
+     * A function a delta removed is refused with the ref of the change that
+     * removed it, so the model knows where the answer is.
+     */
+    private server;
+    /** One environment item's line: its ref, its name and its description. */
+    private answer;
+    private missing;
+    private absent;
+    private notOwned;
+}

package/modules/env.js

@@ -0,0 +1,237 @@
+/**
+ * The environment modules: `env`, `services`, and one module per installed MCP
+ * server (docs/tools.md#modules, docs/environment.md).
+ *
+ * A module whose backing feature is not configured is absent, so `env` and
+ * `services` appear only when the host has an environment and a supervisor. A
+ * capability is never a direct tool: an MCP server arrives as a module of its
+ * own, declared with the functions it listed when it was validated, and reaches
+ * a live window through an environment delta.
+ */
+import { textOf } from "@4fu/arbor-prompt";
+import { moduleSpec } from "../host.js";
+export class EnvModuleGroup {
+    id = "modules.env";
+    services;
+    constructor(services) {
+        this.services = services;
+    }
+    tools() {
+        return [];
+    }
+    /** The modules this group declares: `env`, `services` and every MCP server. */
+    modules() {
+        if (this.services.environment === undefined)
+            return [];
+        const catalog = this.services.envCatalog();
+        const table = this.services.table;
+        const modules = [moduleSpec(table, "env", [
+                { name: "env.list", signature: "env.list()" },
+                { name: "env.history", signature: "env.history(item?)" },
+            ])];
+        if (this.services.supervisor !== undefined) {
+            modules.push(moduleSpec(table, "services", [
+                { name: "services.list", signature: "services.list()" },
+                { name: "services.status", signature: "services.status(name)" },
+                { name: "services.logs", signature: "services.logs(name, tail?)" },
+            ]));
+        }
+        for (const module of catalog.modules)
+            modules.push(module);
+        return modules;
+    }
+    async call(request, _context) {
+        if (this.services.environment === undefined)
+            return this.absent(request);
+        switch (request.name) {
+            case "env.list":
+                return this.list(request);
+            case "env.history":
+                return this.history(request);
+            case "services.list":
+                return this.services_(request);
+            case "services.status":
+                return this.status(request);
+            case "services.logs":
+                return this.logs(request);
+            default:
+                return this.server(request);
+        }
+    }
+    /** `env.list`: the items and their revisions, one line each. */
+    async list(request) {
+        const table = this.services.table;
+        const items = (await this.services.environment?.list()) ?? [];
+        const lines = items.map((item) => itemLine(item, table));
+        return this.answer(request, lines);
+    }
+    /** `env.history(item?)`: one item's revisions, or the environment's. */
+    async history(request) {
+        const table = this.services.table;
+        const item = stringArg(request.args, "item");
+        const revisions = (await this.services.environment?.history(item === "" ? undefined : item)) ?? [];
+        const lines = revisions.map((revision) => textOf(table, "result.env.history", {
+            ref: revision.ref,
+            window: revision.window ?? "",
+            time: revision.time,
+            changes: revision.changes
+                .map((change) => `${change.change === "added" ? "+" : change.change === "removed" ? "-" : "~"}${change.item.name}`)
+                .join(", "),
+        }));
+        return this.answer(request, lines);
+    }
+    /** `services.list`: the services and their state. */
+    async services_(request) {
+        const table = this.services.table;
+        const supervisor = this.services.supervisor;
+        if (supervisor === undefined)
+            return this.absent(request);
+        const items = (await this.services.environment?.list()) ?? [];
+        const lines = [];
+        for (const item of items) {
+            if (item.kind !== "service")
+                continue;
+            const status = await supervisor.status(item.name).catch(() => null);
+            if (status === null) {
+                lines.push(textOf(table, "result.services.item", { name: item.name, state: "stopped", revision: item.revision, restarts: 0 }));
+                continue;
+            }
+            lines.push(textOf(table, "result.services.item", {
+                name: status.name,
+                state: status.state,
+                revision: status.revision,
+                restarts: status.restarts,
+            }));
+        }
+        return this.answer(request, lines);
+    }
+    /** `services.status(name)`: one service's real numbers. */
+    async status(request) {
+        const table = this.services.table;
+        const supervisor = this.services.supervisor;
+        if (supervisor === undefined)
+            return this.absent(request);
+        const name = stringArg(request.args, "name");
+        const found = await supervisor.status(name).catch(() => null);
+        if (found === null)
+            return this.missing(request, name);
+        return this.answer(request, [
+            textOf(table, "result.services.status", {
+                name: found.name,
+                state: found.state,
+                revision: found.revision,
+                ports: found.ports.join(", "),
+                restarts: found.restarts,
+                since: found.since,
+            }),
+            ...(found.lastError === undefined ? [] : [`${found.lastError.rule} ${found.lastError.message}`]),
+            ...(found.refs.length === 0 ? [] : [textOf(table, "error.refs", { refs: found.refs.join(", ") })]),
+        ]);
+    }
+    /** `services.logs(name)`: the tail of a service's own output. */
+    async logs(request) {
+        const table = this.services.table;
+        const supervisor = this.services.supervisor;
+        if (supervisor === undefined)
+            return this.absent(request);
+        const name = stringArg(request.args, "name");
+        const tail = numberArg(request.args, "tail");
+        const page = await supervisor.logs(name, tail === undefined ? undefined : { tail }).catch(() => null);
+        if (page === null)
+            return this.missing(request, name);
+        return this.answer(request, [
+            textOf(table, "result.services.logs", { name: page.name, lines: page.total }),
+            ...page.items,
+        ]);
+    }
+    /**
+     * One call into an MCP server: `weather.forecast({ city })` from a script.
+     * A function a delta removed is refused with the ref of the change that
+     * removed it, so the model knows where the answer is.
+     */
+    async server(request) {
+        const dot = request.name.indexOf(".");
+        const server = dot === -1 ? "" : request.name.slice(0, dot);
+        if (server === "")
+            return this.notOwned(request);
+        const catalog = this.services.envCatalog();
+        if (!catalog.modules.some((module) => module.name === server))
+            return this.notOwned(request);
+        try {
+            const content = await this.services.callMcp(server, request.name, request.args);
+            return { callId: request.callId, ok: true, content };
+        }
+        catch (error) {
+            const info = error;
+            return {
+                callId: request.callId,
+                ok: false,
+                content: "",
+                error: {
+                    rule: info.rule ?? "mcp.call.failed",
+                    message: info.message ?? String(error),
+                    ...(info.nextAction === undefined ? {} : { nextAction: info.nextAction }),
+                },
+            };
+        }
+    }
+    /** One environment item's line: its ref, its name and its description. */
+    answer(request, lines) {
+        const table = this.services.table;
+        const body = lines.length === 0 ? textOf(table, "result.search.empty") : lines.join("\n");
+        const total = textOf(table, "result.search.total", { total: lines.length });
+        return { callId: request.callId, ok: true, content: `${body}\n${total}` };
+    }
+    missing(request, name) {
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: "service.notfound",
+                message: textOf(this.services.table, "refused.service.notfound", { name }),
+                nextAction: textOf(this.services.table, "next.service.notfound"),
+            },
+        };
+    }
+    absent(request) {
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: "env.absent",
+                message: textOf(this.services.table, "refused.env.absent"),
+                nextAction: textOf(this.services.table, "next.env.absent"),
+            },
+        };
+    }
+    notOwned(request) {
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: "module.function.unknown",
+                message: textOf(this.services.table, "refused.unknown_function", { module: "env", name: request.name }),
+                nextAction: textOf(this.services.table, "next.unknown_function"),
+            },
+        };
+    }
+}
+/** One item's line, in the shape `<env>` uses, so a list reads like the prompt. */
+function itemLine(item, table) {
+    return textOf(table, "result.env.item", {
+        ref: item.ref,
+        name: item.name,
+        description: item.description,
+    });
+}
+function stringArg(args, name) {
+    const value = args[name];
+    return typeof value === "string" ? value : "";
+}
+function numberArg(args, name) {
+    const value = args[name];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}