@better-fs-tools/pi 0.2.0 → 0.3.0

package/dist/mutation-tools.d.ts

@@ -1,32 +1,28 @@
 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 { JsonObject } from "@better-fs-tools/read";
+import type { ApplyPatchToolDefinitionOptions, EditToolDefinitionOptions, MutationToolDefinition, WriteToolDefinitionOptions } 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[];
-}
+import type { PiPromptOptions } from "./prompt.ts";
+import type { PiToolAnnotations } from "./results.ts";
+type Host = ExtensionContext;
 /**
- * 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.
+ * Options for createPiEditTool: the options of editToolDefinition(), with the
+ * Pi extension context as host, plus the Pi prompt options. `fs` is required.
  */
-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 type PiEditToolOptions = EditToolDefinitionOptions<Host> & PiPromptOptions;
+/** As PiEditToolOptions, for write. */
+export type PiWriteToolOptions = WriteToolDefinitionOptions<Host> & PiPromptOptions;
+/** As PiEditToolOptions, for apply_patch. */
+export type PiApplyPatchToolOptions = ApplyPatchToolDefinitionOptions<Host> & PiPromptOptions;
 export interface PiMutationToolResult {
     content: PiContentPart[];
     details: PiMutationDetails | undefined;
+    /** true when the change failed (status "error"). Pi then shows the content as an error. */
+    isError: boolean;
 }
-/** Assignable to ToolDefinition<TSchema, PiMutationDetails | undefined> from Pi 0.84.2. */
+/** Assignable to ToolDefinition<TSchema, PiMutationDetails | undefined> from Pi 1.x. */
 export interface PiMutationTool {
     readonly name: string;
     readonly label: string;
@@ -42,31 +38,22 @@ export interface PiMutationTool {
             openai_lark: string;
         };
     };
+    /** destructiveHint: true. idempotentHint is true for write only. */
+    readonly annotations: PiToolAnnotations;
     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;
+export type PiMutationKind = "edit" | "write" | "apply_patch";
+/** Creates a Pi edit tool with the options and defaults of createEditTool(). */
+export declare function createPiEditTool(options: PiEditToolOptions): PiMutationTool;
+/**
+ * Creates a Pi write tool with the options and defaults of createWriteTool().
+ * `details` is always undefined, as for Pi's own write.
+ */
+export declare function createPiWriteTool(options: PiWriteToolOptions): PiMutationTool;
 /**
- * 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.
+ * Creates a Pi apply_patch tool with the options and defaults of
+ * createApplyPatchTool(). A signature with a grammar sets constrainedSampling.
  */
-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 declare function createPiApplyPatchTool(options: PiApplyPatchToolOptions): PiMutationTool;
+export declare function adaptPiMutationTool<TInput>(kind: PiMutationKind, definition: MutationToolDefinition<TInput, Host>, prompt: PiPromptOptions): PiMutationTool;
 export {};

package/dist/mutation-tools.js

@@ -1,117 +1,66 @@
 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 { applyPatchToolDefinition, editToolDefinition, writeToolDefinition, } 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 },
-    };
+import { checkPiOptions, piPrompt, splitPrompt } from "./prompt.js";
+import { canonicalArgs, piEditArgs, setRenderArgs } from "./renderers.js";
+import { PI_PATCH_ANNOTATIONS, PI_WRITE_ANNOTATIONS } from "./results.js";
+/** Creates a Pi edit tool with the options and defaults of createEditTool(). */
+export function createPiEditTool(options) {
+    checkPiOptions(options, "Pi edit tool");
+    const { prompt, rest } = splitPrompt(options);
+    return adaptPiMutationTool("edit", editToolDefinition(rest), prompt);
 }
 /**
- * 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.
+ * Creates a Pi write tool with the options and defaults of createWriteTool().
+ * `details` is always undefined, as for Pi's own write.
  */
-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 }));
+export function createPiWriteTool(options) {
+    checkPiOptions(options, "Pi write tool");
+    const { prompt, rest } = splitPrompt(options);
+    return adaptPiMutationTool("write", writeToolDefinition(rest), prompt);
 }
