@4fu/arbor-workspace-dir 0.0.0-stage → 0.1.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/directory-workspace.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The plain-directory `Workspace` (docs/workspaces.md).
+ *
+ * A workspace is a plain directory, not bound to any repository: the framework
+ * gives isolation and continuity, and the agent does the rest. This
+ * implementation keeps every window's directory under one root:
+ *
+ * ```text
+ * <root>/ws3/                    the window's own directory
+ * ```
+ *
+ * A new window gets a directory of its own, created on first use. A
+ * continuation works in its predecessor's directory in place, under the same
+ * ref: no copy, no link, no fork. Only one window in a chain is live at a time,
+ * so in place is safe, and the chain is in the journal, so a restart recovers
+ * which directory a continuation uses.
+ *
+ * It isolates by directory only. Another window's directory is a path on this
+ * host, which a command may name and `read`, `write` and `edit` may open and
+ * change; nothing here refuses a path outside the window's own directory, and
+ * nothing here stops `bash`. What keeps one window out of another's directory
+ * is the prompt text `workspace.path` answers with, not a rule this
+ * implementation enforces. That is not a security boundary, and the docs say
+ * so: real isolation comes from an implementation that owns its execution
+ * environment.
+ */
+import type { TextTable, ToolGroup, WindowRef, Workspace, WorkspaceMount, WorkspaceQuota, WorkspaceRef } from "@4fu/arbor-interfaces";
+export interface DirectoryWorkspaceOptions {
+    /** The root every workspace lives under. */
+    root: string;
+}
+export declare class DirectoryWorkspace implements Workspace {
+    private readonly root;
+    constructor(options: DirectoryWorkspaceOptions);
+    /**
+     * The directory a window works in, created on first use. Idempotent: the
+     * window that already has one gets the same ref back, which is how a
+     * continuation - which asks for the window that opened its chain - lands in
+     * its predecessor's directory, in place, under the same ref.
+     */
+    create(window: WindowRef): Promise<WorkspaceRef>;
+    /**
+     * The directory a window's workspace has, or `undefined` when the window
+     * never touched files. Another window's directory is a path on this host,
+     * which is what a window reads it by.
+     */
+    pathOfWindow(window: WindowRef): Promise<string | undefined>;
+    mount(ref: WorkspaceRef): Promise<WorkspaceMount>;
+    quota(workspace: WorkspaceRef): Promise<WorkspaceQuota>;
+    reclaim(workspace: WorkspaceRef): Promise<void>;
+    /**
+     * The workspace a window's chain already has, or `undefined` when it has
+     * none. The host asks for it to reclaim a chain's directory after the
+     * retention period (docs/workspaces.md#lifecycle).
+     */
+    refOf(window: WindowRef): Promise<WorkspaceRef | undefined>;
+    /** The directory a window works in, for the file tools. */
+    pathOf(ref: WorkspaceRef): string;
+    /**
+     * What this implementation adds to the catalog: another window's directory,
+     * by its window. The core declares no such capability of its own
+     * (docs/workspaces.md).
+     */
+    groups(table: TextTable): readonly ToolGroup[];
+    private workspacePath;
+    /**
+     * The ref a window's directory has: the one it already has, or the next
+     * number nothing has taken. A window's number only grows, so a directory is
+     * never handed to a second window.
+     */
+    private allocate;
+    /** Resolve a ref a model may pass back into a path on this host. */
+    private resolve;
+}

package/directory-workspace.js

