@better-fs-tools/pi 0.2.0 → 0.3.0

package/dist/tool.d.ts

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

package/dist/tool.js

@@ -1,89 +1,40 @@
 import { Type } from "typebox";
-import { nodeDigest } from "@better-fs-tools/node";
-import { createReadTool, imageConverter, lineNumberFormatter, resolveReadLimits, } from "@better-fs-tools/read";
-import { defaultReadSignature, readSignatureMessages } from "@better-fs-tools/read/signature";
-import { toPiReadDetails } from "./details.js";
+import { readToolDefinition } from "@better-fs-tools/read/signature";
+import { toPiReadDetails, viewOf } from "./details.js";
 import { toPiPart } from "./parts.js";
-import { checkPiContext, checkPiOptions, piFileSystems } from "./roots.js";
-const PI_BUILTIN_READ_SNIPPET = "Read file contents";
-const PI_BUILTIN_READ_GUIDELINES = [
-    "Use read to examine files instead of cat or sed.",
-];
+import { checkPiOptions, piPrompt, splitPrompt } from "./prompt.js";
+import { canonicalArgs, setRenderArgs } from "./renderers.js";
+import { PI_READ_ANNOTATIONS } from "./results.js";
 /**
- * Creates a Pi read tool rooted at each call's ctx.cwd. Throws TypeError when
- * options set fs, cwd, or allowedRoots. It keeps no read state by default and
- * writes nothing outside the process. An image becomes a Pi image part unless
- * options.converters leaves imageConverter() out.
+ * Creates a Pi read tool with the options and defaults of createReadTool().
+ * The call's host is the Pi extension context.
  */
-export function createPiReadTool(options = {}) {
-    checkPiOptions(options, "read");
-    const { denyRoots, symlinks, signature: _signature, promptSnippet: _promptSnippet, promptGuidelines: _promptGuidelines, ...deps } = options;
-    const parts = piReadParts(options);
-    const fs = piFileSystems({ denyRoots, symlinks });
-    // digest: null narrows the options to the branch without a state.
-    if (deps.digest === null) {
-        const read = createReadTool({ ...deps, ...piReadDeps(parts), fs, digest: null });
-        return adaptPiReadTool(parts, read, null);
-    }
-    const digest = deps.digest ?? nodeDigest();
-    const read = createReadTool({ ...deps, ...piReadDeps(parts), fs, digest });
-    return adaptPiReadTool(parts, read, digest);
+export function createPiReadTool(options) {
+    checkPiOptions(options, "Pi read tool");
+    const { prompt, rest } = splitPrompt(options);
+    return adaptPiReadTool(readToolDefinition(rest), prompt);
 }
-export function piReadParts(options) {
-    const signature = options.signature ?? defaultReadSignature({ name: "read" });
-    return {
-        signature,
-        promptSnippet: options.promptSnippet ?? PI_BUILTIN_READ_SNIPPET,
-        promptGuidelines: options.promptGuidelines ?? PI_BUILTIN_READ_GUIDELINES,
-        limits: resolveReadLimits(options.limits),
-        formatter: options.formatter ?? lineNumberFormatter(),
-        messages: { ...readSignatureMessages(signature), ...options.messages },
-        // Pi's own read returns images, so the Pi host turns them on.
-        converters: options.converters ?? [imageConverter()],
-    };
-}
-export function piReadDeps(parts) {
-    return {
-        limits: parts.limits,
-        formatter: parts.formatter,
-        messages: parts.messages,
-        converters: parts.converters,
-    };
-}
-export function adaptPiReadTool(parts, read, digest) {
-    const { signature, promptSnippet, promptGuidelines, limits, formatter } = parts;
-    return Object.freeze({
-        name: signature.name,
-        label: signature.name,
-        description: signature.description,
-        promptSnippet,
-        promptGuidelines: [...promptGuidelines],
-        parameters: Type.Unsafe(signature.schema),
+export function adaptPiReadTool(definition, prompt) {
+    const { signature, limits, formatter, digest } = definition;
+    const tool = Object.freeze({
+        name: definition.name,
+        label: definition.name,
+        description: definition.description,
+        ...piPrompt(prompt, definition.description),
+        parameters: Type.Unsafe(definition.inputSchema),
+        annotations: { ...PI_READ_ANNOTATIONS },
         async execute(toolCallId, input, signal, _onUpdate, ctx) {
-            checkPiContext(ctx, "read");
             const call = {
                 ...(signal === undefined ? {} : { signal }),
                 callId: toolCallId,
                 host: ctx,
             };
-            const result = await read(signature.toInput(input), call);
-            return {
-                content: result.content.map((part) => toPiPart(part, "read")),
-                details: toPiReadDetails(result, viewOf(formatter, result, { digest, limits, mode: "view", call }), limits.maxViewBytes),
-            };
+            const result = await definition.execute(input, call);
+            const content = result.content.map((part) => toPiPart(part, "read"));
+            const details = toPiReadDetails(result, viewOf(formatter, result, { digest, limits, mode: "view", call }), limits.maxViewBytes);
+            return { content, details, isError: result.status === "error" };
         },
     });
-}
-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;
-    }
+    setRenderArgs(tool, (args) => signature.toInput(args), canonicalArgs);
+    return tool;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-fs-tools/pi",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The Better FS Tools read, edit, write, apply_patch, and bash tools and extension for the Pi coding agent.",
   "license": "MIT",
   "repository": {
@@ -18,9 +18,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./agent-core": {
+      "types": "./dist/agent-core.d.ts",
+      "import": "./dist/agent-core.js"
+    },
     "./extension": {
       "types": "./dist/extension.d.ts",
       "import": "./dist/extension.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
     }
   },
   "publishConfig": {
@@ -29,9 +37,17 @@
         "types": "./dist/index.d.ts",
         "import": "./dist/index.js"
       },
+      "./agent-core": {
+        "types": "./dist/agent-core.d.ts",
+        "import": "./dist/agent-core.js"
+      },
       "./extension": {
         "types": "./dist/extension.d.ts",
         "import": "./dist/extension.js"
+      },
+      "./node": {
+        "types": "./dist/node.d.ts",
+        "import": "./dist/node.js"
       }
     },
     "access": "public",
@@ -42,18 +58,19 @@
     }
   },
   "dependencies": {
-    "@better-fs-tools/node": "^0.2.0",
-    "@better-fs-tools/read": "^0.2.0",
-    "@better-fs-tools/shell": "^0.2.0",
-    "@better-fs-tools/write": "^0.2.0"
+    "@better-fs-tools/node": "^0.3.0",
+    "@better-fs-tools/read": "^0.3.0",
+    "@better-fs-tools/shell": "^0.3.0",
+    "@better-fs-tools/write": "^0.3.0"
   },
   "devDependencies": {
-    "@better-fs-tools/fs": "^0.2.0",
-    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@better-fs-tools/fs": "^0.3.0",
+    "@earendil-works/pi-agent-core": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
     "typebox": "^1.3.16"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
     "typebox": "^1.3.16"
   },
   "engines": {

package/dist/roots.d.ts

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

package/dist/roots.js

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