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

package/groups/files.js

@@ -0,0 +1,343 @@
+/**
+ * The window's workspace: `bash`, `bash_output`, `bash_stop`, `read`, `write`
+ * and `edit` (docs/tools.md#direct-tools, docs/workspaces.md).
+ *
+ * A plain command is a direct call, a chain is a script. One behaviour per
+ * tool: a command that outlives `bash`'s wait window is followed with
+ * `bash_output` and stopped with `bash_stop`.
+ *
+ * Everything reaches the workspace through the `Workspace` interface, never the
+ * host filesystem directly: a capability the implementation owns - `exec`,
+ * `readFile`, `writeFile` - is used when it is present, and the host path in
+ * `mount.path` when it is not. An implementation that owns its execution
+ * environment has a `path` that is not a host path and an `exec` that is the
+ * only way to run a command there; a plain-directory workspace owns no
+ * execution environment, so the caller runs the command itself. Either way a
+ * command that outlives `bash`'s wait window is followed with `bash_output` and
+ * stopped with `bash_stop`, through the host's own process path.
+ */
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { textOf } from "@4fu/arbor-prompt";
+import { boundResult } from "../bound.js";
+import { envCommand } from "../env-stage.js";
+import { toolSpec } from "../host.js";
+/** How long `bash` waits before it hands the command to `bash_output`. */
+const BASH_WAIT_MS = 20000;
+/** How much one background job keeps in memory. */
+const JOB_BUFFER = 200000;
+export class FileToolGroup {
+    id = "files";
+    services;
+    jobs = new Map();
+    nextJob = 1;
+    constructor(services) {
+        this.services = services;
+    }
+    tools() {
+        const table = this.services.table;
+        return [
+            toolSpec(table, "bash", {
+                command: { type: "string", required: true },
+                timeout: { type: "number" },
+            }),
+            toolSpec(table, "bash_output", { job: { type: "string", required: true } }),
+            toolSpec(table, "bash_stop", { job: { type: "string", required: true } }),
+            toolSpec(table, "read", {
+                path: { type: "string", required: true },
+                offset: { type: "number" },
+                limit: { type: "number" },
+            }),
+            toolSpec(table, "write", {
+                path: { type: "string", required: true },
+                text: { type: "string", required: true },
+            }),
+            toolSpec(table, "edit", {
+                path: { type: "string", required: true },
+                old: { type: "string", required: true },
+                new: { type: "string", required: true },
+            }),
+        ];
+    }
+    modules() {
+        return [];
+    }
+    async call(request, context) {
+        switch (request.name) {
+            case "bash":
+                return this.bash(request, context.window, context);
+            case "bash_output":
+                return this.bashOutput(request);
+            case "bash_stop":
+                return this.bashStop(request);
+            case "read":
+                return this.read(request, context.window);
+            case "write":
+                return this.write(request, context.window);
+            case "edit":
+                return this.edit(request, context.window);
+            default:
+                return this.notOwned(request);
+        }
+    }
+    /** The window's own directory, created on first use. */
+    async mount(window) {
+        return this.services.ensureWorkspace(window);
+    }
+    /**
+     * The environment, at the path a window reads it at. It is mounted read-only,
+     * so a window without a workspace still reads `/env/skills/<name>/SKILL.md`
+     * (docs/environment.md#layout), and a write to it is refused.
+     */
+    envPath(path) {
+        const env = this.services.envPaths();
+        if (env === undefined)
+            return undefined;
+        if (path !== env.prefix && !path.startsWith(`${env.prefix}/`))
+            return undefined;
+        const inside = path === env.prefix ? "" : path.slice(env.prefix.length + 1);
+        return inside === "" ? env.directory : join(env.directory, inside);
+    }
+    /** Record which revision of an item a window read, for `reload`'s check. */
+    async noteEnvRead(window, path) {
+        const prefix = this.services.envPaths()?.prefix;
+        if (prefix === undefined || (path !== prefix && !path.startsWith(`${prefix}/`)))
+            return;
+        const item = await this.services.envItemAt(path);
+        if (item !== undefined)
+            this.services.envRead(window, item);
+    }
+    async bash(request, window, context) {
+        const table = this.services.table;
+        const workspace = await this.mount(window);
+        if (workspace === undefined)
+            return this.absent(request);
+        const command = await envCommand(workspace, stringArg(request.args, "command"), this.services.envPaths(), context.envRevision);
+        if (workspace.exec !== undefined) {
+            // The implementation owns the execution environment, so the command runs
+            // there and `path` is not a host path.
+            return this.ran(request, await runToEnd(workspace.exec, command));
+        }
+        const job = this.start(command, workspace.path);
+        await sleep(numberArg(request.args, "timeout", BASH_WAIT_MS));
+        return {
+            callId: request.callId,
+            ok: job.done ? job.code === 0 : true,
+            content: `${job.output}\n${textOf(table, "result.bash.started", { job: job.id })}`,
+        };
+    }
+    /** One command that ran to its end: what it wrote, and whether it succeeded. */
+    ran(request, outcome) {
+        const body = [outcome.stdout, outcome.stderr].filter((part) => part !== "").join("\n");
+        return { callId: request.callId, ok: outcome.exitCode === 0, content: body };
+    }
+    async bashOutput(request) {
+        const table = this.services.table;
+        const id = stringArg(request.args, "job");
+        const job = this.jobs.get(id);
+        if (job === undefined)
+            return this.jobMissing(request, id);
+        const content = job.done
+            ? `${job.output}\n${textOf(table, "result.bash.stopped", { job: id })}`
+            : `${job.output}\n${textOf(table, "result.bash.running", { job: id })}`;
+        return { callId: request.callId, ok: job.done ? job.code === 0 : true, content };
+    }
+    async bashStop(request) {
+        const table = this.services.table;
+        const id = stringArg(request.args, "job");
+        const job = this.jobs.get(id);
+        if (job === undefined)
+            return this.jobMissing(request, id);
+        job.stop();
+        return {
+            callId: request.callId,
+            ok: true,
+            content: `${job.output}\n${textOf(table, "result.bash.stopped", { job: id })}`,
+        };
+    }
+    async read(request, window) {
+        const table = this.services.table;
+        const path = stringArg(request.args, "path");
+        // The environment is read where a window sees it, without a workspace.
+        const env = this.envPath(path);
+        const workspace = env === undefined ? await this.mount(window) : undefined;
+        if (env === undefined && workspace === undefined)
+            return this.absent(request);
+        const text = env === undefined
+            ? await this.readText(workspace, path)
+            : await readFile(env, "utf8").catch(() => null);
+        if (text === null)
+            return this.missing(request, "read.missing", path);
+        if (env !== undefined)
+            await this.noteEnvRead(window, path);
+        const lines = text.split("\n");
+        const offset = Math.max(0, numberArg(request.args, "offset", 0));
+        const limit = Math.min(500, Math.max(1, numberArg(request.args, "limit", 400)));
+        const body = await boundResult(lines.slice(offset, offset + limit).join("\n"), {
+            workspace: workspace?.path ?? path,
+            callId: request.callId,
+            table,
+        });
+        return {
+            callId: request.callId,
+            ok: true,
+            content: `${textOf(table, "result.read.file", { path, lines: lines.length })}\n${body}`,
+        };
+    }
+    async write(request, window) {
+        const table = this.services.table;
+        const path = stringArg(request.args, "path");
+        if (this.envPath(path) !== undefined)
+            return this.readonly(request, path);
+        const workspace = await this.mount(window);
+        if (workspace === undefined)
+            return this.absent(request);
+        const text = stringArg(request.args, "text");
+        await this.writeText(workspace, path, text);
+        return {
+            callId: request.callId,
+            ok: true,
+            content: textOf(table, "result.write.file", { path, bytes: Buffer.byteLength(text) }),
+        };
+    }
+    async edit(request, window) {
+        const table = this.services.table;
+        const path = stringArg(request.args, "path");
+        if (this.envPath(path) !== undefined)
+            return this.readonly(request, path);
+        const workspace = await this.mount(window);
+        if (workspace === undefined)
+            return this.absent(request);
+        const old = stringArg(request.args, "old");
+        const next = stringArg(request.args, "new");
+        const text = await this.readText(workspace, path);
+        if (text === null)
+            return this.missing(request, "edit.missing", path);
+        const count = text.split(old).length - 1;
+        if (count === 0)
+            return this.noMatch(request, path, old);
+        await this.writeText(workspace, path, text.split(old).join(next));
+        return {
+            callId: request.callId,
+            ok: true,
+            content: textOf(table, "result.edit.file", { path, replacements: count }),
+        };
+    }
+    /**
+     * One file's text: the mount's own capability when it has one, the host path
+     * when it does not. `null` means the file is not there.
+     */
+    async readText(workspace, path) {
+        if (workspace.readFile !== undefined)
+            return workspace.readFile(path);
+        return readFile(hostPath(workspace.path, path), "utf8").catch(() => null);
+    }
+    /** Write one file, creating its directory. */
+    async writeText(workspace, path, text) {
+        if (workspace.writeFile !== undefined) {
+            await workspace.writeFile(path, text);
+            return;
+        }
+        const target = hostPath(workspace.path, path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, text, "utf8");
+    }
+    start(command, cwd) {
+        const id = `b${this.nextJob}`;
+        this.nextJob += 1;
+        const child = spawn("/bin/sh", ["-c", command], { cwd });
+        let output = "";
+        const append = (chunk) => {
+            output = (output + chunk.toString("utf8")).slice(-JOB_BUFFER);
+        };
+        child.stdout.on("data", append);
+        child.stderr.on("data", append);
+        const job = {
+            id,
+            output: "",
+            done: false,
+            code: null,
+            stop: () => {
+                child.kill("SIGTERM");
+            },
+        };
+        child.on("close", (code) => {
+            job.done = true;
+            job.code = code;
+            job.output = output;
+        });
+        child.on("error", (error) => {
+            job.done = true;
+            job.code = 1;
+            job.output = output + error.message;
+        });
+        this.jobs.set(id, job);
+        return job;
+    }
+    absent(request) {
+        return this.refusal(request, "workspace.absent", "result.no_workspace", {});
+    }
+    jobMissing(request, id) {
+        return this.refusal(request, "bash.job.not_found", "bash.notfound", { job: id });
+    }
+    missing(request, key, path) {
+        return this.refusal(request, key === "read.missing" ? "file.not_found" : "file.not_found", key, { path });
+    }
+    noMatch(request, path, old) {
+        return this.refusal(request, "edit.no_match", "edit.nomatch", { path, old });
+    }
+    /** The environment is mounted read-only, so nothing there is written. */
+    readonly(request, path) {
+        return this.refusal(request, "env.readonly_path", "env.readonly_path", { path });
+    }
+    refusal(request, rule, key, args) {
+        const table = this.services.table;
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule,
+                message: textOf(table, `refused.${key}`, args, key),
+                nextAction: textOf(table, `next.${key}`, args) || undefined,
+            },
+        };
+    }
+    notOwned(request) {
+        return this.refusal(request, "tool.not_owned", "unknown_tool", { name: request.name });
+    }
+}
+/**
+ * Where a path names on this host: itself when it is absolute, under the
+ * workspace when it is not. Nothing is refused, because the owner asked for no
+ * restriction on where a window reads or writes
+ * (docs/workspaces.md#another-windows-directory).
+ */
+function hostPath(root, path) {
+    return isAbsolute(path) ? normalize(path) : resolve(root, path);
+}
+/**
+ * One command to its end in a mount that owns its execution environment, or
+ * the failure it was answered with - so a command the implementation could not
+ * run at all is reported the way one that ran and failed is.
+ */
+function runToEnd(exec, command) {
+    return exec(command).catch((error) => ({
+        exitCode: 1,
+        stdout: "",
+        stderr: error instanceof Error ? error.message : String(error),
+        truncated: false,
+    }));
+}
+function stringArg(args, name) {
+    const value = args[name];
+    return typeof value === "string" ? value : "";
+}
+function numberArg(args, name, fallback) {
+    const value = args[name];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/groups/notes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The note tools: `note_write`, `note_replace`, `note_delete`
+ * (docs/tools.md#direct-tools, docs/memory.md).
+ *
+ * Writing memory is a decision, so it is a direct call. A write names the
+ * revision it read; a stale one is refused with what changed since, and the
+ * model merges and writes again. The host records where the write happened -
+ * window, event, evidence, range - and the model never fills an anchor in.
+ */
+import type { DirectToolSpec, ToolCall, ToolGroup, ToolResult, WindowRef } from "@4fu/arbor-interfaces";
+import { type ToolServices } from "../host.ts";
+export declare class NoteToolGroup implements ToolGroup {
+    readonly id = "notes";
+    private readonly services;
+    constructor(services: ToolServices);
+    tools(): readonly DirectToolSpec[];
+    modules(): readonly [];
+    call(request: ToolCall, context: {
+        window: WindowRef;
+    }): Promise<ToolResult>;
+    private write;
+    private replace;
+    private remove;
+    /**
+     * One write, with the anchor the host fills in. A refused write changes
+     * nothing; the answer carries the rule, the next action and the revisions
+     * that changed since the one the writer read.
+     */
+    private record;
+    private answer;
+    /** One refusal the note store returned, in the core's error shape. */
+    private refusalOf;
+    private refusal;
+    private absent;
+    private notOwned;
+    private store;
+}

package/groups/notes.js

@@ -0,0 +1,176 @@
+/**
+ * The note tools: `note_write`, `note_replace`, `note_delete`
+ * (docs/tools.md#direct-tools, docs/memory.md).
+ *
+ * Writing memory is a decision, so it is a direct call. A write names the
+ * revision it read; a stale one is refused with what changed since, and the
+ * model merges and writes again. The host records where the write happened -
+ * window, event, evidence, range - and the model never fills an anchor in.
+ */
+import { textOf } from "@4fu/arbor-prompt";
+import { toolSpec } from "../host.js";
+export class NoteToolGroup {
+    id = "notes";
+    services;
+    constructor(services) {
+        this.services = services;
+    }
+    tools() {
+        if (this.services.notes === undefined)
+            return [];
+        const table = this.services.table;
+        return [
+            toolSpec(table, "note_write", {
+                title: { type: "string", required: true },
+                summary: { type: "string" },
+                body: { type: "string", required: true },
+            }),
+            toolSpec(table, "note_replace", {
+                id: { type: "string", required: true },
+                revision: { type: "number", required: true },
+                title: { type: "string" },
+                summary: { type: "string" },
+                body: { type: "string", required: true },
+            }),
+            toolSpec(table, "note_delete", {
+                id: { type: "string", required: true },
+                revision: { type: "number", required: true },
+            }),
+        ];
+    }
+    modules() {
+        return [];
+    }
+    async call(request, context) {
+        const store = this.store();
+        if (store === undefined)
+            return this.absent(request);
+        switch (request.name) {
+            case "note_write":
+                return this.write(request, store, context.window);
+            case "note_replace":
+                return this.replace(request, store, context.window);
+            case "note_delete":
+                return this.remove(request, store, context.window);
+            default:
+                return this.notOwned(request);
+        }
+    }
+    async write(request, store, window) {
+        const title = stringArg(request.args, "title");
+        const body = stringArg(request.args, "body");
+        if (title === "" || body === "")
+            return this.refusal(request, "note.write.empty");
+        return this.record(request, store, window, {
+            title,
+            body,
+            ...(stringArg(request.args, "summary") === "" ? {} : { summary: stringArg(request.args, "summary") }),
+        });
+    }
+    async replace(request, store, window) {
+        const id = stringArg(request.args, "id");
+        const revision = numberArg(request.args, "revision");
+        const body = stringArg(request.args, "body");
+        if (id === "" || body === "")
+            return this.refusal(request, "note.write.empty");
+        return this.record(request, store, window, {
+            id: id,
+            title: stringArg(request.args, "title"),
+            body,
+            replace: true,
+            expectedRevision: revision,
+            ...(stringArg(request.args, "summary") === "" ? {} : { summary: stringArg(request.args, "summary") }),
+        });
+    }
+    async remove(request, store, window) {
+        const id = stringArg(request.args, "id");
+        if (id === "")
+            return this.refusal(request, "note.write.empty");
+        return this.record(request, store, window, {
+            id: id,
+            title: "",
+            body: "",
+            delete: true,
+            expectedRevision: numberArg(request.args, "revision"),
+        });
+    }
+    /**
+     * One write, with the anchor the host fills in. A refused write changes
+     * nothing; the answer carries the rule, the next action and the revisions
+     * that changed since the one the writer read.
+     */
+    async record(request, _store, window, input) {
+        try {
+            const note = await this.services.writeNote(window, input);
+            return this.answer(request, note.ref, this.services.table);
+        }
+        catch (error) {
+            return this.refusalOf(request, error);
+        }
+    }
+    answer(request, ref, table) {
+        return { callId: request.callId, ok: true, content: textOf(table, "result.note_written", { ref }) };
+    }
+    /** One refusal the note store returned, in the core's error shape. */
+    refusalOf(request, error) {
+        const table = this.services.table;
+        const info = error;
+        const revisions = info.details?.revisions ?? [];
+        const lines = [info.message ?? String(error)];
+        if (info.nextAction !== undefined)
+            lines.push(`${textOf(table, "error.next", {})}${info.nextAction}`.trim());
+        for (const revision of revisions) {
+            lines.push(`${revision.ref} ${revision.window ?? ""}`);
+        }
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: info.rule ?? "note.write.failed",
+                message: lines.join("\n"),
+                ...(info.nextAction === undefined ? {} : { nextAction: info.nextAction }),
+            },
+        };
+    }
+    refusal(request, rule) {
+        const table = this.services.table;
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule,
+                message: textOf(table, `refused.${rule}`, {}, rule),
+                nextAction: textOf(table, `next.${rule}`) || undefined,
+            },
+        };
+    }
+    absent(request) {
+        const table = this.services.table;
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: "notes.absent",
+                message: textOf(table, "refused.notes.absent"),
+                nextAction: textOf(table, "next.notes.absent"),
+            },
+        };
+    }
+    notOwned(request) {
+        return this.refusal(request, "unknown_tool");
+    }
+    store() {
+        return this.services.notes;
+    }
+}
+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;
+}