-/** 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 }));
+/**
+ * Creates a Pi apply_patch tool with the options and defaults of
+ * createApplyPatchTool(). A signature with a grammar sets constrainedSampling.
+ */
+export function createPiApplyPatchTool(options) {
+    checkPiOptions(options, "Pi apply_patch tool");
+    const { prompt, rest } = splitPrompt(options);
+    return adaptPiMutationTool("apply_patch", applyPatchToolDefinition(rest), prompt);
 }
-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),
+export function adaptPiMutationTool(kind, definition, prompt) {
+    const { grammar, signature } = definition;
+    const adapted = Object.freeze({
+        name: definition.name,
+        label: definition.name,
+        description: definition.description,
+        ...piPrompt(prompt, definition.description),
+        parameters: Type.Unsafe(definition.inputSchema),
+        annotations: { ...(kind === "write" ? PI_WRITE_ANNOTATIONS : PI_PATCH_ANNOTATIONS) },
         ...(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);
+            const result = await definition.execute(input, call);
             return {
-                content: result.content.map((part) => toPiPart(part, toolName)),
-                details: withDetails ? toPiMutationDetails(result) : undefined,
+                content: result.content.map((part) => toPiPart(part, kind)),
+                details: kind === "write" ? undefined : toPiMutationDetails(result),
+                isError: result.status === "error",
             };
         },
     });
+    // Pi has built-in renderers for edit and write. apply_patch has none.
+    if (kind !== "apply_patch") {
+        const toPi = kind === "edit" ? piEditArgs : canonicalArgs;
+        setRenderArgs(adapted, (args) => signature.toInput(args), toPi);
+    }
+    return adapted;
 }

package/dist/node.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { NodeCommandRunnerOptions, NodeFileSystem, NodeFileSystemOptions } from "@better-fs-tools/node";
+import type { ToolCallContext } from "@better-fs-tools/read";
+import type { CommandRunner } from "@better-fs-tools/shell";
+/** The options of nodeFileSystem() without `cwd` and `allowedRoots`: the root is always ctx.cwd. */
+export type PiCwdFileSystemOptions = Omit<NodeFileSystemOptions, "cwd" | "allowedRoots">;
+/** The options of nodeCommandRunner() without `cwd`: commands run in ctx.cwd. */
+export type PiCwdCommandRunnerOptions = Omit<NodeCommandRunnerOptions, "cwd">;
+/** A factory of the call, as the `fs` and `runner` options of a tool take. */
+export type PiCallFactory<T> = (call: ToolCallContext<ExtensionContext>) => T;
+/**
+ * A per-call filesystem: nodeFileSystem() with `cwd` and `allowedRoots` set to
+ * the call's ctx.cwd. It keeps the filesystems of the last 8 roots. The
+ * factory throws TypeError when ctx.cwd is missing or empty, and when
+ * `options` sets `cwd` or `allowedRoots`.
+ */
+export declare function piCwdFileSystem(options?: PiCwdFileSystemOptions): PiCallFactory<NodeFileSystem>;
+/**
+ * A per-call runner: nodeCommandRunner() at the call's ctx.cwd. It keeps the
+ * runners of the last 8 directories used. The factory throws TypeError when
+ * ctx.cwd is not an absolute path, and when `options` sets `cwd`.
+ */
+export declare function piCwdCommandRunner(options?: PiCwdCommandRunnerOptions): PiCallFactory<CommandRunner>;

package/dist/node.js

