@better-fs-tools/pi 0.2.0 → 0.3.0

package/dist/bash-tool.d.ts

@@ -1,24 +1,15 @@
 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 { BashToolDefinition, BashToolDefinitionOptions } 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[];
-}
+import type { PiPromptOptions } from "./prompt.ts";
+/**
+ * Options for createPiBashTool: the options of bashToolDefinition(), with the
+ * Pi extension context as host, plus the Pi prompt options. `runner` and `env`
+ * are required: piCwdCommandRunner() from `./node` runs commands in ctx.cwd.
+ */
+export type PiBashToolOptions = BashToolDefinitionOptions<ExtensionContext> & PiPromptOptions;
 /** Pi's BashToolDetails shape, so Pi's bash renderer can show the saved output. */
 export interface PiBashDetails {
     fullOutputPath?: string;
@@ -26,8 +17,10 @@ export interface PiBashDetails {
 export interface PiBashToolResult {
     content: PiContentPart[];
     details: PiBashDetails | undefined;
+    /** true for a nonzero exit, a timeout, and an error. */
+    isError: boolean;
 }
-/** Assignable to ToolDefinition<TSchema, PiBashDetails | undefined> from Pi 0.84.2. */
+/** Assignable to ToolDefinition<TSchema, PiBashDetails | undefined> from Pi 1.x. */
 export interface PiBashTool {
     readonly name: string;
     readonly label: string;
@@ -39,10 +32,9 @@ export interface PiBashTool {
     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.
+ * Creates a Pi bash tool with the options and defaults of createBashTool().
+ * 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;
+export declare function createPiBashTool(options: PiBashToolOptions): PiBashTool;
+export declare function adaptPiBashTool(definition: BashToolDefinition<ExtensionContext>, prompt: PiPromptOptions): PiBashTool;

package/dist/bash-tool.js

@@ -1,76 +1,41 @@
-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 { bashToolDefinition } 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;
+import { checkPiOptions, piPrompt, splitPrompt } from "./prompt.js";
+import { piBashArgs, setRenderArgs } from "./renderers.js";
 /**
- * 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.
+ * Creates a Pi bash tool with the options and defaults of createBashTool().
+ * 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),
+export function createPiBashTool(options) {
+    checkPiOptions(options, "Pi bash tool");
+    const { prompt, rest } = splitPrompt(options);
+    return adaptPiBashTool(bashToolDefinition(rest), prompt);
+}
+export function adaptPiBashTool(definition, prompt) {
+    const { signature } = definition;
+    const tool = Object.freeze({
+        name: definition.name,
+        label: definition.name,
+        description: definition.description,
+        ...piPrompt(prompt, definition.description),
+        parameters: Type.Unsafe(definition.inputSchema),
         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 result = await definition.execute(input, call);
             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",
             };
         },
     });
-}
-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;
-    };
+    setRenderArgs(tool, (args) => signature.toInput(args), piBashArgs);
+    return tool;
 }

package/dist/details.d.ts

@@ -1,4 +1,4 @@
-import type { ReadResult } from "@better-fs-tools/read";
+import type { ReadFormatContext, ReadFormatter, ReadResult } from "@better-fs-tools/read";
 /** Pi's published TruncationResult. Fields and meanings are Pi's. */
 export interface PiTruncationResult {
     content: string;
@@ -24,3 +24,9 @@ export interface PiReadDetails {
  * total, because an approximate count is worse than none.
  */
 export declare function toPiReadDetails(result: ReadResult, view: string | null, maxViewBytes: number): PiReadDetails;
+/**
+ * The formatted text of an ok read in "view" mode, for toPiReadDetails. null
+ * for another status, a formatter that returns parts, or a formatter that
+ * throws.
+ */
+export declare function viewOf<THost>(formatter: ReadFormatter<THost>, result: ReadResult, ctx: ReadFormatContext<THost>): string | null;

package/dist/details.js

@@ -28,3 +28,21 @@ export function toPiReadDetails(result, view, maxViewBytes) {
         },
     };
 }
+/**
+ * The formatted text of an ok read in "view" mode, for toPiReadDetails. null
+ * for another status, a formatter that returns parts, or a formatter that
+ * throws.
+ */
+export 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/dist/extension.d.ts

@@ -1,8 +1,20 @@
+/**
+ * Pi package extension entry. Installing the package into a Pi project
+ * registers read, edit, and write, which replace Pi's own tools, and nothing
+ * else. It uses the recommended Pi configuration: a filesystem rooted at each
+ * call's ctx.cwd, Pi's own per-file queue as the locks, so Pi's edit and
+ * write wait for these tools, and nodeDigest(), which is faster on Node. Every
+ * other option has the shared default: no read store, and read returns images.
+ * A renderer resolver lets Pi's built-in read, edit, and write renderers draw
+ * them. Nothing is written outside the process: no settings file, no session file.
+ */
+import type { ToolRendererResolver } from "@earendil-works/pi-coding-agent";
 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;
+    registerToolRenderer(resolver: ToolRendererResolver): void;
 }
 export default function fsToolsExtension(pi: PiExtensionApi): void;

package/dist/extension.js

@@ -1,14 +1,16 @@
-/**
- * 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 { nodeDigest } from "@better-fs-tools/node";
 import { createPiFsTools } from "./fs-tools.js";
+import { piMutationQueueLocks } from "./locks.js";
+import { piCwdFileSystem } from "./node.js";
+import { piToolRenderers } from "./renderers.js";
 export default function fsToolsExtension(pi) {
-    const tools = createPiFsTools();
+    const tools = createPiFsTools({
+        fs: piCwdFileSystem(),
+        locks: piMutationQueueLocks(),
+        digest: nodeDigest(),
+    });
     pi.registerTool(tools.read);
     pi.registerTool(tools.edit);
     pi.registerTool(tools.write);
+    pi.registerToolRenderer(piToolRenderers([tools.read, tools.edit, tools.write]));
 }

package/dist/fs-tools.d.ts

@@ -1,24 +1,48 @@
 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>;
+import type { Clock, Digest, ToolCallContext } from "@better-fs-tools/read";
+import type { ReadSignature } from "@better-fs-tools/read/signature";
+import type { BashSignature } from "@better-fs-tools/shell/signature";
+import type { FsToolsApplyPatchOptions, FsToolsBashOptions, FsToolsEditOptions, FsToolsOptions, FsToolsReadOptions, FsToolsState, FsToolsWriteOptions, InvalidateOutcome, LockManager } from "@better-fs-tools/write";
+import type { EditSignature, PatchSignature, WriteSignature } from "@better-fs-tools/write/signature";
+import type { PiBashTool } from "./bash-tool.ts";
+import type { PiMutationTool } from "./mutation-tools.ts";
+import type { PiPromptOptions } from "./prompt.ts";
+import type { PiReadTool } from "./tool.ts";
+type Host = ExtensionContext;
+/** Read tool options for createPiFsTools. Shared keys are set once at the top level. */
+export type PiFsToolsReadOptions = FsToolsReadOptions<Host> & PiPromptOptions & {
+    /** Default defaultReadSignature(). */
+    readonly signature?: ReadSignature;
+};
+export type PiFsToolsEditOptions = FsToolsEditOptions<Host> & PiPromptOptions & {
+    /** Default defaultEditSignature() for `matchers`. */
+    readonly signature?: EditSignature;
+};
+export type PiFsToolsWriteOptions = FsToolsWriteOptions<Host> & PiPromptOptions & {
+    /** Default defaultWriteSignature(). */
+    readonly signature?: WriteSignature;
+};
+export type PiFsToolsApplyPatchOptions = FsToolsApplyPatchOptions<Host> & PiPromptOptions & {
+    /** Default defaultPatchSignature(). */
+    readonly signature?: PatchSignature;
+};
+/** Bash tool options for createPiFsTools. `runner` and `env` are required. */
+export type PiFsToolsBashOptions = FsToolsBashOptions<Host> & PiPromptOptions & {
+    /** Default defaultBashSignature() for the runner's id and the limits. */
+    readonly signature?: BashSignature;
+};
+/**
+ * The options of createFsTools(), with the Pi extension context as host, and
+ * a `signature` and the Pi prompt options in each tool's options.
+ */
+export interface PiFsToolsOptions extends Omit<FsToolsOptions<Host>, "read" | "edit" | "write" | "applyPatch" | "bash"> {
+    readonly read?: PiFsToolsReadOptions;
+    readonly edit?: PiFsToolsEditOptions;
+    readonly write?: PiFsToolsWriteOptions;
     /** Off by default. `true` or an options object adds an apply_patch tool. */
-    readonly applyPatch?: boolean | Omit<CreatePiApplyPatchToolOptions, BundleSharedKey>;
+    readonly applyPatch?: boolean | PiFsToolsApplyPatchOptions;
+    /** Off by default. Give a runner and an env to add a bash tool. */
+    readonly bash?: false | PiFsToolsBashOptions;
 }
 export interface PiFsTools {
     readonly read: PiReadTool;
@@ -26,34 +50,44 @@ export interface PiFsTools {
     readonly write: PiMutationTool;
     /** null unless options.applyPatch is true or an object. */
     readonly applyPatch: PiMutationTool | null;
-    readonly state: ReadStateStore | null;
-    /** options.digest, or nodeDigest(). */
+    /** null unless options.bash is set. */
+    readonly bash: PiBashTool | null;
+    readonly state: FsToolsState<Host>;
     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.
+     * Forgets the read record for a path, so the next edit needs a read. Pass the
+     * call when fs or state is a factory; in a bash afterRun hook it is ctx.call.
+     * Never throws.
      */
-    invalidate(path: string, call?: ToolCallContext<ExtensionContext>): Promise<InvalidateOutcome>;
+    invalidate(path: string, call?: ToolCallContext<Host>): Promise<InvalidateOutcome>;
 }
 /** The createPiFsTools result when `applyPatch` is true or an object: it is never null. */
 export interface PiFsToolsWithApplyPatch extends PiFsTools {
     readonly applyPatch: PiMutationTool;
 }
+/** The createPiFsTools result when `bash` is set: it is never null. */
+export interface PiFsToolsWithBash extends PiFsTools {
+    readonly bash: PiBashTool;
+}
 /**
- * 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.
+ * Creates Pi read, edit, and write tools over one filesystem, sharing one
+ * digest, lock manager, and clock, and the read state when `state` is given.
+ * With `applyPatch`, also apply_patch. With `bash`, also bash, with the same
+ * digest and clock. Every option and default is the one of createFsTools().
+ * Throws TypeError where createFsTools() does, with createPiFsTools in the
+ * message.
  */
-export declare function createPiFsTools(options: CreatePiFsToolsOptions & {
-    readonly applyPatch: true | Omit<CreatePiApplyPatchToolOptions, BundleSharedKey>;
+export declare function createPiFsTools(options: PiFsToolsOptions & {
+    readonly applyPatch: true | PiFsToolsApplyPatchOptions;
+    readonly bash: PiFsToolsBashOptions;
+}): PiFsToolsWithApplyPatch & PiFsToolsWithBash;
+export declare function createPiFsTools(options: PiFsToolsOptions & {
+    readonly bash: PiFsToolsBashOptions;
+}): PiFsToolsWithBash;
+export declare function createPiFsTools(options: PiFsToolsOptions & {
+    readonly applyPatch: true | PiFsToolsApplyPatchOptions;
 }): PiFsToolsWithApplyPatch;
-export declare function createPiFsTools(options?: CreatePiFsToolsOptions): PiFsTools;
+export declare function createPiFsTools(options: PiFsToolsOptions): PiFsTools;
 export {};

package/dist/fs-tools.js

@@ -1,93 +1,38 @@
-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 } }),
-    });
+import { fsToolDefinitions } from "@better-fs-tools/write/signature";
+import { adaptPiBashTool } from "./bash-tool.js";
+import { adaptPiMutationTool } from "./mutation-tools.js";
+import { checkPiOptions, splitPrompt } from "./prompt.js";
+import { adaptPiReadTool } from "./tool.js";
+export function createPiFsTools(options) {
+    checkPiOptions(options, "createPiFsTools");
+    const read = splitPrompt(options.read ?? {});
+    const edit = splitPrompt(options.edit ?? {});
+    const write = splitPrompt(options.write ?? {});
+    const applyPatch = isObject(options.applyPatch) ? splitPrompt(options.applyPatch) : null;
+    const bash = isObject(options.bash) ? splitPrompt(options.bash) : null;
+    const defs = fsToolDefinitions({
+        ...options,
+        ...(options.read === undefined ? {} : { read: read.rest }),
+        ...(options.edit === undefined ? {} : { edit: edit.rest }),
+        ...(options.write === undefined ? {} : { write: write.rest }),
+        ...(applyPatch === null ? {} : { applyPatch: applyPatch.rest }),
+        ...(bash === null ? {} : { bash: bash.rest }),
+    }, "createPiFsTools");
     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
+        read: adaptPiReadTool(defs.read, read.prompt),
+        edit: adaptPiMutationTool("edit", defs.edit, edit.prompt),
+        write: adaptPiMutationTool("write", defs.write, write.prompt),
+        applyPatch: defs.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),
+            : adaptPiMutationTool("apply_patch", defs.applyPatch, applyPatch?.prompt ?? {}),
+        bash: defs.bash === null ? null : adaptPiBashTool(defs.bash, bash?.prompt ?? {}),
+        state: defs.state,
+        digest: defs.digest,
+        locks: defs.locks,
+        clock: defs.clock,
+        invalidate: defs.invalidate,
     });
 }
