@aliou/pi-dev-kit 0.6.4 → 0.6.5

package/src/skills/pi-extension/references/tools.md

@@ -16,15 +16,27 @@ import type {
   Theme,
   ToolRenderResultOptions,
 } from "@mariozechner/pi-coding-agent";
-import { getMarkdownTheme, keyHint, truncateHead, formatSize } from "@mariozechner/pi-coding-agent";
+import { defineTool, getMarkdownTheme, keyHint, truncateHead, formatSize } from "@mariozechner/pi-coding-agent";
 import { Container, Markdown, Text } from "@mariozechner/pi-tui";
-import { type Static, Type } from "@sinclair/typebox";
+import { type Static, Type } from "typebox";
 ```
 
 ## Registration
 
+Tool files are extension entry points. Put the tool registration in `src/tools/index.ts`, export a default function, and list that file in `package.json` `pi.extensions`.
+
 ```typescript
-const myTool = {
+const parameters = Type.Object({
+  query: Type.String({ description: "Search query" }),
+  limit: Type.Optional(Type.Number({ description: "Max results", default: 10 })),
+});
+
+type MyToolParams = Static<typeof parameters>;
+interface MyToolDetails {
+  results: string[];
+}
+
+const myTool = defineTool({
   name: "my_tool",
   label: "My Tool", // Required: human-readable name for UI
   description: "What this tool does. The LLM reads this to decide when to call it.",
@@ -33,17 +45,14 @@ const myTool = {
     "Use my_tool when the user asks about search.",
     "Prefer specific queries over broad ones when calling my_tool.",
   ],
-  parameters: Type.Object({
-    query: Type.String({ description: "Search query" }),
-    limit: Type.Optional(Type.Number({ description: "Max results", default: 10 })),
-  }),
+  parameters,
 
   async execute(
-    toolCallId: string,
-    params: MyToolParams,
-    signal: AbortSignal | undefined,
-    onUpdate: AgentToolUpdateCallback<MyToolDetails> | undefined,
-    ctx: ExtensionContext,
+    toolCallId,
+    params,
+    signal,
+    onUpdate,
+    ctx,
   ): Promise<AgentToolResult<MyToolDetails>> {
     const results = await doSomething(params.query, params.limit);
     return {
@@ -51,15 +60,13 @@ const myTool = {
       details: { results },
     };
   },
-};
+});
 
-// Typed param alias - define once, use everywhere
-type MyToolParams = Static<typeof myTool.parameters>;
-interface MyToolDetails {
-  results: string[];
-}
+export default async function (pi: ExtensionAPI) {
+  await configLoader.load();
+  const config = configLoader.getConfig();
+  if (!config.enabled) return;
 
-export default function (pi: ExtensionAPI) {
   pi.registerTool(myTool);
 }
 ```
@@ -78,7 +85,11 @@ export default function (pi: ExtensionAPI) {
 | `renderCall` | `function` | No | Custom call rendering |
 | `renderResult` | `function` | No | Custom result rendering |
 
-## Typed Param Alias
+## `defineTool()` and Typed Param Alias
+
+Use `defineTool()` for standalone tool definitions. It infers parameter types from the `parameters` field and preserves them for `execute`, `renderCall`, and `renderResult` so you do not need casts or explicit generic arguments at registration/rendering boundaries.
+
+Inside the `defineTool({...})` object, do not annotate callback parameter types unless TypeScript actually needs help. The contextual type from Pi already provides `toolCallId`, `params`, `signal`, `onUpdate`, `ctx`, `options`, and `theme`. If you want `renderResult` to see a specific `details` shape, annotate the `execute` return type as `Promise<AgentToolResult<MyToolDetails>>`; that is the useful annotation.
 
 Define a type alias at the top of your file instead of repeating `Static<typeof parameters>`:
 
@@ -89,21 +100,29 @@ const parameters = Type.Object({
 });
 
 type MyToolParams = Static<typeof parameters>;
-// Use MyToolParams everywhere: execute params, renderCall args, context.args, etc.
+// Use MyToolParams in helper functions and exported action APIs. Inside defineTool callbacks, prefer inference.
 ```
 
 ## Execute Signature
 
+```typescript
+execute(toolCallId, params, signal, onUpdate, ctx): Promise<AgentToolResult<TDetails>>
+```
+
+Pi's `ToolDefinition` type is:
+
 ```typescript
 execute(
   toolCallId: string,
-  params: Static<TParams>,      // Typed from the parameters schema
+  params: Static<TParams>,
   signal: AbortSignal | undefined,
   onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
   ctx: ExtensionContext,
 ): Promise<AgentToolResult<TDetails>>
 ```
 
+You usually do not need to write those parameter types yourself inside `defineTool()`.
+
 **Parameter order matters.** The signal comes before onUpdate.
 
 Always use optional chaining when calling `onUpdate`:
@@ -126,11 +145,13 @@ Prompt metadata is not inherited automatically when you override a built-in tool
 return {
   content: (TextContent | ImageContent)[],  // Content blocks sent to the LLM
   details?: TDetails,                       // Arbitrary data available in the renderer
+  terminate?: boolean,                      // Optional: skip follow-up LLM call when all finalized results in the batch terminate
 };
 ```
 
 - `content` is what the LLM sees. Each block is `{ type: "text", text: "..." }` or an image. Keep it structured and concise.
 - `details` is what the renderer sees. Put rich data here for custom display.
+- `terminate: true` is for final/structured-output tools that should end the turn without an automatic follow-up LLM call. It only applies when every finalized tool result in the current batch also returns `terminate: true`.
 
 Common pattern:
 
@@ -221,10 +242,10 @@ Both approaches work. Approach 1 is more common in published extensions. Approac
 
 ## Parameters Schema
 
-Use TypeBox (`Type.*`) for parameter schemas. The LLM sees the schema to know what arguments to provide.
+Use TypeBox 1.x (`Type.*`) from `typebox` for parameter schemas. The LLM sees the schema to know what arguments to provide. Do not import from `@sinclair/typebox` in new extensions.
 
 ```typescript
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 // Required string
 Type.String({ description: "File path to read" })
@@ -838,7 +859,7 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import { keyHint, formatSize } from "@mariozechner/pi-coding-agent";
 import { Container, Text } from "@mariozechner/pi-tui";
-import { type Static, Type } from "@sinclair/typebox";
+import { type Static, Type } from "typebox";
 
 // Schema
 const parameters = Type.Object({

package/src/tools/changelog-tool.ts

@@ -4,13 +4,11 @@ import { ToolBody, ToolCallHeader, ToolFooter } from "@aliou/pi-utils-ui";
 import type {
   AgentToolResult,
   ExtensionAPI,
-  ExtensionContext,
   Theme,
-  ToolRenderResultOptions,
 } from "@mariozechner/pi-coding-agent";
-import { keyHint, VERSION } from "@mariozechner/pi-coding-agent";
+import { defineTool, keyHint, VERSION } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
-import { type Static, Type } from "@sinclair/typebox";
+import { type Static, Type } from "typebox";
 import { findPiInstallation } from "./utils";
 
 const GITHUB_RAW_CHANGELOG_URL =
@@ -32,7 +30,7 @@ const ChangelogParamsSchema = Type.Object({
 type ChangelogParams = Static<typeof ChangelogParamsSchema>;
 
 const ChangelogVersionsParamsSchema = Type.Object({});
-type ChangelogVersionsParams = Record<string, never>;
+type ChangelogVersionsParams = Static<typeof ChangelogVersionsParamsSchema>;
 
 // ---------------------------------------------------------------------------
 // Types
@@ -200,6 +198,23 @@ const COLLAPSED_LINES = 8;
 // Render helpers
 // ---------------------------------------------------------------------------
 
+function renderChangelogCall(args: ChangelogParams, theme: Theme) {
+  return new ToolCallHeader(
+    {
+      toolName: "Pi Changelog",
+      mainArg: args.version ? `v${args.version}` : "latest",
+    },
+    theme,
+  );
+}
+
+function renderChangelogVersionsCall(
+  _args: ChangelogVersionsParams,
+  theme: Theme,
+) {
+  return new ToolCallHeader({ toolName: "Pi Changelog Versions" }, theme);
+}
+
 function renderChangelogContent(
   content: string,
   theme: Theme,
@@ -235,250 +250,230 @@ function renderChangelogContent(
 // pi_changelog
 // ---------------------------------------------------------------------------
 
-export function setupChangelogTool(pi: ExtensionAPI) {
-  pi.registerTool<typeof ChangelogParamsSchema, ChangelogDetails>({
-    name: "pi_changelog",
-    label: "Pi Changelog",
-    description:
-      "Get changelog entry for a Pi version. Returns latest by default. Use pi_changelog_versions to list all available versions.",
-    promptSnippet: `pi_changelog version="1.2.3" // Get changelog for specific version
+const changelogTool = defineTool({
+  name: "pi_changelog",
+  label: "Pi Changelog",
+  description:
+    "Get changelog entry for a Pi version. Returns latest by default. Use pi_changelog_versions to list all available versions.",
+  promptSnippet: `pi_changelog version="1.2.3" // Get changelog for specific version
 pi_changelog // Get latest changelog`,
-    promptGuidelines: [
-      "Use pi_changelog to check what's new in a Pi version",
-      "Use pi_changelog_versions first to list available versions",
-      "Leave version empty for pi_changelog to get the latest changelog",
-    ],
-
-    parameters: ChangelogParamsSchema,
-
-    async execute(
-      _toolCallId: string,
-      params: ChangelogParams,
-      _signal: AbortSignal | undefined,
-      _onUpdate: unknown,
-      _ctx: ExtensionContext,
-    ): Promise<AgentToolResult<ChangelogDetails>> {
-      // Newer than installed -> fetch from GitHub
-      if (params.version && isNewerThanInstalled(params.version)) {
-        const githubContent = await fetchGithubChangelog();
-        const changelog = findChangelogEntry(githubContent, params.version);
-
-        const message = `Changelog for ${changelog.version} (from GitHub)\n\n## ${changelog.version}\n\n${changelog.content}`;
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            changelog,
-            source: "github",
-          },
-        };
-      }
-
-      // Local
-      const local = readLocalChangelog();
-      const changelog = findChangelogEntry(local.content, params.version);
-
-      const message = `Changelog for ${changelog.version}\n\n## ${changelog.version}\n\n${changelog.content}`;
+  promptGuidelines: [
+    "Use pi_changelog to check what's new in a Pi version",
+    "Use pi_changelog_versions first to list available versions",
+    "Leave version empty for pi_changelog to get the latest changelog",
+  ],
+
+  parameters: ChangelogParamsSchema,
+
+  async execute(
+    _toolCallId,
+    params,
+    _signal,
+    _onUpdate,
+    _ctx,
+  ): Promise<AgentToolResult<ChangelogDetails>> {
+    // Newer than installed -> fetch from GitHub
+    if (params.version && isNewerThanInstalled(params.version)) {
+      const githubContent = await fetchGithubChangelog();
+      const changelog = findChangelogEntry(githubContent, params.version);
+
+      const message = `Changelog for ${changelog.version} (from GitHub)\n\n## ${changelog.version}\n\n${changelog.content}`;
       return {
         content: [{ type: "text", text: message }],
         details: {
           changelog,
-          source: "local",
+          source: "github",
         },
       };
-    },
+    }
 
-    renderCall(args: ChangelogParams, theme: Theme) {
-      return new ToolCallHeader(
-        {
-          toolName: "Pi Changelog",
-          mainArg: args.version ? `v${args.version}` : "latest",
-        },
-        theme,
+    // Local
+    const local = readLocalChangelog();
+    const changelog = findChangelogEntry(local.content, params.version);
+
+    const message = `Changelog for ${changelog.version}\n\n## ${changelog.version}\n\n${changelog.content}`;
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        changelog,
+        source: "local",
+      },
+    };
+  },
+
+  renderCall(args, theme) {
+    return renderChangelogCall(args, theme);
+  },
+
+  renderResult(result, options, theme) {
+    const { details } = result;
+
+    // Check for missing expected fields to detect errors
+    if (!details?.changelog) {
+      const text = result.content[0];
+      return new Text(
+        text?.type === "text" && text.text ? text.text : "No result",
+        0,
+        0,
       );
-    },
+    }
 
-    renderResult(
-      result: AgentToolResult<ChangelogDetails>,
-      options: ToolRenderResultOptions,
-      theme: Theme,
-    ) {
-      const { details } = result;
-
-      // Check for missing expected fields to detect errors
-      if (!details?.changelog) {
-        const text = result.content[0];
-        return new Text(
-          text?.type === "text" && text.text ? text.text : "No result",
-          0,
-          0,
-        );
-      }
+    const fields: Array<
+      { label: string; value: string; showCollapsed?: boolean } | Text
+    > = [];
 
-      const fields: Array<
-        { label: string; value: string; showCollapsed?: boolean } | Text
-      > = [];
-
-      const lines: string[] = [];
-
-      if (options.expanded) {
-        // Expanded view: show full changelog content
-        lines.push(
-          theme.fg(
-            "accent",
-            theme.bold(`Version: ${details.changelog.version}`),
-          ),
-          "",
-        );
-        lines.push(...renderChangelogContent(details.changelog.content, theme));
-        fields.push(new Text(lines.join("\n"), 0, 0));
-      } else {
-        // Collapsed view: show version + first few lines of changelog + expand hint
-        lines.push(
-          theme.fg(
-            "accent",
-            theme.bold(`Version: ${details.changelog.version}`),
-          ),
-          "",
-        );
-        lines.push(
-          ...renderChangelogContent(
-            details.changelog.content,
-            theme,
-            COLLAPSED_LINES,
-          ),
-        );
-        lines.push(
-          "",
-          theme.fg("muted", `${keyHint("app.tools.expand", "to expand")}`),
-        );
-        fields.push(new Text(lines.join("\n"), 0, 0));
-      }
+    const lines: string[] = [];
 
-      // Footer: show source tag only
-      const footer = new ToolFooter(theme, {
-        items: [
-          {
-            label: "source",
-            value: details.source ?? "local",
-            tone: "accent",
-          },
-        ],
-      });
-
-      return new ToolBody(
-        {
-          fields,
-          footer,
-        },
-        options,
-        theme,
+    if (options.expanded) {
+      // Expanded view: show full changelog content
+      lines.push(
+        theme.fg("accent", theme.bold(`Version: ${details.changelog.version}`)),
+        "",
       );
-    },
-  });
-
-  // -------------------------------------------------------------------------
-  // pi_changelog_versions
-  // -------------------------------------------------------------------------
-
-  pi.registerTool<
-    typeof ChangelogVersionsParamsSchema,
-    ChangelogVersionsDetails
-  >({
-    name: "pi_changelog_versions",
-    label: "Pi Changelog Versions",
-    description: "List all available Pi changelog versions",
-    promptSnippet: `pi_changelog_versions // List all available versions`,
-
-    parameters: ChangelogVersionsParamsSchema,
-
-    async execute(
-      _toolCallId: string,
-      _params: ChangelogVersionsParams,
-      _signal: AbortSignal | undefined,
-      _onUpdate: unknown,
-      _ctx: ExtensionContext,
-    ): Promise<AgentToolResult<ChangelogVersionsDetails>> {
-      const local = readLocalChangelog();
-      const { entries } = parseChangelogEntries(local.content);
-
-      if (entries.length === 0) {
-        throw new Error("No version entries found in changelog");
-      }
-
-      const versions = entries.map((e) => e.version);
-      const message = `${versions.length} versions available:\n${versions.join(", ")}`;
+      lines.push(...renderChangelogContent(details.changelog.content, theme));
+      fields.push(new Text(lines.join("\n"), 0, 0));
+    } else {
+      // Collapsed view: show version + first few lines of changelog + expand hint
+      lines.push(
+        theme.fg("accent", theme.bold(`Version: ${details.changelog.version}`)),
+        "",
+      );
+      lines.push(
+        ...renderChangelogContent(
+          details.changelog.content,
+          theme,
+          COLLAPSED_LINES,
+        ),
+      );
+      lines.push(
+        "",
+        theme.fg("muted", `${keyHint("app.tools.expand", "to expand")}`),
+      );
+      fields.push(new Text(lines.join("\n"), 0, 0));
+    }
 
-      return {
-        content: [{ type: "text", text: message }],
-        details: {
-          versions,
-          source: "local",
+    // Footer: show source tag only
+    const footer = new ToolFooter(theme, {
+      items: [
+        {
+          label: "source",
+          value: details.source ?? "local",
+          tone: "accent",
         },
-      };
-    },
-
-    renderCall(_args: ChangelogVersionsParams, theme: Theme) {
-      return new ToolCallHeader({ toolName: "Pi Changelog Versions" }, theme);
-    },
-
-    renderResult(
-      result: AgentToolResult<ChangelogVersionsDetails>,
-      options: ToolRenderResultOptions,
-      theme: Theme,
-    ) {
-      const { details } = result;
-
-      // Check for missing expected fields to detect errors
-      if (!details?.versions) {
-        const text = result.content[0];
-        return new Text(
-          text?.type === "text" && text.text ? text.text : "No result",
-          0,
-          0,
-        );
-      }
+      ],
+    });
+
+    return new ToolBody(
+      {
+        fields,
+        footer,
+      },
+      options,
+      theme,
+    );
+  },
+});
 
-      const fields: Array<
-        { label: string; value: string; showCollapsed?: boolean } | Text
-      > = [];
+// -------------------------------------------------------------------------
+// pi_changelog_versions
+// -------------------------------------------------------------------------
+
+const changelogVersionsTool = defineTool({
+  name: "pi_changelog_versions",
+  label: "Pi Changelog Versions",
+  description: "List all available Pi changelog versions",
+  promptSnippet: `pi_changelog_versions // List all available versions`,
+
+  parameters: ChangelogVersionsParamsSchema,
+
+  async execute(
+    _toolCallId,
+    _params,
+    _signal,
+    _onUpdate,
+    _ctx,
+  ): Promise<AgentToolResult<ChangelogVersionsDetails>> {
+    const local = readLocalChangelog();
+    const { entries } = parseChangelogEntries(local.content);
+
+    if (entries.length === 0) {
+      throw new Error("No version entries found in changelog");
+    }
 
-      const lines: string[] = [
-        theme.fg("accent", `${details.versions.length} versions available:`),
-        "",
-      ];
-      const cols = 6;
-      const maxLen = Math.max(
-        ...details.versions.map((version) => version.length),
+    const versions = entries.map((e) => e.version);
+    const message = `${versions.length} versions available:\n${versions.join(", ")}`;
+
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        versions,
+        source: "local",
+      },
+    };
+  },
+
+  renderCall(args, theme) {
+    return renderChangelogVersionsCall(args, theme);
+  },
+
+  renderResult(result, options, theme) {
+    const { details } = result;
+
+    // Check for missing expected fields to detect errors
+    if (!details?.versions) {
+      const text = result.content[0];
+      return new Text(
+        text?.type === "text" && text.text ? text.text : "No result",
+        0,
+        0,
       );
-      const colWidth = maxLen + 2;
-      for (let i = 0; i < details.versions.length; i += cols) {
-        const row = details.versions
-          .slice(i, i + cols)
-          .map((version) => version.padEnd(colWidth))
-          .join("");
-        lines.push(theme.fg("dim", row));
-      }
-      fields.push(new Text(lines.join("\n"), 0, 0));
+    }
+
+    const fields: Array<
+      { label: string; value: string; showCollapsed?: boolean } | Text
+    > = [];
+
+    const lines: string[] = [
+      theme.fg("accent", `${details.versions.length} versions available:`),
+      "",
+    ];
+    const cols = 6;
+    const maxLen = Math.max(
+      ...details.versions.map((version) => version.length),
+    );
+    const colWidth = maxLen + 2;
+    for (let i = 0; i < details.versions.length; i += cols) {
+      const row = details.versions
+        .slice(i, i + cols)
+        .map((version) => version.padEnd(colWidth))
+        .join("");
+      lines.push(theme.fg("dim", row));
+    }
+    fields.push(new Text(lines.join("\n"), 0, 0));
 
-      // Footer: just show version count
-      const footer = new ToolFooter(theme, {
-        items: [
-          {
-            label: "count",
-            value: String(details.versions.length),
-            tone: "accent",
-          },
-        ],
-      });
-
-      return new ToolBody(
+    // Footer: just show version count
+    const footer = new ToolFooter(theme, {
+      items: [
         {
-          fields,
-          footer,
+          label: "count",
+          value: String(details.versions.length),
+          tone: "accent",
         },
-        options,
-        theme,
-      );
-    },
-  });
+      ],
+    });
+
+    return new ToolBody(
+      {
+        fields,
+        footer,
+      },
+      options,
+      theme,
+    );
+  },
+});
+
+export function setupChangelogTool(pi: ExtensionAPI) {
+  pi.registerTool(changelogTool);
+  pi.registerTool(changelogVersionsTool);
 }