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

package/src/resources/skills/create-gsd-extension/references/events-reference.md

@@ -0,0 +1,126 @@
+<overview>
+Complete event reference with handler signatures, return types, and type narrowing utilities.
+</overview>
+
+<event_categories>
+
+**Session events:** `session_start`, `session_before_switch`, `session_switch`, `session_before_fork`, `session_fork`, `session_before_compact`, `session_compact`, `session_before_tree`, `session_tree`, `session_shutdown`
+
+**Agent events:** `before_agent_start`, `agent_start`, `agent_end`, `turn_start`, `turn_end`, `context`, `before_provider_request`, `message_start`, `message_update`, `message_end`
+
+**Tool events:** `tool_call`, `tool_execution_start`, `tool_execution_update`, `tool_execution_end`, `tool_result`
+
+**Input events:** `input`
+
+**Model events:** `model_select`
+
+**User bash events:** `user_bash`
+
+**Special:** `session_directory` (CLI startup only, no `ctx` — receives only event)
+
+</event_categories>
+
+<handler_signature>
+```typescript
+pi.on("event_name", async (event, ctx: ExtensionContext) => {
+  // event — typed payload for this event
+  // ctx — access to UI, session, model, control flow
+  // Return undefined for no action, or a typed response
+});
+```
+</handler_signature>
+
+<key_events>
+
+**before_agent_start** — Fired after user prompt, before agent loop. Primary hook for context injection and system prompt modification.
+```typescript
+pi.on("before_agent_start", async (event, ctx) => {
+  // event.prompt — user's prompt text
+  // event.images — attached images
+  // event.systemPrompt — current system prompt
+  return {
+    message: { customType: "my-ext", content: "Extra context", display: true },
+    systemPrompt: event.systemPrompt + "\n\nExtra instructions...",
+  };
+});
+```
+
+**tool_call** — Fired before tool executes. Can block.
+```typescript
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
+
+pi.on("tool_call", async (event, ctx) => {
+  if (isToolCallEventType("bash", event)) {
+    // event.input is typed as { command: string; timeout?: number }
+    if (event.input.command.includes("rm -rf")) {
+      return { block: true, reason: "Dangerous command" };
+    }
+  }
+});
+```
+
+**tool_result** — Fired after tool executes. Can modify result. Handlers chain like middleware.
+```typescript
+import { isBashToolResult } from "@mariozechner/pi-coding-agent";
+
+pi.on("tool_result", async (event, ctx) => {
+  if (isBashToolResult(event)) {
+    // event.details is typed as BashToolDetails
+  }
+  // Return partial patch: { content, details, isError }
+  // Omitted fields keep current values
+});
+```
+
+**context** — Fired before each LLM call. Modify messages non-destructively.
+```typescript
+pi.on("context", async (event, ctx) => {
+  // event.messages is a deep copy — safe to modify
+  const filtered = event.messages.filter(m => !shouldPrune(m));
+  return { messages: filtered };
+});
+```
+
+**input** — Fired when user input is received, before skill/template expansion.
+```typescript
+pi.on("input", async (event, ctx) => {
+  // event.text — raw input
+  // event.source — "interactive", "rpc", or "extension"
+  if (event.text.startsWith("?quick "))
+    return { action: "transform", text: `Respond briefly: ${event.text.slice(7)}` };
+  return { action: "continue" };
+});
+```
+
+**model_select** — Fired when model changes.
+```typescript
+pi.on("model_select", async (event, ctx) => {
+  // event.model, event.previousModel, event.source ("set"|"cycle"|"restore")
+});
+```
+
+</key_events>
+
+<type_narrowing>
+Built-in type guards for tool events:
+
+```typescript
+import { isToolCallEventType, isBashToolResult } from "@mariozechner/pi-coding-agent";
+
+// Tool calls — narrows event.input type
+if (isToolCallEventType("bash", event)) { /* event.input: { command, timeout? } */ }
+if (isToolCallEventType("read", event)) { /* event.input: { path, offset?, limit? } */ }
+if (isToolCallEventType("write", event)) { /* event.input: { path, content } */ }
+if (isToolCallEventType("edit", event)) { /* event.input: { path, oldText, newText } */ }
+
+// Tool results — narrows event.details type
+if (isBashToolResult(event)) { /* event.details: BashToolDetails */ }
+```
+
+For custom tools, export your input type and use explicit type params:
+```typescript
+if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
+  event.input.action; // typed
+}
+```
+</type_narrowing>

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

