gsd-pi 2.29.0-dev.49d972f → 2.29.0-dev.4c155ee

package/src/resources/skills/create-gsd-extension/references/custom-commands.md

@@ -0,0 +1,139 @@
+<overview>
+Custom slash commands — registration, argument completions, subcommand patterns, and the extended command context.
+</overview>
+
+<basic_registration>
+```typescript
+pi.registerCommand("deploy", {
+  description: "Deploy to an environment",
+  handler: async (args, ctx) => {
+    // args = everything after "/deploy "
+    // ctx = ExtensionCommandContext (has session control methods)
+    ctx.ui.notify(`Deploying to ${args || "production"}`, "info");
+  },
+});
+```
+</basic_registration>
+
+<argument_completions>
+Add tab-completion for command arguments:
+
+```typescript
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+
+pi.registerCommand("deploy", {
+  description: "Deploy to an environment",
+  getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+    const envs = ["dev", "staging", "prod"];
+    const items = envs.map(e => ({ value: e, label: e }));
+    const filtered = items.filter(i => i.value.startsWith(prefix));
+    return filtered.length > 0 ? filtered : null;
+  },
+  handler: async (args, ctx) => {
+    ctx.ui.notify(`Deploying to ${args}`, "info");
+  },
+});
+```
+</argument_completions>
+
+<subcommand_pattern>
+Fake nested commands via first-argument parsing. Used by `/wt new|ls|switch|merge|rm`.
+
+```typescript
+pi.registerCommand("foo", {
+  description: "Manage foo items: /foo new|list|delete [name]",
+
+  getArgumentCompletions: (prefix: string) => {
+    const parts = prefix.trim().split(/\s+/);
+
+    // First arg: subcommand
+    if (parts.length <= 1) {
+      return ["new", "list", "delete"]
+        .filter(cmd => cmd.startsWith(parts[0] ?? ""))
+        .map(cmd => ({ value: cmd, label: cmd }));
+    }
+
+    // Second arg: depends on subcommand
+    if (parts[0] === "delete") {
+      const items = getItemsSomehow();
+      return items
+        .filter(name => name.startsWith(parts[1] ?? ""))
+        .map(name => ({ value: `delete ${name}`, label: name }));
+    }
+
+    return [];
+  },
+
+  handler: async (args, ctx) => {
+    const parts = args.trim().split(/\s+/);
+    const sub = parts[0];
+
+    switch (sub) {
+      case "new": /* ... */ return;
+      case "list": /* ... */ return;
+      case "delete": /* handle parts[1] */ return;
+      default:
+        ctx.ui.notify("Usage: /foo <new|list|delete> [name]", "info");
+    }
+  },
+});
+```
+
+**Gotcha:** `"".trim().split(/\s+/)` produces `['']`, not `[]`. That's why `parts.length <= 1` handles both empty and partial first arg.
+</subcommand_pattern>
+
+<command_context>
+Command handlers get `ExtensionCommandContext` which extends `ExtensionContext` with session control methods:
+
+| Method | Purpose |
+|--------|---------|
+| `ctx.waitForIdle()` | Wait for agent to finish streaming |
+| `ctx.newSession(options?)` | Create a new session |
+| `ctx.fork(entryId)` | Fork from an entry |
+| `ctx.navigateTree(targetId, options?)` | Navigate session tree |
+| `ctx.reload()` | Hot-reload everything |
+
+**⚠️ These methods are ONLY available in command handlers.** Calling them from event handlers causes deadlocks.
+
+```typescript
+pi.registerCommand("handoff", {
+  handler: async (args, ctx) => {
+    await ctx.waitForIdle();
+    await ctx.newSession({
+      setup: async (sm) => {
+        sm.appendMessage({
+          role: "user",
+          content: [{ type: "text", text: `Context: ${args}` }],
+          timestamp: Date.now(),
+        });
+      },
+    });
+  },
+});
+```
+</command_context>
+
+<reload_pattern>
+Expose reload as both a command and a tool the LLM can call:
+
+```typescript
+pi.registerCommand("reload-runtime", {
+  description: "Reload extensions, skills, prompts, and themes",
+  handler: async (_args, ctx) => {
+    await ctx.reload();
+    return;  // Treat reload as terminal
+  },
+});
+
+pi.registerTool({
+  name: "reload_runtime",
+  label: "Reload Runtime",
+  description: "Reload extensions, skills, prompts, and themes",
+  parameters: Type.Object({}),
+  async execute() {
+    pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
+    return { content: [{ type: "text", text: "Queued /reload-runtime as follow-up." }] };
+  },
+});
+```
+</reload_pattern>

package/src/resources/skills/create-gsd-extension/references/custom-rendering.md