@@ -0,0 +1,224 @@
+/**
+ * The plain-directory `Workspace` (docs/workspaces.md).
+ *
+ * A workspace is a plain directory, not bound to any repository: the framework
+ * gives isolation and continuity, and the agent does the rest. This
+ * implementation keeps every window's directory under one root:
+ *
+ * ```text
+ * <root>/ws3/                    the window's own directory
+ * ```
+ *
+ * A new window gets a directory of its own, created on first use. A
+ * continuation works in its predecessor's directory in place, under the same
+ * ref: no copy, no link, no fork. Only one window in a chain is live at a time,
+ * so in place is safe, and the chain is in the journal, so a restart recovers
+ * which directory a continuation uses.
+ *
+ * It isolates by directory only. Another window's directory is a path on this
+ * host, which a command may name and `read`, `write` and `edit` may open and
+ * change; nothing here refuses a path outside the window's own directory, and
+ * nothing here stops `bash`. What keeps one window out of another's directory
+ * is the prompt text `workspace.path` answers with, not a rule this
+ * implementation enforces. That is not a security boundary, and the docs say
+ * so: real isolation comes from an implementation that owns its execution
+ * environment.
+ */
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { arborError } from "@4fu/arbor-errors";
+import { WorkspacePathGroup } from "./path-module.js";
+export class DirectoryWorkspace {
+    root;
+    constructor(options) {
+        this.root = options.root;
+    }
+    /**
+     * The directory a window works in, created on first use. Idempotent: the
+     * window that already has one gets the same ref back, which is how a
+     * continuation - which asks for the window that opened its chain - lands in
+     * its predecessor's directory, in place, under the same ref.
+     */
+    async create(window) {
+        const ref = await this.allocate(window);
+        await mkdir(this.workspacePath(ref), { recursive: true });
+        return ref;
+    }
+    /**
+     * The directory a window's workspace has, or `undefined` when the window
+     * never touched files. Another window's directory is a path on this host,
+     * which is what a window reads it by.
+     */
+    async pathOfWindow(window) {
+        const ref = await this.refOf(window);
+        return ref === undefined ? undefined : this.workspacePath(ref);
+    }
+    async mount(ref) {
+        const resolved = await this.resolve(ref);
+        return {
+            ref,
+            path: resolved,
+            readFile: async (path) => {
+                // A relative path is inside this workspace. An absolute one is read
+                // where it is on this host, which is how another window's directory is
+                // read (docs/workspaces.md).
+                return readFile(hostPath(resolved, path), "utf8").catch(() => null);
+            },
+            writeFile: async (path, text) => {
+                // Nothing is refused: a relative path is this workspace's own, an
+                // absolute one is written where it names on this host
+                // (docs/workspaces.md#another-windows-directory).
+                const target = hostPath(resolved, path);
+                await mkdir(dirname(target), { recursive: true });
+                await writeFile(target, text, "utf8");
+            },
+            release: async () => { },
+        };
+    }
+    async quota(workspace) {
+        const resolved = await this.resolve(workspace);
+        const files = await listFiles(resolved);
+        let bytes = 0;
+        for (const size of files.values())
+            bytes += size;
+        return { bytes, used: bytes, files: files.size };
+    }
+    async reclaim(workspace) {
+        await rm(this.workspacePath(workspace), { recursive: true, force: true });
+    }
+    /**
+     * The workspace a window's chain already has, or `undefined` when it has
+     * none. The host asks for it to reclaim a chain's directory after the
+     * retention period (docs/workspaces.md#lifecycle).
+     */
+    async refOf(window) {
+        const wanted = windowNumber(window);
+        if (wanted <= 0)
+            return undefined;
+        const ref = `ws${wanted}`;
+        return (await isDirectory(this.workspacePath(ref))) ? ref : undefined;
+    }
+    /** The directory a window works in, for the file tools. */
+    pathOf(ref) {
+        return this.workspacePath(ref);
+    }
+    /**
+     * What this implementation adds to the catalog: another window's directory,
+     * by its window. The core declares no such capability of its own
+     * (docs/workspaces.md).
+     */
+    groups(table) {
+        return [new WorkspacePathGroup(this, table)];
+    }
+    workspacePath(ref) {
+        return join(this.root, ref);
+    }
+    /**
+     * The ref a window's directory has: the one it already has, or the next
+     * number nothing has taken. A window's number only grows, so a directory is
+     * never handed to a second window.
+     */
+    async allocate(window) {
+        const wanted = windowNumber(window);
+        const own = wanted > 0 ? `ws${wanted}` : undefined;
+        if (own !== undefined && (await isDirectory(this.workspacePath(own))))
+            return own;
+        let entries = [];
+        try {
+            entries = await readdir(this.root);
+        }
+        catch {
+            entries = [];
+        }
+        let highest = 0;
+        for (const entry of entries) {
+            const number = /^ws(\d+)$/.exec(entry)?.[1];
+            if (number === undefined)
+                continue;
+            highest = Math.max(highest, Number(number));
+        }
+        return `ws${Math.max(highest + 1, wanted)}`;
+    }
+    /** Resolve a ref a model may pass back into a path on this host. */
+    async resolve(ref) {
+        if (!/^ws\d+$/.test(ref)) {
+            throw arborError({
+                code: "not_found",
+                rule: "workspace.ref.unknown",
+                message: `workspace: ${ref} 不是工作区引用`,
+                nextAction: "使用 ws3 形式的引用。",
+            });
+        }
+        const path = this.workspacePath(ref);
+        await assertDirectory(path, ref);
+        return path;
+    }
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function windowNumber(window) {
+    return Number(/^c(\d+)$/.exec(window)?.[1] ?? 0);
+}
+/**
+ * Where a path names on this host: itself when it is absolute, under `root`
+ * 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);
+}
+async function assertDirectory(path, ref) {
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch {
+        throw arborError({
+            code: "not_found",
+            rule: "workspace.not_found",
+            message: `workspace: ${ref} 不存在`,
+            nextAction: "先用工作区创建它，或换一个存在的引用。",
+        });
+    }
+    if (!info.isDirectory()) {
+        throw arborError({
+            code: "not_found",
+            rule: "workspace.not_directory",
+            message: `workspace: ${ref} 不是目录`,
+            nextAction: "换一个工作区引用。",
+        });
+    }
+}
+/** Every file under a directory, with its size in bytes. */
+async function listFiles(root) {
+    const files = new Map();
+    const walk = async (directory) => {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await walk(path);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const info = await stat(path);
+            files.set(path.slice(root.length + 1), info.size);
+        }
+    };
+    await walk(root);
+    return files;
+}

