gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

package/dist/resources/extensions/slash-commands/create-extension.js

@@ -0,0 +1,264 @@
+import { showInterviewRound } from "../shared/mod.js";
+export default function createExtension(pi) {
+    pi.registerCommand("create-extension", {
+        description: "Scaffold a new pi extension with interview-driven context gathering",
+        async handler(args, ctx) {
+            const inlineName = (typeof args === "string" ? args : "").trim();
+            // ── Interview — always runs first ─────────────────────────────────────
+            const questions = [
+                ...(!inlineName
+                    ? [
+                        {
+                            id: "purpose",
+                            header: "Purpose",
+                            question: "What should this extension do?",
+                            options: [
+                                {
+                                    label: "Add a custom tool",
+                                    description: "Register a new tool the LLM can call (like gsd_plan, plan_clarify).",
+                                },
+                                {
+                                    label: "Add a slash command",
+                                    description: "A /command the user types — runs logic, optionally triggers an agent turn.",
+                                },
+                                {
+                                    label: "React to agent events",
+                                    description: "Hook into turn_end, agent_end, tool_call, etc. to observe or intercept.",
+                                },
+                                {
+                                    label: "Custom TUI component",
+                                    description: "Render a widget, overlay, dialog, or custom editor in the terminal UI.",
+                                },
+                            ],
+                        },
+                    ]
+                    : []),
+                {
+                    id: "ui",
+                    header: "UI",
+                    question: "Does this extension need any custom UI?",
+                    options: [
+                        {
+                            label: "No UI",
+                            description: "Pure logic — no dialogs, widgets, or custom rendering needed.",
+                        },
+                        {
+                            label: "Dialogs only",
+                            description: "Uses built-in ctx.ui.select / ctx.ui.input / ctx.ui.confirm dialogs.",
+                        },
+                        {
+                            label: "Status / widget",
+                            description: "Shows a persistent status indicator or footer widget.",
+                        },
+                        {
+                            label: "Full custom component",
+                            description: "Uses ctx.ui.custom() to render a fully bespoke TUI component.",
+                        },
+                    ],
+                },
+                {
+                    id: "events",
+                    header: "Events",
+                    question: "Does it need to hook into the agent lifecycle?",
+                    options: [
+                        {
+                            label: "No — standalone",
+                            description: "Runs only when explicitly invoked — no event listeners needed.",
+                        },
+                        {
+                            label: "Yes — tool_call",
+                            description: "Intercepts or observes tool calls before or after they run.",
+                        },
+                        {
+                            label: "Yes — turn / session",
+                            description: "Reacts to turn_end, agent_end, session_start, or similar lifecycle events.",
+                        },
+                        {
+                            label: "Yes — context / prompt",
+                            description: "Modifies the system prompt or filters messages via context / before_agent_start.",
+                        },
+                    ],
+                },
+                {
+                    id: "persistence",
+                    header: "State",
+                    question: "Does this extension need to persist state across sessions?",
+                    options: [
+                        {
+                            label: "No state needed",
+                            description: "Stateless — each invocation is independent.",
+                        },
+                        {
+                            label: "In-memory only",
+                            description: "Keeps state while the session is running but doesn't survive restarts.",
+                        },
+                        {
+                            label: "Persisted to session",
+                            description: "Uses pi.appendEntry() to write state into the session JSONL for resume.",
+                        },
+                    ],
+                },
+                {
+                    id: "complexity",
+                    header: "Complexity",
+                    question: "How complex is the implementation?",
+                    options: [
+                        {
+                            label: "Simple — one concern",
+                            description: "A single tool or command, minimal branching, easy to follow.",
+                        },
+                        {
+                            label: "Moderate — a few parts",
+                            description: "A command plus an event hook, or a tool with custom rendering.",
+                        },
+                        {
+                            label: "Complex — full extension",
+                            description: "Multiple tools, commands, events, UI, and state working together.",
+                        },
+                    ],
+                },
+            ];
+            const result = await showInterviewRound(questions, {
+                progress: "New pi extension · Context",
+                reviewHeadline: "Review your choices",
+                exitHeadline: "Cancel extension creation?",
+                exitLabel: "cancel",
+            }, ctx);
+            // User hit Esc — bail silently
+            if (!result.answers || Object.keys(result.answers).length === 0) {
+                ctx.ui.notify("Cancelled.", "info");
+                return;
+            }
+            // ── Resolve name / description ────────────────────────────────────────
+            let extensionDescription = inlineName;
+            if (!extensionDescription) {
+                const purpose = result.answers["purpose"];
+                if (purpose) {
+                    extensionDescription = purpose.notes?.trim()
+                        ? purpose.notes.trim()
+                        : Array.isArray(purpose.selected) ? purpose.selected[0] : purpose.selected;
+                }
+            }
+            if (!extensionDescription) {
+                ctx.ui.notify("No description captured — add details in the notes field next time.", "warning");
+                return;
+            }
+            // ── Build and send the enriched prompt ────────────────────────────────
+            sendPrompt(extensionDescription, result, pi);
+        },
+    });
+}
+// ─── Prompt builder ───────────────────────────────────────────────────────────
+function formatAnswers(result) {
+    const lines = [];
+    const purpose = result.answers["purpose"];
+    if (purpose?.notes) {
+        lines.push(`- **Extension goal (user's words)**: ${purpose.notes}`);
+    }
+    const ui = result.answers["ui"];
+    if (ui) {
+        const selected = Array.isArray(ui.selected) ? ui.selected[0] : ui.selected;
+        lines.push(`- **UI needs**: ${selected}${ui.notes ? ` — ${ui.notes}` : ""}`);
+    }
+    const events = result.answers["events"];
+    if (events) {
+        const selected = Array.isArray(events.selected) ? events.selected[0] : events.selected;
+        lines.push(`- **Event hooks**: ${selected}${events.notes ? ` — ${events.notes}` : ""}`);
+    }
+    const persistence = result.answers["persistence"];
+    if (persistence) {
+        const selected = Array.isArray(persistence.selected) ? persistence.selected[0] : persistence.selected;
+        lines.push(`- **State persistence**: ${selected}${persistence.notes ? ` — ${persistence.notes}` : ""}`);
+    }
+    const complexity = result.answers["complexity"];
+    if (complexity) {
+        const selected = Array.isArray(complexity.selected) ? complexity.selected[0] : complexity.selected;
+        lines.push(`- **Complexity**: ${selected}${complexity.notes ? ` — ${complexity.notes}` : ""}`);
+    }
+    return lines.join("\n");
+}
+function sendPrompt(description, result, pi) {
+    const contextSection = `\n## Context gathered from user\n${formatAnswers(result)}\n`;
+    // Determine which doc sections to highlight based on answers
+    const uiAnswer = result.answers["ui"];
+    const uiSelected = uiAnswer
+        ? (Array.isArray(uiAnswer.selected) ? uiAnswer.selected[0] : uiAnswer.selected)
+        : "";
+    const eventsAnswer = result.answers["events"];
+    const eventsSelected = eventsAnswer
+        ? (Array.isArray(eventsAnswer.selected) ? eventsAnswer.selected[0] : eventsAnswer.selected)
+        : "";
+    const persistenceAnswer = result.answers["persistence"];
+    const persistenceSelected = persistenceAnswer
+        ? (Array.isArray(persistenceAnswer.selected) ? persistenceAnswer.selected[0] : persistenceAnswer.selected)
+        : "";
+    const docHints = [
+        "- `~/.gsd/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
+        "- `~/.gsd/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
+        "- `~/.gsd/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
+        "- `~/.gsd/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
+        "- `~/.gsd/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
+    ];
+    if (uiSelected.includes("custom component")) {
+        docHints.push("- `~/.gsd/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays");
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API");
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList");
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey");
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules");
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide");
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls");
+    }
+    else if (uiSelected.includes("Dialogs")) {
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor");
+    }
+    else if (uiSelected.includes("Status")) {
+        docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header");
+    }
+    if (uiSelected.includes("tool") || result.answers["purpose"]) {
+        docHints.push("- `~/.gsd/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult");
+    }
+    if (eventsSelected && !eventsSelected.includes("standalone")) {
+        docHints.push("- `~/.gsd/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference");
+    }
+    if (eventsSelected.includes("context / prompt")) {
+        docHints.push("- `~/.gsd/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks");
+    }
+    if (persistenceSelected.includes("session")) {
+        docHints.push("- `~/.gsd/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state");
+    }
+    const prompt = `Create a new pi extension based on this description:
+
+"${description}"
+${contextSection}
+## Reference documentation
+
+Before writing any code, read the relevant docs below. They contain the exact APIs, rules, and patterns for building pi extensions — do not guess or rely on general TypeScript knowledge alone.
+
+${docHints.join("\n")}
+
+## Output
+
+Write the complete implementation as a single self-contained extension file:
+
+\`~/.gsd/agent/extensions/<kebab-case-name>.ts\`
+
+Then register it in the main extensions index:
+
+\`~/.gsd/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
+
+## Rules you must follow exactly
+
+- Extension entry point: \`export default function <camelCaseName>(pi: ExtensionAPI): void { ... }\`
+- Import type: \`import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@gsd/pi-coding-agent";\`
+- \`pi\` is the registration surface — call \`pi.registerCommand\`, \`pi.registerTool\`, \`pi.on\`, \`pi.registerShortcut\` inside the default export
+- \`ctx\` (ExtensionCommandContext or ExtensionContext) is passed to handlers and event callbacks — never stored, never assumed available globally
+- To send a message to the agent: \`pi.sendUserMessage("...")\` or \`pi.sendMessage({ content, display }, { triggerTurn })\`
+- To show UI: \`ctx.ui.notify\`, \`ctx.ui.select\`, \`ctx.ui.input\`, \`ctx.ui.confirm\`, \`ctx.ui.custom\`
+- To run shell commands: \`await pi.exec("cmd", ["arg1"])\` — returns \`{ stdout, stderr, exitCode }\`
+- Events use \`pi.on("event_name", async (event, ctx) => { ... })\`
+- No direct file I/O without \`node:fs\` — import it explicitly if needed
+- Read the gotchas file before finalising: \`22-key-rules-gotchas.md\`
+
+After writing the files, run \`/reload\` to load the new extension.`;
+    pi.sendUserMessage(prompt);
+}

