gsd-pi 2.29.0 → 2.30.0-dev.7e1bbce

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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>

package/dist/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/dist/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/dist/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");
+    },
+  });
+}