package/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @4fu/arbor-workspace-dir - the plain-directory `Workspace`.
+ *
+ * One directory per window, under one root, created on first use; a
+ * continuation works in its predecessor's directory in place, under the same
+ * ref. It is the only `Workspace` the framework ships, and it needs nothing a
+ * host does not already have (docs/workspaces.md).
+ */
+export { DirectoryWorkspace, type DirectoryWorkspaceOptions } from "./directory-workspace.ts";
+export { WorkspacePathGroup } from "./path-module.ts";

package/index.js

@@ -0,0 +1,10 @@
+/**
+ * @4fu/arbor-workspace-dir - the plain-directory `Workspace`.
+ *
+ * One directory per window, under one root, created on first use; a
+ * continuation works in its predecessor's directory in place, under the same
+ * ref. It is the only `Workspace` the framework ships, and it needs nothing a
+ * host does not already have (docs/workspaces.md).
+ */
+export { DirectoryWorkspace } from "./directory-workspace.js";
+export { WorkspacePathGroup } from "./path-module.js";

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@4fu/arbor-workspace-dir",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The plain-directory Workspace: one directory per window, with a continuation working in its predecessor's directory in place.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "directory-workspace.d.ts",
+    "directory-workspace.js",
+    "index.d.ts",
+    "index.js",
+    "path-module.d.ts",
+    "path-module.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/workspace-dir"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "0.1.0",
+    "@4fu/arbor-interfaces": "0.1.0",
+    "@4fu/arbor-prompt": "0.1.0"
+  }
+}

package/path-module.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The capability the built-in directory workspace contributes: another
+ * window's directory, by its window (docs/workspaces.md).
+ *
+ * The core knows nothing about it. A window reads another window's directory
+ * through `read`, by the path this answers, and both the description and the
+ * result say the directory belongs to another window and must not be modified.
+ * Nothing here enforces that, because the built-in workspace isolates by
+ * directory only: another window's directory is a path on the same host, which
+ * a command may name. It is not a security boundary, and real isolation comes
+ * from an implementation that owns its execution environment.
+ */
+import type { ModuleSpec, TextTable, ToolCall, ToolGroup, ToolResult } from "@4fu/arbor-interfaces";
+import type { DirectoryWorkspace } from "./directory-workspace.ts";
+/** `workspace.path`: the directory of a window's workspace, by its window. */
+export declare class WorkspacePathGroup implements ToolGroup {
+    readonly id = "workspace.path";
+    private readonly workspace;
+    private readonly table;
+    constructor(workspace: DirectoryWorkspace, table: TextTable);
+    tools(): readonly [];
+    modules(): readonly ModuleSpec[];
+    call(request: ToolCall): Promise<ToolResult>;
+    private notOwned;
+}

package/path-module.js

@@ -0,0 +1,80 @@
+/**
+ * The capability the built-in directory workspace contributes: another
+ * window's directory, by its window (docs/workspaces.md).
+ *
+ * The core knows nothing about it. A window reads another window's directory
+ * through `read`, by the path this answers, and both the description and the
+ * result say the directory belongs to another window and must not be modified.
+ * Nothing here enforces that, because the built-in workspace isolates by
+ * directory only: another window's directory is a path on the same host, which
+ * a command may name. It is not a security boundary, and real isolation comes
+ * from an implementation that owns its execution environment.
+ */
+import { textOf } from "@4fu/arbor-prompt";
+/** `workspace.path`: the directory of a window's workspace, by its window. */
+export class WorkspacePathGroup {
+    id = "workspace.path";
+    workspace;
+    table;
+    constructor(workspace, table) {
+        this.workspace = workspace;
+        this.table = table;
+    }
+    tools() {
+        return [];
+    }
+    modules() {
+        return [
+            {
+                name: "workspace",
+                description: textOf(this.table, "module.workspace"),
+                functions: [
+                    {
+                        name: "workspace.path",
+                        signature: "workspace.path(window)",
+                        description: textOf(this.table, "function.workspace.path"),
+                    },
+                ],
+            },
+        ];
+    }
+    async call(request) {
+        if (request.name !== "workspace.path")
+            return this.notOwned(request);
+        const window = windowArg(request.args.window);
+        const path = await this.workspace.pathOfWindow(window);
+        if (path === undefined) {
+            return {
+                callId: request.callId,
+                ok: false,
+                content: "",
+                error: {
+                    rule: "workspace.not_found",
+                    message: textOf(this.table, "refused.workspace.path", { window }),
+                    nextAction: textOf(this.table, "next.workspace.path"),
+                },
+            };
+        }
+        return {
+            callId: request.callId,
+            ok: true,
+            content: textOf(this.table, "result.workspace.path", { window, path }),
+        };
+    }
+    notOwned(request) {
+        return {
+            callId: request.callId,
+            ok: false,
+            content: "",
+            error: {
+                rule: "module.function.unknown",
+                message: textOf(this.table, "refused.unknown_function", { module: "workspace", name: request.name }),
+                nextAction: textOf(this.table, "next.unknown_function"),
+            },
+        };
+    }
+}
+/** The window an argument names, or `c0` when it names none. */
+function windowArg(value) {
+    return typeof value === "string" && /^c\d+$/.test(value) ? value : "c0";
+}