@@ -0,0 +1,108 @@
+<overview>
+Custom rendering for tools and messages — control how they appear in the TUI.
+</overview>
+
+<tool_rendering>
+Tools can provide `renderCall` (how the call looks) and `renderResult` (how the result looks):
+
+```typescript
+import { Text } from "@mariozechner/pi-tui";
+import { keyHint } from "@mariozechner/pi-coding-agent";
+
+pi.registerTool({
+  name: "my_tool",
+  // ...
+
+  renderCall(args, theme) {
+    let text = theme.fg("toolTitle", theme.bold("my_tool "));
+    text += theme.fg("muted", args.action);
+    if (args.text) text += " " + theme.fg("dim", `"${args.text}"`);
+    return new Text(text, 0, 0);  // 0,0 padding — Box handles it
+  },
+
+  renderResult(result, { expanded, isPartial }, theme) {
+    // isPartial = true during streaming (onUpdate was called)
+    if (isPartial) {
+      return new Text(theme.fg("warning", "Processing..."), 0, 0);
+    }
+
+    // expanded = user toggled expand (Ctrl+O)
+    if (result.details?.error) {
+      return new Text(theme.fg("error", `Error: ${result.details.error}`), 0, 0);
+    }
+
+    let text = theme.fg("success", "✓ Done");
+    if (!expanded) {
+      text += ` (${keyHint("expandTools", "to expand")})`;
+    }
+    if (expanded && result.details?.items) {
+      for (const item of result.details.items) {
+        text += "\n  " + theme.fg("dim", item);
+      }
+    }
+    return new Text(text, 0, 0);
+  },
+});
+```
+
+If you omit `renderCall`/`renderResult`, the built-in renderer is used. Useful for tool overrides where you just wrap logic without reimplementing UI.
+
+**Fallback:** If render methods throw, `renderCall` shows tool name, `renderResult` shows raw `content` text.
+</tool_rendering>
+
+<key_hints>
+Key hint helpers for showing keybinding info in render output:
+
+```typescript
+import { keyHint, appKeyHint, editorKey, rawKeyHint } from "@mariozechner/pi-coding-agent";
+
+// Editor action hint (respects user keybinding config)
+keyHint("expandTools", "to expand")    // e.g., "Ctrl+O to expand"
+keyHint("selectConfirm", "to select")
+
+// Raw key hint (always shows literal key)
+rawKeyHint("Ctrl+O", "to expand")
+```
+</key_hints>
+
+<message_rendering>
+Register a renderer for custom message types:
+
+```typescript
+import { Text } from "@mariozechner/pi-tui";
+
+pi.registerMessageRenderer("my-extension", (message, options, theme) => {
+  const { expanded } = options;
+  let text = theme.fg("accent", `[${message.customType}] `) + message.content;
+  if (expanded && message.details) {
+    text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
+  }
+  return new Text(text, 0, 0);
+});
+
+// Send messages that use this renderer:
+pi.sendMessage({
+  customType: "my-extension",  // Matches renderer name
+  content: "Status update",
+  display: true,
+  details: { foo: "bar" },
+});
+```
+</message_rendering>
+
+<syntax_highlighting>
+```typescript
+import { highlightCode, getLanguageFromPath } from "@mariozechner/pi-coding-agent";
+
+const lang = getLanguageFromPath("/path/to/file.rs");  // "rust"
+const highlighted = highlightCode(code, lang, theme);
+```
+</syntax_highlighting>
+
+<best_practices>
+- Return `Text` with padding `(0, 0)` — the wrapping `Box` handles padding
+- Support `expanded` for detail on demand
+- Handle `isPartial` for streaming progress
+- Keep collapsed view compact
+- Use `\n` for multi-line content within a single `Text`
+</best_practices>

package/src/resources/skills/create-gsd-extension/references/custom-tools.md