package/dist/resources/extensions/slash-commands/create-slash-command.js

@@ -0,0 +1,208 @@
+import { showInterviewRound } from "../shared/mod.js";
+export default function createSlashCommand(pi) {
+    pi.registerCommand("create-slash-command", {
+        description: "Generate a new slash command extension from a plain-English description",
+        async handler(args, ctx) {
+            const inlineDescription = (typeof args === "string" ? args : "").trim();
+            // ── Interview — always run, no free-text step first ───────────────────
+            //
+            // If the user already typed a description as args, we skip the "what
+            // should it do?" question and go straight to the behaviour questions.
+            // Otherwise it's the first question in the round.
+            const questions = [
+                ...(!inlineDescription
+                    ? [
+                        {
+                            id: "purpose",
+                            header: "Purpose",
+                            question: "What should this slash command do?",
+                            options: [
+                                {
+                                    label: "Automate git workflow",
+                                    description: "Commit, branch, diff, stash — anything git-related.",
+                                },
+                                {
+                                    label: "Send a crafted prompt",
+                                    description: "Build a rich context prompt and hand it to the LLM.",
+                                },
+                                {
+                                    label: "Run a shell task",
+                                    description: "Execute CLI tools (npm, docker, etc.) and show the output.",
+                                },
+                                {
+                                    label: "Something else",
+                                    description: "Describe it in the notes field below.",
+                                },
+                            ],
+                        },
+                    ]
+                    : []),
+                {
+                    id: "trigger",
+                    header: "Trigger",
+                    question: "How does this command kick off its work?",
+                    options: [
+                        {
+                            label: "Sends to agent",
+                            description: "Builds a prompt and hands off to the LLM to do the heavy lifting.",
+                        },
+                        {
+                            label: "Runs shell commands",
+                            description: "Executes CLI commands directly (git, npm, etc.) without an LLM turn.",
+                        },
+                        {
+                            label: "Shows a UI prompt",
+                            description: "Pops up a select/input dialog to gather more info, then acts.",
+                        },
+                        {
+                            label: "Mixed — UI then agent",
+                            description: "Collects some info via a dialog, then sends a crafted prompt to the LLM.",
+                        },
+                    ],
+                },
+                {
+                    id: "output",
+                    header: "Output",
+                    question: "How should the command communicate results to the user?",
+                    options: [
+                        {
+                            label: "Agent response",
+                            description: "The LLM writes the response — the command just triggers the turn.",
+                        },
+                        {
+                            label: "Notification",
+                            description: "A brief inline notification (success/error/info) — no agent turn.",
+                        },
+                        {
+                            label: "Command output",
+                            description: "Shows raw shell output or a formatted summary in the chat.",
+                        },
+                    ],
+                },
+                {
+                    id: "args",
+                    header: "Arguments",
+                    question: "Does the command take arguments when invoked?",
+                    options: [
+                        {
+                            label: "No args needed",
+                            description: "Called as just /command-name — gathers everything it needs at runtime.",
+                        },
+                        {
+                            label: "Optional freeform arg",
+                            description: "User can type /command-name <something>, but it works without it too.",
+                        },
+                        {
+                            label: "Required arg",
+                            description: "Needs a specific value typed after the name; shows usage if missing.",
+                        },
+                    ],
+                },
+                {
+                    id: "complexity",
+                    header: "Complexity",
+                    question: "How complex does the implementation need to be?",
+                    options: [
+                        {
+                            label: "Simple — one action",
+                            description: "Does one thing in a handful of lines. Easy to follow.",
+                        },
+                        {
+                            label: "Moderate — a few steps",
+                            description: "Some branching, maybe a shell call or two, a conditional prompt.",
+                        },
+                        {
+                            label: "Complex — multi-step",
+                            description: "Multiple async steps, error handling, state, or UI interactions.",
+                        },
+                    ],
+                },
+            ];
+            const result = await showInterviewRound(questions, {
+                progress: "New slash command · Context",
+                reviewHeadline: "Review your choices",
+                exitHeadline: "Cancel command creation?",
+                exitLabel: "cancel",
+            }, ctx);
+            // User hit Esc with nothing answered — bail silently
+            if (!result.answers || Object.keys(result.answers).length === 0) {
+                ctx.ui.notify("Cancelled.", "info");
+                return;
+            }
+            // ── Resolve description ───────────────────────────────────────────────
+            let description = inlineDescription;
+            if (!description) {
+                const purpose = result.answers["purpose"];
+                if (purpose) {
+                    const selected = Array.isArray(purpose.selected) ? purpose.selected[0] : purpose.selected;
+                    description = purpose.notes
+                        ? purpose.notes // prefer their own words from the notes field
+                        : selected;
+                }
+            }
+            if (!description) {
+                ctx.ui.notify("No description captured — add details in the notes field next time.", "warning");
+                return;
+            }
+            // ── Build and send the enriched prompt ────────────────────────────────
+            sendPrompt(description, result, pi);
+        },
+    });
+}
+// ─── Prompt builder ───────────────────────────────────────────────────────────
+function formatAnswers(result) {
+    const lines = [];
+    const purpose = result.answers["purpose"];
+    if (purpose?.notes) {
+        lines.push(`- **Command goal (user's words)**: ${purpose.notes}`);
+    }
+    const trigger = result.answers["trigger"];
+    if (trigger) {
+        const selected = Array.isArray(trigger.selected) ? trigger.selected[0] : trigger.selected;
+        lines.push(`- **Trigger pattern**: ${selected}${trigger.notes ? ` — ${trigger.notes}` : ""}`);
+    }
+    const output = result.answers["output"];
+    if (output) {
+        const selected = Array.isArray(output.selected) ? output.selected[0] : output.selected;
+        lines.push(`- **Output style**: ${selected}${output.notes ? ` — ${output.notes}` : ""}`);
+    }
+    const argsAnswer = result.answers["args"];
+    if (argsAnswer) {
+        const selected = Array.isArray(argsAnswer.selected) ? argsAnswer.selected[0] : argsAnswer.selected;
+        lines.push(`- **Arguments**: ${selected}${argsAnswer.notes ? ` — ${argsAnswer.notes}` : ""}`);
+    }
+    const complexity = result.answers["complexity"];
+    if (complexity) {
+        const selected = Array.isArray(complexity.selected) ? complexity.selected[0] : complexity.selected;
+        lines.push(`- **Complexity**: ${selected}${complexity.notes ? ` — ${complexity.notes}` : ""}`);
+    }
+    return lines.join("\n");
+}
+function sendPrompt(description, result, pi) {
+    const contextSection = `\n## Context gathered from user\n${formatAnswers(result)}\n`;
+    const prompt = `Create a new pi slash command extension based on this description:
+
+"${description}"
+${contextSection}
+Write the complete file contents for two files:
+
+1. \`~/.gsd/agent/extensions/slash-commands/<name>.ts\` — the command implementation
+2. Update \`~/.gsd/agent/extensions/slash-commands/index.ts\` — import and register the new command alongside existing ones
+
+Rules you must follow exactly:
+- Command registration: \`pi.registerCommand("name", { description, handler })\`
+- Handler signature: \`async handler(args: string, ctx: ExtensionCommandContext)\`
+- \`args\` is the raw string typed after the command name (may be empty)
+- To send a message to the agent: \`pi.sendUserMessage("...")\` — this triggers an agent turn
+- To show a quick notification without triggering a turn: \`ctx.ui.notify("...", "info" | "success" | "error")\`
+- To run a shell command: \`await pi.exec("cmd", ["arg1", "arg2"])\` — returns \`{ stdout, stderr, exitCode }\`
+- To show a select dialog: \`await ctx.ui.select("prompt", ["Option A", "Option B"])\` — returns the chosen string
+- To show a text input dialog: \`await ctx.ui.input("prompt", "placeholder")\` — returns the string or null
+- \`pi\` is captured in closure from the outer \`export default function(pi: ExtensionAPI)\` — use it freely inside the handler
+- No \`ctx.session\`, no \`ctx.sendMessage\`, no \`args[]\` array — these do not exist
+- Import type: \`import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";\`
+- Export default: \`export default function <camelCaseName>(pi: ExtensionAPI) { ... }\`
+
+After writing the files, run \`/reload\` to load the new command.`;
+    pi.sendUserMessage(prompt);
+}

