@better-fs-tools/pi 0.0.0-tegami-trusted-publish-setup → 0.2.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,142 @@
-# 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
+
+Better FS Tools for the [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). It replaces Pi's built-in `read`, `edit`, and `write` tools, and can add `apply_patch`. Every call is confined to the working directory of that call. A read store, so that `edit` and `write` need a read first, is opt-in.
+
+## Install
+
+```sh
+npm install @better-fs-tools/pi @better-fs-tools/read @better-fs-tools/write @earendil-works/pi-coding-agent typebox
+```
+
+`@earendil-works/pi-coding-agent` (`^0.84.2`) and `typebox` (`^1.3.16`) are required peers. The package needs Node 24 or later.
+
+The package has a `pi.extensions` entry. When Pi loads the package, the entry registers `read`, `edit`, and `write` from `createPiFsTools()`, as Pi's own tools are. `read` returns images, as Pi's own `read` does. There is no read store, so `edit` and `write` do not check for a read first. Writes stay inside `ctx.cwd`. The entry writes no settings or session file.
+
+## Example
+
+To choose your own options, register the tools from your own extension:
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createPiFsTools } from "@better-fs-tools/pi";
+import { denyPaths, memoryStore, unicodeRepair } from "@better-fs-tools/read";
+import { hashlineFormat } from "@better-fs-tools/read/formats";
+import { protectPaths } from "@better-fs-tools/write";
+
+export default function fsToolsExtension(pi: ExtensionAPI): void {
+  // Four tools with one read store, so edit and write need a read first. The
+  // store and apply_patch are opt-in.
+  const tools = createPiFsTools({
+    state: memoryStore(),
+    read: {
+      resolve: unicodeRepair({ note: false }),
+      authorize: denyPaths(["**/.env", "**/.env.*"]),
+      formatter: hashlineFormat(),
+    },
+    edit: { authorize: protectPaths() },
+    write: { authorize: protectPaths() },
+    applyPatch: { authorize: protectPaths() },
+  });
+  pi.registerTool(tools.read);
+  pi.registerTool(tools.edit);
+  pi.registerTool(tools.write);
+  pi.registerTool(tools.applyPatch);
+}
+```
+
+To register only the read tool:
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createPiReadTool } from "@better-fs-tools/pi";
+import { denyPaths, unicodeRepair } from "@better-fs-tools/read";
+import { hashlineFormat } from "@better-fs-tools/read/formats";
+import { defaultReadSignature } from "@better-fs-tools/read/signature";
+
+export default function readExtension(pi: ExtensionAPI): void {
+  pi.registerTool(
+    createPiReadTool({
+      signature: defaultReadSignature({ name: "read", names: { path: "file_path" } }),
+      resolve: unicodeRepair({ note: false }),
+      authorize: denyPaths(["**/.env", "**/.env.*"]),
+      formatter: hashlineFormat(),
+    }),
+  );
+}
+```
+
+## What the read tool does
+
+- `createPiReadTool(options?)` takes every `createReadTool()` option except `fs`. It also takes `signature`, `promptSnippet`, `promptGuidelines`, `denyRoots`, and `symlinks`.
+- `fs`, `cwd`, and `allowedRoots` throw `TypeError`. Each call reads through `nodeFileSystem` with Pi's `ctx.cwd` as the only allowed root. When the working directory changes between calls, the root changes too. The tool keeps the filesystems for the last 8 working directories.
+- Pi's `ExtensionContext` is the host type. Host functions get it as `ctx.call.host`, for example `ctx.call.host.ui.confirm(...)` in `askUser`, or `ctx.call.host.sessionManager.getSessionId()` in a `state` factory.
+- The default signature is `defaultReadSignature({ name: "read" })`. Its schema has integer `offset` and `limit`, so a model that sends `2.5` gets Pi's validation error. `digest` defaults to `nodeDigest()`.
+- `converters` defaults to `[imageConverter()]`, as Pi's own `read` returns images. This holds for `createPiReadTool()`, `createPiFsTools()`, and the extension entry. A list you pass replaces the default, so `converters: []` turns images off, and a list without `imageConverter()` refuses images. In `createPiFsTools()` the option goes under `read`, for example `read: { converters: [] }`.
+- Image parts become Pi `image` parts. Other media becomes a text part that says what was left out.
+- `details.truncation` follows Pi's own read tool for line and byte stops. Its `content` comes from the formatter in `"view"` mode. For other results, or a formatter that returns parts, `details` is `{}`. `toPiReadDetails()` builds the details for your own tool.
+
+## What the write tools do
+
+- `createPiFsTools(options?)` wraps `createFsTools()` from `@better-fs-tools/write`. It builds `read`, `edit`, and `write` with one `nodeDigest()`, one lock manager, one clock, and one cache of filesystems over `ctx.cwd`. `applyPatch: true`, or an options object, adds `apply_patch`. `state` defaults to `null`, so read-before-write is off; `state: memoryStore()` turns it on. `digest` (default `nodeDigest()`), `locks`, `clock`, and the root options (`denyRoots`, `symlinks`, `hardLinks`, `newFileMode`, `newDirectoryMode`) are set once for all the tools. Each tool's other options go under `read`, `edit`, `write`, and `applyPatch`. The result also has `applyPatch` (`null` when off), `state`, `digest`, `locks`, `clock`, and `invalidate(path, call?)`, which returns an `InvalidateOutcome`. Pass the call, so the path resolves under its `ctx.cwd`: in a bash `afterRun` hook it is `ctx.call`. Without it the outcome is `{ ok: false }` with reason `unsupported`. An unknown top-level key, or `state`, `digest`, `locks`, `clock`, or a root option inside a tool's options, throws `TypeError`.
+- `createPiEditTool()`, `createPiWriteTool()`, and `createPiApplyPatchTool()` build one tool each. They default to `state: null`, so read-before-write is off. Pass the same `state` as your read tool, or use `createPiFsTools()`.
+- `fs`, `cwd`, and `allowedRoots` throw `TypeError`, as for the read tool. Writes go through `nodeFileSystem` with `ctx.cwd` as the only allowed root, and `hardLinks: "in-place"` by default: a file with more than one hard link is written through the link, not atomically. `hardLinks: "refuse"` fails that write with `DENIED`. `newFileMode` and `newDirectoryMode` set the modes of new files and directories exactly. Without them, a new file is `0o666` and a new directory `0o777`, less the process umask.
+- The default signatures follow Pi's own tools: `edit` takes `path` and `edits: [{ oldText, newText }]` (`multiEditSignature({ name: "edit" })`), and `write` takes `path` and `content`. Their prompt snippets and guidelines are Pi's own, so the system prompt stays the same. `apply_patch` uses `freeformPatchSignature()`: models with grammar-tool support get the Codex patch grammar, and other models get the JSON schema.
+- `edit` and `apply_patch` return `details` in the shape of Pi's `EditToolDetails` (`diff`, `patch`, `firstChangedLine`), so Pi's edit renderer draws the diff. `toPiMutationDetails()` builds them for your own tool. `write` returns no details, as Pi's own `write` does.
+- A tool error becomes Pi content text. The tool does not throw for a tool error.
+- Pi's `edit` guideline says the old text must match exactly. The tool also accepts close matches, and the result says when it used one.
+
+## Bash tool
+
+`createPiBashTool()` is a `bash` tool from [`@better-fs-tools/shell`](https://www.npmjs.com/package/@better-fs-tools/shell) with Pi's own shape: `{ command, timeout }` with the timeout in seconds, and Pi's prompt snippet. It runs in `ctx.cwd` on every call, also with a `runner` you pass: the runner gets `ctx.cwd` as the request's `cwd`, not its own. A relative `ctx.cwd` throws `TypeError`. The extension entry does not register it, so Pi's own `bash` stays unless you register this one:
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createPiBashTool } from "@better-fs-tools/pi";
+
+// Replaces Pi's own bash: same name, { command, timeout } in seconds, run in ctx.cwd.
+export default function bashExtension(pi: ExtensionAPI): void {
+  pi.registerTool(createPiBashTool());
+}
+```
+
+The options take every `createBashTool()` dependency except `cwd`, plus `runner`, `signature`, `promptSnippet`, and `promptGuidelines`. `runner` and `env` are optional here. The default description names the timeouts and output limits from `limits`, and the id of a `runner` object when you pass one.
+
+Pi's own `bash` also sets `PI_*` session variables. This tool does not. Add them with the `env` option when you need them. `env` defaults to `shellEnv(() => process.env)`.
+
+With the file tools, a bash `afterRun` hook can make the next edit of a file need a read:
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createPiBashTool, createPiFsTools } from "@better-fs-tools/pi";
+import { memoryStore } from "@better-fs-tools/read";
+
+// The file tools with a read store, and Pi-shaped bash. After each command,
+// the next edit of package.json needs a read, since the command may have
+// changed it.
+export default function fsAndBashExtension(pi: ExtensionAPI): void {
+  const tools = createPiFsTools({ state: memoryStore() });
+  const bash = createPiBashTool({
+    afterRun: [
+      {
+        id: "invalidate-package-json",
+        afterRun: async (_outcome, ctx) => {
+          // ctx.call carries Pi's ctx, so the path resolves under its cwd.
+          await tools.invalidate("package.json", ctx.call);
+          return {};
+        },
+      },
+    ],
+  });
+  pi.registerTool(tools.read);
+  pi.registerTool(tools.edit);
+  pi.registerTool(tools.write);
+  pi.registerTool(bash);
+}
+```
+
+## Links
+
+- `docs/hosts.md` in [`@better-fs-tools/write`](https://www.npmjs.com/package/@better-fs-tools/write): the defaults of every host and bundle, and what each backend can do
+- [`@better-fs-tools/read`](https://www.npmjs.com/package/@better-fs-tools/read): every read option, the signature builders, and the format presets. Its README has a full Pi host example.
+- [`@better-fs-tools/write`](https://www.npmjs.com/package/@better-fs-tools/write): every write option, the guards, and the authorizers
+- [`@better-fs-tools/node`](https://www.npmjs.com/package/@better-fs-tools/node): the filesystem that each call uses

package/dist/bash-tool.d.ts

@@ -0,0 +1,48 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import type { JsonObject } from "@better-fs-tools/read";
+import type { ShellToolDeps } from "@better-fs-tools/shell";
+import type { BashSignature } from "@better-fs-tools/shell/signature";
+import type { PiContentPart } from "./parts.ts";
+/** Options for createPiBashTool. Commands always run in ctx.cwd. */
+export interface CreatePiBashToolOptions extends Omit<ShellToolDeps<ExtensionContext>, "runner" | "cwd" | "env"> {
+    /** Default a nodeCommandRunner at ctx.cwd. */
+    readonly runner?: ShellToolDeps<ExtensionContext>["runner"];
+    /** Default process.env with defaultShellEnv over it. */
+    readonly env?: ShellToolDeps<ExtensionContext>["env"];
+    /**
+     * Default Pi's own bash input, { command, timeout } with the timeout in
+     * seconds, so Pi's bash renderer and prompt fit. Its description names the
+     * configured timeouts, output limits, and runner id.
+     */
+    readonly signature?: BashSignature;
+    readonly promptSnippet?: string;
+    readonly promptGuidelines?: readonly string[];
+}
+/** Pi's BashToolDetails shape, so Pi's bash renderer can show the saved output. */
+export interface PiBashDetails {
+    fullOutputPath?: string;
+}
+export interface PiBashToolResult {
+    content: PiContentPart[];
+    details: PiBashDetails | undefined;
+}
+/** Assignable to ToolDefinition<TSchema, PiBashDetails | undefined> from Pi 0.84.2. */
+export interface PiBashTool {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptSnippet: string;
+    readonly promptGuidelines: string[];
+    /** The JSON Schema of the tool input. */
+    readonly parameters: TSchema;
+    execute(toolCallId: string, input: JsonObject, signal: AbortSignal | undefined, onUpdate: unknown, ctx: ExtensionContext): Promise<PiBashToolResult>;
+}
+/**
+ * Creates a Pi bash tool that runs commands in ctx.cwd, also with your own
+ * runner. Throws TypeError when options set fs, cwd, or allowedRoots, and
+ * execute throws TypeError when ctx.cwd is not an absolute path. The Pi
+ * extension does not register this tool, so Pi's own bash stays in place
+ * unless you register it.
+ */
+export declare function createPiBashTool(options?: CreatePiBashToolOptions): PiBashTool;

package/dist/bash-tool.js

@@ -0,0 +1,76 @@
+import { isAbsolute } from "node:path";
+import { Type } from "typebox";
+import { nodeCommandRunner } from "@better-fs-tools/node";
+import { createBashTool, shellEnv } from "@better-fs-tools/shell";
+import { bashSignatureMessages, defaultBashSignature } from "@better-fs-tools/shell/signature";
+import { toPiPart } from "./parts.js";
+import { checkPiContext, checkPiOptions } from "./roots.js";
+const PI_BUILTIN_BASH_PROMPT_SNIPPET = "Execute bash commands (ls, grep, find, etc.)";
+const MAX_CACHED_RUNNERS = 8;
+/**
+ * Creates a Pi bash tool that runs commands in ctx.cwd, also with your own
+ * runner. Throws TypeError when options set fs, cwd, or allowedRoots, and
+ * execute throws TypeError when ctx.cwd is not an absolute path. The Pi
+ * extension does not register this tool, so Pi's own bash stays in place
+ * unless you register it.
+ */
+export function createPiBashTool(options = {}) {
+    checkPiOptions(options, "bash");
+    const { signature: given, promptSnippet = PI_BUILTIN_BASH_PROMPT_SNIPPET, promptGuidelines = [], runner = recentRunnerPerCwd(), ...deps } = options;
+    const runnerId = typeof runner === "function" ? undefined : runner.id;
+    const signature = given ??
+        defaultBashSignature({
+            timeoutUnit: "s",
+            cwd: false,
+            ...(runnerId === undefined ? {} : { runner: runnerId }),
+            ...(deps.limits === undefined ? {} : { limits: deps.limits }),
+        });
+    const bash = createBashTool({
+        ...deps,
+        runner,
+        cwd: (call) => call.host.cwd,
+        env: deps.env ?? shellEnv(() => process.env),
+        messages: { ...bashSignatureMessages(signature), ...deps.messages },
+    });
+    return Object.freeze({
+        name: signature.name,
+        label: signature.name,
+        description: signature.description,
+        promptSnippet,
+        promptGuidelines: [...promptGuidelines],
+        parameters: Type.Unsafe(signature.schema),
+        async execute(toolCallId, input, signal, _onUpdate, ctx) {
+            checkPiContext(ctx, "bash");
+            if (!isAbsolute(ctx.cwd))
+                throw new TypeError("Pi bash execution requires an absolute ctx.cwd");
+            const call = {
+                ...(signal === undefined ? {} : { signal }),
+                callId: toolCallId,
+                host: ctx,
+            };
+            const result = await bash(signature.toInput(input), call);
+            const spill = result.output?.spill ?? null;
+            return {
+                content: result.content.map((part) => toPiPart(part, "bash")),
+                details: spill === null ? undefined : { fullOutputPath: spill },
+            };
+        },
+    });
+}
+function recentRunnerPerCwd() {
+    const cache = new Map();
+    return (call) => {
+        const cwd = call.host.cwd;
+        const cached = cache.get(cwd);
+        if (cached !== undefined) {
+            cache.delete(cwd);
+            cache.set(cwd, cached);
+            return cached;
+        }
+        const made = nodeCommandRunner({ cwd });
+        cache.set(cwd, made);
+        if (cache.size > MAX_CACHED_RUNNERS)
+            cache.delete(cache.keys().next().value);
+        return made;
+    };
+}

package/dist/details.d.ts

@@ -0,0 +1,26 @@
+import type { ReadResult } from "@better-fs-tools/read";
+/** Pi's published TruncationResult. Fields and meanings are Pi's. */
+export interface PiTruncationResult {
+    content: string;
+    truncated: boolean;
+    truncatedBy: "lines" | "bytes" | null;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    lastLinePartial: boolean;
+    firstLineExceedsLimit: boolean;
+    maxLines: number;
+    maxBytes: number;
+}
+/** Empty unless the read stopped at exactly a line or byte limit. */
+export interface PiReadDetails {
+    truncation?: PiTruncationResult;
+}
+/**
+ * Converts a read result to Pi's read details, from which Pi prints "showing
+ * N of M lines". `view` is the formatted text in "view" mode, or null. Returns
+ * {} unless the read stopped exactly at a line or byte limit with an exact
+ * total, because an approximate count is worse than none.
+ */
+export declare function toPiReadDetails(result: ReadResult, view: string | null, maxViewBytes: number): PiReadDetails;

package/dist/details.js

@@ -0,0 +1,30 @@
+/**
+ * Converts a read result to Pi's read details, from which Pi prints "showing
+ * N of M lines". `view` is the formatted text in "view" mode, or null. Returns
+ * {} unless the read stopped exactly at a line or byte limit with an exact
+ * total, because an approximate count is worse than none.
+ */
+export function toPiReadDetails(result, view, maxViewBytes) {
+    if (view === null)
+        return {};
+    if (result.status !== "ok" || !result.totals.exact || result.totals.lines === null)
+        return {};
+    const primary = result.truncation.primary;
+    if (!result.truncation.truncated || (primary !== "lines" && primary !== "bytes"))
+        return {};
+    return {
+        truncation: {
+            content: view,
+            truncated: true,
+            truncatedBy: primary,
+            totalLines: result.totals.lines,
+            totalBytes: result.totals.bytes,
+            outputLines: result.view.lines.length,
+            outputBytes: result.view.bytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: primary === "bytes" && result.view.lines.length === 0,
+            maxLines: result.request.limit,
+            maxBytes: maxViewBytes,
+        },
+    };
+}

package/dist/extension.d.ts

@@ -0,0 +1,8 @@
+import type { PiMutationTool } from "./mutation-tools.ts";
+import type { PiReadTool } from "./tool.ts";
+/** The part of Pi's ExtensionAPI this extension uses. Pi's full API satisfies it. */
+export interface PiExtensionApi {
+    registerTool(tool: PiReadTool): void;
+    registerTool(tool: PiMutationTool): void;
+}
+export default function fsToolsExtension(pi: PiExtensionApi): void;

package/dist/extension.js

@@ -0,0 +1,14 @@
+/**
+ * Pi package extension entry. Installing the package into a Pi project
+ * registers read, edit, and write, as Pi's own tools are, and nothing else.
+ * There is no read store, so edit and write do not check for a read first.
+ * read returns images, as Pi's own read does.
+ * Nothing is written outside the process: no settings file, no session file.
+ */
+import { createPiFsTools } from "./fs-tools.js";
+export default function fsToolsExtension(pi) {
+    const tools = createPiFsTools();
+    pi.registerTool(tools.read);
+    pi.registerTool(tools.edit);
+    pi.registerTool(tools.write);
+}

package/dist/fs-tools.d.ts

@@ -0,0 +1,59 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Clock, Digest, ReadStateStore, ToolCallContext } from "@better-fs-tools/read";
+import type { FsToolsSharedKey, InvalidateOutcome, LockManager } from "@better-fs-tools/write";
+import type { CreatePiApplyPatchToolOptions, CreatePiEditToolOptions, CreatePiWriteToolOptions, PiMutationTool } from "./mutation-tools.ts";
+import type { PiRootOptions } from "./roots.ts";
+import type { CreatePiReadToolOptions, PiReadTool } from "./tool.ts";
+type BundleSharedKey = FsToolsSharedKey | keyof PiRootOptions;
+export interface CreatePiFsToolsOptions extends PiRootOptions {
+    /** Default null: no read-before-write. A store, for example memoryStore(), turns it on. */
+    readonly state?: ReadStateStore | null;
+    /** Default nodeDigest(). */
+    readonly digest?: Digest;
+    /** Default memoryLocks(). */
+    readonly locks?: LockManager;
+    /** Default () => new Date(). */
+    readonly clock?: Clock;
+    readonly read?: Omit<CreatePiReadToolOptions, BundleSharedKey>;
+    readonly edit?: Omit<CreatePiEditToolOptions, BundleSharedKey>;
+    readonly write?: Omit<CreatePiWriteToolOptions, BundleSharedKey>;
+    /** Off by default. `true` or an options object adds an apply_patch tool. */
+    readonly applyPatch?: boolean | Omit<CreatePiApplyPatchToolOptions, BundleSharedKey>;
+}
+export interface PiFsTools {
+    readonly read: PiReadTool;
+    readonly edit: PiMutationTool;
+    readonly write: PiMutationTool;
+    /** null unless options.applyPatch is true or an object. */
+    readonly applyPatch: PiMutationTool | null;
+    readonly state: ReadStateStore | null;
+    /** options.digest, or nodeDigest(). */
+    readonly digest: Digest;
+    readonly locks: LockManager;
+    readonly clock: Clock;
+    /**
+     * Forgets the read record for a path under the call's ctx.cwd, so the next
+     * edit needs a read. Pass the call; in a bash afterRun hook it is ctx.call.
+     * Without it the outcome is { ok: false } with reason "unsupported". Never
+     * throws. With state null it reports recorded: false.
+     */
+    invalidate(path: string, call?: ToolCallContext<ExtensionContext>): Promise<InvalidateOutcome>;
+}
+/** The createPiFsTools result when `applyPatch` is true or an object: it is never null. */
+export interface PiFsToolsWithApplyPatch extends PiFsTools {
+    readonly applyPatch: PiMutationTool;
+}
+/**
+ * Creates Pi read, edit, and write tools rooted at each call's ctx.cwd, and
+ * an apply_patch tool when `applyPatch` is true or an object. They share one
+ * digest, lock manager, and clock, and the read store when `state` is given.
+ * Throws TypeError on fs, cwd, or allowedRoots anywhere in the options, on an
+ * unknown key, and on a shared option (state, digest, locks, clock, or a root
+ * option) inside one tool's options. There is no bash: register
+ * createPiBashTool() and call invalidate from its afterRun hook.
+ */
+export declare function createPiFsTools(options: CreatePiFsToolsOptions & {
+    readonly applyPatch: true | Omit<CreatePiApplyPatchToolOptions, BundleSharedKey>;
+}): PiFsToolsWithApplyPatch;
+export declare function createPiFsTools(options?: CreatePiFsToolsOptions): PiFsTools;
+export {};

package/dist/fs-tools.js

@@ -0,0 +1,93 @@
+import { nodeDigest } from "@better-fs-tools/node";
+import { createFsTools } from "@better-fs-tools/write";
+import { adaptPiMutationTool, piApplyPatchParts, piEditParts, piWriteParts, } from "./mutation-tools.js";
+import { checkPiOptions, PI_ROOT_KEYS, piFileSystems } from "./roots.js";
+import { adaptPiReadTool, piReadDeps, piReadParts } from "./tool.js";
+const KNOWN_OPTIONS = new Set([
+    "state",
+    "digest",
+    "locks",
+    "clock",
+    ...PI_ROOT_KEYS,
+    "read",
+    "edit",
+    "write",
+    "applyPatch",
+]);
+const BUNDLE_SHARED_KEYS = ["state", "digest", "locks", "clock", ...PI_ROOT_KEYS];
+export function createPiFsTools(options = {}) {
+    checkPiOptions(options, "fs");
+    for (const key of Object.keys(options)) {
+        if (!KNOWN_OPTIONS.has(key))
+            throw new TypeError(`Unknown createPiFsTools option: ${key}`);
+    }
+    const state = options.state;
+    if (state !== undefined && state !== null && !isReadStateStore(state)) {
+        throw new TypeError(`createPiFsTools state must be a read state store or null: a bundle takes one store, not a per-call factory`);
+    }
+    const given = {
+        read: options.read ?? {},
+        edit: options.edit ?? {},
+        write: options.write ?? {},
+        applyPatch: options.applyPatch === true
+            ? {}
+            : options.applyPatch === false || options.applyPatch === undefined
+                ? null
+                : options.applyPatch,
+    };
+    for (const [key, value] of Object.entries(given)) {
+        if (value === null)
+            continue;
+        checkPiOptions(value, key);
+        for (const shared of BUNDLE_SHARED_KEYS) {
+            if (Object.hasOwn(value, shared)) {
+                throw new TypeError(`createPiFsTools ${key} options cannot set ${shared}: set it once at the top level`);
+            }
+        }
+    }
+    const { denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode } = options;
+    const fs = piFileSystems({ denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode });
+    const { signature: _readSignature, promptSnippet: _readSnippet, promptGuidelines: _readLines, ...read } = given.read;
+    const { signature: _editSignature, promptSnippet: _editSnippet, promptGuidelines: _editLines, ...edit } = given.edit;
+    const { signature: _writeSignature, promptSnippet: _writeSnippet, promptGuidelines: _writeLines, ...write } = given.write;
+    const parts = {
+        read: piReadParts(given.read),
+        edit: piEditParts(given.edit),
+        write: piWriteParts(given.write),
+    };
+    let patch = null;
+    if (given.applyPatch !== null) {
+        const { signature: _patchSignature, promptSnippet: _patchSnippet, promptGuidelines: _patchLines, ...deps } = given.applyPatch;
+        patch = { deps, parts: piApplyPatchParts(given.applyPatch) };
+    }
+    const core = createFsTools({
+        fs,
+        digest: options.digest ?? nodeDigest(),
+        ...(options.state === undefined ? {} : { state: options.state }),
+        ...(options.locks === undefined ? {} : { locks: options.locks }),
+        ...(options.clock === undefined ? {} : { clock: options.clock }),
+        read: { ...read, ...piReadDeps(parts.read) },
+        edit: { ...edit, messages: parts.edit.messages },
+        write: { ...write, messages: parts.write.messages },
+        ...(patch === null ? {} : { applyPatch: { ...patch.deps, messages: patch.parts.messages } }),
+    });
+    return Object.freeze({
+        read: adaptPiReadTool(parts.read, core.read, core.digest),
+        edit: adaptPiMutationTool(parts.edit, core.edit),
+        write: adaptPiMutationTool(parts.write, core.write),
+        applyPatch: patch === null || core.applyPatch === null
+            ? null
+            : adaptPiMutationTool(patch.parts, core.applyPatch),
+        state: core.state,
+        digest: core.digest,
+        locks: core.locks,
+        clock: core.clock,
+        invalidate: (path, call) => core.invalidate(path, call),
+    });
+}
+function isReadStateStore(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const store = value;
+    return ["get", "put", "delete"].every((key) => typeof store[key] === "function");
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { createPiBashTool } from "./bash-tool.ts";
+export type { CreatePiBashToolOptions, PiBashDetails, PiBashTool, PiBashToolResult, } from "./bash-tool.ts";
+export { toPiReadDetails } from "./details.ts";
+export type { PiReadDetails, PiTruncationResult } from "./details.ts";
+export { createPiFsTools } from "./fs-tools.ts";
+export type { CreatePiFsToolsOptions, PiFsTools, PiFsToolsWithApplyPatch } from "./fs-tools.ts";
+export { toPiMutationDetails } from "./mutation-details.ts";
+export type { PiMutationDetails } from "./mutation-details.ts";
+export { createPiApplyPatchTool, createPiEditTool, createPiWriteTool } from "./mutation-tools.ts";
+export type { CreatePiApplyPatchToolOptions, CreatePiEditToolOptions, CreatePiWriteToolOptions, PiMutationTool, PiMutationToolResult, } from "./mutation-tools.ts";
+export { createPiReadTool } from "./tool.ts";
+export type { CreatePiReadToolOptions, PiContentPart, PiReadTool, PiReadToolResult, } from "./tool.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createPiBashTool } from "./bash-tool.js";
+export { toPiReadDetails } from "./details.js";
+export { createPiFsTools } from "./fs-tools.js";
+export { toPiMutationDetails } from "./mutation-details.js";
+export { createPiApplyPatchTool, createPiEditTool, createPiWriteTool } from "./mutation-tools.js";
+export { createPiReadTool } from "./tool.js";

package/dist/mutation-details.d.ts

@@ -0,0 +1,15 @@
+import type { MutationResult } from "@better-fs-tools/write";
+/** Pi's EditToolDetails shape, so Pi's built-in edit renderer draws the diff. */
+export interface PiMutationDetails {
+    /** Pi's display diff, with lines like "+NN text", "-NN text", " NN text", and "...". */
+    diff: string;
+    /** Unified diff of every change. */
+    patch: string;
+    firstChangedLine?: number;
+}
+/**
+ * Converts an edit or apply_patch result to Pi's edit details, so Pi draws the
+ * diff. Returns undefined for an error or a result with no changes. With more
+ * than one file, each file's lines follow a line with its path.
+ */
+export declare function toPiMutationDetails(result: MutationResult): PiMutationDetails | undefined;

package/dist/mutation-details.js

@@ -0,0 +1,76 @@
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/u;
+/**
+ * Converts an edit or apply_patch result to Pi's edit details, so Pi draws the
+ * diff. Returns undefined for an error or a result with no changes. With more
+ * than one file, each file's lines follow a line with its path.
+ */
+export function toPiMutationDetails(result) {
+    if (result.status !== "ok" || result.changes.length === 0)
+        return undefined;
+    const blocks = [];
+    let firstChangedLine;
+    for (const change of result.changes) {
+        const display = toPiDisplayDiff(change.diff);
+        firstChangedLine ??= display.firstChangedLine;
+        const header = result.changes.length > 1 ? `${label(change)}\n` : "";
+        blocks.push(`${header}${display.text}`);
+    }
+    return {
+        diff: blocks.join("\n"),
+        patch: result.changes.map((change) => change.diff).join(""),
+        ...(firstChangedLine === undefined ? {} : { firstChangedLine }),
+    };
+}
+function label(change) {
+    return change.movedFrom === null ? change.path : `${change.movedFrom} → ${change.path}`;
+}
+// Context and removed lines carry the old line number, added lines the new one, as Pi's generateDiffString does.
+function toPiDisplayDiff(unified) {
+    const rows = [];
+    let oldLine = 0;
+    let newLine = 0;
+    let inHunk = false;
+    let firstChangedLine;
+    for (const raw of unified.split("\n")) {
+        const hunk = HUNK_HEADER.exec(raw);
+        if (hunk !== null) {
+            if (inHunk)
+                rows.push({ kind: "...", line: 0, text: "" });
+            inHunk = true;
+            oldLine = firstLineOfRange(hunk[1], hunk[2]);
+            newLine = firstLineOfRange(hunk[3], hunk[4]);
+            continue;
+        }
+        if (!inHunk || raw.startsWith("\\"))
+            continue;
+        const kind = raw[0];
+        const text = raw.slice(1);
+        if (kind === "+") {
+            firstChangedLine ??= newLine;
+            rows.push({ kind, line: newLine, text });
+            newLine += 1;
+        }
+        else if (kind === "-") {
+            firstChangedLine ??= newLine;
+            rows.push({ kind, line: oldLine, text });
+            oldLine += 1;
+        }
+        else if (kind === " ") {
+            rows.push({ kind, line: oldLine, text });
+            oldLine += 1;
+            newLine += 1;
+        }
+    }
+    const width = String(Math.max(1, ...rows.map((row) => row.line))).length;
+    const text = rows
+        .map((row) => row.kind === "..."
+        ? ` ${"".padStart(width, " ")} ...`
+        : `${row.kind}${String(row.line).padStart(width, " ")} ${row.text}`)
+        .join("\n");
+    return { text, firstChangedLine };
+}
+// In a unified diff, a range with a zero count names the line before it.
+function firstLineOfRange(line, count) {
+    const value = Number(line);
+    return count === "0" ? value + 1 : value;
+}

package/dist/mutation-tools.d.ts

@@ -0,0 +1,72 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import type { JsonObject, StateNeedsDigestOrDefault, ToolCallContext } from "@better-fs-tools/read";
+import type { ApplyPatchToolDeps, EditToolDeps, MutationResult, WriteMessageCatalog, WriteToolDeps } from "@better-fs-tools/write";
+import type { EditSignature, MutationSignature, PatchSignature, WriteSignature } from "@better-fs-tools/write/signature";
+import type { PiMutationDetails } from "./mutation-details.ts";
+import type { PiContentPart } from "./parts.ts";
+import type { PiRootOptions } from "./roots.ts";
+/** Pi prompt options of the edit, write, and apply_patch tools. */
+export interface PiMutationOptions<TSignature> {
+    readonly signature?: TSignature;
+    readonly promptSnippet?: string;
+    readonly promptGuidelines?: readonly string[];
+}
+/**
+ * Options for createPiEditTool. The default signature is Pi's own edit input,
+ * multiEditSignature({ matchers }), so Pi's edit renderer and prompt fit.
+ * digest defaults to nodeDigest(); a state needs a digest that is not null.
+ */
+export type CreatePiEditToolOptions = Omit<EditToolDeps<ExtensionContext>, "fs"> & StateNeedsDigestOrDefault & PiRootOptions & PiMutationOptions<EditSignature>;
+/** As CreatePiEditToolOptions, for write. The default signature is defaultWriteSignature(). */
+export type CreatePiWriteToolOptions = Omit<WriteToolDeps<ExtensionContext>, "fs"> & StateNeedsDigestOrDefault & PiRootOptions & PiMutationOptions<WriteSignature>;
+/** As CreatePiEditToolOptions, for apply_patch. The default signature is freeformPatchSignature(). */
+export type CreatePiApplyPatchToolOptions = Omit<ApplyPatchToolDeps<ExtensionContext>, "fs"> & StateNeedsDigestOrDefault & PiRootOptions & PiMutationOptions<PatchSignature>;
+export interface PiMutationToolResult {
+    content: PiContentPart[];
+    details: PiMutationDetails | undefined;
+}
+/** Assignable to ToolDefinition<TSchema, PiMutationDetails | undefined> from Pi 0.84.2. */
+export interface PiMutationTool {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptSnippet: string;
+    readonly promptGuidelines: string[];
+    /** The JSON Schema of the tool input. */
+    readonly parameters: TSchema;
+    /** Set when the signature has a grammar. */
+    readonly constrainedSampling?: {
+        type: "grammar";
+        variants: {
+            openai_lark: string;
+        };
+    };
+    execute(toolCallId: string, input: JsonObject, signal: AbortSignal | undefined, onUpdate: unknown, ctx: ExtensionContext): Promise<PiMutationToolResult>;
+}
+type Core = (input: never, ctx: ToolCallContext<ExtensionContext>) => Promise<MutationResult>;
+export interface PiMutationParts {
+    readonly tool: "edit" | "write" | "apply_patch";
+    readonly signature: MutationSignature<unknown>;
+    readonly promptSnippet: string;
+    readonly promptGuidelines: readonly string[];
+    readonly messages: Partial<WriteMessageCatalog>;
+}
+type PartsInput<TSignature> = PiMutationOptions<TSignature> & {
+    readonly messages?: Partial<WriteMessageCatalog>;
+};
+export declare function piEditParts(options: PartsInput<EditSignature> & Pick<Partial<EditToolDeps>, "matchers">): PiMutationParts;
+export declare function piWriteParts(options: PartsInput<WriteSignature>): PiMutationParts;
+export declare function piApplyPatchParts(options: PartsInput<PatchSignature>): PiMutationParts;
+/**
+ * Creates a Pi edit tool rooted at each call's ctx.cwd. Throws TypeError when
+ * options set fs, cwd, or allowedRoots. Read-before-write is off unless you
+ * pass a `state`; use createPiFsTools({ state }) for a store shared with read.
+ */
+export declare function createPiEditTool(options?: CreatePiEditToolOptions): PiMutationTool;
+/** Creates a Pi write tool, as createPiEditTool. `details` is always undefined, as for Pi's own write. */
+export declare function createPiWriteTool(options?: CreatePiWriteToolOptions): PiMutationTool;
+/** Creates a Pi apply_patch tool, as createPiEditTool. A grammar signature sets constrainedSampling. */
+export declare function createPiApplyPatchTool(options?: CreatePiApplyPatchToolOptions): PiMutationTool;
+export declare function adaptPiMutationTool(made: PiMutationParts, tool: Core): PiMutationTool;
+export {};

package/dist/mutation-tools.js

@@ -0,0 +1,117 @@
+import { Type } from "typebox";
+import { nodeDigest } from "@better-fs-tools/node";
+import { createApplyPatchTool, createEditTool, createWriteTool } from "@better-fs-tools/write";
+import { defaultWriteSignature, freeformPatchSignature, multiEditSignature, writeSignatureMessages, } from "@better-fs-tools/write/signature";
+import { toPiMutationDetails } from "./mutation-details.js";
+import { toPiPart } from "./parts.js";
+import { checkPiContext, checkPiOptions, piFileSystems } from "./roots.js";
+const PI_BUILTIN_EDIT_SNIPPET = "Make precise file edits with exact text replacement, including multiple disjoint edits in one call";
+const EDIT_GUIDELINES = [
+    "Use edit for precise changes (edits[].oldText must match exactly)",
+    "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls",
+    "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.",
+    "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
+];
+const PI_BUILTIN_WRITE_SNIPPET = "Create or overwrite files";
+const WRITE_GUIDELINES = ["Use write only for new files or complete rewrites."];
+const PATCH_SNIPPET = "Add, update, move, or delete files with one patch";
+const PATCH_GUIDELINES = [
+    "Use apply_patch for related changes across several files, or to add, move, or delete files.",
+];
+export function piEditParts(options) {
+    const signature = options.signature ??
+        multiEditSignature(options.matchers === undefined ? {} : { matchers: options.matchers });
+    return parts("edit", signature, options, PI_BUILTIN_EDIT_SNIPPET, EDIT_GUIDELINES);
+}
+export function piWriteParts(options) {
+    const signature = options.signature ?? defaultWriteSignature();
+    return parts("write", signature, options, PI_BUILTIN_WRITE_SNIPPET, WRITE_GUIDELINES);
+}
+export function piApplyPatchParts(options) {
+    const signature = options.signature ?? freeformPatchSignature();
+    return parts("apply_patch", signature, options, PATCH_SNIPPET, PATCH_GUIDELINES);
+}
+function parts(tool, signature, options, snippet, guidelines) {
+    return {
+        tool,
+        signature,
+        promptSnippet: options.promptSnippet ?? snippet,
+        promptGuidelines: options.promptGuidelines ?? guidelines,
+        messages: { ...writeSignatureMessages(signature), ...options.messages },
+    };
+}
+/**
+ * Creates a Pi edit tool rooted at each call's ctx.cwd. Throws TypeError when
+ * options set fs, cwd, or allowedRoots. Read-before-write is off unless you
+ * pass a `state`; use createPiFsTools({ state }) for a store shared with read.
+ */
+export function createPiEditTool(options = {}) {
+    checkPiOptions(options, "edit");
+    const { denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode, signature: _signature, promptSnippet: _snippet, promptGuidelines: _lines, ...deps } = options;
+    const fs = piFileSystems({ denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode });
+    const made = piEditParts(options);
+    const { messages } = made;
+    // digest: null narrows the options to the branch without a state.
+    if (deps.digest === null) {
+        return adaptPiMutationTool(made, createEditTool({ ...deps, fs, messages, digest: null }));
+    }
+    const digest = deps.digest ?? nodeDigest();
+    return adaptPiMutationTool(made, createEditTool({ ...deps, fs, messages, digest }));
+}
+/** Creates a Pi write tool, as createPiEditTool. `details` is always undefined, as for Pi's own write. */
+export function createPiWriteTool(options = {}) {
+    checkPiOptions(options, "write");
+    const { denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode, signature: _signature, promptSnippet: _snippet, promptGuidelines: _lines, ...deps } = options;
+    const fs = piFileSystems({ denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode });
+    const made = piWriteParts(options);
+    const { messages } = made;
+    if (deps.digest === null) {
+        return adaptPiMutationTool(made, createWriteTool({ ...deps, fs, messages, digest: null }));
+    }
+    const digest = deps.digest ?? nodeDigest();
+    return adaptPiMutationTool(made, createWriteTool({ ...deps, fs, messages, digest }));
+}
+/** Creates a Pi apply_patch tool, as createPiEditTool. A grammar signature sets constrainedSampling. */
+export function createPiApplyPatchTool(options = {}) {
+    checkPiOptions(options, "apply_patch");
+    const { denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode, signature: _signature, promptSnippet: _snippet, promptGuidelines: _lines, ...deps } = options;
+    const fs = piFileSystems({ denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode });
+    const made = piApplyPatchParts(options);
+    const { messages } = made;
+    if (deps.digest === null) {
+        return adaptPiMutationTool(made, createApplyPatchTool({ ...deps, fs, messages, digest: null }));
+    }
+    const digest = deps.digest ?? nodeDigest();
+    return adaptPiMutationTool(made, createApplyPatchTool({ ...deps, fs, messages, digest }));
+}
+export function adaptPiMutationTool(made, tool) {
+    const { signature, tool: toolName, promptSnippet, promptGuidelines } = made;
+    const withDetails = toolName !== "write";
+    const grammar = signature.grammar;
+    return Object.freeze({
+        name: signature.name,
+        label: signature.name,
+        description: signature.description,
+        promptSnippet,
+        promptGuidelines: [...promptGuidelines],
+        parameters: Type.Unsafe(signature.schema),
+        ...(grammar === undefined
+            ? {}
+            : {
+                constrainedSampling: { type: "grammar", variants: { openai_lark: grammar.lark } },
+            }),
+        async execute(toolCallId, input, signal, _onUpdate, ctx) {
+            checkPiContext(ctx, toolName);
+            const call = {
+                ...(signal === undefined ? {} : { signal }),
+                callId: toolCallId,
+                host: ctx,
+            };
+            const result = await tool(signature.toInput(input), call);
+            return {
+                content: result.content.map((part) => toPiPart(part, toolName)),
+                details: withDetails ? toPiMutationDetails(result) : undefined,
+            };
+        },
+    });
+}

package/dist/parts.d.ts

@@ -0,0 +1,10 @@
+import type { ContentPart } from "@better-fs-tools/read";
+export type PiContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export declare function toPiPart(part: ContentPart, tool: string): PiContentPart;

package/dist/parts.js

@@ -0,0 +1,20 @@
+import { Buffer } from "node:buffer";
+export function toPiPart(part, tool) {
+    switch (part.type) {
+        case "text":
+            return { type: "text", text: part.text };
+        case "media":
+            // Pi's tool content takes images only.
+            if (!part.mediaType.startsWith("image/")) {
+                return {
+                    type: "text",
+                    text: `[${tool}:media-omitted] ${part.mediaType} (${part.data.byteLength} bytes) cannot be shown in Pi.`,
+                };
+            }
+            return {
+                type: "image",
+                data: Buffer.from(part.data.buffer, part.data.byteOffset, part.data.byteLength).toString("base64"),
+                mimeType: part.mediaType,
+            };
+    }
+}

package/dist/roots.d.ts

@@ -0,0 +1,20 @@
+import type { NodeFileSystem, NodeFileSystemOptions } from "@better-fs-tools/node";
+import type { ToolCallContext } from "@better-fs-tools/read";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** Filesystem options for a Pi tool. The root is always ctx.cwd. */
+export interface PiRootOptions {
+    /** Added to /dev, /proc, /sys. */
+    readonly denyRoots?: readonly string[];
+    readonly symlinks?: NodeFileSystemOptions["symlinks"];
+    /** How to replace a file with more than one hard link. Default "in-place". "refuse" fails with DENIED. */
+    readonly hardLinks?: "refuse" | "in-place";
+    /** Mode of a new file, exactly. Default 0o666 less the process umask. */
+    readonly newFileMode?: number;
+    /** Mode of a directory that createParents makes, exactly. Default 0o777 less the umask. */
+    readonly newDirectoryMode?: number;
+}
+export declare const PI_ROOT_KEYS: readonly ["denyRoots", "symlinks", "hardLinks", "newFileMode", "newDirectoryMode"];
+export type PiFileSystems = (call: ToolCallContext<ExtensionContext>) => NodeFileSystem;
+export declare function checkPiOptions(options: unknown, tool: string): void;
+export declare function checkPiContext(ctx: unknown, tool: string): void;
+export declare function piFileSystems(options: PiRootOptions): PiFileSystems;

package/dist/roots.js

@@ -0,0 +1,58 @@
+import path from "node:path";
+import { nodeFileSystem } from "@better-fs-tools/node";
+const MAX_CACHED_ROOTS = 8;
+const ROOT_WIDENING_OPTIONS = ["fs", "cwd", "allowedRoots"];
+export const PI_ROOT_KEYS = [
+    "denyRoots",
+    "symlinks",
+    "hardLinks",
+    "newFileMode",
+    "newDirectoryMode",
+];
+export function checkPiOptions(options, tool) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError(`Pi ${tool} tool options must be an object`);
+    }
+    for (const key of ROOT_WIDENING_OPTIONS) {
+        if (Object.hasOwn(options, key)) {
+            throw new TypeError(`Pi ${tool} tool options cannot set ${key}: the root is bound to ctx.cwd on every call`);
+        }
+    }
+}
+export function checkPiContext(ctx, tool) {
+    if (ctx === null ||
+        typeof ctx !== "object" ||
+        typeof ctx.cwd !== "string" ||
+        ctx.cwd.length === 0) {
+        throw new TypeError(`Pi ${tool} execution requires ctx.cwd`);
+    }
+}
+export function piFileSystems(options) {
+    const { denyRoots, symlinks, hardLinks, newFileMode, newDirectoryMode } = options;
+    const fileSystemFor = rootCache((root) => nodeFileSystem({
+        cwd: root,
+        allowedRoots: [root],
+        ...(denyRoots === undefined ? {} : { denyRoots }),
+        ...(symlinks === undefined ? {} : { symlinks }),
+        ...(hardLinks === undefined ? {} : { hardLinks }),
+        ...(newFileMode === undefined ? {} : { newFileMode }),
+        ...(newDirectoryMode === undefined ? {} : { newDirectoryMode }),
+    }));
+    return (call) => fileSystemFor(path.resolve(call.host.cwd));
+}
+function rootCache(build) {
+    const cache = new Map();
+    return (root) => {
+        const cached = cache.get(root);
+        if (cached !== undefined)
+            return cached;
+        const fs = build(root);
+        if (cache.size >= MAX_CACHED_ROOTS) {
+            const oldest = cache.keys().next();
+            if (!oldest.done)
+                cache.delete(oldest.value);
+        }
+        cache.set(root, fs);
+        return fs;
+    };
+}

package/dist/tool.d.ts

@@ -0,0 +1,66 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import type { NodeFileSystemOptions } from "@better-fs-tools/node";
+import type { Converter, Digest, JsonObject, ReadFormatter, ReadLimits, ReadMessageCatalog, ReadTool, ReadToolDeps, StateNeedsDigestOrDefault } from "@better-fs-tools/read";
+import type { ReadSignature } from "@better-fs-tools/read/signature";
+import type { PiReadDetails } from "./details.ts";
+import type { PiContentPart } from "./parts.ts";
+export type { PiContentPart } from "./parts.ts";
+/** Pi prompt options of the read tool. */
+export interface PiReadOptions {
+    /** Default defaultReadSignature({ name: "read" }). */
+    readonly signature?: ReadSignature;
+    /** Default "Read file contents". */
+    readonly promptSnippet?: string;
+    /** Default ["Use read to examine files instead of cat or sed."]. */
+    readonly promptGuidelines?: readonly string[];
+}
+/**
+ * Options for createPiReadTool. digest defaults to nodeDigest(); a state needs
+ * a digest that is not null. converters defaults to [imageConverter()], as
+ * Pi's own read shows images. A list you pass replaces it: [] turns images off.
+ */
+export type CreatePiReadToolOptions = Omit<ReadToolDeps<ExtensionContext>, "fs"> & StateNeedsDigestOrDefault & PiReadOptions & {
+    /** Added to /dev, /proc, /sys. */
+    readonly denyRoots?: readonly string[];
+    readonly symlinks?: NodeFileSystemOptions["symlinks"];
+};
+export interface PiReadToolResult {
+    content: PiContentPart[];
+    details: PiReadDetails;
+}
+/** Assignable to ToolDefinition<TSchema, PiReadDetails> from Pi 0.84.2. */
+export interface PiReadTool {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptSnippet: string;
+    readonly promptGuidelines: string[];
+    /** The JSON Schema of the tool input. */
+    readonly parameters: TSchema;
+    execute(toolCallId: string, input: JsonObject, signal: AbortSignal | undefined, onUpdate: unknown, ctx: ExtensionContext): Promise<PiReadToolResult>;
+}
+/**
+ * Creates a Pi read tool rooted at each call's ctx.cwd. Throws TypeError when
+ * options set fs, cwd, or allowedRoots. It keeps no read state by default and
+ * writes nothing outside the process. An image becomes a Pi image part unless
+ * options.converters leaves imageConverter() out.
+ */
+export declare function createPiReadTool(options?: CreatePiReadToolOptions): PiReadTool;
+export interface PiReadParts {
+    readonly signature: ReadSignature;
+    readonly promptSnippet: string;
+    readonly promptGuidelines: readonly string[];
+    readonly limits: Readonly<ReadLimits>;
+    readonly formatter: ReadFormatter<ExtensionContext>;
+    readonly messages: Partial<ReadMessageCatalog>;
+    readonly converters: readonly Converter<ExtensionContext>[];
+}
+export declare function piReadParts(options: PiReadOptions & Pick<Partial<ReadToolDeps<ExtensionContext>>, "limits" | "messages" | "formatter" | "converters">): PiReadParts;
+export declare function piReadDeps(parts: PiReadParts): {
+    limits: Readonly<ReadLimits>;
+    formatter: ReadFormatter<ExtensionContext>;
+    messages: Partial<ReadMessageCatalog>;
+    converters: readonly Converter<ExtensionContext>[];
+};
+export declare function adaptPiReadTool(parts: PiReadParts, read: ReadTool<ExtensionContext>, digest: Digest | null): PiReadTool;

package/dist/tool.js

@@ -0,0 +1,89 @@
+import { Type } from "typebox";
+import { nodeDigest } from "@better-fs-tools/node";
+import { createReadTool, imageConverter, lineNumberFormatter, resolveReadLimits, } from "@better-fs-tools/read";
+import { defaultReadSignature, readSignatureMessages } from "@better-fs-tools/read/signature";
+import { toPiReadDetails } from "./details.js";
+import { toPiPart } from "./parts.js";
+import { checkPiContext, checkPiOptions, piFileSystems } from "./roots.js";
+const PI_BUILTIN_READ_SNIPPET = "Read file contents";
+const PI_BUILTIN_READ_GUIDELINES = [
+    "Use read to examine files instead of cat or sed.",
+];
+/**
+ * Creates a Pi read tool rooted at each call's ctx.cwd. Throws TypeError when
+ * options set fs, cwd, or allowedRoots. It keeps no read state by default and
+ * writes nothing outside the process. An image becomes a Pi image part unless
+ * options.converters leaves imageConverter() out.
+ */
+export function createPiReadTool(options = {}) {
+    checkPiOptions(options, "read");
+    const { denyRoots, symlinks, signature: _signature, promptSnippet: _promptSnippet, promptGuidelines: _promptGuidelines, ...deps } = options;
+    const parts = piReadParts(options);
+    const fs = piFileSystems({ denyRoots, symlinks });
+    // digest: null narrows the options to the branch without a state.
+    if (deps.digest === null) {
+        const read = createReadTool({ ...deps, ...piReadDeps(parts), fs, digest: null });
+        return adaptPiReadTool(parts, read, null);
+    }
+    const digest = deps.digest ?? nodeDigest();
+    const read = createReadTool({ ...deps, ...piReadDeps(parts), fs, digest });
+    return adaptPiReadTool(parts, read, digest);
+}
+export function piReadParts(options) {
+    const signature = options.signature ?? defaultReadSignature({ name: "read" });
+    return {
+        signature,
+        promptSnippet: options.promptSnippet ?? PI_BUILTIN_READ_SNIPPET,
+        promptGuidelines: options.promptGuidelines ?? PI_BUILTIN_READ_GUIDELINES,
+        limits: resolveReadLimits(options.limits),
+        formatter: options.formatter ?? lineNumberFormatter(),
+        messages: { ...readSignatureMessages(signature), ...options.messages },
+        // Pi's own read returns images, so the Pi host turns them on.
+        converters: options.converters ?? [imageConverter()],
+    };
+}
+export function piReadDeps(parts) {
+    return {
+        limits: parts.limits,
+        formatter: parts.formatter,
+        messages: parts.messages,
+        converters: parts.converters,
+    };
+}
+export function adaptPiReadTool(parts, read, digest) {
+    const { signature, promptSnippet, promptGuidelines, limits, formatter } = parts;
+    return Object.freeze({
+        name: signature.name,
+        label: signature.name,
+        description: signature.description,
+        promptSnippet,
+        promptGuidelines: [...promptGuidelines],
+        parameters: Type.Unsafe(signature.schema),
+        async execute(toolCallId, input, signal, _onUpdate, ctx) {
+            checkPiContext(ctx, "read");
+            const call = {
+                ...(signal === undefined ? {} : { signal }),
+                callId: toolCallId,
+                host: ctx,
+            };
+            const result = await read(signature.toInput(input), call);
+            return {
+                content: result.content.map((part) => toPiPart(part, "read")),
+                details: toPiReadDetails(result, viewOf(formatter, result, { digest, limits, mode: "view", call }), limits.maxViewBytes),
+            };
+        },
+    });
+}
+function viewOf(formatter, result, ctx) {
+    if (result.status !== "ok")
+        return null;
+    const { content: _content, ...outcome } = result;
+    try {
+        const view = formatter.format(outcome, ctx);
+        return typeof view === "string" ? view : null;
+    }
+    catch {
+        // The core already fell back and reported the error in "model" mode.
+        return null;
+    }
+}

package/package.json

@@ -1,5 +1,67 @@
 {
   "name": "@better-fs-tools/pi",
-  "version": "0.0.0-tegami-trusted-publish-setup",
-  "description": "Placeholder published by Tegami for npm trusted publishing setup."
+  "version": "0.2.0",
+  "description": "The Better FS Tools read, edit, write, apply_patch, and bash tools and extension for the Pi coding agent.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gingerhendrix/better-fs-tools.git",
+    "directory": "packages/pi"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./extension": {
+      "types": "./dist/extension.d.ts",
+      "import": "./dist/extension.js"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./extension": {
+        "types": "./dist/extension.d.ts",
+        "import": "./dist/extension.js"
+      }
+    },
+    "access": "public",
+    "pi": {
+      "extensions": [
+        "./dist/extension.js"
+      ]
+    }
+  },
+  "dependencies": {
+    "@better-fs-tools/node": "^0.2.0",
+    "@better-fs-tools/read": "^0.2.0",
+    "@better-fs-tools/shell": "^0.2.0",
+    "@better-fs-tools/write": "^0.2.0"
+  },
+  "devDependencies": {
+    "@better-fs-tools/fs": "^0.2.0",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "typebox": "^1.3.16"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "typebox": "^1.3.16"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension.js"
+    ]
+  }
 }