@@ -0,0 +1,76 @@
+/**
+ * The `./node` subpath: Node backends for a Pi tool, rooted at each call's
+ * ctx.cwd. Pass `fs: piCwdFileSystem()` to a Pi file tool, and
+ * `runner: piCwdCommandRunner()` to createPiBashTool(). The main entry does
+ * not import Node.
+ */
+import path from "node:path";
+import { nodeCommandRunner, nodeFileSystem } from "@better-fs-tools/node";
+const MAX_CACHED = 8;
+/**
+ * A per-call filesystem: nodeFileSystem() with `cwd` and `allowedRoots` set to
+ * the call's ctx.cwd. It keeps the filesystems of the last 8 roots. The
+ * factory throws TypeError when ctx.cwd is missing or empty, and when
+ * `options` sets `cwd` or `allowedRoots`.
+ */
+export function piCwdFileSystem(options = {}) {
+    checkOptions(options, "piCwdFileSystem", ["cwd", "allowedRoots"]);
+    const cache = new Map();
+    return (call) => {
+        const root = path.resolve(cwdOf(call, "piCwdFileSystem"));
+        const cached = cache.get(root);
+        if (cached !== undefined)
+            return cached;
+        const fs = nodeFileSystem({ ...options, cwd: root, allowedRoots: [root] });
+        if (cache.size >= MAX_CACHED) {
+            const oldest = cache.keys().next();
+            if (!oldest.done)
+                cache.delete(oldest.value);
+        }
+        cache.set(root, fs);
+        return fs;
+    };
+}
+/**
+ * A per-call runner: nodeCommandRunner() at the call's ctx.cwd. It keeps the
+ * runners of the last 8 directories used. The factory throws TypeError when
+ * ctx.cwd is not an absolute path, and when `options` sets `cwd`.
+ */
+export function piCwdCommandRunner(options = {}) {
+    checkOptions(options, "piCwdCommandRunner", ["cwd"]);
+    const cache = new Map();
+    return (call) => {
+        const cwd = cwdOf(call, "piCwdCommandRunner");
+        if (!path.isAbsolute(cwd)) {
+            throw new TypeError("piCwdCommandRunner needs an absolute ctx.cwd");
+        }
+        const cached = cache.get(cwd);
+        if (cached !== undefined) {
+            cache.delete(cwd);
+            cache.set(cwd, cached);
+            return cached;
+        }
+        const made = nodeCommandRunner({ ...options, cwd });
+        cache.set(cwd, made);
+        if (cache.size > MAX_CACHED)
+            cache.delete(cache.keys().next().value);
+        return made;
+    };
+}
+function cwdOf(call, label) {
+    const cwd = call?.host?.cwd;
+    if (typeof cwd !== "string" || cwd === "") {
+        throw new TypeError(`${label} needs ctx.cwd: pass the Pi extension context as the host`);
+    }
+    return cwd;
+}
+function checkOptions(options, label, refused) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError(`${label} options must be an object`);
+    }
+    for (const key of refused) {
+        if (Object.hasOwn(options, key)) {
+            throw new TypeError(`${label} options cannot set ${key}: the root is ctx.cwd on every call`);
+        }
+    }
+}

package/dist/parts.js

@@ -1,4 +1,5 @@
-import { Buffer } from "node:buffer";
+// Keeps each String.fromCharCode spread under engine argument-count limits.
+const CHUNK = 0x8000;
 export function toPiPart(part, tool) {
     switch (part.type) {
         case "text":
@@ -11,10 +12,14 @@ export function toPiPart(part, tool) {
                     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,
-            };
+            return { type: "image", data: toBase64(part.data), mimeType: part.mediaType };
     }
 }
+/** Base64 without node:buffer, so the agent core tools run in a browser or a Worker. */
+function toBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.byteLength; offset += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + CHUNK));
+    }
+    return btoa(binary);
+}

package/dist/prompt.d.ts

