@mariozechner/pi-coding-agent 0.55.3 → 0.55.4

package/docs/extensions.md

@@ -880,6 +880,14 @@ Subscribe to events. See [Events](#events) for event types and return values.
 
 Register a custom tool callable by the LLM. See [Custom Tools](#custom-tools) for full details.
 
+`pi.registerTool()` works both during extension load and after startup. You can call it inside `session_start`, command handlers, or other event handlers. New tools are refreshed immediately in the same session, so they appear in `pi.getAllTools()` and are callable by the LLM without `/reload`.
+
+Use `pi.setActiveTools()` to enable or disable tools (including dynamically added tools) at runtime.
+
+Use `promptSnippet` to customize that tool's one-line entry in `Available tools`, and `promptGuidelines` to append tool-specific bullets to the default `Guidelines` section when the tool is active.
+
+See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
+
 ```typescript
 import { Type } from "@sinclair/typebox";
 import { StringEnum } from "@mariozechner/pi-ai";
@@ -888,6 +896,8 @@ pi.registerTool({
   name: "my_tool",
   label: "My Tool",
   description: "What this tool does",
+  promptSnippet: "Summarize or transform text according to action",
+  promptGuidelines: ["Use this tool when the user asks to summarize previously generated text."],
   parameters: Type.Object({
     action: StringEnum(["list", "add"] as const),
     text: Type.Optional(Type.String()),
@@ -1116,7 +1126,7 @@ const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
 
 ### pi.getActiveTools() / pi.getAllTools() / pi.setActiveTools(names)
 
-Manage active tools.
+Manage active tools. This works for both built-in tools and dynamically registered tools.
 
 ```typescript
 const active = pi.getActiveTools();  // ["read", "bash", "edit", "write"]
@@ -1276,6 +1286,10 @@ export default function (pi: ExtensionAPI) {
 
 Register tools the LLM can call via `pi.registerTool()`. Tools appear in the system prompt and can have custom rendering.
 
+Use `promptSnippet` for a short one-line entry in the `Available tools` section in the default system prompt. If omitted, pi falls back to `description`.
+
+Use `promptGuidelines` to add tool-specific bullets to the default system prompt `Guidelines` section. These bullets are included only while the tool is active (for example, after `pi.setActiveTools([...])`).
+
 Note: Some models are idiots and include the @ prefix in tool path arguments. Built-in tools strip a leading @ before resolving paths. If your custom tool accepts a path, normalize a leading @ as well.
 
 ### Tool Definition
@@ -1289,6 +1303,10 @@ pi.registerTool({
   name: "my_tool",
   label: "My Tool",
   description: "What this tool does (shown to LLM)",
+  promptSnippet: "List or add items in the project todo list",
+  promptGuidelines: [
+    "Use this tool for todo planning instead of direct file edits when the user asks for a task list."
+  ],
   parameters: Type.Object({
     action: StringEnum(["list", "add"] as const),  // Use StringEnum for Google compatibility
     text: Type.Optional(Type.String()),
@@ -1886,6 +1904,7 @@ All examples in [examples/extensions/](../examples/extensions/).
 | `question.ts` | Tool with user interaction | `registerTool`, `ui.select` |
 | `questionnaire.ts` | Multi-step wizard tool | `registerTool`, `ui.custom` |
 | `todo.ts` | Stateful tool with persistence | `registerTool`, `appendEntry`, `renderResult`, session events |
+| `dynamic-tools.ts` | Register tools after startup and during commands | `registerTool`, `session_start`, `registerCommand` |
 | `truncated-tool.ts` | Output truncation example | `registerTool`, `truncateHead` |
 | `tool-override.ts` | Override built-in read tool | `registerTool` (same name as built-in) |
 | **Commands** |||

package/examples/extensions/README.md

@@ -33,6 +33,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions with custom UI |
 | `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
 | `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
+| `dynamic-tools.ts` | Register tools after startup (`session_start`) and at runtime via command, with prompt snippets and tool-specific prompt guidelines |
 | `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
 | `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.6.3",
+      "version": "1.6.4",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "1.6.3",
+  "version": "1.6.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "1.6.3",
+  "version": "1.6.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-qwen-cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-qwen-cli",
   "private": true,
-  "version": "1.5.3",
+  "version": "1.5.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/dynamic-tools.ts

@@ -0,0 +1,74 @@
+/**
+ * Dynamic Tools Extension
+ *
+ * Demonstrates registering tools after session initialization.
+ *
+ * - Registers one tool during session_start
+ * - Registers additional tools at runtime via /add-echo-tool <name>
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const ECHO_PARAMS = Type.Object({
+	message: Type.String({ description: "Message to echo" }),
+});
+
+function normalizeToolName(input: string): string | undefined {
+	const trimmed = input.trim().toLowerCase();
+	if (!trimmed) return undefined;
+	if (!/^[a-z0-9_]+$/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+export default function dynamicToolsExtension(pi: ExtensionAPI) {
+	const registeredToolNames = new Set<string>();
+
+	const registerEchoTool = (name: string, label: string, prefix: string): boolean => {
+		if (registeredToolNames.has(name)) {
+			return false;
+		}
+
+		registeredToolNames.add(name);
+		pi.registerTool({
+			name,
+			label,
+			description: `Echo a message with prefix: ${prefix}`,
+			promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
+			promptGuidelines: ["Use this tool when the user asks for exact echo output."],
+			parameters: ECHO_PARAMS,
+			async execute(_toolCallId, params) {
+				return {
+					content: [{ type: "text", text: `${prefix}${params.message}` }],
+					details: { tool: name, prefix },
+				};
+			},
+		});
+
+		return true;
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		registerEchoTool("echo_session", "Echo Session", "[session] ");
+		ctx.ui.notify("Registered dynamic tool: echo_session", "info");
+	});
+
+	pi.registerCommand("add-echo-tool", {
+		description: "Register a new echo tool dynamically: /add-echo-tool <tool_name>",
+		handler: async (args, ctx) => {
+			const toolName = normalizeToolName(args);
+			if (!toolName) {
+				ctx.ui.notify("Usage: /add-echo-tool <tool_name> (lowercase, numbers, underscores)", "warning");
+				return;
+			}
+
+			const created = registerEchoTool(toolName, `Echo ${toolName}`, `[${toolName}] `);
+			if (!created) {
+				ctx.ui.notify(`Tool already registered: ${toolName}`, "warning");
+				return;
+			}
+
+			ctx.ui.notify(`Registered dynamic tool: ${toolName}`, "info");
+		},
+	});
+}

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "1.19.3",
+  "version": "1.19.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "1.19.3",
+      "version": "1.19.4",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "1.19.3",
+  "version": "1.19.4",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mariozechner/pi-coding-agent",
-	"version": "0.55.3",
+	"version": "0.55.4",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -40,9 +40,9 @@
 	},
 	"dependencies": {
 		"@mariozechner/jiti": "^2.6.2",
-		"@mariozechner/pi-agent-core": "^0.55.3",
-		"@mariozechner/pi-ai": "^0.55.3",
-		"@mariozechner/pi-tui": "^0.55.3",
+		"@mariozechner/pi-agent-core": "^0.55.4",
+		"@mariozechner/pi-ai": "^0.55.4",
+		"@mariozechner/pi-tui": "^0.55.4",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",