@@ -0,0 +1,64 @@
+<overview>
+The extension lifecycle from load to shutdown, including the full event flow.
+</overview>
+
+<loading>
+Extensions load when GSD starts (or on `/reload`). The default export function runs synchronously — subscribe to events and register tools/commands during this call.
+
+```
+GSD starts
+  └─► Extension default function runs
+      ├── pi.on("event", handler)      ← Subscribe
+      ├── pi.registerTool({...})       ← Register tools
+      ├── pi.registerCommand(...)      ← Register commands
+      └── pi.registerShortcut(...)     ← Register shortcuts
+  └─► session_start fires
+```
+</loading>
+
+<event_flow>
+Full event flow per user prompt:
+
+```
+user sends prompt
+  ├─► Extension commands checked (bypass if match)
+  ├─► input event (can intercept/transform/handle)
+  ├─► Skill/template expansion
+  ├─► before_agent_start (inject message, modify system prompt)
+  ├─► agent_start
+  │
+  │   ┌── Turn loop (repeats while LLM calls tools) ──┐
+  │   │ turn_start                                     │
+  │   │ context (can modify messages sent to LLM)      │
+  │   │ before_provider_request (inspect/replace payload)│
+  │   │ LLM responds → may call tools:                 │
+  │   │   tool_call (can BLOCK)                        │
+  │   │   tool_execution_start/update/end              │
+  │   │   tool_result (can MODIFY)                     │
+  │   │ turn_end                                       │
+  │   └────────────────────────────────────────────────┘
+  │
+  └─► agent_end
+```
+</event_flow>
+
+<session_events>
+| Event | When | Can Return |
+|-------|------|------------|
+| `session_start` | Session loads | — |
+| `session_before_switch` | Before `/new` or `/resume` | `{ cancel: true }` |
+| `session_switch` | After switch | — |
+| `session_before_fork` | Before `/fork` | `{ cancel: true }`, `{ skipConversationRestore: true }` |
+| `session_fork` | After fork | — |
+| `session_before_compact` | Before compaction | `{ cancel: true }`, `{ compaction: {...} }` |
+| `session_compact` | After compaction | — |
+| `session_shutdown` | On exit | — |
+</session_events>
+
+<hot_reload>
+Extensions in auto-discovered locations hot-reload with `/reload`:
+- `session_shutdown` fires for old runtime
+- Resources re-scanned
+- `session_start` fires for new runtime
+- Code after `await ctx.reload()` still runs from the pre-reload version — treat as terminal
+</hot_reload>

package/src/resources/skills/create-gsd-extension/references/extensionapi-reference.md

@@ -0,0 +1,75 @@
+<overview>
+ExtensionAPI methods — the `pi` object received in the default export function.
+</overview>
+
+<core_registration>
+| Method | Purpose |
+|--------|---------|
+| `pi.on(event, handler)` | Subscribe to events |
+| `pi.registerTool(definition)` | Register LLM-callable tool |
+| `pi.registerCommand(name, options)` | Register `/command` |
+| `pi.registerShortcut(key, options)` | Register keyboard shortcut |
+| `pi.registerFlag(name, options)` | Register CLI flag |
+| `pi.registerMessageRenderer(customType, renderer)` | Custom message rendering |
+| `pi.registerProvider(name, config)` | Register/override model provider |
+| `pi.unregisterProvider(name)` | Remove a provider |
+</core_registration>
+
+<messaging>
+| Method | Purpose |
+|--------|---------|
+| `pi.sendMessage(message, options?)` | Inject custom message into session |
+| `pi.sendUserMessage(content, options?)` | Send user message (triggers turn) |
+
+**Delivery modes for `sendMessage`:**
+- `"steer"` (default) — Interrupts streaming after current tool
+- `"followUp"` — Waits for agent to finish all tools
+- `"nextTurn"` — Queued for next user prompt
+
+```typescript
+pi.sendMessage({
+  customType: "my-extension",
+  content: "Additional context",
+  display: true,
+  details: { ... },
+}, { deliverAs: "steer", triggerTurn: true });
+```
+</messaging>
+
+<state_session>
+| Method | Purpose |
+|--------|---------|
+| `pi.appendEntry(customType, data?)` | Persist state (NOT sent to LLM) |
+| `pi.setSessionName(name)` | Set session display name |
+| `pi.getSessionName()` | Get session name |
+| `pi.setLabel(entryId, label)` | Bookmark entry for `/tree` |
+</state_session>
+
+<tool_management>
+```typescript
+const active = pi.getActiveTools();    // ["read", "bash", "edit", "write"]
+const all = pi.getAllTools();          // [{ name, description }, ...]
+pi.setActiveTools(["read", "bash"]);  // Enable/disable tools
+```
+</tool_management>
+
+<model_management>
+```typescript
+const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
+if (model) {
+  const success = await pi.setModel(model);  // Returns false if no API key
+}
+
+pi.getThinkingLevel();               // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
+pi.setThinkingLevel("high");
+```
+</model_management>
+
+<utilities>
+| Method | Purpose |
+|--------|---------|
+| `pi.exec(cmd, args, opts?)` | Shell command (prefer over child_process) |
+| `pi.events` | Shared event bus for inter-extension communication |
+| `pi.getFlag(name)` | Get CLI flag value |
+| `pi.getCommands()` | All available slash commands |
+</utilities>