@@ -0,0 +1,30 @@
+/** Pi prompt options of every Pi tool. */
+export interface PiPromptOptions {
+    /** Default the first sentence of the signature description. Pi lists the tool with it. */
+    readonly promptSnippet?: string;
+    /** Default []. */
+    readonly promptGuidelines?: readonly string[];
+}
+/** The prompt options of a Pi tool, with their defaults applied. */
+export interface PiPrompt {
+    readonly promptSnippet: string;
+    readonly promptGuidelines: string[];
+}
+/** Applies the defaults of the prompt options for a tool with this description. */
+export declare function piPrompt(options: PiPromptOptions, description: string): PiPrompt;
+/** Omit for each member of a union, so the state and digest pairing stays. */
+type WithoutPrompt<T> = T extends unknown ? Omit<T, keyof PiPromptOptions> : never;
+/** Splits the prompt options off a Pi tool's options. */
+export declare function splitPrompt<T extends PiPromptOptions>(options: T): {
+    readonly prompt: PiPromptOptions;
+    readonly rest: WithoutPrompt<T>;
+};
+/**
+ * The default Pi promptSnippet of a tool: the first sentence of its signature
+ * description, without the full stop. Pi lists a custom tool under "Available
+ * tools" only when it has a snippet, so every Pi tool gets one. The text comes
+ * from the shared signature, so each integration describes the tool the same way.
+ */
+export declare function signatureSnippet(description: string): string;
+export declare function checkPiOptions(options: unknown, label: string): void;
+export {};

package/dist/prompt.js

@@ -0,0 +1,35 @@
+/** Applies the defaults of the prompt options for a tool with this description. */
+export function piPrompt(options, description) {
+    return {
+        promptSnippet: options.promptSnippet ?? signatureSnippet(description),
+        promptGuidelines: [...(options.promptGuidelines ?? [])],
+    };
+}
+/** Splits the prompt options off a Pi tool's options. */
+export function splitPrompt(options) {
+    const { promptSnippet, promptGuidelines, ...rest } = options;
+    return {
+        prompt: {
+            ...(promptSnippet === undefined ? {} : { promptSnippet }),
+            ...(promptGuidelines === undefined ? {} : { promptGuidelines }),
+        },
+        rest: rest,
+    };
+}
+/**
+ * The default Pi promptSnippet of a tool: the first sentence of its signature
+ * description, without the full stop. Pi lists a custom tool under "Available
+ * tools" only when it has a snippet, so every Pi tool gets one. The text comes
+ * from the shared signature, so each integration describes the tool the same way.
+ */
+export function signatureSnippet(description) {
+    const text = description.trim();
+    const end = /\.(\s|$)/u.exec(text);
+    const sentence = end === null ? text.split("\n", 1)[0] : text.slice(0, end.index);
+    return sentence.trim();
+}
+export function checkPiOptions(options, label) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError(`${label} options must be an object`);
+    }
+}

package/dist/renderers.d.ts

@@ -0,0 +1,27 @@
+import type { ToolRendererResolver } from "@earendil-works/pi-coding-agent";
+/** Turns the model's arguments into the arguments that Pi's built-in renderer of the tool reads. */
+type RenderArgs = (args: unknown) => unknown;
+/** Records how a tool's arguments map to the arguments of Pi's built-in renderer of the same name. */
+export declare function setRenderArgs(tool: object, toInput: (args: unknown) => unknown, toPi: RenderArgs): void;
+/** Pi's read and write renderers read path, offset, limit, and content: the canonical names. */
+export declare function canonicalArgs(input: unknown): unknown;
+/**
+ * Pi's edit renderer reads { path, edits: [{ oldText, newText }] }, the
+ * canonical edit input. It cannot show a replace-all edit, so then it gets
+ * only the path and shows the diff of the result.
+ */
+export declare function piEditArgs(input: unknown): unknown;
+/** Pi's bash renderer shows `timeout` in seconds. */
+export declare function piBashArgs(input: unknown): unknown;
+/**
+ * A Pi tool renderer resolver for Better FS Tools. A tool named read, edit,
+ * write, or bash gets Pi's built-in renderer of that name. That renderer reads
+ * Pi's own argument names. This resolver gives it the arguments in those names,
+ * so it draws the call for any signature: the edit preview, the read range, and
+ * the bash timeout. Register it with pi.registerToolRenderer(). The extension
+ * entry does this for its own tools.
+ */
+export declare function piToolRenderers(tools: Iterable<{
+    readonly name: string;
+}>): ToolRendererResolver;
+export {};

package/dist/renderers.js