package/dist/resources/extensions/slash-commands/index.js

@@ -0,0 +1,10 @@
+import createSlashCommand from "./create-slash-command.js";
+import createExtension from "./create-extension.js";
+import auditCommand from "./audit.js";
+import clearCommand from "./clear.js";
+export default function slashCommands(pi) {
+    createSlashCommand(pi);
+    createExtension(pi);
+    auditCommand(pi);
+    clearCommand(pi);
+}

package/dist/resources/extensions/subagent/agents.js

@@ -0,0 +1,103 @@
+/**
+ * Agent discovery and configuration
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@gsd/pi-coding-agent";
+function loadAgentsFromDir(dir, source) {
+    const agents = [];
+    if (!fs.existsSync(dir)) {
+        return agents;
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return agents;
+    }
+    for (const entry of entries) {
+        if (!entry.name.endsWith(".md"))
+            continue;
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            continue;
+        const filePath = path.join(dir, entry.name);
+        let content;
+        try {
+            content = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const { frontmatter, body } = parseFrontmatter(content);
+        if (!frontmatter.name || !frontmatter.description) {
+            continue;
+        }
+        const tools = frontmatter.tools
+            ?.split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+        agents.push({
+            name: frontmatter.name,
+            description: frontmatter.description,
+            tools: tools && tools.length > 0 ? tools : undefined,
+            model: frontmatter.model,
+            systemPrompt: body,
+            source,
+            filePath,
+        });
+    }
+    return agents;
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function findNearestProjectAgentsDir(cwd) {
+    let currentDir = cwd;
+    while (true) {
+        const candidate = path.join(currentDir, ".pi", "agents");
+        if (isDirectory(candidate))
+            return candidate;
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            return null;
+        currentDir = parentDir;
+    }
+}
+export function discoverAgents(cwd, scope) {
+    const userDir = path.join(getAgentDir(), "agents");
+    const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+    const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+    const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+    const agentMap = new Map();
+    if (scope === "both") {
+        for (const agent of userAgents)
+            agentMap.set(agent.name, agent);
+        for (const agent of projectAgents)
+            agentMap.set(agent.name, agent);
+    }
+    else if (scope === "user") {
+        for (const agent of userAgents)
+            agentMap.set(agent.name, agent);
+    }
+    else {
+        for (const agent of projectAgents)
+            agentMap.set(agent.name, agent);
+    }
+    return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}
+export function formatAgentList(agents, maxItems) {
+    if (agents.length === 0)
+        return { text: "none", remaining: 0 };
+    const listed = agents.slice(0, maxItems);
+    const remaining = agents.length - listed.length;
+    return {
+        text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+        remaining,
+    };
+}