@better-fs-tools/pi 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+Better FS Tools for the [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) and for `@earendil-works/pi-agent-core`. It replaces Pi's built-in `read`, `edit`, and `write` tools, and can add `apply_patch` and `bash`. The tools take the options of every Better FS Tools integration, with the same defaults, plus Pi's prompt options. `piCwdFileSystem()` from the `./node` subpath confines each call to its working directory.
 
 ## Install
 
@@ -8,9 +8,9 @@ Better FS Tools for the [Pi coding agent](https://www.npmjs.com/package/@earendi
 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.
+`@earendil-works/pi-coding-agent` (`^1.0.0`) and `typebox` (`^1.3.16`) are required peers. Pi versions before 1.0 are not supported. 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.
+The package has a `pi.extensions` entry. When Pi loads the package, the entry registers `read`, `edit`, and `write` from `createPiFsTools()`. They replace Pi's own tools of those names. The entry uses the recommended Pi configuration: `fs: piCwdFileSystem()`, so each call reads and writes inside `ctx.cwd`; `locks: piMutationQueueLocks()`, so Pi's own `edit` and `write` wait for these tools; and `digest: nodeDigest()`. Every other option has the shared default: `read` returns images, and there is no read store, so `edit` and `write` do not check for a read first. The entry registers `piToolRenderers()` so that Pi's built-in renderers draw the tools. It writes no settings or session file.
 
 ## Example
 
@@ -18,15 +18,20 @@ 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 { createPiFsTools, piMutationQueueLocks, piToolRenderers } from "@better-fs-tools/pi";
+import { piCwdFileSystem } from "@better-fs-tools/pi/node";
+import { nodeDigest } from "@better-fs-tools/node";
 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({
+    // The recommended Pi configuration, as in the package's extension entry.
+    fs: piCwdFileSystem(), // a Node filesystem rooted at ctx.cwd on each call
+    locks: piMutationQueueLocks(), // the per-file queue of Pi's own edit and write
+    digest: nodeDigest(), // faster on Node than the default sha256Digest()
+    // Opt-ins: one read store, so edit and write need a read first, and apply_patch.
     state: memoryStore(),
     read: {
       resolve: unicodeRepair({ note: false }),
@@ -41,6 +46,8 @@ export default function fsToolsExtension(pi: ExtensionAPI): void {
   pi.registerTool(tools.edit);
   pi.registerTool(tools.write);
   pi.registerTool(tools.applyPatch);
+  // Pi's built-in read, edit, and write renderers draw the shared signatures.
+  pi.registerToolRenderer(piToolRenderers([tools.read, tools.edit, tools.write]));
 }
 ```
 
@@ -49,6 +56,7 @@ To register only the read tool:
 ```ts
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createPiReadTool } from "@better-fs-tools/pi";
+import { piCwdFileSystem } from "@better-fs-tools/pi/node";
 import { denyPaths, unicodeRepair } from "@better-fs-tools/read";
 import { hashlineFormat } from "@better-fs-tools/read/formats";
 import { defaultReadSignature } from "@better-fs-tools/read/signature";
@@ -56,6 +64,7 @@ import { defaultReadSignature } from "@better-fs-tools/read/signature";
 export default function readExtension(pi: ExtensionAPI): void {
   pi.registerTool(
     createPiReadTool({
+      fs: piCwdFileSystem(),
       signature: defaultReadSignature({ name: "read", names: { path: "file_path" } }),
       resolve: unicodeRepair({ note: false }),
       authorize: denyPaths(["**/.env", "**/.env.*"]),
@@ -65,78 +74,194 @@ export default function readExtension(pi: ExtensionAPI): void {
 }
 ```
 
-## What the read tool does
+## Use the Pi SDK
 
-- `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.
+The tools also work with `createAgentSession()` from the Pi SDK. Give them to `customTools`. A custom tool with the name of a built-in tool replaces it:
+
+```ts
+import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import { createPiFsTools } from "@better-fs-tools/pi";
+import { piCwdFileSystem } from "@better-fs-tools/pi/node";
+import { memoryStore } from "@better-fs-tools/read";
+
+const cwd = "/work/repo";
+const tools = createPiFsTools({ fs: piCwdFileSystem(), state: memoryStore(), applyPatch: true });
+
+// read, edit, and write have the names of Pi's built-in tools, so they replace
+// them. Pi's own bash stays.
+const { session } = await createAgentSession({
+  cwd,
+  sessionManager: SessionManager.inMemory(cwd),
+  customTools: [tools.read, tools.edit, tools.write, tools.applyPatch],
+});
+
+try {
+  await session.prompt("Rename greet() to welcome() in src/greet.ts.");
+} finally {
+  session.dispose();
+}
+```
+
+The session's `cwd` is the root of every call. For `tools`, `noTools`, and inline extensions with hooks and guards, see [Use Pi from code (SDK)](https://better-fs-tools.gandrew.com/integrations/pi#use-pi-from-code-sdk). For `pi-agent-core`, use `createAgentCoreFsTools()`: see [Pi agent core](#pi-agent-core) below. For the experimental `pi-durable` harness, use [`@better-fs-tools/pi-durable`](https://www.npmjs.com/package/@better-fs-tools/pi-durable).
+
+## Options
 
-## What the write tools do
+Every Pi factory takes the options of the matching core factory, with the same defaults, plus `signature`, `promptSnippet`, and `promptGuidelines`:
 
-- `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.
+| Factory                                                                 | Options                                                                                                             |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `createPiReadTool(options)`                                             | `createReadTool()`: `fs` is required                                                                                |
+| `createPiEditTool()`, `createPiWriteTool()`, `createPiApplyPatchTool()` | `createEditTool()`, `createWriteTool()`, `createApplyPatchTool()`: `fs` is required                                 |
+| `createPiBashTool(options)`                                             | `createBashTool()`: `runner` and `env` are required                                                                 |
+| `createPiFsTools(options)`                                              | `createFsTools()`: `fs` is required. Each tool's options go under `read`, `edit`, `write`, `applyPatch`, and `bash` |
+
+- `promptSnippet` and `promptGuidelines` are Pi fields. The snippet defaults to the first sentence of the signature description, because Pi lists a tool under "Available tools" only when it has a snippet. The guidelines default to `[]`.
+- 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. A factory `fs`, `state`, or `runner` gets the call, so it can use `ctx.cwd`.
+- The defaults are those of every integration: `digest` is `sha256Digest()`, `locks` is `memoryLocks()`, `state` is `null`, `read.converters` is `[imageConverter()]`, and the default signatures are `defaultReadSignature()`, `defaultEditSignature({ matchers })`, `defaultWriteSignature()`, `defaultPatchSignature()`, and `defaultBashSignature({ runner, limits })`. `docs/hosts.md` in `@better-fs-tools/write` has the full table.
+- `createPiFsTools()` returns `read`, `edit`, `write`, `applyPatch` and `bash` (each `null` when off), `state`, `digest`, `locks`, `clock`, and `invalidate(path, call?)`. Pass the call to `invalidate` when `fs` or `state` is a factory: in a bash `afterRun` hook it is `ctx.call`.
+
+## The Node helpers
+
+`@better-fs-tools/pi/node` has the Node backends of a Pi extension. The main entry imports no Node module.
+
+| Helper                         | Gives                                                                                                                                                                                                                                                                 |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `piCwdFileSystem(options?)`    | A per-call `fs`: `nodeFileSystem()` with `cwd` and `allowedRoots` set to `ctx.cwd`. It keeps the filesystems of the last 8 roots. It takes every other `nodeFileSystem()` option, such as `denyRoots`, `symlinks`, `hardLinks`, `newFileMode`, and `newDirectoryMode` |
+| `piCwdCommandRunner(options?)` | A per-call bash `runner`: `nodeCommandRunner()` at `ctx.cwd`, which must be absolute. It keeps the runners of the last 8 directories                                                                                                                                  |
+
+A call without a usable `ctx.cwd` gives an `extension-failed` error result.
+
+## Recommended configuration
+
+These choices suit Pi. They are options, not defaults:
+
+- `fs: piCwdFileSystem()`: each call is confined to its working directory.
+- `locks: piMutationQueueLocks()`: Pi's own per-file queue, `withFileMutationQueue()`. A Better FS Tools `edit` and Pi's own `edit` or `write` on the same file then wait for each other. `piMutationQueueLocks({ timeoutMs })` waits 30 seconds by default, then fails the change with `LOCK_TIMEOUT`. In a Pi extension, Pi's loader resolves the package's import of `@earendil-works/pi-coding-agent` to Pi's own module, so the queue is Pi's. In an SDK host, install one copy of Pi, so that the package and the host share the queue.
+- `digest: nodeDigest()`: the same values as `sha256Digest()`, faster on Node.
+- For bash: `runner: piCwdCommandRunner()` and `env: shellEnv(() => process.env)`.
+
+## What the tools return
+
+- Image parts become Pi `image` parts. Other media becomes a text part that says what was left out.
+- `read` gives `details.truncation` as Pi's own read tool does 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.
 - `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.
+- A signature with a `grammar` sets `constrainedSampling` for models with grammar-tool support. For the Codex patch grammar, pass `applyPatch: { signature: freeformPatchSignature() }`. To give a model Pi's own edit input, `edits: [{ oldText, newText }]`, pass `edit: { signature: multiEditSignature() }`. Both presets come from `@better-fs-tools/write/signature`.
+- A tool error becomes Pi content text with `isError: true`. The tool does not throw for a tool error. Pi shows the text as an error, and `tool_result` handlers see `isError: true`. Bad model input rejects with `TypeError`.
+
+## Renderers
+
+Pi draws a tool named `read`, `edit`, `write`, or `bash` with its built-in renderer of that name, unless the tool has its own. Those renderers read Pi's own argument names: `edits[].oldText` for the edit preview, and `timeout` in seconds for bash. `piToolRenderers(tools)` returns a `ToolRendererResolver` that gives each renderer the arguments in Pi's names, for any signature. Register it with `pi.registerToolRenderer()`. The extension entry does this for its own tools. Without it, the tools still work, but Pi draws no edit preview before the change and shows a bash timeout in milliseconds as seconds. A replace-all edit gets no preview, and Pi shows the diff of the result.
+
+## Results and hints
+
+Each tool sets these Pi 1.x tool fields:
+
+| Tool                  | `isError`                                      | `annotations`                                                            |
+| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
+| `read`                | `true` for status `error`                      | `readOnlyHint: true`                                                     |
+| `edit`, `apply_patch` | `true` for status `error`                      | `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: false` |
+| `write`               | `true` for status `error`                      | As `edit`, with `idempotentHint: true`                                   |
+| `bash`                | `true` for a nonzero exit, a timeout, an error | None                                                                     |
+
+No tool declares an `outputSchema` or returns `structuredContent`, as in every integration. A codemode script that calls a tool gets its text. A result with `isError: true` makes the call reject with that text.
+
+Permission extensions read `annotations` from `pi.getAllTools()`. The hints are not checked.
 
 ## 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:
+`createPiBashTool()` is a `bash` tool from [`@better-fs-tools/shell`](https://www.npmjs.com/package/@better-fs-tools/shell) with the shared default signature, `defaultBashSignature()`: `{ command, timeout?, cwd? }` with the timeout in milliseconds. `runner` and `env` are required. With `piCwdCommandRunner()`, commands run in `ctx.cwd`, and a `cwd` from the model is relative to it. For a runner with its own directory, the `cwd` option sets another one, for example `cwd: (call) => call.host.cwd`. The extension entry does not register this tool, 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";
+import { createPiBashTool, piToolRenderers } from "@better-fs-tools/pi";
+import { piCwdCommandRunner } from "@better-fs-tools/pi/node";
+import { shellEnv } from "@better-fs-tools/shell";
 
-// Replaces Pi's own bash: same name, { command, timeout } in seconds, run in ctx.cwd.
+// Replaces Pi's own bash with the shared signature: { command, timeout?, cwd? },
+// the timeout in milliseconds, run in ctx.cwd. Pi's bash renderer still draws it.
 export default function bashExtension(pi: ExtensionAPI): void {
-  pi.registerTool(createPiBashTool());
+  const bash = createPiBashTool({
+    runner: piCwdCommandRunner(), // a Node runner at ctx.cwd on each call
+    env: shellEnv(() => process.env),
+  });
+  pi.registerTool(bash);
+  pi.registerToolRenderer(piToolRenderers([bash]));
 }
 ```
 
-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.
+The default description names the timeouts and output limits from `limits`, and the id of a `runner` object. A runner factory, such as `piCwdCommandRunner()`, has no id to name.
 
-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)`.
+Pi's own `bash` also sets `PI_*` session variables. This tool does not. Add them with the `env` option when you need them.
 
-With the file tools, a bash `afterRun` hook can make the next edit of a file need a read:
+The bundle takes `bash` too. With a read store, 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 { createPiFsTools, piToolRenderers } from "@better-fs-tools/pi";
+import { piCwdCommandRunner, piCwdFileSystem } from "@better-fs-tools/pi/node";
 import { memoryStore } from "@better-fs-tools/read";
+import { shellEnv } from "@better-fs-tools/shell";
 
-// 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.
+// The file tools with a read store, and bash in the same bundle. 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 {};
+  const tools = createPiFsTools({
+    fs: piCwdFileSystem(),
+    state: memoryStore(),
+    bash: {
+      runner: piCwdCommandRunner(),
+      env: shellEnv(() => process.env),
+      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);
+  pi.registerTool(tools.bash);
+  pi.registerToolRenderer(piToolRenderers([tools.read, tools.edit, tools.write, tools.bash]));
+}
+```
+
+## Pi agent core
+
+`@better-fs-tools/pi/agent-core` gives the tools as `AgentTool` objects for `@earendil-works/pi-agent-core`: for `agent.state.tools`, or the `tools` of an `agentLoop()` context. It has `createAgentCoreFsTools()` and the single-tool factories `createAgentCoreReadTool()`, `createAgentCoreEditTool()`, `createAgentCoreWriteTool()`, `createAgentCoreApplyPatchTool()`, and `createAgentCoreBashTool()`. An `AgentTool` gets no context object, so the host type is `undefined`:
+
+```ts
+import { Agent } from "@earendil-works/pi-agent-core";
+import { createAgentCoreFsTools } from "@better-fs-tools/pi/agent-core";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import { memoryStore } from "@better-fs-tools/read";
+
+const fsTools = createAgentCoreFsTools({
+  fs: nodeFileSystem({ cwd: "/work/repo", allowedRoots: ["/work/repo"] }),
+  state: memoryStore(),
+});
+
+export function addFsTools(agent: Agent): void {
+  agent.state.tools = [...agent.state.tools, ...fsTools.tools];
 }
 ```
 
+- The options are those of the core factories and `createFsTools()`, with the same defaults, plus a `signature` for each tool. No tool declares an output schema.
+- `fs` can be any writable filesystem. The module imports no Node module and no Pi package at run time, so it runs in a browser or a Worker, for example with `memoryFileSystem()` or a Cloudflare filesystem.
+- pi-agent-core has no tools of its own. `bash: { runner, env }` adds a `bash` tool with `defaultBashSignature()`: `{ command, timeout?, cwd? }` with the timeout in milliseconds.
+- A tool error is a result with `isError: true`. Bad model input rejects with `TypeError`, which the agent reports as an error result.
+- `read` sets `replay: "safe"`. `edit` and `apply_patch` give `toPiMutationDetails()` as `details`.
+- The tools use `memoryLocks()` by default, as every integration does. pi-agent-core has no file queue of its own. Two calls in one batch that change one file wait for each other.
+
 ## 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.
+- [Choose an integration](https://better-fs-tools.gandrew.com/integrations) and [Filesystems](https://better-fs-tools.gandrew.com/filesystems) on the docs site: the defaults of every host and bundle, and what each backend can do. `docs/hosts.md` in [`@better-fs-tools/write`](https://www.npmjs.com/package/@better-fs-tools/write) has the same tables
+- [`@better-fs-tools/read`](https://www.npmjs.com/package/@better-fs-tools/read): every read option, the default signature, `readToolDefinition()`, 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
+- [`@better-fs-tools/node`](https://www.npmjs.com/package/@better-fs-tools/node): the filesystem and runner that the `./node` helpers build on

package/dist/agent-core.d.ts

@@ -0,0 +1,141 @@
+import type { TSchema } from "typebox";
+import type { Clock, Digest, ToolCallContext } from "@better-fs-tools/read";
+import type { ReadSignature, ReadToolDefinitionOptions } from "@better-fs-tools/read/signature";
+import type { BashSignature, BashToolDefinitionOptions } from "@better-fs-tools/shell/signature";
+import type { FsToolsApplyPatchOptions, FsToolsBashOptions, FsToolsEditOptions, FsToolsOptions, FsToolsReadOptions, FsToolsState, FsToolsWriteOptions, InvalidateOutcome, LockManager } from "@better-fs-tools/write";
+import type { ApplyPatchToolDefinitionOptions, EditSignature, EditToolDefinitionOptions, PatchSignature, WriteSignature, WriteToolDefinitionOptions } from "@better-fs-tools/write/signature";
+import type { PiReadDetails } from "./details.ts";
+import type { PiMutationDetails } from "./mutation-details.ts";
+import type { PiContentPart } from "./parts.ts";
+/** An AgentTool host has no context object, so each call's host is undefined. */
+type Host = undefined;
+/** The result of an agent core tool. Assignable to AgentToolResult<TDetails>. */
+export interface AgentCoreToolResult<TDetails> {
+    content: PiContentPart[];
+    details: TDetails;
+    /** true for a tool error. bash also sets it for a nonzero exit and a timeout. */
+    isError: boolean;
+}
+/** Assignable to AgentTool<TSchema, TDetails> from @earendil-works/pi-agent-core 1.x. */
+export interface AgentCoreTool<TDetails> {
+    readonly name: string;
+    readonly label: string;
+    readonly description: 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;
+        };
+    };
+    /** "safe" on read: a rerun after a crash changes nothing. */
+    readonly replay?: "never" | "safe";
+    /** Model input is checked with the signature: bad input throws TypeError. */
+    readonly execute: (toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: unknown) => Promise<AgentCoreToolResult<TDetails>>;
+}
+export type AgentCoreReadTool = AgentCoreTool<PiReadDetails>;
+export type AgentCoreMutationTool = AgentCoreTool<PiMutationDetails | undefined>;
+export type AgentCoreBashTool = AgentCoreTool<{
+    fullOutputPath?: string;
+} | undefined>;
+/** Options for createAgentCoreReadTool: the options of readToolDefinition(). `fs` is required. */
+export type AgentCoreReadToolOptions = ReadToolDefinitionOptions<Host>;
+/** Options for createAgentCoreEditTool: the options of editToolDefinition(). */
+export type AgentCoreEditToolOptions = EditToolDefinitionOptions<Host>;
+/** Options for createAgentCoreWriteTool: the options of writeToolDefinition(). */
+export type AgentCoreWriteToolOptions = WriteToolDefinitionOptions<Host>;
+/** Options for createAgentCoreApplyPatchTool: the options of applyPatchToolDefinition(). */
+export type AgentCoreApplyPatchToolOptions = ApplyPatchToolDefinitionOptions<Host>;
+/** Options for createAgentCoreBashTool: the options of bashToolDefinition(). `runner` and `env` are required. */
+export type AgentCoreBashToolOptions = BashToolDefinitionOptions<Host>;
+/** Read options of the bundle. Shared keys are set once at the top level. */
+export type AgentCoreFsToolsReadOptions = FsToolsReadOptions<Host> & {
+    /** Default defaultReadSignature(). */
+    readonly signature?: ReadSignature;
+};
+export type AgentCoreFsToolsEditOptions = FsToolsEditOptions<Host> & {
+    /** Default defaultEditSignature({ matchers }). */
+    readonly signature?: EditSignature;
+};
+export type AgentCoreFsToolsWriteOptions = FsToolsWriteOptions<Host> & {
+    /** Default defaultWriteSignature(). */
+    readonly signature?: WriteSignature;
+};
+export type AgentCoreFsToolsApplyPatchOptions = FsToolsApplyPatchOptions<Host> & {
+    /** Default defaultPatchSignature(). */
+    readonly signature?: PatchSignature;
+};
+/** bash options of the bundle. `runner` and `env` are required. */
+export type AgentCoreFsToolsBashOptions = FsToolsBashOptions<Host> & {
+    /** Default defaultBashSignature() for the runner's id and the limits. */
+    readonly signature?: BashSignature;
+};
+/** The options of createFsTools(), with a `signature` in each tool's options. */
+export interface AgentCoreFsToolsOptions extends Omit<FsToolsOptions<Host>, "read" | "edit" | "write" | "applyPatch" | "bash"> {
+    readonly read?: AgentCoreFsToolsReadOptions;
+    readonly edit?: AgentCoreFsToolsEditOptions;
+    readonly write?: AgentCoreFsToolsWriteOptions;
+    /** Off by default. `true` or an options object adds an apply_patch tool. */
+    readonly applyPatch?: boolean | AgentCoreFsToolsApplyPatchOptions;
+    /** Off by default. pi-agent-core has no tools of its own: give a runner and an env for bash. */
+    readonly bash?: false | AgentCoreFsToolsBashOptions;
+}
+export interface AgentCoreFsTools {
+    readonly read: AgentCoreReadTool;
+    readonly edit: AgentCoreMutationTool;
+    readonly write: AgentCoreMutationTool;
+    /** null unless options.applyPatch is true or an object. */
+    readonly applyPatch: AgentCoreMutationTool | null;
+    /** null unless options.bash is set. */
+    readonly bash: AgentCoreBashTool | null;
+    /** Every tool of the bundle, for agent.state.tools or an agentLoop() context. */
+    readonly tools: readonly (AgentCoreReadTool | AgentCoreMutationTool | AgentCoreBashTool)[];
+    readonly state: FsToolsState<Host>;
+    readonly digest: Digest;
+    readonly locks: LockManager;
+    readonly clock: Clock;
+    /** As createFsTools().invalidate. When fs or state is a factory, pass the call context. */
+    invalidate(path: string, call?: ToolCallContext<Host>): Promise<InvalidateOutcome>;
+}
+/** The createAgentCoreFsTools result when `applyPatch` is true or an object: it is never null. */
+export interface AgentCoreFsToolsWithApplyPatch extends AgentCoreFsTools {
+    readonly applyPatch: AgentCoreMutationTool;
+}
+/** The createAgentCoreFsTools result when `bash` is set: it is never null. */
+export interface AgentCoreFsToolsWithBash extends AgentCoreFsTools {
+    readonly bash: AgentCoreBashTool;
+}
+/** Creates a read AgentTool with the options and defaults of createReadTool(). read is replay-safe. */
+export declare function createAgentCoreReadTool(options: AgentCoreReadToolOptions): AgentCoreReadTool;
+/** Creates an edit AgentTool with the options and defaults of createEditTool(). */
+export declare function createAgentCoreEditTool(options: AgentCoreEditToolOptions): AgentCoreMutationTool;
+/** Creates a write AgentTool with the options and defaults of createWriteTool(). */
+export declare function createAgentCoreWriteTool(options: AgentCoreWriteToolOptions): AgentCoreMutationTool;
+/** Creates an apply_patch AgentTool with the options and defaults of createApplyPatchTool(). */
+export declare function createAgentCoreApplyPatchTool(options: AgentCoreApplyPatchToolOptions): AgentCoreMutationTool;
+/** Creates a bash AgentTool with the options and defaults of createBashTool(). */
+export declare function createAgentCoreBashTool(options: AgentCoreBashToolOptions): AgentCoreBashTool;
+/**
+ * Creates read, edit, and write AgentTools over one writable filesystem, with
+ * one digest, lock manager, and clock, and the read state when `state` is
+ * given. With `applyPatch`, also apply_patch. With `bash`, also bash. Every
+ * option and default is the one of createFsTools().
+ *
+ * A tool error is a result with `isError: true`, not a throw. Bad model input
+ * throws TypeError. Throws TypeError where createFsTools() does, with
+ * createAgentCoreFsTools in the message.
+ */
+export declare function createAgentCoreFsTools(options: AgentCoreFsToolsOptions & {
+    readonly applyPatch: true | AgentCoreFsToolsApplyPatchOptions;
+    readonly bash: AgentCoreFsToolsBashOptions;
+}): AgentCoreFsToolsWithApplyPatch & AgentCoreFsToolsWithBash;
+export declare function createAgentCoreFsTools(options: AgentCoreFsToolsOptions & {
+    readonly bash: AgentCoreFsToolsBashOptions;
+}): AgentCoreFsToolsWithBash;
+export declare function createAgentCoreFsTools(options: AgentCoreFsToolsOptions & {
+    readonly applyPatch: true | AgentCoreFsToolsApplyPatchOptions;
+}): AgentCoreFsToolsWithApplyPatch;
+export declare function createAgentCoreFsTools(options: AgentCoreFsToolsOptions): AgentCoreFsTools;
+export {};

package/dist/agent-core.js

@@ -0,0 +1,121 @@
+/**
+ * The Better FS Tools as AgentTool objects for @earendil-works/pi-agent-core:
+ * an Agent's state.tools, or the tools of an agentLoop() context. This module
+ * imports neither Node nor Pi at run time, so it runs in a browser or a
+ * Worker with any writable filesystem.
+ */
+import { Type } from "typebox";
+import { readToolDefinition } from "@better-fs-tools/read/signature";
+import { bashToolDefinition } from "@better-fs-tools/shell/signature";
+import { applyPatchToolDefinition, editToolDefinition, fsToolDefinitions, writeToolDefinition, } from "@better-fs-tools/write/signature";
+import { toPiReadDetails, viewOf } from "./details.js";
+import { toPiMutationDetails } from "./mutation-details.js";
+import { toPiPart } from "./parts.js";
+import { checkPiOptions } from "./prompt.js";
+/** Creates a read AgentTool with the options and defaults of createReadTool(). read is replay-safe. */
+export function createAgentCoreReadTool(options) {
+    checkPiOptions(options, "agent core read tool");
+    return adaptReadTool(readToolDefinition(options));
+}
+/** Creates an edit AgentTool with the options and defaults of createEditTool(). */
+export function createAgentCoreEditTool(options) {
+    checkPiOptions(options, "agent core edit tool");
+    return adaptMutationTool("edit", editToolDefinition(options));
+}
+/** Creates a write AgentTool with the options and defaults of createWriteTool(). */
+export function createAgentCoreWriteTool(options) {
+    checkPiOptions(options, "agent core write tool");
+    return adaptMutationTool("write", writeToolDefinition(options));
+}
+/** Creates an apply_patch AgentTool with the options and defaults of createApplyPatchTool(). */
+export function createAgentCoreApplyPatchTool(options) {
+    checkPiOptions(options, "agent core apply_patch tool");
+    return adaptMutationTool("apply_patch", applyPatchToolDefinition(options));
+}
+/** Creates a bash AgentTool with the options and defaults of createBashTool(). */
+export function createAgentCoreBashTool(options) {
+    checkPiOptions(options, "agent core bash tool");
+    return adaptBashTool(bashToolDefinition(options));
+}
+export function createAgentCoreFsTools(options) {
+    checkPiOptions(options, "createAgentCoreFsTools");
+    const defs = fsToolDefinitions(options, "createAgentCoreFsTools");
+    const adapted = {
+        read: adaptReadTool(defs.read),
+        edit: adaptMutationTool("edit", defs.edit),
+        write: adaptMutationTool("write", defs.write),
+        applyPatch: defs.applyPatch === null ? null : adaptMutationTool("apply_patch", defs.applyPatch),
+        bash: defs.bash === null ? null : adaptBashTool(defs.bash),
+    };
+    return Object.freeze({
+        ...adapted,
+        tools: Object.freeze(Object.values(adapted).filter((tool) => tool !== null)),
+        state: defs.state,
+        digest: defs.digest,
+        locks: defs.locks,
+        clock: defs.clock,
+        invalidate: defs.invalidate,
+    });
+}
+function declaration(definition) {
+    return {
+        name: definition.name,
+        label: definition.name,
+        description: definition.description,
+        parameters: Type.Unsafe(definition.inputSchema),
+        ...(definition.grammar === undefined
+            ? {}
+            : {
+                constrainedSampling: {
+                    type: "grammar",
+                    variants: { openai_lark: definition.grammar.lark },
+                },
+            }),
+    };
+}
+function callOf(toolCallId, signal) {
+    return { ...(signal === undefined ? {} : { signal }), callId: toolCallId, host: undefined };
+}
+function adaptReadTool(definition) {
+    const { limits, formatter, digest } = definition;
+    return Object.freeze({
+        ...declaration(definition),
+        replay: "safe",
+        async execute(toolCallId, params, signal) {
+            const call = callOf(toolCallId, signal);
+            const result = await definition.execute(params, call);
+            const content = result.content.map((part) => toPiPart(part, "read"));
+            const view = viewOf(formatter, result, { digest, limits, mode: "view", call });
+            const details = toPiReadDetails(result, view, limits.maxViewBytes);
+            return { content, details, isError: result.status === "error" };
+        },
+    });
+}
+function adaptMutationTool(kind, definition) {
+    return Object.freeze({
+        ...declaration(definition),
+        async execute(toolCallId, params, signal) {
+            const result = await definition.execute(params, callOf(toolCallId, signal));
+            return {
+                content: result.content.map((part) => toPiPart(part, kind)),
+                // The coding agent's own write has no details.
+                details: kind === "write" ? undefined : toPiMutationDetails(result),
+                isError: result.status === "error",
+            };
+        },
+    });
+}
+function adaptBashTool(definition) {
+    return Object.freeze({
+        ...declaration(definition),
+        async execute(toolCallId, params, signal) {
+            const result = await definition.execute(params, callOf(toolCallId, signal));
+            const spill = result.output?.spill ?? null;
+            return {
+                content: result.content.map((part) => toPiPart(part, "bash")),
+                details: spill === null ? undefined : { fullOutputPath: spill },
+                isError: result.status !== "ok",
+            };
+        },
+    });
+}