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

package/src/resources/extensions/remote-questions/discord-adapter.ts

@@ -2,11 +2,12 @@
  * Remote Questions — Discord adapter
  */
 
-import type { ChannelAdapter, RemotePrompt, RemoteDispatchResult, RemoteAnswer, RemotePromptRef } from "./types.js";
+import { type ChannelAdapter, type RemotePrompt, type RemoteDispatchResult, type RemoteAnswer, type RemotePromptRef } from "./types.js";
 import { formatForDiscord, parseDiscordResponse, DISCORD_NUMBER_EMOJIS } from "./format.js";
+import { apiRequest } from "./http-client.js";
 
 const DISCORD_API = "https://discord.com/api/v10";
-const PER_REQUEST_TIMEOUT_MS = 15_000;
+
 export class DiscordAdapter implements ChannelAdapter {
   readonly name = "discord" as const;
   private botUserId: string | null = null;
@@ -137,23 +138,11 @@ export class DiscordAdapter implements ChannelAdapter {
     return parseDiscordResponse([], String(replies[0].content), prompt.questions);
   }
 
-  private async discordApi(method: string, path: string, body?: unknown): Promise<any> {
-    const headers: Record<string, string> = { Authorization: `Bot ${this.token}` };
-    const init: RequestInit = { method, headers };
-    if (body) {
-      headers["Content-Type"] = "application/json";
-      init.body = JSON.stringify(body);
-    }
-
-    init.signal = AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS);
-    const response = await fetch(`${DISCORD_API}${path}`, init);
-    if (response.status === 204) return {};
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      // Limit error body length to avoid leaking verbose Discord error responses
-      const safeText = text.length > 200 ? text.slice(0, 200) + "…" : text;
-      throw new Error(`Discord API HTTP ${response.status}: ${safeText}`);
-    }
-    return response.json();
+  private async discordApi(method: "GET" | "POST" | "PUT" | "DELETE", path: string, body?: unknown): Promise<any> {
+    return apiRequest(`${DISCORD_API}${path}`, method, body, {
+      authScheme: "Bot",
+      authToken: this.token,
+      errorLabel: "Discord API",
+    });
   }
 }

package/src/resources/extensions/remote-questions/http-client.ts

@@ -0,0 +1,76 @@
+/**
+ * Remote Questions — shared HTTP client
+ *
+ * Centralizes timeout, error handling, and JSON serialization logic
+ * used by all channel adapters (Discord, Slack, Telegram).
+ */
+
+import { PER_REQUEST_TIMEOUT_MS } from "./types.js";
+
+export interface ApiRequestOptions {
+  /** Authorization header scheme. Omit to skip the Authorization header entirely. */
+  authScheme?: "Bearer" | "Bot";
+  /** Token for the Authorization header. Ignored when authScheme is omitted. */
+  authToken?: string;
+  /** Max chars of error body to include in thrown Error. Default 200. */
+  safeErrorLength?: number;
+  /** Label used in error messages (e.g. "Discord API", "Slack API"). Default "HTTP". */
+  errorLabel?: string;
+  /** Content-Type override. Default "application/json" when body is present. */
+  contentType?: string;
+}
+
+/**
+ * Makes an HTTP request with standardized timeout, error handling, and JSON
+ * serialization.
+ *
+ * - Sets `AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS)` on every request.
+ * - Serializes `body` as JSON and sets Content-Type when provided.
+ * - Returns `{}` for 204 No Content responses.
+ * - Truncates error response bodies to `safeErrorLength` chars (default 200).
+ */
+export async function apiRequest(
+  url: string,
+  method: "GET" | "POST" | "PUT" | "DELETE",
+  body?: unknown,
+  options: ApiRequestOptions = {},
+): Promise<any> {
+  const {
+    authScheme,
+    authToken,
+    safeErrorLength = 200,
+    errorLabel = "HTTP",
+    contentType,
+  } = options;
+
+  const headers: Record<string, string> = {};
+  if (authScheme && authToken) {
+    headers["Authorization"] = `${authScheme} ${authToken}`;
+  }
+
+  const init: RequestInit = {
+    method,
+    headers,
+    signal: AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS),
+  };
+
+  if (body !== undefined) {
+    headers["Content-Type"] = contentType ?? "application/json";
+    init.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(url, init);
+
+  if (response.status === 204) return {};
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    const safeText =
+      text.length > safeErrorLength
+        ? text.slice(0, safeErrorLength) + "\u2026"
+        : text;
+    throw new Error(`${errorLabel} HTTP ${response.status}: ${safeText}`);
+  }
+
+  return response.json();
+}

package/src/resources/extensions/remote-questions/notify.ts

@@ -9,8 +9,7 @@
 
 import { resolveRemoteConfig } from "./config.js";
 import type { ResolvedConfig } from "./config.js";
-
-const PER_REQUEST_TIMEOUT_MS = 15_000;
+import { PER_REQUEST_TIMEOUT_MS } from "./types.js";
 
 /**
  * Send a one-way notification to the configured remote channel.

package/src/resources/extensions/remote-questions/slack-adapter.ts

@@ -2,11 +2,11 @@
  * Remote Questions — Slack adapter
  */
 