@@ -0,0 +1,72 @@
+const RENDER_ARGS = new WeakMap();
+/** Records how a tool's arguments map to the arguments of Pi's built-in renderer of the same name. */
+export function setRenderArgs(tool, toInput, toPi) {
+    RENDER_ARGS.set(tool, (args) => {
+        try {
+            return toPi(toInput(args));
+        }
+        catch {
+            // Arguments that stream in, or that are not valid, go to the renderer as they are.
+            return args;
+        }
+    });
+}
+/** Pi's read and write renderers read path, offset, limit, and content: the canonical names. */
+export function canonicalArgs(input) {
+    return input;
+}
+/**
+ * Pi's edit renderer reads { path, edits: [{ oldText, newText }] }, the
+ * canonical edit input. It cannot show a replace-all edit, so then it gets
+ * only the path and shows the diff of the result.
+ */
+export function piEditArgs(input) {
+    const { path, edits } = input;
+    if (edits.some((edit) => edit.replaceAll === true))
+        return { path };
+    return { path, edits: edits.map(({ oldText, newText }) => ({ oldText, newText })) };
+}
+/** Pi's bash renderer shows `timeout` in seconds. */
+export function piBashArgs(input) {
+    const { command, timeoutMs } = input;
+    return timeoutMs === undefined ? { command } : { command, timeout: timeoutMs / 1_000 };
+}
+/**
+ * A Pi tool renderer resolver for Better FS Tools. A tool named read, edit,
+ * write, or bash gets Pi's built-in renderer of that name. That renderer reads
+ * Pi's own argument names. This resolver gives it the arguments in those names,
+ * so it draws the call for any signature: the edit preview, the read range, and
+ * the bash timeout. Register it with pi.registerToolRenderer(). The extension
+ * entry does this for its own tools.
+ */
+export function piToolRenderers(tools) {
+    const byName = new Map();
+    for (const tool of tools) {
+        const renderArgs = RENDER_ARGS.get(tool);
+        if (renderArgs !== undefined)
+            byName.set(tool.name, renderArgs);
+    }
+    return (toolName, next) => {
+        const base = next();
+        const renderArgs = byName.get(toolName);
+        if (base === undefined || renderArgs === undefined)
+            return base;
+        return withArgs(base, renderArgs);
+    };
+}
+function withArgs(base, renderArgs) {
+    const { renderCall, renderResult } = base;
+    return {
+        ...base,
+        ...(renderCall === undefined
+            ? {}
+            : {
+                renderCall: (args, theme, context) => renderCall(renderArgs(args), theme, { ...context, args: renderArgs(context.args) }),
+            }),
+        ...(renderResult === undefined
+            ? {}
+            : {
+                renderResult: (result, options, theme, context) => renderResult(result, options, theme, { ...context, args: renderArgs(context.args) }),
+            }),
+    };
+}

package/dist/results.d.ts

@@ -0,0 +1,13 @@
+/** Pi's ToolAnnotations: MCP tool hints that permission extensions read. */
+export interface PiToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** read changes nothing. */
+export declare const PI_READ_ANNOTATIONS: Readonly<PiToolAnnotations>;
+/** edit and apply_patch can replace or remove file content, and a second run is not a no-op. */
+export declare const PI_PATCH_ANNOTATIONS: Readonly<PiToolAnnotations>;
+/** write replaces a whole file. The same call twice gives the same file. */
+export declare const PI_WRITE_ANNOTATIONS: Readonly<PiToolAnnotations>;

package/dist/results.js

@@ -0,0 +1,18 @@
+/** read changes nothing. */
+export const PI_READ_ANNOTATIONS = Object.freeze({
+    readOnlyHint: true,
+});
+/** edit and apply_patch can replace or remove file content, and a second run is not a no-op. */
+export const PI_PATCH_ANNOTATIONS = Object.freeze({
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+});
+/** write replaces a whole file. The same call twice gives the same file. */
+export const PI_WRITE_ANNOTATIONS = Object.freeze({
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+});