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

package/src/resources/skills/create-gsd-extension/references/compaction-session-control.md

@@ -1,77 +0,0 @@
-<overview>
-Custom compaction hooks, triggering compaction, and session control methods available only in command handlers.
-</overview>
-
-<custom_compaction>
-Override default compaction behavior:
-
-```typescript
-pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, signal } = event;
-
-  // Option 1: Cancel
-  return { cancel: true };
-
-  // Option 2: Custom summary
-  return {
-    compaction: {
-      summary: "Custom summary of conversation so far...",
-      firstKeptEntryId: preparation.firstKeptEntryId,
-      tokensBefore: preparation.tokensBefore,
-    }
-  };
-});
-```
-</custom_compaction>
-
-<trigger_compaction>
-Trigger compaction programmatically from any handler:
-
-```typescript
-ctx.compact({
-  customInstructions: "Focus on the authentication changes",
-  onComplete: (result) => ctx.ui.notify("Compacted!", "info"),
-  onError: (error) => ctx.ui.notify(`Failed: ${error.message}`, "error"),
-});
-```
-</trigger_compaction>
-
-<session_control>
-**Only available in command handlers** (deadlocks in event handlers):
-
-```typescript
-pi.registerCommand("handoff", {
-  handler: async (args, ctx) => {
-    await ctx.waitForIdle();
-
-    // Create new session with initial context
-    const result = await ctx.newSession({
-      parentSession: ctx.sessionManager.getSessionFile(),
-      setup: async (sm) => {
-        sm.appendMessage({
-          role: "user",
-          content: [{ type: "text", text: `Context: ${args}` }],
-          timestamp: Date.now(),
-        });
-      },
-    });
-
-    if (result.cancelled) { /* extension cancelled via session_before_switch */ }
-  },
-});
-```
-
-| Method | Purpose |
-|--------|---------|
-| `ctx.waitForIdle()` | Wait for agent to finish streaming |
-| `ctx.newSession(options?)` | Create a new session |
-| `ctx.fork(entryId)` | Fork from a specific entry |
-| `ctx.navigateTree(targetId, options?)` | Navigate session tree (with optional summary) |
-| `ctx.reload()` | Hot-reload everything (treat as terminal — code after runs pre-reload version) |
-
-`navigateTree` options:
-- `summarize: boolean` — generate summary of abandoned branch
-- `customInstructions: string` — instructions for summarizer
-- `replaceInstructions: boolean` — replace default prompt entirely
-- `label: string` — label to attach to branch summary
-</session_control>

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

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

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

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