gsd-pi 2.28.0-dev.e19bf89 → 2.29.0-dev.2ccf3fb

package/src/resources/skills/create-gsd-extension/references/state-management.md

@@ -0,0 +1,70 @@
+<overview>
+State management patterns for extensions — tool result details (branch-safe) and appendEntry (private).
+</overview>
+
+<tool_result_details>
+**Recommended for stateful tools.** State in `details` works correctly with branching/forking.
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  let items: string[] = [];
+
+  // Reconstruct state from session on load
+  pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_switch", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_fork", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
+
+  const reconstructState = (ctx: ExtensionContext) => {
+    items = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "toolResult") {
+        if (entry.message.toolName === "my_tool") {
+          items = entry.message.details?.items ?? [];
+        }
+      }
+    }
+  };
+
+  pi.registerTool({
+    name: "my_tool",
+    // ...
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      items.push(params.text);
+      return {
+        content: [{ type: "text", text: "Added" }],
+        details: { items: [...items] },  // ← Snapshot full state
+      };
+    },
+  });
+}
+```
+
+**Key:** Reconstruct on ALL session change events: `session_start`, `session_switch`, `session_fork`, `session_tree`.
+</tool_result_details>
+
+<append_entry>
+**For extension-private state** that doesn't participate in LLM context but needs to survive restarts:
+
+```typescript
+// Save
+pi.appendEntry("my-state", { count: 42, lastRun: Date.now() });
+
+// Restore
+pi.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type === "custom" && entry.customType === "my-state") {
+      const data = entry.data;  // { count: 42, lastRun: ... }
+    }
+  }
+});
+```
+</append_entry>
+
+<when_to_use_which>
+| Pattern | Use When |
+|---------|----------|
+| Tool result `details` | State the LLM's tools produce (todo items, connection state, query results) |
+| `pi.appendEntry()` | Extension-private config, timestamps, counters the LLM doesn't need |
+| File on disk | Large data, config files, caches that shouldn't be in session |
+</when_to_use_which>

package/src/resources/skills/create-gsd-extension/references/system-prompt-modification.md

@@ -0,0 +1,52 @@
+<overview>
+System prompt modification — per-turn injection, context manipulation, and tool-specific prompt content.
+</overview>
+
+<per_turn_modification>
+Use `before_agent_start` to inject messages and/or modify the system prompt for each turn:
+
+```typescript
+pi.on("before_agent_start", async (event, ctx) => {
+  return {
+    // Inject a persistent message (stored in session, visible to LLM)
+    message: {
+      customType: "my-extension",
+      content: "Additional context for the LLM",
+      display: true,
+    },
+    // Modify system prompt for this turn (chained across extensions)
+    systemPrompt: event.systemPrompt + "\n\nYou must respond only in haiku.",
+  };
+});
+```
+</per_turn_modification>
+
+<context_manipulation>
+Use the `context` event to modify messages before each LLM call:
+
+```typescript
+pi.on("context", async (event, ctx) => {
+  // event.messages is a deep copy — safe to modify
+  const filtered = event.messages.filter(m => !isIrrelevant(m));
+  return { messages: filtered };
+});
+```
+</context_manipulation>
+
+<tool_specific_prompts>
+Tools can add content to the system prompt when active:
+
+```typescript
+pi.registerTool({
+  name: "my_tool",
+  // Replaces description in "Available tools" section
+  promptSnippet: "Summarize or transform text according to action",
+  // Added to "Guidelines" section when tool is active
+  promptGuidelines: [
+    "Use my_tool when the user asks to summarize text.",
+    "Prefer my_tool over direct output for structured data."
+  ],
+  // ...
+});
+```
+</tool_specific_prompts>

package/src/resources/skills/create-gsd-extension/templates/extension-skeleton.ts

@@ -0,0 +1,51 @@
+/**
+ * {{EXTENSION_NAME}} — {{DESCRIPTION}}
+ *
+ * Capabilities:
+ * {{CAPABILITIES_LIST}}
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+
+export default function (pi: ExtensionAPI) {
+  // === Events ===
+
+  pi.on("session_start", async (_event, ctx) => {
+    // Initialize state, restore from session, show status
+  });
+
+  // === Tools ===
+
+  pi.registerTool({
+    name: "{{tool_name}}",
+    label: "{{Tool Label}}",
+    description: "{{Tool description for LLM}}",
+    parameters: Type.Object({
+      action: StringEnum(["list", "add"] as const),
+      text: Type.Optional(Type.String({ description: "Item text" })),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      if (signal?.aborted) {
+        return { content: [{ type: "text", text: "Cancelled" }] };
+      }
+
+      // Do work here
+
+      return {
+        content: [{ type: "text", text: "Result for LLM" }],
+        details: {},
+      };
+    },
+  });
+
+  // === Commands ===
+
+  pi.registerCommand("{{command_name}}", {
+    description: "{{Command description}}",
+    handler: async (args, ctx) => {
+      ctx.ui.notify(`Running ${args}`, "info");
+    },
+  });
+}

package/src/resources/skills/create-gsd-extension/templates/stateful-tool-skeleton.ts

@@ -0,0 +1,143 @@
+/**
+ * {{EXTENSION_NAME}} — Stateful tool with persistence
+ *
+ * State is stored in tool result details for proper branching support.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Text, truncateToWidth, matchesKey, Key } from "@mariozechner/pi-tui";
+
+interface {{ItemType}} {
+  id: number;
+  // Add fields
+}
+
+interface {{ToolDetails}} {
+  action: string;
+  items: {{ItemType}}[];
+  nextId: number;
+  error?: string;
+}
+
+export default function (pi: ExtensionAPI) {
+  let items: {{ItemType}}[] = [];
+  let nextId = 1;
+
+  // Reconstruct state from session
+  const reconstructState = (ctx: ExtensionContext) => {
+    items = [];
+    nextId = 1;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "toolResult") {
+        if (entry.message.toolName === "{{tool_name}}") {
+          const details = entry.message.details as {{ToolDetails}} | undefined;
+          if (details) {
+            items = details.items;
+            nextId = details.nextId;
+          }
+        }
+      }
+    }
+  };
+
+  // Reconstruct on ALL session change events
+  pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_switch", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_fork", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
+
+  // Register the tool
+  pi.registerTool({
+    name: "{{tool_name}}",
+    label: "{{Tool Label}}",
+    description: "{{Description for LLM}}",
+    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) {
+      if (signal?.aborted) {
+        return { content: [{ type: "text", text: "Cancelled" }] };
+      }
+
+      switch (params.action) {
+        case "list":
+          return {
+            content: [{ type: "text", text: items.length ? JSON.stringify(items) : "No items" }],
+            details: { action: "list", items: [...items], nextId } as {{ToolDetails}},
+          };
+
+        case "add": {
+          if (!params.text) throw new Error("text required for add");
+          const item: {{ItemType}} = { id: nextId++ /* , ... */ };
+          items.push(item);
+          return {
+            content: [{ type: "text", text: `Added #${item.id}` }],
+            details: { action: "add", items: [...items], nextId } as {{ToolDetails}},
+          };
+        }
+
+        case "remove": {
+          if (params.id === undefined) throw new Error("id required for remove");
+          const idx = items.findIndex(i => i.id === params.id);
+          if (idx === -1) throw new Error(`Item #${params.id} not found`);
+          items.splice(idx, 1);
+          return {
+            content: [{ type: "text", text: `Removed #${params.id}` }],
+            details: { action: "remove", items: [...items], nextId } as {{ToolDetails}},
+          };
+        }
+
+        default:
+          throw new Error(`Unknown action: ${params.action}`);
+      }
+    },
+
+    // Custom rendering
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("{{tool_name}} "));
+      text += theme.fg("muted", args.action);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as {{ToolDetails}} | undefined;
+      if (!details) return new Text("", 0, 0);
+      if (details.error) return new Text(theme.fg("error", details.error), 0, 0);
+      return new Text(theme.fg("success", `✓ ${details.action} (${details.items.length} items)`), 0, 0);
+    },
+  });
+
+  // User command to view state
+  pi.registerCommand("{{command_name}}", {
+    description: "View {{items}}",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Requires interactive mode", "error");
+        return;
+      }
+      await ctx.ui.custom<void>((_tui, theme, _kb, done) => ({
+        render(width: number): string[] {
+          const lines = [
+            "",
+            truncateToWidth(theme.fg("accent", ` {{Items}} (${items.length}) `), width),
+            "",
+          ];
+          for (const item of items) {
+            lines.push(truncateToWidth(`  #${item.id}`, width));
+          }
+          lines.push("", truncateToWidth(theme.fg("dim", "  Press Escape to close"), width), "");
+          return lines;
+        },
+        handleInput(data: string) {
+          if (matchesKey(data, Key.escape)) done();
+        },
+        invalidate() {},
+      }));
+    },
+  });
+}