package/src/resources/skills/create-gsd-extension/references/extensioncontext-reference.md

@@ -0,0 +1,53 @@
+<overview>
+ExtensionContext (`ctx`) — available in all event handlers (except `session_directory`).
+</overview>
+
+<ui_methods>
+**Dialogs (blocking — wait for user response):**
+```typescript
+const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
+const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
+const name = await ctx.ui.input("Name:", "placeholder");
+const text = await ctx.ui.editor("Edit:", "prefilled text");
+
+// Timed dialog — auto-dismiss after timeout
+const ok = await ctx.ui.confirm("Auto-confirm?", "Proceeds in 5s", { timeout: 5000 });
+```
+
+**Non-blocking UI:**
+```typescript
+ctx.ui.notify("Done!", "info");                     // Toast: "info" | "warning" | "error"
+ctx.ui.setStatus("my-ext", "● Active");             // Footer status
+ctx.ui.setStatus("my-ext", undefined);              // Clear
+ctx.ui.setWidget("my-id", ["Line 1", "Line 2"]);   // Widget above editor
+ctx.ui.setWidget("my-id", ["Below!"], { placement: "belowEditor" });
+ctx.ui.setTitle("gsd - my project");                 // Terminal title
+ctx.ui.setEditorText("Prefill");                    // Set editor content
+ctx.ui.setWorkingMessage("Analyzing...");           // Working message during streaming
+ctx.ui.setToolsExpanded(true);                      // Expand tool output
+```
+</ui_methods>
+
+<ctx_properties>
+| Property/Method | Purpose |
+|----------------|---------|
+| `ctx.hasUI` | `false` in print/JSON mode — check before dialogs |
+| `ctx.cwd` | Current working directory |
+| `ctx.sessionManager` | Read-only session state |
+| `ctx.modelRegistry` / `ctx.model` | Model access |
+| `ctx.isIdle()` / `ctx.abort()` / `ctx.hasPendingMessages()` | Agent state |
+| `ctx.shutdown()` | Request graceful exit (deferred until idle) |
+| `ctx.getContextUsage()` | Current context token usage |
+| `ctx.compact(options?)` | Trigger compaction |
+| `ctx.getSystemPrompt()` | Current effective system prompt |
+</ctx_properties>
+
+<session_manager>
+```typescript
+ctx.sessionManager.getEntries()       // All entries
+ctx.sessionManager.getBranch()        // Current branch
+ctx.sessionManager.getLeafId()        // Current leaf entry ID
+ctx.sessionManager.getSessionFile()   // Session JSONL path
+ctx.sessionManager.getLabel(entryId)  // Entry label
+```
+</session_manager>

package/src/resources/skills/create-gsd-extension/references/key-rules-gotchas.md

