@4fu/arbor-tools 0.0.0-stage → 2026.1106.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/bound.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Bounded results (docs/prompting.md#information-density).
+ *
+ * Every read is bounded by one head-and-tail cut in the tool pipeline, with a
+ * marker that says how much was cut and where the whole is kept in the
+ * workspace. A limit that shapes a result without refusing is reported by the
+ * result every time.
+ */
+import type { TextTable } from "@4fu/arbor-interfaces";
+/** How much of one result the model reads, after the cut. */
+export declare const RESULT_LIMIT = 20000;
+export interface Bound {
+    text: string;
+    /** True when the cut removed something. */
+    truncated: boolean;
+    /** The whole result's length, before the cut. */
+    total: number;
+    head: number;
+    tail: number;
+}
+/** One head-and-tail cut. */
+export declare function boundText(text: string, limit?: number): Bound;
+/**
+ * Bound one result and keep the whole of it in the workspace, so the marker can
+ * name where. A window without a workspace gets the cut with no path.
+ */
+export declare function boundResult(text: string, options: {
+    limit?: number;
+    workspace?: string;
+    callId?: string;
+    table?: TextTable;
+}): Promise<string>;
+/** The exact call that pages the rest of a read (docs/prompting.md). */
+export declare function nextCall(name: string, offset: number, limit: number): string;

package/bound.js

@@ -0,0 +1,55 @@
+/**
+ * Bounded results (docs/prompting.md#information-density).
+ *
+ * Every read is bounded by one head-and-tail cut in the tool pipeline, with a
+ * marker that says how much was cut and where the whole is kept in the
+ * workspace. A limit that shapes a result without refusing is reported by the
+ * result every time.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { textOf } from "@4fu/arbor-prompt";
+/** How much of one result the model reads, after the cut. */
+export const RESULT_LIMIT = 20000;
+/** How much of what is kept comes from the tail, so the end is not lost. */
+const TAIL_SHARE = 0.25;
+/** One head-and-tail cut. */
+export function boundText(text, limit = RESULT_LIMIT) {
+    if (text.length <= limit) {
+        return { text, truncated: false, total: text.length, head: text.length, tail: 0 };
+    }
+    const head = Math.floor(limit * (1 - TAIL_SHARE));
+    const tail = limit - head;
+    return {
+        text: `${text.slice(0, head)}\n${text.slice(text.length - tail)}`,
+        truncated: true,
+        total: text.length,
+        head,
+        tail,
+    };
+}
+/**
+ * Bound one result and keep the whole of it in the workspace, so the marker can
+ * name where. A window without a workspace gets the cut with no path.
+ */
+export async function boundResult(text, options) {
+    const bound = boundText(text, options.limit);
+    if (!bound.truncated)
+        return bound.text;
+    const table = options.table ?? {};
+    const marker = textOf(table, "result.bounded", {
+        head: bound.head,
+        tail: bound.tail,
+        total: bound.total,
+    });
+    if (options.workspace === undefined || options.callId === undefined)
+        return `${bound.text}\n${marker}`;
+    const path = join(options.workspace, ".arbor", "outputs", `${options.callId}.txt`);
+    await mkdir(join(options.workspace, ".arbor", "outputs"), { recursive: true });
+    await writeFile(path, text, "utf8");
+    return `${bound.text}\n${marker}\n${textOf(table, "result.bounded.path", { path })}`;
+}
+/** The exact call that pages the rest of a read (docs/prompting.md). */
+export function nextCall(name, offset, limit) {
+    return `${name}({ offset: ${offset + limit}, limit: ${limit} })`;
+}

package/catalog.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The one tool catalog: every direct tool and every code mode module, and the
+ * two paths that reach the service layer (docs/tools.md).
+ *
+ * A direct tool and a code mode function are thin wrappers of one service call:
+ * same arguments, same behaviour, same errors. `tool_search` and `tool_describe`
+ * read this catalog, so the lookup and the prompt never disagree. `code_exec`
+ * runs a script against it and refuses a script that names a direct tool.
+ */
+import type { CallContext, DirectToolSpec, EnvItem, FunctionSpec, ModuleSpec, ToolCall, ToolGroup, ToolResult } from "@4fu/arbor-interfaces";
+import { type CodeExecContext, type ScriptCatalog } from "./code-exec.ts";
+import type { ToolServices } from "./host.ts";
+export interface ToolCatalogOptions {
+    services: ToolServices;
+    /** Extra groups, from a plugin. */
+    groups?: readonly ToolGroup[];
+}
+export declare class ToolCatalog implements ToolGroup, ScriptCatalog {
+    readonly id = "catalog";
+    private readonly services;
+    private readonly groups;
+    constructor(options: ToolCatalogOptions);
+    /** Every direct tool, one line each in the prompt. */
+    tools(): readonly DirectToolSpec[];
+    /**
+     * Every module, one line each in the prompt. A name is declared once: every
+     * group that declares it lists its functions together, so a group that adds a
+     * function to a module the core already declares - an implementation's own
+     * capability, or an MCP server named after a built-in module - adds no second
+     * line for it.
+     */
+    modules(): readonly ModuleSpec[];
+    /** Every function the modules declare. */
+    functions(): readonly FunctionSpec[];
+    /** The direct tool names, which a script may not call. */
+    directTools(): readonly string[];
+    /** One call, through the group that owns it. */
+    call(request: ToolCall, context: CallContext): Promise<ToolResult>;
+    /** One `module.function` call from a script: the same path as a direct call. */
+    callModule(name: string, args: Record<string, unknown>, context: CodeExecContext): Promise<ToolResult>;
+    /**
+     * `tool_search`: keywords, an exact `module.function`, or nothing. An exact
+     * module name answers with that module's functions, and a skill's name or
+     * keywords answer with its path and how to read it
+     * (docs/environment.md#using-a-skill-or-a-server).
+     */
+    search(keywords?: string): {
+        modules: readonly string[];
+        functions: readonly string[];
+        skills: readonly EnvItem[];
+    };
+    /** `tool_describe`: one function's signature and description. */
+    describe(name: string): string | undefined;
+    /** `code_exec`: run one script against this catalog. */
+    codeExec(script: string, context: CodeExecContext): Promise<ToolResult>;
+    /** `tool_search` as a direct call: one block per name it answers. */
+    private toolSearch;
+    /** The guard a script goes through, exposed for tests. */
+    decisionIn(script: string): string | undefined;
+}

package/catalog.js

@@ -0,0 +1,224 @@
+/**
+ * The one tool catalog: every direct tool and every code mode module, and the
+ * two paths that reach the service layer (docs/tools.md).
+ *
+ * A direct tool and a code mode function are thin wrappers of one service call:
+ * same arguments, same behaviour, same errors. `tool_search` and `tool_describe`
+ * read this catalog, so the lookup and the prompt never disagree. `code_exec`
+ * runs a script against it and refuses a script that names a direct tool.
+ */
+import { textOf } from "@4fu/arbor-prompt";
+import { directToolIn, runScript } from "./code-exec.js";
+import { CoreToolGroup } from "./groups/core.js";
+import { EnvToolGroup } from "./groups/env.js";
+import { FileToolGroup } from "./groups/files.js";
+import { NoteToolGroup } from "./groups/notes.js";
+import { BoardModuleGroup, ChannelsModuleGroup, EnvModuleGroup, JournalModuleGroup, NotesModuleGroup, ScheduleModuleGroup, TasksModuleGroup, WindowsModuleGroup, WorkspaceModuleGroup, } from "./modules/modules.js";
+export class ToolCatalog {
+    id = "catalog";
+    services;
+    groups;
+    constructor(options) {
+        this.services = options.services;
+        this.groups = [
+            new CoreToolGroup(options.services),
+            new FileToolGroup(options.services),
+            new NoteToolGroup(options.services),
+            new JournalModuleGroup(options.services),
+            new WindowsModuleGroup(options.services),
+            new BoardModuleGroup(options.services),
+            new NotesModuleGroup(options.services),
+            new ChannelsModuleGroup(options.services),
+            new TasksModuleGroup(options.services),
+            new ScheduleModuleGroup(options.services),
+            new WorkspaceModuleGroup(options.services),
+            new EnvToolGroup(options.services),
+            new EnvModuleGroup(options.services),
+            // What the workspace implementation contributes: a capability the core
+            // does not name, such as showing another window's directory.
+            ...(options.services.workspace?.groups?.(options.services.table) ?? []),
+            ...(options.groups ?? []),
+        ];
+    }
+    /** Every direct tool, one line each in the prompt. */
+    tools() {
+        const table = this.services.table;
+        const entryPoints = [
+            {
+                name: "code_exec",
+                description: lookup(table, "tool.code_exec", {}),
+                parameters: { script: { type: "string", description: lookup(table, "param.script", {}), required: true } },
+            },
+            {
+                name: "tool_search",
+                description: lookup(table, "tool.tool_search", {}),
+                parameters: { keywords: { type: "string", description: lookup(table, "param.keywords", {}) } },
+            },
+        ];
+        return [...entryPoints, ...this.groups.flatMap((group) => group.tools())];
+    }
+    /**
+     * Every module, one line each in the prompt. A name is declared once: every
+     * group that declares it lists its functions together, so a group that adds a
+     * function to a module the core already declares - an implementation's own
+     * capability, or an MCP server named after a built-in module - adds no second
+     * line for it.
+     */
+    modules() {
+        const merged = new Map();
+        for (const module of this.groups.flatMap((group) => group.modules())) {
+            const found = merged.get(module.name);
+            if (found === undefined) {
+                merged.set(module.name, module);
+                continue;
+            }
+            const declared = new Set(found.functions.map((fn) => fn.name));
+            merged.set(module.name, {
+                ...found,
+                functions: [...found.functions, ...module.functions.filter((fn) => !declared.has(fn.name))],
+            });
+        }
+        return [...merged.values()];
+    }
+    /** Every function the modules declare. */
+    functions() {
+        return this.modules().flatMap((module) => module.functions);
+    }
+    /** The direct tool names, which a script may not call. */
+    directTools() {
+        return this.tools().map((tool) => tool.name);
+    }
+    /** One call, through the group that owns it. */
+    async call(request, context) {
+        // A removal never changes a prompt, but a call into what it removed is
+        // refused with the ref of the change that removed it
+        // (docs/environment.md#deltas-in-a-window).
+        const removed = this.services.environment === undefined
+            ? undefined
+            : this.services.envCatalog().removed.find((one) => one.name === request.name);
+        if (removed !== undefined) {
+            return {
+                callId: request.callId,
+                ok: false,
+                content: "",
+                error: {
+                    rule: "env.removed",
+                    message: textOf(this.services.table, "refused.env.removed", { name: request.name, ref: removed.ref }),
+                    nextAction: textOf(this.services.table, "next.env.removed"),
+                },
+            };
+        }
+        if (request.name === "code_exec") {
+            return this.codeExec(stringArg(request.args, "script"), {
+                window: context.window,
+                ...(context.task === undefined ? {} : { task: context.task }),
+                ...(context.workspace === undefined ? {} : { workspace: context.workspace.path }),
+                ...(context.envRevision === undefined ? {} : { envRevision: context.envRevision }),
+                ...(context.call === undefined ? {} : { call: context.call }),
+            });
+        }
+        if (request.name === "tool_search")
+            return this.toolSearch(request);
+        const owner = this.groups.find((group) => group.tools().some((tool) => tool.name === request.name) ||
+            group.modules().some((module) => module.functions.some((fn) => fn.name === request.name)));
+        if (owner === undefined) {
+            return {
+                callId: request.callId,
+                ok: false,
+                content: "",
+                error: {
+                    rule: "tool.unknown",
+                    message: textOf(this.services.table, "refused.unknown_tool", { name: request.name }),
+                    nextAction: textOf(this.services.table, "next.unknown_tool"),
+                },
+            };
+        }
+        return owner.call(request, context);
+    }
+    /** One `module.function` call from a script: the same path as a direct call. */
+    async callModule(name, args, context) {
+        return this.call({ name, args, callId: context.call ?? "script" }, { window: context.window });
+    }
+    /**
+     * `tool_search`: keywords, an exact `module.function`, or nothing. An exact
+     * module name answers with that module's functions, and a skill's name or
+     * keywords answer with its path and how to read it
+     * (docs/environment.md#using-a-skill-or-a-server).
+     */
+    search(keywords) {
+        const modules = this.modules();
+        const functions = this.functions();
+        const skills = this.services.environment === undefined ? [] : this.services.envCatalog().items.filter((item) => item.kind === "skill");
+        if (keywords === undefined || keywords.trim() === "") {
+            return { modules: modules.map((module) => module.name), functions: [], skills };
+        }
+        const wanted = keywords.trim();
+        const named = modules.filter((module) => module.name === wanted);
+        if (wanted.includes(".")) {
+            const found = functions.filter((fn) => fn.name === wanted);
+            return { modules: named.map((module) => module.name), functions: found.map((fn) => fn.name), skills: [] };
+        }
+        return {
+            modules: modules
+                .filter((module) => module.name.includes(wanted) || module.description.includes(wanted))
+                .map((module) => module.name),
+            // A server's name answers with its functions, not only the module's line.
+            functions: functions
+                .filter((fn) => fn.name.includes(wanted) ||
+                fn.description.includes(wanted) ||
+                named.some((module) => module.functions.includes(fn)))
+                .map((fn) => fn.name),
+            skills: skills.filter((skill) => skill.name.includes(wanted) || skill.description.includes(wanted)),
+        };
+    }
+    /** `tool_describe`: one function's signature and description. */
+    describe(name) {
+        const found = this.functions().find((fn) => fn.name === name);
+        return found === undefined ? undefined : `${found.signature} - ${found.description}`;
+    }
+    /** `code_exec`: run one script against this catalog. */
+    async codeExec(script, context) {
+        return runScript(script, this, this.services, context);
+    }
+    /** `tool_search` as a direct call: one block per name it answers. */
+    toolSearch(request) {
+        const table = this.services.table;
+        const keywords = stringArg(request.args, "keywords");
+        const found = this.search(keywords === "" ? undefined : keywords);
+        const lines = [];
+        if (found.modules.length > 0) {
+            lines.push(textOf(table, "result.tool_search.modules", { names: found.modules.join(", ") }));
+        }
+        for (const name of found.functions) {
+            lines.push(this.describe(name) ?? name);
+        }
+        // A skill is used by reading it, so the answer names its path.
+        for (const skill of found.skills) {
+            if (skill.path === undefined)
+                continue;
+            lines.push(textOf(table, "result.tool_search.skill", { name: skill.name, description: skill.description, path: skill.path }));
+        }
+        return {
+            callId: request.callId,
+            ok: true,
+            content: lines.length === 0 ? textOf(table, "result.tool_search.none") : lines.join("\n"),
+        };
+    }
+    /** The guard a script goes through, exposed for tests. */
+    decisionIn(script) {
+        return directToolIn(script, this.directTools());
+    }
+}
+function stringArg(args, name) {
+    const value = args[name];
+    return typeof value === "string" ? value : "";
+}
+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);
+    });
+}