package/src/resources/skills/create-gsd-extension/workflows/add-capability.md

@@ -0,0 +1,57 @@
+<required_reading>
+Read the reference file for the specific capability being added:
+- Tools → references/custom-tools.md
+- Commands → references/custom-commands.md
+- Events → references/events-reference.md
+- UI → references/custom-ui.md
+- Rendering → references/custom-rendering.md
+- State → references/state-management.md
+- System prompt → references/system-prompt-modification.md
+</required_reading>
+
+<process>
+
+## Step 1: Identify the Extension
+
+Locate the existing extension file. Check:
+- `~/.gsd/agent/extensions/` (global)
+- `.gsd/extensions/` (project-local)
+
+Read the current extension code to understand its structure.
+
+## Step 2: Add the Capability
+
+Add the new registration/hook inside the existing `export default function (pi: ExtensionAPI)` body. Follow the patterns in the relevant reference file.
+
+If the extension needs new imports, add them at the top of the file.
+
+## Step 3: Handle Structural Changes
+
+**Single file → Directory**: If the extension is outgrowing a single file:
+1. Create `~/.gsd/agent/extensions/my-extension/`
+2. Move the file to `index.ts`
+3. Extract helpers to separate files
+
+**Adding npm dependencies**: If new packages are needed:
+1. Create `package.json` in the extension directory
+2. Add dependencies
+3. Run `npm install`
+4. Add `"pi": { "extensions": ["./index.ts"] }` to package.json
+
+## Step 4: Test
+
+```bash
+/reload
+```
+
+Verify the new capability works alongside existing ones.
+
+</process>
+
+<success_criteria>
+Capability addition is complete when:
+- [ ] New capability added without breaking existing functionality
+- [ ] All new imports resolve
+- [ ] `/reload` succeeds
+- [ ] New tool/command/hook tested with real invocation
+</success_criteria>