-function isReadStateStore(value) {
-    if (value === null || typeof value !== "object")
-        return false;
-    const store = value;
-    return ["get", "put", "delete"].every((key) => typeof store[key] === "function");
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/dist/index.d.ts

@@ -1,12 +1,17 @@
 export { createPiBashTool } from "./bash-tool.ts";
-export type { CreatePiBashToolOptions, PiBashDetails, PiBashTool, PiBashToolResult, } from "./bash-tool.ts";
+export type { PiBashDetails, PiBashTool, PiBashToolOptions, 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 type { PiFsTools, PiFsToolsApplyPatchOptions, PiFsToolsBashOptions, PiFsToolsEditOptions, PiFsToolsOptions, PiFsToolsReadOptions, PiFsToolsWithApplyPatch, PiFsToolsWithBash, PiFsToolsWriteOptions, } from "./fs-tools.ts";
+export { piMutationQueueLocks } from "./locks.ts";
+export type { PiMutationQueueLocksOptions } from "./locks.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 type { PiApplyPatchToolOptions, PiEditToolOptions, PiMutationTool, PiMutationToolResult, PiWriteToolOptions, } from "./mutation-tools.ts";
+export type { PiPromptOptions } from "./prompt.ts";
+export { piToolRenderers } from "./renderers.ts";
+export type { PiToolAnnotations } from "./results.ts";
 export { createPiReadTool } from "./tool.ts";
-export type { CreatePiReadToolOptions, PiContentPart, PiReadTool, PiReadToolResult, } from "./tool.ts";
+export type { PiContentPart, PiReadTool, PiReadToolOptions, PiReadToolResult } from "./tool.ts";

package/dist/index.js

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

package/dist/locks.d.ts

@@ -0,0 +1,16 @@
+import type { LockManager } from "@better-fs-tools/write";
+export interface PiMutationQueueLocksOptions {
+    /** How long acquire() waits for every key. Default 30 000. */
+    readonly timeoutMs?: number;
+}
+/**
+ * A lock manager on Pi's withFileMutationQueue(), the per-file queue of Pi's
+ * own edit and write. A Better FS Tools edit and a Pi tool that change the same
+ * file then wait for each other. The keys are the resolved paths that the
+ * write tools pass, which are the real paths that Pi's queue uses.
+ *
+ * A caller takes the keys one after another in sorted order, inside one queue
+ * slot each. On a timeout or an abort the outcome comes at once, and the slots
+ * that the caller got later are given back as soon as they arrive.
+ */
+export declare function piMutationQueueLocks(options?: PiMutationQueueLocksOptions): LockManager;

package/dist/locks.js

@@ -0,0 +1,68 @@
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * A lock manager on Pi's withFileMutationQueue(), the per-file queue of Pi's
+ * own edit and write. A Better FS Tools edit and a Pi tool that change the same
+ * file then wait for each other. The keys are the resolved paths that the
+ * write tools pass, which are the real paths that Pi's queue uses.
+ *
+ * A caller takes the keys one after another in sorted order, inside one queue
+ * slot each. On a timeout or an abort the outcome comes at once, and the slots
+ * that the caller got later are given back as soon as they arrive.
+ */
+export function piMutationQueueLocks(options = {}) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("piMutationQueueLocks options must be an object");
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new TypeError("timeoutMs must be a positive safe integer");
+    }
+    return Object.freeze({
+        id: "pi-file-mutation-queue",
+        acquire: (keys, { signal } = {}) => acquire(keys, signal, timeoutMs),
+    });
+}
+function acquire(keys, signal, timeoutMs) {
+    if (signal?.aborted)
+        return Promise.resolve({ ok: false, reason: "aborted" });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (finish) => {
+            if (settled)
+                return false;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            finish();
+            return true;
+        };
+        const timer = setTimeout(() => settle(() => resolve({ ok: false, reason: "timeout" })), timeoutMs);
+        const onAbort = () => settle(() => resolve({ ok: false, reason: "aborted" }));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        // Each key's queue slot stays taken until the slot callback returns. The
+        // innermost callback holds every slot until release() resolves `held`.
+        let release = () => { };
+        const held = new Promise((done) => {
+            release = done;
+        });
+        const hold = (index) => {
+            if (index < keys.length) {
+                return withFileMutationQueue(keys[index], () => hold(index + 1));
+            }
+            let released = false;
+            const granted = settle(() => resolve({
+                ok: true,
+                release() {
+                    if (released)
+                        return;
+                    released = true;
+                    release();
+                },
+            }));
+            // After a timeout or an abort, give the slots back at once.
+            return granted ? held : Promise.resolve();
+        };
+        hold(0).catch((error) => settle(() => reject(error)));
+    });
+}