@better-fs-tools/pi-durable 0.0.0-tegami-trusted-publish-setup → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth Andrew
+
+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,6 +1,98 @@
-# Placeholder package
-  
-  This empty package was published by [Tegami](https://tegami.fuma-nama.dev) to configure npm trusted publishing.
-  
-  The real package contents will be published via CI with OIDC.
-  
+# @better-fs-tools/pi-durable
+
+Better FS Tools for [`@earendil-works/pi-durable`](https://www.npmjs.com/package/@earendil-works/pi-durable), the experimental durable harness of Pi. It replaces the `read`, `edit`, and `write` of `CodingTools`, and can add `apply_patch` and `bash`. Each call reads and writes through the call's execution environment, so the tools work on the local machine, over SSH with `@earendil-works/pi-env`, and in a container.
+
+`@earendil-works/pi-durable` is experimental. Its API can change in each release. This package follows pi-durable 1.2.
+
+## Install
+
+```sh
+npm install @better-fs-tools/pi-durable @earendil-works/pi-durable @earendil-works/chord typebox
+```
+
+`@earendil-works/pi-durable` (`~1.2.0`), `@earendil-works/chord` (`~1.2.0`), and `typebox` (`^1.3.16`) are required peers. The package imports no `node:` module.
+
+## Example
+
+Install the extension after `CodingTools`. When two extensions have a tool with the same name, the one installed later wins. In the first registry, `read`, `edit`, and `write` come from Better FS Tools, and `bash` stays from `CodingTools`. The second registry has the recommended configuration:
+
+```ts
+import { createRegistry } from "@earendil-works/pi-durable";
+import { CodingTools } from "@earendil-works/pi-durable/tools";
+import {
+  createDurableFsTools,
+  documentReadStore,
+  durableEnvFileSystem,
+  durableEnvRunner,
+} from "@better-fs-tools/pi-durable";
+import { shellEnv } from "@better-fs-tools/shell";
+
+// Installed after CodingTools, so its read, edit, and write win. The bash of
+// CodingTools stays.
+export function fsToolsRegistry() {
+  const registry = createRegistry();
+  registry.install(CodingTools);
+  registry.install(
+    createDurableFsTools({
+      fs: durableEnvFileSystem(), // each call reads and writes through its ExecutionEnv
+    }),
+  );
+  return registry;
+}
+
+// The recommended configuration: read records in the conversation's
+// documents, so they stay after a restart and follow a fork, and bash over the
+// environment's exec() in place of the bash of CodingTools.
+export function recommendedRegistry() {
+  const registry = createRegistry();
+  registry.install(CodingTools);
+  registry.install(
+    createDurableFsTools({
+      fs: durableEnvFileSystem({ allowedRoots: ["."] }),
+      state: documentReadStore(),
+      bash: { runner: durableEnvRunner(), env: shellEnv() },
+    }),
+  );
+  return registry;
+}
+```
+
+Give the registry to `Harness.open()` with an `env` option, as for `CodingTools`.
+
+## What the extension does
+
+- `createDurableFsTools(options)` takes the options of `createFsTools()`, with the same defaults, plus a `signature` in each tool's options and the Harness settings `name` and `outputLimits`. `fs` is required. bash needs a `runner` and an `env`, and `bash: true` throws. `docs/hosts.md` in `@better-fs-tools/write` has the full table.
+- The host of each call is `{ api, env, context }`: the tool API, the `ExecutionEnv` of the call, and its Chord context. Host functions, such as an authorizer, get it as `ctx.call.host`. A factory `fs`, `state`, or `runner` gets the call. A call without an environment fails with an error result.
+- `read` is `replay: "safe"`, so the Harness runs it again after a crash. `edit`, `write`, and `apply_patch` keep the default `"unsafe"`: after a crash the model gets an interrupted result and reads the file again.
+- `outputLimits` defaults to 128 KiB and 4,000 lines, above the 2,000-line and 50 KiB view of `read`, so the Harness does not cut the output a second time. `name` defaults to `"better-fs-tools"`.
+- A signature with a `grammar` sets `constrainedSampling`, as in the Pi integrations. For the Codex patch grammar, pass `applyPatch: { signature: freeformPatchSignature() }`. `edit: { signature: multiEditSignature() }` gives the `edits: [{ oldText, newText }]` input of Durable's own `edit`.
+- A tool error is a result with `isError: true`. A nonzero bash exit, a timeout, and an error are error results too. No tool declares a `structuredOutputSchema`, so programs get the text.
+- `locks` defaults to one `memoryLocks()` for every call of the extension. The keys get the environment id, so the same path in two environments does not wait. The tools do not share the queue of the `CodingTools` `edit` and `write`: pi-durable does not export it.
+
+## Recommended configuration
+
+These choices suit the durable harness. They are options, not defaults:
+
+- `fs: durableEnvFileSystem()`: each call reads and writes through the call's `ExecutionEnv`, so the tools work on the local machine, over SSH with pi-env, and in a container. `allowedRoots` is relative to the environment's `cwd`, and defaults to `["."]`. It also takes `denyRoots` and `symlinks`.
+- `state: documentReadStore()`: each read record is a `ReadStateDoc` document of the conversation. The records stay after a restart, so an `edit` in the next process needs no new read. A fork starts with the records its parent had at the fork entry. A `ReadStateStore`, such as `memoryStore()`, is shared by every conversation in place.
+- `bash: { runner: durableEnvRunner(), env: shellEnv() }`: commands run through the environment's `exec()`. A `cwd` from the model is relative to the environment's `cwd`. By default a command keeps the environment's own variables, with `defaultShellEnv` over them: `durableEnvRunner({ inheritEnv: false })` makes `env` the whole environment.
+
+## The parts
+
+| Export                                                   | What it is                                                                   |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `createDurableFsTools(options)`                          | The extension                                                                |
+| `durableEnvFileSystem(options?)`                         | A per-call `fs`: `executionEnvFileSystem()` over the call's environment      |
+| `durableEnvRunner(options?)`                             | A per-call bash `runner`: `executionEnvRunner()` over the call's environment |
+| `documentReadStore()`                                    | A per-call `state` in the conversation's `ReadStateDoc` documents            |
+| `executionEnvFileSystem(env, { context, allowedRoots })` | A `WritableFileSystem` over any `ExecutionEnv`, for any tool or bundle       |
+| `executionEnvRunner(env, { context })`                   | A bash `CommandRunner` over `env.exec()`                                     |
+| `ReadStateDoc`                                           | The document family of the read records                                      |
+
+`executionEnvFileSystem()` passes the filesystem and write conformance suites of `@better-fs-tools/fs`. Paths are POSIX paths in the environment. A path is checked against the roots as written, and again after its symbolic links resolve. A write through a dangling symbolic link is refused. Reads stream through `openBinaryReader()`. Writes use the environment's `writeFile()`, which replaces the content in place: the file keeps its mode, but the write is not atomic. Versions are weak: size and modification time.
+
+## Links
+
+- [`@better-fs-tools/write`](https://www.npmjs.com/package/@better-fs-tools/write): `createFsTools()`, the write options, and the guards
+- [`@better-fs-tools/read`](https://www.npmjs.com/package/@better-fs-tools/read): every read option and the signatures
+- [`@better-fs-tools/pi`](https://www.npmjs.com/package/@better-fs-tools/pi): the tools for the Pi coding agent and for pi-agent-core

package/dist/extension.d.ts

@@ -0,0 +1,65 @@
+import type { Extension, ToolRegistration } from "@earendil-works/pi-durable";
+import type { ReadSignature } from "@better-fs-tools/read/signature";
+import type { BashSignature } from "@better-fs-tools/shell/signature";
+import type { FsToolsApplyPatchOptions, FsToolsBashOptions, FsToolsEditOptions, FsToolsOptions, FsToolsReadOptions, FsToolsWriteOptions } from "@better-fs-tools/write";
+import type { EditSignature, PatchSignature, WriteSignature } from "@better-fs-tools/write/signature";
+import type { DurableFsHost } from "./host.ts";
+type Host = DurableFsHost;
+export type DurableFsToolsReadOptions = FsToolsReadOptions<Host> & {
+    /** Default defaultReadSignature(). */
+    readonly signature?: ReadSignature;
+};
+export type DurableFsToolsEditOptions = FsToolsEditOptions<Host> & {
+    /** Default defaultEditSignature({ matchers }). */
+    readonly signature?: EditSignature;
+};
+export type DurableFsToolsWriteOptions = FsToolsWriteOptions<Host> & {
+    /** Default defaultWriteSignature(). */
+    readonly signature?: WriteSignature;
+};
+export type DurableFsToolsApplyPatchOptions = FsToolsApplyPatchOptions<Host> & {
+    /** Default defaultPatchSignature(). */
+    readonly signature?: PatchSignature;
+};
+/** bash options. `runner` and `env` are required: durableEnvRunner() runs over the environment's exec(). */
+export type DurableFsToolsBashOptions = FsToolsBashOptions<Host> & {
+    /** Default defaultBashSignature() for the runner's id and the limits. */
+    readonly signature?: BashSignature;
+};
+/**
+ * The options of createFsTools(), with the call's `{ api, env, context }` as
+ * host and a `signature` in each tool's options, plus the Harness settings
+ * `name` and `outputLimits`. `fs` is required: durableEnvFileSystem() reads
+ * and writes through the call's environment.
+ */
+export interface DurableFsToolsOptions extends Omit<FsToolsOptions<Host>, "read" | "edit" | "write" | "applyPatch" | "bash"> {
+    /** The extension name. Default "better-fs-tools". */
+    readonly name?: string;
+    /** The Harness output limits of read, edit, write, and apply_patch. Default 128 KiB and 4,000 lines. */
+    readonly outputLimits?: ToolRegistration["outputLimits"];
+    readonly read?: DurableFsToolsReadOptions;
+    readonly edit?: DurableFsToolsEditOptions;
+    readonly write?: DurableFsToolsWriteOptions;
+    /** Off by default. `true` or an options object adds apply_patch. */
+    readonly applyPatch?: boolean | DurableFsToolsApplyPatchOptions;
+    /**
+     * Off by default, so the bash of CodingTools stays. An options object with a
+     * runner and an env adds a bash tool.
+     */
+    readonly bash?: false | DurableFsToolsBashOptions;
+}
+/**
+ * A pi-durable extension with Better FS Tools read, edit, and write, and
+ * optionally apply_patch and bash. Install it after CodingTools: a later
+ * extension's tool with the same name replaces the earlier one. Every tool
+ * option and default is the one of createFsTools(). The lock keys get the
+ * environment id, so the same path in two environments does not wait.
+ *
+ * read is replay-safe. edit, write, and apply_patch are not: after a crash the
+ * model gets an interrupted result and reads the file again.
+ *
+ * Throws TypeError where createFsTools() does, with createDurableFsTools in the
+ * message. A call without an environment fails with an error result.
+ */
+export declare function createDurableFsTools(options: DurableFsToolsOptions): Extension;
+export {};

package/dist/extension.js

@@ -0,0 +1,146 @@
+import { defineExtension, defineTool } from "@earendil-works/pi-durable";
+import { Type } from "typebox";
+import { fsToolDefinitions } from "@better-fs-tools/write/signature";
+const LABEL = "createDurableFsTools";
+/** Above the default view of 2,000 lines and 50 KiB, so the Harness does not cut it again. */
+const DEFAULT_OUTPUT_LIMITS = Object.freeze({ maxBytes: 128 * 1024, maxLines: 4_000 });
+/**
+ * A pi-durable extension with Better FS Tools read, edit, and write, and
+ * optionally apply_patch and bash. Install it after CodingTools: a later
+ * extension's tool with the same name replaces the earlier one. Every tool
+ * option and default is the one of createFsTools(). The lock keys get the
+ * environment id, so the same path in two environments does not wait.
+ *
+ * read is replay-safe. edit, write, and apply_patch are not: after a crash the
+ * model gets an interrupted result and reads the file again.
+ *
+ * Throws TypeError where createFsTools() does, with createDurableFsTools in the
+ * message. A call without an environment fails with an error result.
+ */
+export function createDurableFsTools(options) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError(`${LABEL} options must be an object`);
+    }
+    const { name = "better-fs-tools", outputLimits = DEFAULT_OUTPUT_LIMITS, ...rest } = options;
+    // Built once to check the options and to declare the tools. Each call builds its own.
+    const declared = fsToolDefinitions(rest, LABEL);
+    const perCall = perCallOptions(rest, declared);
+    /** The tool definitions and the call of one tool call, over the call's environment. */
+    const definitionsFor = (api, context) => {
+        const env = api.env;
+        if (env === undefined)
+            throw new Error("Better FS Tools needs an execution environment");
+        const definitions = fsToolDefinitions({ ...perCall, locks: keyedLocks(declared.locks, env.id) }, LABEL);
+        const call = {
+            ...(context.abortSignal === undefined ? {} : { signal: context.abortSignal }),
+            callId: api.callId,
+            host: { api, env, context },
+        };
+        return { definitions, call };
+    };
+    const tools = [
+        defineTool({
+            ...declaration(declared.read),
+            replay: "safe",
+            outputLimits,
+            async execute(args, api, context) {
+                const { definitions, call } = definitionsFor(api, context);
+                const result = await definitions.read.execute(args, call);
+                return { output: toOutput(result.content), isError: result.status === "error" };
+            },
+        }),
+        mutationTool(declared.edit, outputLimits, (d) => d.edit, definitionsFor),
+        mutationTool(declared.write, outputLimits, (d) => d.write, definitionsFor),
+    ];
+    if (declared.applyPatch !== null) {
+        tools.push(mutationTool(declared.applyPatch, outputLimits, (d) => d.applyPatch, definitionsFor));
+    }
+    if (declared.bash !== null) {
+        tools.push(defineTool({
+            ...declaration(declared.bash),
+            outputLimits: { ...outputLimits, retain: "tail" },
+            async execute(args, api, context) {
+                const { definitions, call } = definitionsFor(api, context);
+                if (definitions.bash === null)
+                    throw new Error("bash is off");
+                return bashResult(await definitions.bash.execute(args, call));
+            },
+        }));
+    }
+    return defineExtension({ name, tools });
+}
+/** The options of each call: the given options, with the signatures, digest, and clock of the declared tools. */
+function perCallOptions(options, declared) {
+    const applyPatch = options.applyPatch === true ? {} : options.applyPatch;
+    return {
+        ...options,
+        digest: declared.digest,
+        clock: declared.clock,
+        read: { ...options.read, signature: declared.read.signature },
+        edit: { ...options.edit, signature: declared.edit.signature },
+        write: { ...options.write, signature: declared.write.signature },
+        ...(declared.applyPatch === null || applyPatch === false || applyPatch === undefined
+            ? {}
+            : { applyPatch: { ...applyPatch, signature: declared.applyPatch.signature } }),
+        ...(declared.bash === null || options.bash === false || options.bash === undefined
+            ? {}
+            : { bash: { ...options.bash, signature: declared.bash.signature } }),
+    };
+}
+/** A signature with a grammar sets constrainedSampling, as in the Pi integrations. */
+function declaration(definition) {
+    return {
+        name: definition.name,
+        description: definition.description,
+        parameters: Type.Unsafe(definition.inputSchema),
+        ...(definition.grammar === undefined
+            ? {}
+            : {
+                constrainedSampling: {
+                    type: "grammar",
+                    variants: { openai_lark: definition.grammar.lark },
+                },
+            }),
+    };
+}
+function mutationTool(declared, outputLimits, pick, definitionsFor) {
+    return defineTool({
+        ...declaration(declared),
+        ...(outputLimits === undefined ? {} : { outputLimits }),
+        async execute(args, api, context) {
+            const { definitions, call } = definitionsFor(api, context);
+            const definition = pick(definitions);
+            if (definition === null)
+                throw new Error(`${declared.name} is off`);
+            const result = await definition.execute(args, call);
+            return { output: toOutput(result.content), isError: result.status === "error" };
+        },
+    });
+}
+/** A nonzero exit, a timeout, an abort, and an error are error results, as in the Pi integration. */
+function bashResult(result) {
+    return { output: toOutput(result.content), isError: result.status !== "ok" };
+}
+/** Lock keys with the environment id: one path on two machines is two files. */
+function keyedLocks(locks, envId) {
+    return Object.freeze({
+        id: locks.id,
+        acquire: (keys, options) => locks.acquire(keys.map((key) => `${envId}\0${key}`), options),
+    });
+}
+// Keeps each String.fromCharCode spread under engine argument-count limits.
+const CHUNK = 0x8000;
+function toOutput(parts) {
+    return parts.map((part) => {
+        if (part.type === "text")
+            return { type: "text", text: part.text };
+        if (!part.mediaType.startsWith("image/")) {
+            return { type: "text", text: `[media omitted] ${part.mediaType}` };
+        }
+        let binary = "";
+        for (let offset = 0; offset < part.data.byteLength; offset += CHUNK) {
+            binary += String.fromCharCode(...part.data.subarray(offset, offset + CHUNK));
+        }
+        return { type: "image", data: btoa(binary), mimeType: part.mediaType };
+    });
+}

package/dist/filesystem.d.ts

@@ -0,0 +1,38 @@
+import type { Context } from "@earendil-works/chord/context";
+import type { ExecutionEnv, FileInfo as EnvFileInfo } from "@earendil-works/pi-durable/env";
+import type { FileSystemRootOptions, FileSystemRootSettings, ListOptions, ListOutcome, MutateOptions, MutationOutcome, WritableFileSystem } from "@better-fs-tools/fs";
+import type { EnvSymlinkPolicy } from "./policy.ts";
+/**
+ * The root options, with the environment's paths. `cwd` defaults to `env.cwd`,
+ * and relative roots resolve against it. `symlinks` defaults to
+ * "follow-within-roots": a link is followed, and its real path must stay inside
+ * the real allowed roots. `identity` can only be "none". `id` defaults to
+ * `pi-durable:<env.id>`.
+ */
+export interface ExecutionEnvFileSystemOptions extends FileSystemRootOptions<EnvSymlinkPolicy, "none"> {
+    /**
+     * The Chord context of the tool call. Every environment call runs in it, so
+     * cancelling the call stops the filesystem too. An operation's own signal
+     * also stops it.
+     */
+    readonly context: Context;
+}
+/** A writable filesystem over a pi-durable ExecutionEnv. No compare-and-swap, no stage(). */
+export interface ExecutionEnvFileSystem extends WritableFileSystem, FileSystemRootSettings<EnvSymlinkPolicy, "none"> {
+    list(path: string, options: ListOptions): Promise<ListOutcome>;
+    remove(path: string, options: MutateOptions): Promise<MutationOutcome>;
+}
+/**
+ * Adapts the files of a pi-durable ExecutionEnv (a NodeExecutionEnv, pi-env's
+ * RemoteExecutionEnv over SSH, or a container) to the Better FS Tools
+ * filesystem contract. Paths are POSIX paths in the environment.
+ *
+ * Paths outside the allowed roots or inside a deny root are refused, both as
+ * written and after symbolic links resolve. Reads stream through
+ * openBinaryReader() without following a final symbolic link. Writes use the
+ * environment's writeFile(), which replaces the content in place: a write keeps
+ * the file's mode and hard links, but it is not atomic. Versions are weak: size
+ * and modification time.
+ */
+export declare function executionEnvFileSystem(env: ExecutionEnv, options: ExecutionEnvFileSystemOptions): ExecutionEnvFileSystem;
+export declare function fileInfo(env: ExecutionEnv, target: string, ctx: Context): Promise<EnvFileInfo>;

package/dist/filesystem.js

@@ -0,0 +1,209 @@
+import { posixPaths } from "@better-fs-tools/fs";
+import { contextFor, fromFileError, locate, notAFile, realRoots, refuse, resolveRoots, toFileSystemError, } from "./policy.js";
+import { envVersion, envWrites } from "./write.js";
+/** Bytes that one positional read of an opened file asks for. */
+const CHUNK_BYTES = 64 * 1024;
+/**
+ * Adapts the files of a pi-durable ExecutionEnv (a NodeExecutionEnv, pi-env's
+ * RemoteExecutionEnv over SSH, or a container) to the Better FS Tools
+ * filesystem contract. Paths are POSIX paths in the environment.
+ *
+ * Paths outside the allowed roots or inside a deny root are refused, both as
+ * written and after symbolic links resolve. Reads stream through
+ * openBinaryReader() without following a final symbolic link. Writes use the
+ * environment's writeFile(), which replaces the content in place: a write keeps
+ * the file's mode and hard links, but it is not atomic. Versions are weak: size
+ * and modification time.
+ */
+export function executionEnvFileSystem(env, options) {
+    if (env === null || typeof env !== "object" || typeof env.canonicalPath !== "function") {
+        throw new TypeError("executionEnvFileSystem needs a pi-durable ExecutionEnv");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("executionEnvFileSystem options must be an object");
+    }
+    const { context } = options;
+    if (context === null || typeof context !== "object" || typeof context.value !== "function") {
+        throw new TypeError("executionEnvFileSystem needs the Chord context of the call");
+    }
+    const roots = resolveRoots(options, env.cwd);
+    const id = options.id ?? `pi-durable:${env.id}`;
+    if (typeof id !== "string" || id === "")
+        throw new TypeError("id must be a non-empty string");
+    // The real roots are found once, on the first call that needs them.
+    let real = null;
+    const realOnce = (ctx) => {
+        if (real === null) {
+            real = realRoots(env, roots, ctx);
+            real.catch(() => {
+                real = null;
+            });
+        }
+        return real;
+    };
+    const resolve = async (requested, ctx) => locate(env, roots, await realOnce(ctx), requested, ctx);
+    return Object.freeze({
+        id,
+        capabilities: Object.freeze({ identity: false }),
+        paths: posixPaths,
+        cwd: roots.cwd,
+        allowedRoots: roots.allowedRoots,
+        denyRoots: roots.denyRoots,
+        symlinks: roots.symlinks,
+        identity: "none",
+        ...envWrites(env, (signal) => contextFor(context, signal), resolve),
+        async open(requested, callOptions = {}) {
+            if (callOptions.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            const ctx = contextFor(context, callOptions.signal);
+            try {
+                const located = await resolve(requested, ctx);
+                if (!located.exists)
+                    throw refuse({ reason: "not-found" });
+                const entry = await fileInfo(env, located.target, ctx);
+                if (entry.kind !== "file") {
+                    throw refuse(notAFile(entry.kind === "directory" ? "directory" : "other", located));
+                }
+                // The target is a real path, so a symbolic link here was swapped in after locate().
+                const opened = await env.openBinaryReader(located.target, { noFollow: true }, ctx);
+                if (!opened.ok) {
+                    if (opened.error.code === "invalid") {
+                        throw refuse({ reason: "denied", detail: "the file changed into a symbolic link" });
+                    }
+                    throw refuse(fromFileError(opened.error, "openBinaryReader"));
+                }
+                const reader = opened.value;
+                const info = await reader.info(ctx);
+                if (!info.ok) {
+                    await reader.close(ctx);
+                    throw refuse(fromFileError(info.error, "info"));
+                }
+                return { ok: true, file: envOpenFile(env, ctx, located, info.value, reader) };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+        async list(requested, listOptions) {
+            if (listOptions.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            const limit = listOptions.limit;
+            if (!Number.isSafeInteger(limit) || limit <= 0) {
+                return {
+                    ok: false,
+                    error: { reason: "io", detail: "list limit must be a positive safe integer" },
+                };
+            }
+            const ctx = contextFor(context, listOptions.signal);
+            try {
+                const located = await resolve(requested, ctx);
+                if (!located.exists)
+                    throw refuse({ reason: "not-found" });
+                const opened = await env.openDirReader(located.target, ctx);
+                if (!opened.ok)
+                    throw refuse(fromFileError(opened.error, "openDirReader"));
+                const reader = opened.value;
+                const entries = [];
+                let done = false;
+                try {
+                    // One entry past the limit tells whether the listing was cut.
+                    while (!done && entries.length <= limit) {
+                        const page = await reader.next(limit + 1 - entries.length, ctx);
+                        if (!page.ok)
+                            throw refuse(fromFileError(page.error, "openDirReader"));
+                        done = page.value.done;
+                        for (const entry of page.value.entries) {
+                            entries.push({
+                                name: entry.name,
+                                type: entry.kind === "symlink" ? "other" : entry.kind,
+                            });
+                        }
+                    }
+                }
+                finally {
+                    await reader.close(ctx);
+                }
+                return { ok: true, entries: entries.slice(0, limit), truncated: entries.length > limit };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+    });
+}
+export async function fileInfo(env, target, ctx) {
+    const result = await env.fileInfo(target, ctx);
+    if (!result.ok)
+        throw refuse(fromFileError(result.error, "fileInfo"));
+    return result.value;
+}
+function envOpenFile(env, ctx, located, info, reader) {
+    let consumed = false;
+    let closed = false;
+    return {
+        info: {
+            resolvedPath: located.target,
+            displayPath: located.displayPath,
+            size: info.size,
+            mtimeMs: info.mtimeMs,
+            identity: null,
+            mimeType: null,
+            version: envVersion(info),
+        },
+        bytes() {
+            if (consumed)
+                throw new TypeError("execution environment byte source is single-use");
+            consumed = true;
+            let offset = 0;
+            let ended = closed;
+            return {
+                [Symbol.asyncIterator]() {
+                    return {
+                        async next() {
+                            if (ended || closed)
+                                return { done: true, value: undefined };
+                            const chunk = await reader.read(offset, CHUNK_BYTES, ctx);
+                            if (!chunk.ok) {
+                                ended = true;
+                                throw refuse(fromFileError(chunk.error, "read"));
+                            }
+                            offset += chunk.value.byteLength;
+                            if (chunk.value.byteLength < CHUNK_BYTES)
+                                ended = true;
+                            if (chunk.value.byteLength === 0)
+                                return { done: true, value: undefined };
+                            return { done: false, value: chunk.value };
+                        },
+                        async return() {
+                            ended = true;
+                            return { done: true, value: undefined };
+                        },
+                    };
+                },
+            };
+        },
+        async verify() {
+            try {
+                const current = await env.fileInfo(located.target, ctx);
+                if (!current.ok) {
+                    if (current.error.code === "not_found")
+                        return { ok: true, changed: true };
+                    return { ok: false, error: fromFileError(current.error, "fileInfo") };
+                }
+                const now = current.value;
+                const changed = now.kind !== info.kind || now.size !== info.size || now.mtimeMs !== info.mtimeMs;
+                return { ok: true, changed };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            consumed = true;
+            await reader.close(ctx);
+        },
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from "@earendil-works/chord/context";
+import type { ToolExecutionApi } from "@earendil-works/pi-durable";
+import type { ExecutionEnv } from "@earendil-works/pi-durable/env";
+import type { ToolCallContext } from "@better-fs-tools/read";
+import type { CommandRunner } from "@better-fs-tools/shell";
+import type { ExecutionEnvFileSystem, ExecutionEnvFileSystemOptions } from "./filesystem.ts";
+import type { ExecutionEnvRunnerOptions } from "./runner.ts";
+/** The host of each call. Host functions, such as an authorizer, get it as ctx.call.host. */
+export interface DurableFsHost {
+    readonly api: ToolExecutionApi;
+    readonly env: ExecutionEnv;
+    readonly context: Context;
+}
+/** A factory of the call, as the `fs`, `state`, and `runner` options of a tool take. */
+export type DurableCallFactory<T> = (call: ToolCallContext<DurableFsHost>) => T;
+/**
+ * The options of executionEnvFileSystem() without `context`, which comes from
+ * the call. `allowedRoots` is optional here.
+ */
+export type DurableEnvFileSystemOptions = Omit<ExecutionEnvFileSystemOptions, "context" | "allowedRoots"> & {
+    /** Relative to the environment's cwd. Default ["."]: only the working directory of the call. */
+    readonly allowedRoots?: readonly string[];
+};
+/** The options of executionEnvRunner() without `context`, which comes from the call. */
+export type DurableEnvRunnerOptions = Omit<ExecutionEnvRunnerOptions, "context">;
+/**
+ * A per-call filesystem: executionEnvFileSystem() over the call's environment
+ * and Chord context. Pass it as `fs` to createDurableFsTools().
+ */
+export declare function durableEnvFileSystem(options?: DurableEnvFileSystemOptions): DurableCallFactory<ExecutionEnvFileSystem>;
+/**
+ * A per-call runner: executionEnvRunner() over the call's environment and
+ * Chord context. Pass it as the bash `runner` of createDurableFsTools().
+ */
+export declare function durableEnvRunner(options?: DurableEnvRunnerOptions): DurableCallFactory<CommandRunner>;

package/dist/host.js

@@ -0,0 +1,31 @@
+import { executionEnvFileSystem } from "./filesystem.js";
+import { executionEnvRunner } from "./runner.js";
+/**
+ * A per-call filesystem: executionEnvFileSystem() over the call's environment
+ * and Chord context. Pass it as `fs` to createDurableFsTools().
+ */
+export function durableEnvFileSystem(options = {}) {
+    checkOptions(options, "durableEnvFileSystem");
+    const { allowedRoots = ["."], ...rest } = options;
+    return (call) => executionEnvFileSystem(call.host.env, {
+        ...rest,
+        allowedRoots,
+        context: call.host.context,
+    });
+}
+/**
+ * A per-call runner: executionEnvRunner() over the call's environment and
+ * Chord context. Pass it as the bash `runner` of createDurableFsTools().
+ */
+export function durableEnvRunner(options = {}) {
+    checkOptions(options, "durableEnvRunner");
+    return (call) => executionEnvRunner(call.host.env, { ...options, context: call.host.context });
+}
+function checkOptions(options, label) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError(`${label} options must be an object`);
+    }
+    if (Object.hasOwn(options, "context")) {
+        throw new TypeError(`${label} options cannot set context: it comes from the call`);
+    }
+}