@aliou/pi-dev-kit 0.5.0 → 0.6.1

package/src/tools/docs-tool.ts

@@ -13,19 +13,15 @@ import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { findPiInstallation } from "./utils";
 
-const DocsParams = Type.Object({});
-type DocsParamsType = Record<string, never>;
+const DocsParamsSchema = Type.Object({});
+type DocsParams = Record<string, never>;
 
 interface DocsDetails {
-  success: boolean;
-  message: string;
   /** Relative paths from the pi install root, markdown only. */
   docFiles?: string[];
   installPath?: string;
 }
 
-type ExecuteResult = AgentToolResult<DocsDetails>;
-
 function listFilesRecursive(dir: string, prefix = ""): string[] {
   const results: string[] = [];
   if (!fs.existsSync(dir)) return results;
@@ -43,108 +39,78 @@ function listFilesRecursive(dir: string, prefix = ""): string[] {
 }
 
 export function setupDocsTool(pi: ExtensionAPI) {
-  pi.registerTool<typeof DocsParams, DocsDetails>({
+  pi.registerTool<typeof DocsParamsSchema, DocsDetails>({
     name: "pi_docs",
     label: "Pi Documentation",
     description:
       "List Pi markdown documentation files (README, docs/, examples/)",
 
-    parameters: DocsParams,
+    promptSnippet: "List Pi documentation files",
+    promptGuidelines: [
+      "Use to discover available Pi documentation",
+      "Returns markdown files from README.md, docs/, and examples/",
+    ],
+
+    parameters: DocsParamsSchema,
 
     async execute(
       _toolCallId: string,
-      _params: DocsParamsType,
+      _params: DocsParams,
       _signal: AbortSignal | undefined,
       _onUpdate: unknown,
       _ctx: ExtensionContext,
-    ): Promise<ExecuteResult> {
-      try {
-        const piPath = findPiInstallation();
-        if (!piPath) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Could not locate running Pi installation directory",
-              },
-            ],
-            details: {
-              success: false,
-              message: "Could not locate running Pi installation directory",
-            },
-          };
-        }
+    ): Promise<AgentToolResult<DocsDetails>> {
+      const piPath = findPiInstallation();
+      if (!piPath) {
+        throw new Error("Could not locate running Pi installation directory");
+      }
 
-        const readmePath = path.join(piPath, "README.md");
-        const docsDir = path.join(piPath, "docs");
-        const examplesDir = path.join(piPath, "examples");
+      const readmePath = path.join(piPath, "README.md");
+      const docsDir = path.join(piPath, "docs");
+      const examplesDir = path.join(piPath, "examples");
 
-        const docFiles: string[] = [];
+      const docFiles: string[] = [];
 
-        if (fs.existsSync(readmePath)) {
-          docFiles.push("README.md");
-        }
+      if (fs.existsSync(readmePath)) {
+        docFiles.push("README.md");
+      }
 
-        if (fs.existsSync(docsDir)) {
-          for (const file of listFilesRecursive(docsDir)) {
-            if (file.endsWith(".md")) {
-              docFiles.push(`docs/${file}`);
-            }
+      if (fs.existsSync(docsDir)) {
+        for (const file of listFilesRecursive(docsDir)) {
+          if (file.endsWith(".md")) {
+            docFiles.push(`docs/${file}`);
           }
         }
+      }
 
-        if (fs.existsSync(examplesDir)) {
-          for (const file of listFilesRecursive(examplesDir)) {
-            if (file.endsWith(".md")) {
-              docFiles.push(`examples/${file}`);
-            }
+      if (fs.existsSync(examplesDir)) {
+        for (const file of listFilesRecursive(examplesDir)) {
+          if (file.endsWith(".md")) {
+            docFiles.push(`examples/${file}`);
           }
         }
+      }
 
-        if (docFiles.length === 0) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `No markdown documentation found in Pi installation`,
-              },
-            ],
-            details: {
-              success: false,
-              message: `No markdown documentation found in Pi installation`,
-              installPath: piPath,
-            },
-          };
-        }
-
-        // Content sent to LLM: full relative paths so it can read them.
-        const lines = docFiles.map(
-          (rel) => `${path.join(piPath, rel)} (${rel})`,
+      if (docFiles.length === 0) {
+        throw new Error(
+          `No markdown documentation found in Pi installation at ${piPath}`,
         );
-        const message = `${docFiles.length} markdown files:\n${lines.join("\n")}`;
-
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            success: true,
-            message: `Found ${docFiles.length} markdown files`,
-            docFiles,
-            installPath: piPath,
-          },
-        };
-      } catch (error) {
-        const message = `Error reading Pi documentation: ${error instanceof Error ? error.message : String(error)}`;
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            success: false,
-            message,
-          },
-        };
       }
+
+      // Content sent to LLM: full relative paths so it can read them.
+      const lines = docFiles.map((rel) => `${path.join(piPath, rel)} (${rel})`);
+      const message = `${docFiles.length} markdown files:\n${lines.join("\n")}`;
+
+      return {
+        content: [{ type: "text", text: message }],
+        details: {
+          docFiles,
+          installPath: piPath,
+        },
+      };
     },
 
