@4fu/arbor-tools 2026.1106.0 → 2026.1107.0

package/README.md

@@ -27,9 +27,11 @@ everything that takes judgment, such as git, merges and conflicts, to the agent.
   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 shared workspace with per-window checkouts.** The default workspace is
+  ovnfs: one shared folder every window reads, and a window opens its own
+  copy-on-write checkout of the project it needs, works there and merges back
+  with `apply`. It falls back to a plain directory per window when ovnfs is not
+  installed. It is not a sandbox: ovnfs isolates files, not processes.
 - **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.
@@ -54,7 +56,9 @@ npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
 ```
 
 `@4fu/arbor-plugin-http` is optional; it is the example plugin below.
-`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the lexical package, and
+`@4fu/arbor-search-zvec` an optional peer of the journal: absent either one, the
+journal searches lexically and nothing else changes.
 
 ## A minimal host
 
@@ -118,7 +122,10 @@ window gets, and how a continuation keeps working in it, are in
 | [`@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-lexical`](packages/lexical) | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
+| [`@4fu/arbor-search-zvec`](packages/search-zvec) | the optional semantic channel: event text embedded and searched by meaning with zvec |
+| [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the fallback `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@4fu/arbor-workspace-ovnfs`](packages/workspace-ovnfs) | the default `Workspace` when ovnfs is installed: one shared folder, per-window copy-on-write checkouts the model opens and applies back |
 | [`@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 |
@@ -151,7 +158,7 @@ deployment can see what it would be taking on before it adopts one.
 | [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/workspaces.md](docs/workspaces.md) | the shared folder and per-window checkouts: 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 |
@@ -168,6 +175,7 @@ tarball would contain ([docs/release.md](docs/release.md)).
 | `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/lexical` | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
 | `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 |

package/catalog.d.ts

@@ -5,9 +5,15 @@
  * 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.
+ * runs a script against it and refuses a script that names one of arbor's own
+ * direct tools.
+ *
+ * A tool declared from outside the core - a plugin's own, or a backend's
+ * injection of an outside harness's - is registered here too, and from that
+ * moment it is an ordinary direct tool: same declaration, same routing, same
+ * result cut (docs/tools.md#external-tools).
  */
-import type { CallContext, DirectToolSpec, EnvItem, FunctionSpec, ModuleSpec, ToolCall, ToolGroup, ToolResult } from "@4fu/arbor-interfaces";
+import type { CallContext, DirectToolSpec, EnvItem, ExternalTool, 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 {
@@ -15,13 +21,70 @@ export interface ToolCatalogOptions {
     /** Extra groups, from a plugin. */
     groups?: readonly ToolGroup[];
 }
+/**
+ * One external tool the catalog did not register, because its name was already
+ * declared. A core tool always wins, and so does the external tool that arrived
+ * first; the collision is handed back rather than thrown, so the host records
+ * it with its rule and the operator sees it (docs/tools.md#external-tools).
+ */
+export interface ExternalToolRefusal {
+    /** The tool that was not registered. */
+    name: string;
+    /** Who declared it: the plugin's name, or the backend's. */
+    source: string;
+    /** The rule that refused it: `tool.name_taken`. */
+    rule: string;
+}
+/** What one `tool_search` answers: names, and the items a name belongs to. */
+export interface SearchAnswer {
+    modules: readonly string[];
+    functions: readonly string[];
+    skills: readonly EnvItem[];
+    tools: readonly DirectToolSpec[];
+}
+/** How many names one `tool_search` answer lists before it says there are more. */
+export declare const SEARCH_CAP = 20;
 export declare class ToolCatalog implements ToolGroup, ScriptCatalog {
     readonly id = "catalog";
     private readonly services;
-    private readonly groups;
+    /** The groups the core declares itself, which no external tool may shadow. */
+    private readonly own;
+    /**
+     * The groups a deployment registered - the core's own, what the workspace
+     * implementation contributes, and a plugin's own groups - which no external
+     * tool may shadow either.
+     */
+    private readonly base;
+    /**
+     * One group per source that declared external tools, the source's name as the
+     * key. A refresh replaces the group its source declared before, so a tool the
+     * source dropped is no longer declared and no longer callable
+     * (docs/tools.md#external-tools-that-change).
+     */
+    private readonly externalGroups;
     constructor(options: ToolCatalogOptions);
+    /** Every group: the base, then one per source that declared external tools. */
+    private get groups();
+    /**
+     * Register direct tools declared from outside the core - a plugin's own, or a
+     * backend's injection of the tools an outside harness registered
+     * (docs/tools.md#external-tools).
+     *
+     * A name the model already has is not registered: a core tool always wins,
+     * and so does the external tool that arrived first. The collisions come back
+     * with the rule that refused them, so the host records them for the operator
+     * instead of throwing. The rule runs on every call, so every refresh of the
+     * set is checked the same way.
+     *
+     * What this source declared before is replaced, so a refresh that drops a
+     * tool leaves it undeclared and uncallable - and a tool the source declares
+     * again is not a collision with itself.
+     */
+    external(tools: readonly ExternalTool[], source: string): readonly ExternalToolRefusal[];
     /** Every direct tool, one line each in the prompt. */
     tools(): readonly DirectToolSpec[];
+    /** The two entry points to the modules, which every window has. */
+    private entryPoints;
     /**
      * 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
@@ -34,21 +97,36 @@ export declare class ToolCatalog implements ToolGroup, ScriptCatalog {
     functions(): readonly FunctionSpec[];
     /** The direct tool names, which a script may not call. */
     directTools(): readonly string[];
+    /**
+     * The direct tools a script may call: every one the core does not declare
+     * itself (docs/tools.md#rules). A plugin's or a backend's tool is a
+     * capability of its own, like a module function, so a script reaches it the
+     * same way; arbor's own decisions and commands stay in the turn.
+     */
+    scriptTools(): readonly DirectToolSpec[];
+    /** The direct tools arbor declares itself: its decisions and its commands. */
+    private ownTools;
     /** 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).
+     * The call itself: the removal check, the two entry points, then the group
+     * that owns the name. A name no group owns is refused, because the prompt
+     * promises `tool_search` answers it (docs/tools.md#rules).
+     */
+    private route;
+    /** The result as it leaves: the tool that was called, and the call's own id. */
+    private named;
+    /**
+     * `tool_search`: keywords, an exact `module.function` or tool name, or
+     * nothing. An exact module name answers with that module's functions, a
+     * direct tool answers with its description, 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). A name is matched exactly
+     * first, then by prefix, then by description.
      */
-    search(keywords?: string): {
-        modules: readonly string[];
-        functions: readonly string[];
-        skills: readonly EnvItem[];
-    };
+    search(keywords?: string): SearchAnswer;
     /** `tool_describe`: one function's signature and description. */
     describe(name: string): string | undefined;
     /** `code_exec`: run one script against this catalog. */

package/catalog.js

@@ -5,22 +5,46 @@
  * 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.
+ * runs a script against it and refuses a script that names one of arbor's own
+ * direct tools.
+ *
+ * A tool declared from outside the core - a plugin's own, or a backend's
+ * injection of an outside harness's - is registered here too, and from that
+ * moment it is an ordinary direct tool: same declaration, same routing, same
+ * result cut (docs/tools.md#external-tools).
  */
-import { textOf } from "@4fu/arbor-prompt";
+import { textOf, toolLine } from "@4fu/arbor-prompt";
 import { directToolIn, runScript } from "./code-exec.js";
+import { boundResult } from "./bound.js";
 import { CoreToolGroup } from "./groups/core.js";
 import { EnvToolGroup } from "./groups/env.js";
+import { ExternalToolGroup } from "./groups/external.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";
+/** How many names one `tool_search` answer lists before it says there are more. */
+export const SEARCH_CAP = 20;
 export class ToolCatalog {
     id = "catalog";
     services;
-    groups;
+    /** The groups the core declares itself, which no external tool may shadow. */
+    own;
+    /**
+     * The groups a deployment registered - the core's own, what the workspace
+     * implementation contributes, and a plugin's own groups - which no external
+     * tool may shadow either.
+     */
+    base;
+    /**
+     * One group per source that declared external tools, the source's name as the
+     * key. A refresh replaces the group its source declared before, so a tool the
+     * source dropped is no longer declared and no longer callable
+     * (docs/tools.md#external-tools-that-change).
+     */
+    externalGroups = new Map();
     constructor(options) {
         this.services = options.services;
-        this.groups = [
+        this.own = [
             new CoreToolGroup(options.services),
             new FileToolGroup(options.services),
             new NoteToolGroup(options.services),
@@ -34,16 +58,61 @@ export class ToolCatalog {
             new WorkspaceModuleGroup(options.services),
             new EnvToolGroup(options.services),
             new EnvModuleGroup(options.services),
+        ];
+        this.base = [
+            ...this.own,
             // 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 group: the base, then one per source that declared external tools. */
+    get groups() {
+        return [...this.base, ...this.externalGroups.values()];
+    }
+    /**
+     * Register direct tools declared from outside the core - a plugin's own, or a
+     * backend's injection of the tools an outside harness registered
+     * (docs/tools.md#external-tools).
+     *
+     * A name the model already has is not registered: a core tool always wins,
+     * and so does the external tool that arrived first. The collisions come back
+     * with the rule that refused them, so the host records them for the operator
+     * instead of throwing. The rule runs on every call, so every refresh of the
+     * set is checked the same way.
+     *
+     * What this source declared before is replaced, so a refresh that drops a
+     * tool leaves it undeclared and uncallable - and a tool the source declares
+     * again is not a collision with itself.
+     */
+    external(tools, source) {
+        const others = [...this.base, ...[...this.externalGroups].filter(([name]) => name !== source).map(([, group]) => group)];
+        const taken = new Set([
+            ...others.flatMap((group) => group.tools()).map((tool) => tool.name),
+            ...others.flatMap((group) => group.modules()).map((module) => module.name),
+        ]);
+        const refused = [];
+        const declared = [];
+        for (const tool of tools) {
+            if (taken.has(tool.name)) {
+                refused.push({ name: tool.name, source, rule: "tool.name_taken" });
+                continue;
+            }
+            taken.add(tool.name);
+            declared.push(tool);
+        }
+        this.externalGroups.set(source, new ExternalToolGroup(declared, source, this.services));
+        return refused;
+    }
     /** Every direct tool, one line each in the prompt. */
     tools() {
+        return [...this.entryPoints(), ...this.groups.flatMap((group) => group.tools())];
+    }
+    /** The two entry points to the modules, which every window has. */
+    entryPoints() {
         const table = this.services.table;
-        const entryPoints = [
+        return [
             {
                 name: "code_exec",
                 description: lookup(table, "tool.code_exec", {}),
@@ -55,7 +124,6 @@ export class ToolCatalog {
                 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
@@ -86,10 +154,54 @@ export class ToolCatalog {
     }
     /** The direct tool names, which a script may not call. */
     directTools() {
-        return this.tools().map((tool) => tool.name);
+        return this.ownTools().map((tool) => tool.name);
+    }
+    /**
+     * The direct tools a script may call: every one the core does not declare
+     * itself (docs/tools.md#rules). A plugin's or a backend's tool is a
+     * capability of its own, like a module function, so a script reaches it the
+     * same way; arbor's own decisions and commands stay in the turn.
+     */
+    scriptTools() {
+        const own = new Set(this.directTools());
+        return this.tools().filter((tool) => !own.has(tool.name));
+    }
+    /** The direct tools arbor declares itself: its decisions and its commands. */
+    ownTools() {
+        return [...this.entryPoints(), ...this.own.flatMap((group) => group.tools())];
     }
     /** One call, through the group that owns it. */
     async call(request, context) {
+        const result = this.named(request, await this.route(request, context));
+        // The one exit every direct call leaves by: one head-and-tail cut, for
+        // every tool, with the whole kept in the workspace
+        // (docs/prompting.md#information-density).
+        if (!result.ok)
+            return result;
+        return {
+            ...result,
+            content: await boundResult(result.content, {
+                ...(context.workspace === undefined ? {} : { workspace: context.workspace.path }),
+                ...(context.call === undefined ? {} : { callId: context.call }),
+                table: this.services.table,
+            }),
+        };
+    }
+    /** One `module.function` call from a script: the same path as a direct call. */
+    async callModule(name, args, context) {
+        // No cut here: the script reads the whole answer and cuts what it returns.
+        return this.named({ name, args, callId: context.call ?? "script" }, await this.route({
+            name,
+            args,
+            callId: context.call ?? "script",
+        }, { window: context.window }));
+    }
+    /**
+     * The call itself: the removal check, the two entry points, then the group
+     * that owns the name. A name no group owns is refused, because the prompt
+     * promises `tool_search` answers it (docs/tools.md#rules).
+     */
+    async route(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).
@@ -135,40 +247,51 @@ export class ToolCatalog {
         }
         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 });
+    /** The result as it leaves: the tool that was called, and the call's own id. */
+    named(request, result) {
+        return {
+            ...result,
+            callId: result.callId === "" ? request.callId : result.callId,
+            tool: result.tool ?? request.name,
+        };
     }
     /**
-     * `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).
+     * `tool_search`: keywords, an exact `module.function` or tool name, or
+     * nothing. An exact module name answers with that module's functions, a
+     * direct tool answers with its description, 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). A name is matched exactly
+     * first, then by prefix, then by description.
      */
     search(keywords) {
         const modules = this.modules();
         const functions = this.functions();
+        const tools = this.tools();
         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 };
+            return { modules: modules.map((module) => module.name), functions: [], skills, tools: [] };
         }
         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: named.map((module) => module.name),
+                functions: functions.filter((fn) => fn.name === wanted).map((fn) => fn.name),
+                skills: [],
+                tools: tools.filter((tool) => tool.name === wanted),
+            };
         }
+        const rankedFunctions = ranked(wanted, functions, (fn) => [shortName(fn.name), fn.description]);
         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)),
+            modules: ranked(wanted, modules, (module) => [module.name, module.description]).map((module) => module.name),
+            // A server's name answers with its functions, not only the module's line;
+            // any other keyword answers with the functions whose own name or
+            // description holds it.
+            functions: (named.length === 0
+                ? rankedFunctions
+                : functions.filter((fn) => named.some((module) => module.functions.includes(fn)))).map((fn) => fn.name),
+            skills: ranked(wanted, skills, (skill) => [skill.name, skill.description]),
+            tools: ranked(wanted, tools, (tool) => [tool.name, tool.description]),
         };
     }
     /** `tool_describe`: one function's signature and description. */
@@ -185,10 +308,14 @@ export class ToolCatalog {
         const table = this.services.table;
         const keywords = stringArg(request.args, "keywords");
         const found = this.search(keywords === "" ? undefined : keywords);
-        const lines = [];
+        const lines = [textOf(table, "result.tool_search.lead")];
         if (found.modules.length > 0) {
             lines.push(textOf(table, "result.tool_search.modules", { names: found.modules.join(", ") }));
         }
+        for (const tool of found.tools) {
+            // The renderer's own rule, so the lookup and the prompt never disagree.
+            lines.push(toolLine(table, tool));
+        }
         for (const name of found.functions) {
             lines.push(this.describe(name) ?? name);
         }
@@ -198,11 +325,22 @@ export class ToolCatalog {
                 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"),
-        };
+        const listed = found.modules.length + found.tools.length + found.functions.length + found.skills.length;
+        if (listed === 0) {
+            lines.push(textOf(table, "result.tool_search.none"));
+        }
+        else {
+            // A module the answer names with no function to call is said out loud,
+            // so the model does not go looking for one.
+            if (found.modules.length > 0 && found.functions.length === 0 && found.tools.length === 0 && found.skills.length === 0) {
+                lines.push(textOf(table, "result.tool_search.none_functions"));
+            }
+            if (listed > SEARCH_CAP) {
+                lines.push(textOf(table, "result.tool_search.more", { count: listed - SEARCH_CAP }));
+            }
+        }
+        lines.push(textOf(table, "result.tool_search.hint"));
+        return { callId: request.callId, ok: true, content: lines.join("\n") };
     }
     /** The guard a script goes through, exposed for tests. */
     decisionIn(script) {
@@ -213,6 +351,29 @@ function stringArg(args, name) {
     const value = args[name];
     return typeof value === "string" ? value : "";
 }
+/**
+ * The matches, strongest first: an exact name, then a name that starts with
+ * the query, then a description that holds it. Ties keep the order the catalog
+ * declares them in, so the answer is deterministic.
+ */
+function ranked(wanted, items, keys) {
+    const found = [];
+    for (const item of items) {
+        const [name, description] = keys(item);
+        if (name === wanted)
+            found.push({ rank: 0, item });
+        else if (name.startsWith(wanted))
+            found.push({ rank: 1, item });
+        else if (description.includes(wanted))
+            found.push({ rank: 2, item });
+    }
+    return found.sort((left, right) => left.rank - right.rank).map((one) => one.item);
+}
+/** A function's own name, without the `module.` the catalog declares it with. */
+function shortName(name) {
+    const dot = name.indexOf(".");
+    return dot === -1 ? name : name.slice(dot + 1);
+}
 function lookup(table, key, args) {
     const template = table[key];
     if (template === undefined)

package/child-env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The environment a child process gets
+ * (docs/environment.md#what-a-subprocess-gets).
+ *
+ * Every MCP server, resident service and command a window runs inherits the
+ * host's whole environment, plus what its own configuration adds: the
+ * directory it works in, the item's own `env`, and the secrets it names by
+ * name. Nothing is withheld here on purpose: protection is one layer, the
+ * secret scrub, which replaces every configured secret value in whatever
+ * reaches the model or the journal (docs/environment.md#secrets).
+ */
+/** The variable that carries the directory a child process works in. */
+export declare const WORKSPACE_ENV = "ARBOR_WORKSPACE";
+/** What one child process is given beyond the host's own environment. */
+export interface ChildEnvInput {
+    /** The directory it works in, when it has one. */
+    workspace?: string;
+    /** What its own configuration declares. */
+    env?: Record<string, string | undefined>;
+    /** The secrets its configuration names; their values are resolved by the caller. */
+    secrets?: Record<string, string | undefined>;
+}
+/** One child process's environment: the host's, then what its configuration adds. */
+export declare function childEnvironment(input: ChildEnvInput): Record<string, string>;

package/child-env.js

@@ -0,0 +1,32 @@
+/**
+ * The environment a child process gets
+ * (docs/environment.md#what-a-subprocess-gets).
+ *
+ * Every MCP server, resident service and command a window runs inherits the
+ * host's whole environment, plus what its own configuration adds: the
+ * directory it works in, the item's own `env`, and the secrets it names by
+ * name. Nothing is withheld here on purpose: protection is one layer, the
+ * secret scrub, which replaces every configured secret value in whatever
+ * reaches the model or the journal (docs/environment.md#secrets).
+ */
+/** The variable that carries the directory a child process works in. */
+export const WORKSPACE_ENV = "ARBOR_WORKSPACE";
+/** One child process's environment: the host's, then what its configuration adds. */
+export function childEnvironment(input) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    if (input.workspace !== undefined && input.workspace !== "")
+        env[WORKSPACE_ENV] = input.workspace;
+    for (const [key, value] of Object.entries(input.env ?? {})) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(input.secrets ?? {})) {
+        if (value !== undefined && value !== "")
+            env[key] = value;
+    }
+    return env;
+}

package/code-exec.d.ts

@@ -2,17 +2,18 @@
  * `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.
+ * A script that names one of arbor's own direct tools 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, and so is every tool a plugin or a backend declared.
  *
  * 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 { DirectToolSpec, 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;
@@ -38,17 +39,32 @@ export interface ScriptCatalog {
             description: string;
             path?: string;
         }[];
+        tools: readonly {
+            name: string;
+            description: string;
+        }[];
     };
     /** `tool_describe`: one function's signature. */
     describe(name: string): string | undefined;
-    /** The direct tool names a script may not call. */
+    /**
+     * The direct tool names a script may not call: arbor's own decisions and
+     * commands, which belong in the turn (docs/tools.md#rules).
+     */
     directTools(): readonly string[];
+    /**
+     * The direct tools a script may call: a plugin's or a backend's, which are
+     * capabilities of their own like a module function (docs/tools.md#rules).
+     */
+    scriptTools(): readonly DirectToolSpec[];
 }
 /** 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.
+ * keeps one of arbor's own decisions or commands out of a script, and the host
+ * still enforces every rule. A tool a plugin or a backend declared is not in
+ * the list - a script may call it, the way it calls a module function
+ * (docs/tools.md#rules).
  */
 export declare function directToolIn(script: string, tools: readonly string[]): string | undefined;
 export { SCRIPT_TIMEOUT_MS };