@@ -0,0 +1,36 @@
+<overview>
+Non-negotiable rules and common gotchas when building GSD extensions.
+</overview>
+
+<must_follow>
+1. **Use `StringEnum` for string enums** — `Type.Union`/`Type.Literal` breaks Google's API.
+2. **Truncate tool output** — Large output causes context overflow, compaction failures, degraded performance. Limit: 50KB / 2000 lines.
+3. **Use theme from callback** — Don't import theme directly. Use the `theme` parameter from `ctx.ui.custom()` or render functions.
+4. **`DynamicBorder` color param** — Type as `(s: string) => theme.fg("accent", s)`.
+5. **Call `tui.requestRender()` after state changes** in `handleInput`.
+6. **Return `{ render, invalidate, handleInput }`** from custom components.
+7. **Lines must not exceed `width`** in `render()` — use `truncateToWidth()`.
+8. **Session control methods ONLY in commands** — `waitForIdle()`, `newSession()`, `fork()`, `navigateTree()`, `reload()` will **deadlock** in event handlers.
+9. **Strip leading `@` from path arguments** — some models add it.
+10. **Store state in tool result `details`** for proper branching support.
+</must_follow>
+
+<common_patterns>
+- Rebuild component on `invalidate()` when pre-baking theme colors
+- Check `signal?.aborted` in long-running tool executions
+- Use `pi.exec()` instead of `child_process` for shell commands
+- Overlay components are **disposed when closed** — create fresh instances each time
+- Treat `ctx.reload()` as terminal — code after runs from pre-reload version
+- Check `ctx.hasUI` before dialog methods (false in print/JSON mode)
+- Extension errors are logged but don't crash GSD — tool_call handler errors fail-safe (block the tool)
+</common_patterns>
+
+<gsd_paths>
+**GSD extension paths:**
+- Global: `~/.gsd/agent/extensions/*.ts`
+- Global (subdir): `~/.gsd/agent/extensions/*/index.ts`
+- Project-local: `.gsd/extensions/*.ts`
+- Project-local (subdir): `.gsd/extensions/*/index.ts`
+
+The upstream pi docs reference `~/.pi` paths — GSD uses `~/.gsd` everywhere instead.
+</gsd_paths>

package/src/resources/skills/create-gsd-extension/references/mode-behavior.md