@@ -0,0 +1,183 @@
+<overview>
+Complete custom tools reference — registration, parameters, execution, output truncation, overrides, rendering, and dynamic registration.
+</overview>
+
+<registration>
+```typescript
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+
+pi.registerTool({
+  name: "my_tool",                    // Unique identifier (snake_case)
+  label: "My Tool",                   // Display name in TUI
+  description: "What this does",      // Full description shown to LLM
+
+  // Optional: one-liner for system prompt "Available tools" section
+  promptSnippet: "Manage project todo items",
+
+  // Optional: bullets added to system prompt "Guidelines" when tool is active
+  promptGuidelines: [
+    "Use my_tool for task management instead of file edits."
+  ],
+
+  // Parameter schema (MUST use TypeBox)
+  parameters: Type.Object({
+    action: StringEnum(["list", "add", "remove"] as const),
+    text: Type.Optional(Type.String({ description: "Item text" })),
+    id: Type.Optional(Type.Number({ description: "Item ID" })),
+  }),
+
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    // 1. Check cancellation
+    if (signal?.aborted) {
+      return { content: [{ type: "text", text: "Cancelled" }] };
+    }
+
+    // 2. Stream progress (optional)
+    onUpdate?.({
+      content: [{ type: "text", text: "Working..." }],
+      details: { progress: 50 },
+    });
+
+    // 3. Do the work
+    const result = await doWork(params);
+
+    // 4. Return result
+    return {
+      content: [{ type: "text", text: "Result text for LLM" }],  // Sent to LLM context
+      details: { data: result },                                   // For rendering & state
+    };
+  },
+
+  // Optional: custom TUI rendering
+  renderCall(args, theme) { ... },
+  renderResult(result, { expanded, isPartial }, theme) { ... },
+});
+```
+</registration>
+
+<critical_stringenum>
+**⚠️ MUST use `StringEnum` for string enum parameters:**
+
+```typescript
+import { StringEnum } from "@mariozechner/pi-ai";
+
+// ✅ Correct — works with all providers including Google
+action: StringEnum(["list", "add", "remove"] as const)
+
+// ❌ BROKEN with Google's API
+action: Type.Union([Type.Literal("list"), Type.Literal("add")])
+```
+</critical_stringenum>
+
+<output_truncation>
+Tools MUST truncate output to avoid context overflow. Built-in limit: 50KB / 2000 lines.
+
+```typescript
+import {
+  truncateHead, truncateTail, formatSize,
+  DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES,
+} from "@mariozechner/pi-coding-agent";
+
+async execute(toolCallId, params, signal, onUpdate, ctx) {
+  const output = await runCommand();
+  const truncation = truncateHead(output, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+
+  let result = truncation.content;
+  if (truncation.truncated) {
+    const tempFile = writeTempFile(output);
+    result += `\n\n[Output truncated: ${truncation.outputLines}/${truncation.totalLines} lines`;
+    result += ` (${formatSize(truncation.outputBytes)}/${formatSize(truncation.totalBytes)}).`;
+    result += ` Full output: ${tempFile}]`;
+  }
+  return { content: [{ type: "text", text: result }] };
+}
+```
+
+Use `truncateHead` when beginning matters (search results, file reads). Use `truncateTail` when end matters (logs, command output).
+</output_truncation>
+
+<signaling_errors>
+Throw to signal an error (sets `isError: true`). Returning a value never sets error flag.
+
+```typescript
+async execute(toolCallId, params) {
+  if (!isValid(params.input)) {
+    throw new Error(`Invalid input: ${params.input}`);
+  }
+  return { content: [{ type: "text", text: "OK" }], details: {} };
+}
+```
+</signaling_errors>
+
+<dynamic_registration>
+Tools can be registered at any time — during load, in `session_start`, in command handlers. Available immediately without `/reload`.
+
+```typescript
+pi.on("session_start", async (_event, ctx) => {
+  pi.registerTool({ name: "dynamic_tool", ... });
+});
+```
+
+Use `pi.setActiveTools(names)` to enable/disable tools at runtime.
+</dynamic_registration>
+
+<overriding_builtins>
+Register a tool with the same name as a built-in (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) to override it. **Must match exact result shape including `details` type.**
+
+```typescript
+import { createReadTool } from "@mariozechner/pi-coding-agent";
+
+pi.registerTool({
+  name: "read",
+  label: "Read (Logged)",
+  description: "Read file contents with logging",
+  parameters: Type.Object({
+    path: Type.String(),
+    offset: Type.Optional(Type.Number()),
+    limit: Type.Optional(Type.Number()),
+  }),
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    console.log(`[AUDIT] Reading: ${params.path}`);
+    const builtIn = createReadTool(ctx.cwd);
+    return builtIn.execute(toolCallId, params, signal, onUpdate);
+  },
+  // Omit renderCall/renderResult to use built-in renderer
+});
+```
+
+Start with no built-in tools: `gsd --no-tools -e ./my-extension.ts`
+</overriding_builtins>
+
+<multiple_tools>
+One extension can register multiple tools with shared state:
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  let connection = null;
+
+  pi.registerTool({ name: "db_connect", ... });
+  pi.registerTool({ name: "db_query", ... });
+  pi.registerTool({ name: "db_close", ... });
+
+  pi.on("session_shutdown", async () => {
+    connection?.close();
+  });
+}
+```
+</multiple_tools>
+
+<path_normalization>
+Some models add `@` prefix to path arguments. Strip it:
+
+```typescript
+async execute(toolCallId, params, signal, onUpdate, ctx) {
+  let path = params.path;
+  if (path.startsWith("@")) path = path.slice(1);
+  // ...
+}
+```
+</path_normalization>