-    renderCall(_args: DocsParamsType, theme: Theme) {
+    renderCall(_args: DocsParams, theme: Theme) {
       return new ToolCallHeader({ toolName: "Pi Docs" }, theme);
     },
 
@@ -154,8 +120,15 @@ export function setupDocsTool(pi: ExtensionAPI) {
       theme: Theme,
     ) {
       const { details } = result;
+      const { isPartial } = options;
+
+      // Handle isPartial first (this tool doesn't stream, but keep the pattern)
+      if (isPartial) {
+        return new Text(theme.fg("dim", "Loading..."), 0, 0);
+      }
 
-      if (!details) {
+      // Check for missing expected fields in details to detect errors
+      if (!details || !details.docFiles) {
         const text = result.content[0];
         return new Text(
           text?.type === "text" && text.text ? text.text : "No result",
@@ -164,77 +137,45 @@ export function setupDocsTool(pi: ExtensionAPI) {
         );
       }
 
+      const { docFiles } = details;
       const fields: Array<
         { label: string; value: string; showCollapsed?: boolean } | Text
       > = [];
 
-      if (!details.success) {
-        fields.push({
-          label: "Error",
-          value: theme.fg("error", details.message),
-          showCollapsed: true,
-        });
-      } else if (!details.docFiles || details.docFiles.length === 0) {
-        fields.push({
-          label: "Result",
-          value: theme.fg("warning", "No docs found"),
-          showCollapsed: true,
-        });
-      } else {
+      if (options.expanded) {
+        // Expanded view: show full file list
         const lines: string[] = [];
-
-        if (options.expanded) {
-          lines.push(
-            theme.fg("accent", `${details.docFiles.length} markdown files:`),
-            "",
-          );
-          for (const rel of details.docFiles) {
-            lines.push(theme.fg("dim", `  ${rel}`));
-          }
-        } else {
-          lines.push(
-            theme.fg("accent", `${details.docFiles.length} markdown files`) +
-              ` (${keyHint("app.tools.expand", "to expand")})`,
-            "",
-          );
-
-          const filenames = details.docFiles.map((file) => path.basename(file));
-          const maxLen = Math.max(...filenames.map((file) => file.length));
-          const colWidth = maxLen + 2;
-          const cols = Math.max(1, Math.floor(80 / colWidth));
-          for (let i = 0; i < filenames.length; i += cols) {
-            const row = filenames
-              .slice(i, i + cols)
-              .map((file) => file.padEnd(colWidth))
-              .join("");
-            lines.push(theme.fg("dim", row));
-          }
+        lines.push(
+          theme.fg("accent", `${docFiles.length} markdown files:`),
+          "",
+        );
+        for (const rel of docFiles) {
+          lines.push(theme.fg("dim", `  ${rel}`));
         }
-
         fields.push(new Text(lines.join("\n"), 0, 0));
+      } else {
+        // Collapsed view: show file count + expand hint
+        fields.push({
+          label: "Files",
+          value:
+            theme.fg("accent", `${docFiles.length} markdown files`) +
+            ` (${keyHint("app.tools.expand", "to expand")})`,
+          showCollapsed: true,
+        });
       }
 
-      return new ToolBody(
-        {
-          fields,
-          footer: new ToolFooter(theme, {
-            items: [
-              {
-                label: "status",
-                value: details.success ? "ok" : "error",
-                tone: details.success ? "success" : "error",
-              },
-              {
-                label: "docs",
-                value: String(details.docFiles?.length ?? 0),
-                tone: "accent",
-              },
-            ],
-          }),
-        },
-        options,
-        theme,
-      );
+      // Only show footer if there are items worth showing
+      const footer = new ToolFooter(theme, {
+        items: [
+          {
+            label: "docs",
+            value: String(docFiles.length),
+            tone: "accent",
+          },
+        ],
+      });
+
+      return new ToolBody({ fields, footer }, options, theme);
     },
   });
 }

package/src/tools/package-manager-tool.ts

@@ -10,14 +10,11 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { resolveCtx } from "./utils";
 
 const Params = Type.Object({});
-type ParamsType = Record<string, never>;
+type PackageManagerParams = Record<string, never>;
 
 interface PackageManagerDetails {
-  success: boolean;
-  message: string;
   packageManager?: string;
   version?: string;
   lockfile?: string;
@@ -26,8 +23,6 @@ interface PackageManagerDetails {
   cwd?: string;
 }
 
-type ExecuteResult = AgentToolResult<PackageManagerDetails>;
-
 const LOCKFILES: Record<string, string> = {
   "pnpm-lock.yaml": "pnpm",
   "yarn.lock": "yarn",
@@ -49,137 +44,115 @@ export function setupPackageManagerTool(pi: ExtensionAPI) {
     label: "Package Manager",
     description:
       "Detect the package manager used in the current project by checking lockfiles and package.json",
+    promptSnippet: "Detect the package manager for this project",
+    promptGuidelines: [
+      "Use when you need to know which package manager (npm, yarn, pnpm, bun) the project uses",
+      "Helpful before running install commands or scripts",
+    ],
 
     parameters: Params,
 
     async execute(
       _toolCallId: string,
-      _params: ParamsType,
-      signal: AbortSignal | undefined,
-      onUpdate: unknown,
+      _params: PackageManagerParams,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
       ctx: ExtensionContext,
-    ): Promise<ExecuteResult> {
-      const resolvedCtx = resolveCtx(signal, onUpdate, ctx);
-      const cwd = resolvedCtx.cwd;
-
-      try {
-        const packageJsonPath = path.join(cwd, "package.json");
-        if (!fs.existsSync(packageJsonPath)) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `No package.json found in ${cwd}`,
-              },
-            ],
-            details: {
-              success: false,
-              message: `No package.json found in ${cwd}`,
-              cwd,
-            },
-          };
-        }
+    ): Promise<AgentToolResult<PackageManagerDetails>> {
+      const cwd = ctx.cwd;
 
-        // Walk up from cwd to repo root, collecting packageManager and lockfile.
-        // Stop at .git boundary to avoid escaping the repository.
-        let declaredPm: string | undefined;
-        let declaredVersion: string | undefined;
-        let lockfile: string | undefined;
-        let lockfilePm: string | undefined;
-
-        let searchDir = cwd;
-        while (true) {
-          // Check packageManager field in package.json
-          if (!declaredPm) {
-            const pkgPath = path.join(searchDir, "package.json");
-            try {
-              if (fs.existsSync(pkgPath)) {
-                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-                if (typeof pkg.packageManager === "string") {
-                  const match = pkg.packageManager.match(/^([^@]+)@?(.*)?$/);
-                  if (match) {
-                    declaredPm = match[1];
-                    declaredVersion = match[2] || undefined;
-                  }
+      const packageJsonPath = path.join(cwd, "package.json");
+      if (!fs.existsSync(packageJsonPath)) {
+        throw new Error(`No package.json found in ${cwd}`);
+      }
+
+      // Walk up from cwd to repo root, collecting packageManager and lockfile.
+      // Stop at .git boundary to avoid escaping the repository.
+      let declaredPm: string | undefined;
+      let declaredVersion: string | undefined;
+      let lockfile: string | undefined;
+      let lockfilePm: string | undefined;
+
+      let searchDir = cwd;
+      while (true) {
+        // Check packageManager field in package.json
+        if (!declaredPm) {
+          const pkgPath = path.join(searchDir, "package.json");
+          try {
+            if (fs.existsSync(pkgPath)) {
+              const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+              if (typeof pkg.packageManager === "string") {
+                const match = pkg.packageManager.match(/^([^@]+)@?(.*)?$/);
+                if (match) {
+                  declaredPm = match[1];
+                  declaredVersion = match[2] || undefined;
                 }
               }
-            } catch {
-              // Ignore parse errors
             }
+          } catch {
+            // Ignore parse errors
           }
+        }
 
-          // Check lockfiles
-          if (!lockfilePm) {
-            for (const [filename, pm] of Object.entries(LOCKFILES)) {
-              if (fs.existsSync(path.join(searchDir, filename))) {
-                lockfilePm = pm;
-                lockfile = filename;
-                break;
-              }
+        // Check lockfiles
+        if (!lockfilePm) {
+          for (const [filename, pm] of Object.entries(LOCKFILES)) {
+            if (fs.existsSync(path.join(searchDir, filename))) {
+              lockfilePm = pm;
+              lockfile = filename;
+              break;
             }
           }
+        }
 
-          // Stop if we found both, hit .git, or hit filesystem root
-          if (
-            (declaredPm && lockfilePm) ||
-            fs.existsSync(path.join(searchDir, ".git"))
-          ) {
-            break;
-          }
-          const parent = path.dirname(searchDir);
-          if (parent === searchDir) break;
-          searchDir = parent;
+        // Stop if we found both, hit .git, or hit filesystem root
+        if (
+          (declaredPm && lockfilePm) ||
+          fs.existsSync(path.join(searchDir, ".git"))
+        ) {
+          break;
         }
+        const parent = path.dirname(searchDir);
+        if (parent === searchDir) break;
+        searchDir = parent;
+      }
 
-        const pm = declaredPm || lockfilePm || "npm";
-        const fallback = { install: `${pm} install`, run: pm };
-        const commands = COMMANDS[pm] ?? fallback;
+      const pm = declaredPm || lockfilePm || "npm";
+      const fallback = { install: `${pm} install`, run: pm };
+      const commands = COMMANDS[pm] ?? fallback;
 
-        const parts: string[] = [];
-        parts.push(`Package manager: ${pm}`);
-        if (declaredVersion) {
-          parts.push(`Declared version: ${declaredVersion}`);
-        }
-        if (lockfile) {
-          parts.push(`Lockfile: ${lockfile}`);
-        }
-        if (!lockfile && !declaredPm) {
-          parts.push(
-            "No lockfile or packageManager field found, defaulting to npm",
-          );
-        }
-        parts.push(`Install: ${commands.install}`);
-        parts.push(`Run: ${commands.run}`);
-
-        const message = parts.join("\n");
-
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            success: true,
-            message,
-            packageManager: pm,
-            version: declaredVersion,
-            lockfile,
-            installCommand: commands.install,
-            runCommand: commands.run,
-            cwd,
-          },
-        };
-      } catch (error) {
-        const message = `Error detecting package manager: ${error instanceof Error ? error.message : String(error)}`;
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            success: false,
-            message,
-            cwd,
-          },
-        };
+      const parts: string[] = [];
+      parts.push(`Package manager: ${pm}`);
+      if (declaredVersion) {
+        parts.push(`Declared version: ${declaredVersion}`);
       }
+      if (lockfile) {
+        parts.push(`Lockfile: ${lockfile}`);
+      }
+      if (!lockfile && !declaredPm) {
+        parts.push(
+          "No lockfile or packageManager field found, defaulting to npm",
+        );
+      }
+      parts.push(`Install: ${commands.install}`);
+      parts.push(`Run: ${commands.run}`);
+
+      const message = parts.join("\n");
+
+      return {
+        content: [{ type: "text", text: message }],
+        details: {
+          packageManager: pm,
+          version: declaredVersion,
+          lockfile,
+          installCommand: commands.install,
+          runCommand: commands.run,
+          cwd,
+        },
+      };
     },
 
-    renderCall(_args: ParamsType, theme: Theme) {
+    renderCall(_args: PackageManagerParams, theme: Theme) {
       return new ToolCallHeader({ toolName: "Detect Package Manager" }, theme);
     },
 
@@ -190,24 +163,22 @@ export function setupPackageManagerTool(pi: ExtensionAPI) {
     ): Text {
       const { details } = result;
 
-      if (!details) {
+      // Check for missing expected fields (framework passes {} on error)
+      if (!details?.packageManager) {
+        // Extract error message from result.content
         const text = result.content[0];
-        return new Text(
-          text?.type === "text" && text.text ? text.text : "No result",
-          0,
-          0,
-        );
-      }
-
-      if (!details.success) {
-        return new Text(theme.fg("error", details.message), 0, 0);
+        const errorMessage =
+          text?.type === "text" && text.text
+            ? text.text
+            : "Failed to detect package manager";
+        return new Text(theme.fg("error", errorMessage), 0, 0);
       }
 
       const lines: string[] = [];
       lines.push(
         theme.fg(
           "success",
-          `Package manager: ${theme.bold(details.packageManager || "unknown")}`,
+          `Package manager: ${theme.bold(details.packageManager)}`,
         ),
       );
       if (details.version) {

package/src/tools/utils.ts

@@ -1,6 +1,5 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
 /**
  * Find the currently running Pi installation directory by resolving the
@@ -37,26 +36,3 @@ export function findPiInstallation(): string | null {
     return null;
   }
 }
-
-/**
- * Resolve ExtensionContext from execute args, compatible with Pi 0.50.x and
- * 0.51.0+.
- *
- * Pi 0.50.x: execute(id, params, onUpdate, ctx, signal)
- * Pi 0.51.0+: execute(id, params, signal, onUpdate, ctx)
- *
- * When compiled against 0.51.0+, the typed params are (signal, onUpdate, ctx).
- * On 0.50.x at runtime, `signal` actually receives the onUpdate callback
- * (a function), `onUpdate` receives ctx, and `ctx` receives signal.
- */
-export function resolveCtx(
-  signal: AbortSignal | undefined,
-  onUpdate: unknown,
-  ctx: ExtensionContext,
-): ExtensionContext {
-  // AbortSignal is never callable; a function here means we got onUpdate (0.50.x)
-  if (typeof signal === "function") {
-    return onUpdate as ExtensionContext;
-  }
-  return ctx;
-}

package/src/tools/version-tool.ts

@@ -14,18 +14,18 @@ const VersionParams = Type.Object({});
 type VersionParamsType = Record<string, never>;
 
 interface VersionDetails {
-  success: boolean;
-  message: string;
-  version: string;
+  version?: string;
 }
 
-type ExecuteResult = AgentToolResult<VersionDetails>;
-
 export function setupVersionTool(pi: ExtensionAPI) {
   pi.registerTool<typeof VersionParams, VersionDetails>({
     name: "pi_version",
     label: "Pi Version",
     description: "Get the version of the currently running Pi instance",
+    promptSnippet: "Check the current Pi version.",
+    promptGuidelines: [
+      "Use when the user asks about the Pi version or when a task depends on knowing the installed version.",
+    ],
 
     parameters: VersionParams,
 
@@ -35,15 +35,10 @@ export function setupVersionTool(pi: ExtensionAPI) {
       _signal: AbortSignal | undefined,
       _onUpdate: unknown,
       _ctx: ExtensionContext,
-    ): Promise<ExecuteResult> {
-      const message = `Pi version ${VERSION}`;
+    ): Promise<AgentToolResult<VersionDetails>> {
       return {
-        content: [{ type: "text", text: message }],
-        details: {
-          success: true,
-          message,
-          version: VERSION,
-        },
+        content: [{ type: "text", text: `Pi version ${VERSION}` }],
+        details: { version: VERSION },
       };
     },
 
@@ -58,13 +53,11 @@ export function setupVersionTool(pi: ExtensionAPI) {
     ): Text {
       const { details } = result;
 
-      if (!details) {
-        const text = result.content[0];
-        return new Text(
-          text?.type === "text" && text.text ? text.text : "No result",
-          0,
-          0,
-        );
+      if (!details?.version) {
+        const textBlock = result.content.find((c) => c.type === "text");
+        const msg =
+          (textBlock?.type === "text" && textBlock.text) || "Unknown version";
+        return new Text(theme.fg("error", msg), 0, 0);
       }
 
       return new Text(