@@ -0,0 +1,32 @@
+<overview>
+Mode behavior determines which UI methods work. Extensions may run in non-interactive modes where dialogs are unavailable.
+</overview>
+
+<mode_table>
+| Mode | UI Methods | Notes |
+|------|-----------|-------|
+| **Interactive** (default) | Full TUI | Normal operation — all UI works |
+| **RPC** (`--mode rpc`) | JSON protocol | Host handles UI, dialogs work via sub-protocol |
+| **JSON** (`--mode json`) | No-op | Event stream to stdout, no UI |
+| **Print** (`-p`) | No-op | Extensions run but can't prompt users |
+</mode_table>
+
+<checking_ui>
+**Always check `ctx.hasUI`** before calling dialog methods:
+
+```typescript
+if (ctx.hasUI) {
+  const ok = await ctx.ui.confirm("Delete?", "Sure?");
+  if (!ok) return;
+} else {
+  // Default behavior for non-interactive mode
+  // Or just proceed without confirmation
+}
+```
+
+`ctx.hasUI` is `false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode.
+</checking_ui>
+
+<fire_and_forget>
+Non-blocking methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) are safe in all modes — they're no-ops when no UI is available.
+</fire_and_forget>

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

@@ -0,0 +1,89 @@
+<overview>
+Model and provider management — switching models, registering custom providers with OAuth, and reacting to model changes.
+</overview>
+
+<switching_models>
+```typescript
+const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
+if (model) {
+  const success = await pi.setModel(model);
+  if (!success) ctx.ui.notify("No API key for this model", "error");
+}
+
+// Thinking level
+pi.getThinkingLevel();  // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
+pi.setThinkingLevel("high");  // Clamped to model capabilities
+```
+</switching_models>
+
+<register_provider>
+```typescript
+pi.registerProvider("my-proxy", {
+  baseUrl: "https://proxy.example.com",
+  apiKey: "PROXY_API_KEY",  // Env var name or literal
+  api: "anthropic-messages",  // or "openai-completions", "openai-responses"
+  headers: { "X-Custom": "value" },  // Optional custom headers
+  authHeader: true,  // Auto-add Authorization: Bearer header
+  models: [
+    {
+      id: "claude-sonnet-4-20250514",
+      name: "Claude 4 Sonnet (proxy)",
+      reasoning: false,
+      input: ["text", "image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 16384,
+    }
+  ],
+});
+
+// Override just baseUrl for an existing provider (keeps all models)
+pi.registerProvider("anthropic", {
+  baseUrl: "https://proxy.example.com",
+});
+
+// Remove a provider (restores any overridden built-in models)
+pi.unregisterProvider("my-proxy");
+```
+
+Takes effect immediately after initial load phase — no `/reload` required.
+</register_provider>
+
+<oauth_provider>
+Register a provider with OAuth support for `/login`:
+
+```typescript
+pi.registerProvider("corporate-ai", {
+  baseUrl: "https://ai.corp.com",
+  api: "openai-responses",
+  models: [/* ... */],
+  oauth: {
+    name: "Corporate AI (SSO)",
+    async login(callbacks) {
+      callbacks.onAuth({ url: "https://sso.corp.com/..." });
+      const code = await callbacks.onPrompt({ message: "Enter code:" });
+      return { refresh: code, access: code, expires: Date.now() + 3600000 };
+    },
+    async refreshToken(credentials) {
+      return credentials;  // Refresh logic
+    },
+    getApiKey(credentials) {
+      return credentials.access;
+    },
+  },
+});
+```
+</oauth_provider>
+
+<model_events>
+React to model changes:
+
+```typescript
+pi.on("model_select", async (event, ctx) => {
+  // event.model — newly selected model
+  // event.previousModel — previous model (undefined if first)
+  // event.source — "set" | "cycle" | "restore"
+  ctx.ui.setStatus("model", `${event.model.provider}/${event.model.id}`);
+});
+```
+</model_events>

package/src/resources/skills/create-gsd-extension/references/packaging-distribution.md

@@ -0,0 +1,55 @@
+<overview>
+Packaging extensions for distribution via npm, git, or local paths. Creating GSD/pi packages.
+</overview>
+
+<package_manifest>
+Add a `pi` manifest to `package.json`:
+
+```json
+{
+  "name": "my-gsd-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
+}
+```
+</package_manifest>
+
+<installing>
+```bash
+gsd install npm:@foo/bar@1.0.0
+gsd install git:github.com/user/repo@v1
+gsd install ./local/path
+
+# Try without installing:
+gsd -e npm:@foo/bar
+```
+</installing>
+
+<convention_directories>
+If no `pi` manifest exists, auto-discovers:
+- `extensions/` → `.ts` and `.js` files
+- `skills/` → `SKILL.md` folders
+- `prompts/` → `.md` files
+- `themes/` → `.json` files
+</convention_directories>
+
+<dependencies>
+- List `@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@sinclair/typebox` in `peerDependencies` with `"*"` — they're bundled by the runtime.
+- Other npm deps go in `dependencies`. The runtime runs `npm install` on package installation.
+</dependencies>
+
+<gallery_metadata>
+```json
+{
+  "pi": {
+    "video": "https://example.com/demo.mp4",
+    "image": "https://example.com/screenshot.png"
+  }
+}
+```
+</gallery_metadata>

package/src/resources/skills/create-gsd-extension/references/remote-execution-overrides.md

@@ -0,0 +1,90 @@
+<overview>
+Remote execution via pluggable operations, spawnHook for bash, and tool override patterns.
+</overview>
+
+<pluggable_operations>
+Built-in tools support pluggable operations for SSH, containers, etc.:
+
+```typescript
+import { createReadTool, createBashTool, createWriteTool } from "@mariozechner/pi-coding-agent";
+
+// Create tool with custom remote operations
+const remoteBash = createBashTool(cwd, {
+  operations: {
+    execute: (cmd) => sshExec(remote, cmd),
+  },
+});
+```
+
+**Operations interfaces:** `ReadOperations`, `WriteOperations`, `EditOperations`, `BashOperations`, `LsOperations`, `GrepOperations`, `FindOperations`
+</pluggable_operations>
+
+<spawn_hook>
+The bash tool supports a `spawnHook` to modify commands before execution:
+
+```typescript
+const bashTool = createBashTool(cwd, {
+  spawnHook: ({ command, cwd, env }) => ({
+    command: `source ~/.profile\n${command}`,
+    cwd: `/mnt/sandbox${cwd}`,
+    env: { ...env, CI: "1" },
+  }),
+});
+```
+</spawn_hook>
+
+<ssh_pattern>
+Full SSH pattern with flag-based switching:
+
+```typescript
+import { createBashTool, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerFlag("ssh", { description: "SSH target", type: "string" });
+
+  const localBash = createBashTool(process.cwd());
+
+  pi.registerTool({
+    ...localBash,
+    async execute(id, params, signal, onUpdate, ctx) {
+      const sshTarget = pi.getFlag("--ssh");
+      if (sshTarget) {
+        const remoteBash = createBashTool(process.cwd(), {
+          operations: createSSHOperations(sshTarget),
+        });
+        return remoteBash.execute(id, params, signal, onUpdate);
+      }
+      return localBash.execute(id, params, signal, onUpdate);
+    },
+  });
+}
+```
+</ssh_pattern>
+
+<tool_override_pattern>
+Override built-in tools for logging/access control — omit renderCall/renderResult to keep built-in rendering:
+
+```typescript
+import { createReadTool } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+pi.registerTool({
+  name: "read",  // Same name = overrides built-in
+  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 → built-in renderer used automatically
+});
+```
+
+**Must match exact result shape** including `details` type.
+</tool_override_pattern>