package/code-exec.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `code_exec`: everything that is not a decision runs from a script
+ * (docs/tools.md#rules).
+ *
+ * A script that names a direct tool is refused with the rule and never reaches
+ * the host. Calls from a script go through the same hooks as direct calls, so
+ * anchors, watermarks, quotas, validation and logging behave the same: every
+ * module function is the same service call the direct tool makes.
+ *
+ * Two lookups are script globals: `tool_search` takes keywords, an exact
+ * `module.function` name, or nothing for every module; `tool_describe` returns
+ * one signature. Both read the catalog frozen with the window plus the
+ * environment deltas since.
+ */
+import type { ModuleSpec, ToolResult, WindowRef } from "@4fu/arbor-interfaces";
+import type { ToolServices } from "./host.ts";
+/** How long one script may run before it is stopped. */
+declare const SCRIPT_TIMEOUT_MS = 60000;
+export interface CodeExecContext {
+    window: WindowRef;
+    workspace?: string;
+    task?: string;
+    envRevision?: string;
+    /** The event the `code_exec` call itself is recorded at. */
+    call?: string;
+}
+/** The catalog a script calls through. */
+export interface ScriptCatalog {
+    modules(): readonly ModuleSpec[];
+    /** Run one `module.function` call, the same path a direct call takes. */
+    callModule(name: string, args: Record<string, unknown>, context: CodeExecContext): Promise<ToolResult>;
+    /** `tool_search`: keywords, an exact name, or nothing for every module. */
+    search(keywords?: string): {
+        modules: readonly string[];
+        functions: readonly string[];
+        skills: readonly {
+            name: string;
+            description: string;
+            path?: string;
+        }[];
+    };
+    /** `tool_describe`: one function's signature. */
+    describe(name: string): string | undefined;
+    /** The direct tool names a script may not call. */
+    directTools(): readonly string[];
+}
+/** Run one script in its own context, with the modules as globals. */
+export declare function runScript(script: string, catalog: ScriptCatalog, services: ToolServices, context: CodeExecContext): Promise<ToolResult>;
+/**
+ * The direct tool a script names, if any. This is a guard, not a sandbox: it
+ * keeps a decision out of a script, and the host still enforces every rule.
+ */
+export declare function directToolIn(script: string, tools: readonly string[]): string | undefined;
+export { SCRIPT_TIMEOUT_MS };
+export type { WindowRef };