package/src/resources/skills/create-gsd-extension/workflows/create-extension.md

@@ -0,0 +1,156 @@
+<required_reading>
+**Read these reference files before proceeding:**
+1. references/extension-lifecycle.md
+2. references/custom-tools.md (if building tools)
+3. references/custom-commands.md (if building commands)
+4. references/events-reference.md (if building event hooks)
+5. references/key-rules-gotchas.md (always)
+</required_reading>
+
+<process>
+
+## Step 1: Determine Scope and Placement
+
+Ask the user:
+- **Global** (`~/.gsd/agent/extensions/`) — Available in all GSD sessions
+- **Project-local** (`.gsd/extensions/`) — Available only in this project
+
+## Step 2: Determine Extension Capabilities
+
+Identify what the extension needs from the user's description:
+
+| Capability | API | When |
+|------------|-----|------|
+| Custom tool (LLM-callable) | `pi.registerTool()` | LLM needs to perform new actions |
+| Slash command | `pi.registerCommand()` | User needs direct actions |
+| Event interception | `pi.on("event", ...)` | Block/modify tool calls, inject context, react to lifecycle |
+| Custom UI | `ctx.ui.custom()` | Complex interactive displays |
+| System prompt modification | `before_agent_start` event | Add per-turn instructions |
+| Context filtering | `context` event | Modify messages sent to LLM |
+| State persistence | `details` in tool results or `pi.appendEntry()` | Stateful behavior |
+| Custom rendering | `renderCall` / `renderResult` | Control how tools appear in TUI |
+| Provider management | `pi.registerProvider()` | Custom model endpoints |
+| Keyboard shortcut | `pi.registerShortcut()` | Hotkey triggers |
+
+## Step 3: Choose Extension Structure
+
+**Single file** — for small extensions (1-2 tools/commands, simple hooks):
+```
+~/.gsd/agent/extensions/my-extension.ts
+```
+
+**Directory with index.ts** — for multi-file extensions:
+```
+~/.gsd/agent/extensions/my-extension/
+├── index.ts
+├── tools.ts
+└── utils.ts
+```
+
+**Package with dependencies** — when npm packages are needed:
+```
+~/.gsd/agent/extensions/my-extension/
+├── package.json
+├── src/index.ts
+└── node_modules/
+```
+
+For packages, `package.json` needs:
+```json
+{
+  "name": "my-extension",
+  "dependencies": { ... },
+  "pi": { "extensions": ["./src/index.ts"] }
+}
+```
+
+## Step 4: Write the Extension
+
+Start with the skeleton:
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  // Register events, tools, commands here
+}
+```
+
+Then add capabilities based on Step 2. Reference the appropriate reference files for each capability.
+
+**Tool registration pattern:**
+```typescript
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "What this tool does (shown to LLM)",
+  parameters: Type.Object({
+    action: StringEnum(["list", "add"] as const),
+    text: Type.Optional(Type.String({ description: "Item text" })),
+  }),
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    if (signal?.aborted) return { content: [{ type: "text", text: "Cancelled" }] };
+    return {
+      content: [{ type: "text", text: "Result for LLM" }],
+      details: { data: "for rendering and state" },
+    };
+  },
+});
+```
+
+**Command registration pattern:**
+```typescript
+pi.registerCommand("mycommand", {
+  description: "What this command does",
+  handler: async (args, ctx) => {
+    ctx.ui.notify(`Running with args: ${args}`, "info");
+  },
+});
+```
+
+**Event hook pattern:**
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+    return { block: true, reason: "Blocked dangerous command" };
+  }
+});
+```
+
+## Step 5: Test the Extension
+
+```bash
+# Quick test without installing
+gsd -e ./path/to/my-extension.ts
+
+# Or place in extensions dir and reload
+/reload
+```
+
+Verify:
+- Extension loads without errors (check GSD startup output)
+- Tools appear when LLM is asked to use them
+- Commands respond to `/mycommand`
+- Event hooks trigger at expected points
+
+## Step 6: Iterate
+
+Fix issues, add features, refine. Use `/reload` for hot-reload during development.
+
+</process>
+
+<success_criteria>
+Extension creation is complete when:
+- [ ] Extension file(s) written to correct location
+- [ ] All imports resolve (TypeBox, pi-ai, pi-coding-agent, pi-tui as needed)
+- [ ] Tools use `StringEnum` for string enums (not `Type.Union`/`Type.Literal`)
+- [ ] Tool output is truncated if variable-length
+- [ ] State stored in `details` if extension is stateful
+- [ ] `ctx.hasUI` checked before dialog methods
+- [ ] Extension loads on `/reload` without errors
+- [ ] Tools callable by LLM, commands by user
+- [ ] Tested with at least one real invocation
+</success_criteria>