-import type { ChannelAdapter, RemotePrompt, RemoteDispatchResult, RemoteAnswer, RemotePromptRef } from "./types.js";
+import { type ChannelAdapter, type RemotePrompt, type RemoteDispatchResult, type RemoteAnswer, type RemotePromptRef } from "./types.js";
 import { formatForSlack, parseSlackReply, parseSlackReactionResponse, SLACK_NUMBER_REACTION_NAMES } from "./format.js";
+import { apiRequest } from "./http-client.js";
 
 const SLACK_API = "https://slack.com/api";
-const PER_REQUEST_TIMEOUT_MS = 15_000;
 const SLACK_ACK_REACTION = "white_check_mark";
 
 export class SlackAdapter implements ChannelAdapter {
@@ -123,26 +123,19 @@ export class SlackAdapter implements ChannelAdapter {
   }
 
   private async slackApi(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>> {
-    const url = `${SLACK_API}/${method}`;
     const isGet = method === "conversations.replies" || method === "auth.test" || method === "reactions.get";
+    const opts = { authScheme: "Bearer" as const, authToken: this.token, errorLabel: "Slack API" };
 
-    let response: Response;
     if (isGet) {
-      const qs = new URLSearchParams(Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)]))).toString();
-      response = await fetch(`${url}?${qs}`, { method: "GET", headers: { Authorization: `Bearer ${this.token}` }, signal: AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS) });
-    } else {
-      response = await fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.token}`,
-          "Content-Type": "application/json; charset=utf-8",
-        },
-        body: JSON.stringify(params),
-        signal: AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS),
-      });
+      const qs = new URLSearchParams(
+        Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)])),
+      ).toString();
+      return apiRequest(`${SLACK_API}/${method}?${qs}`, "GET", undefined, opts);
     }
 
-    if (!response.ok) throw new Error(`Slack API HTTP ${response.status}: ${response.statusText}`);
-    return (await response.json()) as Record<string, unknown>;
+    return apiRequest(`${SLACK_API}/${method}`, "POST", params, {
+      ...opts,
+      contentType: "application/json; charset=utf-8",
+    });
   }
 }

package/src/resources/extensions/remote-questions/telegram-adapter.ts

@@ -2,11 +2,11 @@
  * Remote Questions — Telegram adapter
  */
 
-import type { ChannelAdapter, RemotePrompt, RemoteDispatchResult, RemoteAnswer, RemotePromptRef } from "./types.js";
+import { type ChannelAdapter, type RemotePrompt, type RemoteDispatchResult, type RemoteAnswer, type RemotePromptRef } from "./types.js";
 import { formatForTelegram, parseTelegramResponse } from "./format.js";
+import { apiRequest } from "./http-client.js";
 
 const TELEGRAM_API = "https://api.telegram.org";
-const PER_REQUEST_TIMEOUT_MS = 15_000;
 
 export class TelegramAdapter implements ChannelAdapter {
   readonly name = "telegram" as const;
@@ -139,23 +139,11 @@ export class TelegramAdapter implements ChannelAdapter {
   }
 
   private async telegramApi(method: string, params?: Record<string, unknown>): Promise<any> {
-    const url = `${TELEGRAM_API}/bot${this.token}/${method}`;
-    const init: RequestInit = {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      signal: AbortSignal.timeout(PER_REQUEST_TIMEOUT_MS),
-    };
-
-    if (params) {
-      init.body = JSON.stringify(params);
-    }
-
-    const response = await fetch(url, init);
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      const safeText = text.length > 200 ? text.slice(0, 200) + "…" : text;
-      throw new Error(`Telegram API HTTP ${response.status}: ${safeText}`);
-    }
-    return response.json();
+    return apiRequest(
+      `${TELEGRAM_API}/bot${this.token}/${method}`,
+      "POST",
+      params,
+      { errorLabel: "Telegram API" },
+    );
   }
 }

package/src/resources/extensions/remote-questions/types.ts

@@ -2,6 +2,9 @@
  * Remote Questions — shared types
  */
 
+/** Timeout applied to every outbound HTTP request across all channel adapters. */
+export const PER_REQUEST_TIMEOUT_MS = 15_000;
+
 export type RemoteChannel = "slack" | "discord" | "telegram";
 
 export interface RemoteQuestionOption {

package/src/resources/extensions/shared/mod.ts

@@ -28,3 +28,6 @@ export { showInterviewRound } from "./interview-ui.js";
 export type { Question, QuestionOption, RoundResult } from "./interview-ui.js";
 export { showNextAction } from "./next-action-ui.js";
 export { showConfirm } from "./confirm-ui.js";
+export { sanitizeError } from "./sanitize.js";
+export { formatDateShort, truncateWithEllipsis } from "./format-utils.js";
+export { splitFrontmatter, parseFrontmatterMap } from "./frontmatter.js";

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

@@ -0,0 +1,87 @@
+---
+name: create-gsd-extension
+description: Create, debug, and iterate on GSD extensions (TypeScript modules that add tools, commands, event hooks, custom UI, and providers to GSD). Use when asked to build an extension, add a tool the LLM can call, register a slash command, hook into GSD events, create custom TUI components, or modify GSD behavior. Triggers on "create extension", "build extension", "add a tool", "register command", "hook into gsd", "custom tool", "gsd plugin", "gsd extension".
+---
+
+<essential_principles>
+
+**Extensions are TypeScript modules** that hook into GSD's runtime (built on pi). They export a default function receiving `ExtensionAPI` and use it to subscribe to events, register tools/commands/shortcuts, and interact with the session.
+
+**GSD extension paths:**
+- Global extensions: `~/.gsd/agent/extensions/*.ts` or `~/.gsd/agent/extensions/*/index.ts`
+- Project-local extensions: `.gsd/extensions/*.ts` or `.gsd/extensions/*/index.ts`
+
+**The three primitives:**
+1. **Events** — Listen and react (`pi.on("event", handler)`). Can block tool calls, modify messages, inject context.
+2. **Tools** — Give the LLM new abilities (`pi.registerTool()`). LLM calls them autonomously.
+3. **Commands** — Give users slash commands (`pi.registerCommand()`). Users type `/mycommand`.
+
+**Non-negotiable rules:**
+- Use `StringEnum` from `@mariozechner/pi-ai` for string enum params (NOT `Type.Union`/`Type.Literal` — breaks Google's API)
+- Truncate tool output to 50KB / 2000 lines max (use `truncateHead`/`truncateTail` from `@mariozechner/pi-coding-agent`)
+- Store stateful tool state in `details` for branching support
+- Check `signal?.aborted` in long-running tool executions
+- Use `pi.exec()` not `child_process` for shell commands
+- Check `ctx.hasUI` before dialog methods (non-interactive modes exist)
+- Session control methods (`waitForIdle`, `newSession`, `fork`, `navigateTree`, `reload`) are ONLY available in command handlers — they deadlock in event handlers
+- Lines from `render()` must not exceed `width` — use `truncateToWidth()`
+- Use theme from callback params, never import directly
+- Strip leading `@` from path params in custom tools (some models add it)
+
+**Available imports:**
+
+| Package | Purpose |
+|---------|---------|
+| `@mariozechner/pi-coding-agent` | `ExtensionAPI`, `ExtensionContext`, `Theme`, event types, tool utilities, `DynamicBorder`, `BorderedLoader`, `CustomEditor`, `highlightCode` |
+| `@sinclair/typebox` | `Type.Object`, `Type.String`, `Type.Number`, `Type.Optional`, `Type.Boolean`, `Type.Array` |
+| `@mariozechner/pi-ai` | `StringEnum` (required for string enums), `Type` re-export |
+| `@mariozechner/pi-tui` | `Text`, `Box`, `Container`, `Spacer`, `Markdown`, `SelectList`, `Input`, `matchesKey`, `Key`, `truncateToWidth`, `visibleWidth` |
+| Node.js built-ins | `node:fs`, `node:path`, `node:child_process`, etc. |
+
+</essential_principles>
+
+<routing>
+Based on user intent, route to the appropriate workflow:
+
+**Building a new extension:**
+- "Create an extension", "build a tool", "I want to add a command" → `workflows/create-extension.md`
+
+**Adding capabilities to an existing extension:**
+- "Add a tool to my extension", "add event hook", "add custom rendering" → `workflows/add-capability.md`
+
+**Debugging an extension:**
+- "My extension doesn't work", "tool not showing up", "event not firing" → `workflows/debug-extension.md`
+
+**If user intent is clear from context, skip the question and go directly to the workflow.**
+</routing>
+
+<reference_index>
+All domain knowledge in `references/`:
+
+**Core architecture:** extension-lifecycle.md, events-reference.md
+**API surface:** extensionapi-reference.md, extensioncontext-reference.md
+**Capabilities:** custom-tools.md, custom-commands.md, custom-ui.md, custom-rendering.md
+**Patterns:** state-management.md, system-prompt-modification.md, compaction-session-control.md
+**Infrastructure:** model-provider-management.md, remote-execution-overrides.md, packaging-distribution.md, mode-behavior.md
+**Gotchas:** key-rules-gotchas.md
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|----------|---------|
+| create-extension.md | Build a new extension from scratch |
+| add-capability.md | Add tools, commands, hooks, UI to an existing extension |
+| debug-extension.md | Diagnose and fix extension issues |
+</workflows_index>
+
+<success_criteria>
+Extension is complete when:
+- TypeScript compiles without errors (jiti handles this at runtime)
+- Extension loads on GSD startup or `/reload` without errors
+- Tools appear in the LLM's system prompt and are callable
+- Commands respond to `/command` input
+- Event hooks fire at the expected lifecycle points
+- Custom UI renders correctly within terminal width
+- State persists correctly across session restarts (if stateful)
+- Output is truncated to safe limits (if tools produce variable output)
+</success_criteria>

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

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

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

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