gsd-pi 2.29.0-dev.2ccf3fb → 2.29.0-dev.6a38b5d

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

@@ -1,143 +0,0 @@
-/**
- * {{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

@@ -1,57 +0,0 @@
-<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

@@ -1,156 +0,0 @@
-<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

@@ -1,74 +0,0 @@
-<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>