package/src/resources/skills/create-gsd-extension/workflows/debug-extension.md

@@ -0,0 +1,74 @@
+<required_reading>
+1. references/key-rules-gotchas.md
+2. references/extension-lifecycle.md
+</required_reading>
+
+<process>
+
+## Step 1: Identify the Symptom
+
+| Symptom | Likely Cause |
+|---------|--------------|
+| Extension not loading | File not in discovery path, syntax error, missing export default |
+| Tool not appearing for LLM | Tool not registered, `pi.setActiveTools()` excluding it, tool name conflict |
+| Command not responding | Command not registered, name collision with built-in |
+| Event not firing | Wrong event name, handler returning too early, handler error (logged but swallowed) |
+| UI not rendering | `ctx.hasUI` is false (print mode), render lines exceed width, component not returning lines |
+| State lost on restart | State not stored in `details` or `appendEntry`, not reconstructing on `session_start` |
+| Google API errors | Using `Type.Union`/`Type.Literal` instead of `StringEnum` |
+| Context overflow | Tool output not truncated |
+| Deadlock/hang | Session control methods called from event handler (must be in command handler only) |
+| Render garbage | Theme imported directly instead of from callback, missing `truncateToWidth()` |
+
+## Step 2: Check Extension Loading
+
+```bash
+# Test in isolation
+gsd -e ./path/to/extension.ts
+
+# Check GSD startup output for errors
+# Extension errors are logged but don't crash GSD
+```
+
+## Step 3: Verify File Location
+
+Extensions must be in auto-discovery paths:
+- `~/.gsd/agent/extensions/*.ts`
+- `~/.gsd/agent/extensions/*/index.ts`
+- `.gsd/extensions/*.ts`
+- `.gsd/extensions/*/index.ts`
+
+The file must `export default function(pi: ExtensionAPI) { ... }`.
+
+## Step 4: Check for Common Mistakes
+
+Read `references/key-rules-gotchas.md` and verify each rule against the extension code.
+
+## Step 5: Add Debugging
+
+```typescript
+// Temporary: log to stderr (visible in GSD output)
+console.error("[my-ext] Loading...");
+
+pi.on("session_start", async (_event, ctx) => {
+  console.error("[my-ext] Session started");
+  ctx.ui.notify("Extension loaded", "info");
+});
+```
+
+## Step 6: Fix and Reload
+
+Apply the fix and test:
+```
+/reload
+```
+
+</process>
+
+<success_criteria>
+Debugging is complete when:
+- [ ] Root cause identified
+- [ ] Fix applied
+- [ ] Extension loads and functions correctly after `/reload`
+- [ ] No regression in existing functionality
+</success_criteria>