gsd-pi 2.10.12 → 2.12.0

package/dist/resources/agents/scout.md

@@ -0,0 +1,56 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff to other agents
+tools: read, grep, find, ls, bash
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
+
+Your output will be passed to an agent who has NOT seen the files you explored.
+
+Thoroughness (infer from task, default medium):
+
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+
+1. grep/find to locate relevant code
+2. Read key sections (not entire files)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Output format:
+
+## Files Retrieved
+
+List with exact line ranges:
+
+1. `path/to/file.ts` (lines 10-50) - Description of what's here
+2. `path/to/other.ts` (lines 100-150) - Description
+3. ...
+
+## Key Code
+
+Critical types, interfaces, or functions:
+
+```typescript
+interface Example {
+  // actual code from the files
+}
+```
+
+```typescript
+function keyFunction() {
+  // actual implementation
+}
+```
+
+## Architecture
+
+Brief explanation of how the pieces connect.
+
+## Start Here
+
+Which file to look at first and why.

package/dist/resources/agents/worker.md

@@ -0,0 +1,31 @@
+---
+name: worker
+description: General-purpose subagent with full capabilities, isolated context
+---
+
+You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
+
+Work autonomously to complete the assigned task. Use all available tools as needed, with one important restriction:
+
+- Do **not** spawn subagents or act as an orchestrator unless the parent task explicitly instructs you to do so.
+- If the task looks like GSD orchestration, planning, scouting, parallel dispatch, or review routing, stop and report that the caller should use the appropriate specialist agent instead (for example: `gsd-worker`, `gsd-scout`, `gsd-reviewer`, or the top-level orchestrator).
+- In particular, do **not** call `gsd_scout`, `subagent`, `launch_parallel_view`, or `gsd_execute_parallel` on your own initiative.
+
+Output format when finished:
+
+## Completed
+
+What was done.
+
+## Files Changed
+
+- `path/to/file.ts` - what changed
+
+## Notes (if any)
+
+Anything the main agent should know.
+
+If handing off to another agent (e.g. reviewer), include:
+
+- Exact file paths changed
+- Key functions/types touched (short list)

package/dist/resources/extensions/ask-user-questions.ts

@@ -0,0 +1,289 @@
+/**
+ * Request User Input — LLM tool for asking the user questions
+ *
+ * Thin wrapper around the shared interview-ui. The LLM presents 1-3
+ * questions with 2-3 options each. Each question can be single-select (default)
+ * or multi-select (allowMultiple: true). A free-form "None of the above" option
+ * is added automatically to single-select questions.
+ *
+ * Based on: https://github.com/openai/codex (codex-rs/core/src/tools/handlers/ask_user_questions.rs)
+ */
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Text } from "@gsd/pi-tui";
+import { Type } from "@sinclair/typebox";
+import {
+	showInterviewRound,
+	type Question,
+	type QuestionOption,
+	type RoundResult,
+} from "./shared/interview-ui.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface LocalResultDetails {
+	remote?: false;
+	questions: Question[];
+	response: RoundResult | null;
+	cancelled: boolean;
+}
+
+interface RemoteResultDetails {
+	remote: true;
+	channel: string;
+	timed_out: boolean;
+	promptId?: string;
+	threadUrl?: string;
+	status?: string;
+	questions?: Question[];
+	response?: import("./remote-questions/types.js").RemoteAnswer;
+	error?: boolean;
+}
+
+type AskUserQuestionsDetails = LocalResultDetails | RemoteResultDetails;
+
+// ─── Schema ───────────────────────────────────────────────────────────────────
+
+const OptionSchema = Type.Object({
+	label: Type.String({ description: "User-facing label (1-5 words)" }),
+	description: Type.String({ description: "One short sentence explaining impact/tradeoff if selected" }),
+});
+
+const QuestionSchema = Type.Object({
+	id: Type.String({ description: "Stable identifier for mapping answers (snake_case)" }),
+	header: Type.String({ description: "Short header label shown in the UI (12 or fewer chars)" }),
+	question: Type.String({ description: "Single-sentence prompt shown to the user" }),
+	options: Type.Array(OptionSchema, {
+		description:
+			'Provide 2-3 mutually exclusive choices for single-select, or any number for multi-select. Put the recommended option first and suffix its label with "(Recommended)". Do not include an "Other" option for single-select; the client adds a free-form "None of the above" option automatically.',
+	}),
+	allowMultiple: Type.Optional(
+		Type.Boolean({
+			description:
+				"If true, the user can select multiple options using SPACE to toggle and ENTER to confirm. No 'None of the above' option is added. Default: false.",
+		}),
+	),
+});
+
+const AskUserQuestionsParams = Type.Object({
+	questions: Type.Array(QuestionSchema, {
+		description: "Questions to show the user. Prefer 1 and do not exceed 3.",
+	}),
+});
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const OTHER_OPTION_LABEL = "None of the above";
+
+function errorResult(
+	message: string,
+	questions: Question[] = [],
+): { content: { type: "text"; text: string }[]; details: AskUserQuestionsDetails } {
+	return {
+		content: [{ type: "text", text: message }],
+		details: { questions, response: null, cancelled: true },
+	};
+}
+
+/** Convert the shared RoundResult into the JSON the LLM expects. */
+function formatForLLM(result: RoundResult): string {
+	const answers: Record<string, { answers: string[] }> = {};
+	for (const [id, answer] of Object.entries(result.answers)) {
+		const list: string[] = [];
+		if (Array.isArray(answer.selected)) {
+			list.push(...answer.selected);
+		} else {
+			list.push(answer.selected);
+		}
+		if (answer.notes) {
+			list.push(`user_note: ${answer.notes}`);
+		}
+		answers[id] = { answers: list };
+	}
+	return JSON.stringify({ answers });
+}
+
+// ─── Extension ────────────────────────────────────────────────────────────────
+
+export default function AskUserQuestions(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "ask_user_questions",
+		label: "Request User Input",
+		description:
+			"Request user input for one to three short questions and wait for the response. Single-select questions have 2-3 mutually exclusive options with a free-form 'None of the above' added automatically. Multi-select questions (allowMultiple: true) let the user toggle multiple options with SPACE and confirm with ENTER.",
+		promptGuidelines: [
+			"Use ask_user_questions when you need the user to choose between concrete alternatives before proceeding.",
+			"Keep questions to 1 when possible; never exceed 3.",
+			"For single-select: each question must have 2-3 options. Put the recommended option first with '(Recommended)' suffix. Do not include an 'Other' or 'None of the above' option - the client adds one automatically.",
+			"For multi-select: set allowMultiple: true. The user can pick any number of options. No 'None of the above' is added.",
+		],
+		parameters: AskUserQuestionsParams,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			// Validation
+			if (params.questions.length === 0 || params.questions.length > 3) {
+				return errorResult("Error: questions must contain 1-3 items", params.questions);
+			}
+
+			for (const q of params.questions) {
+				if (!q.options || q.options.length === 0) {
+					return errorResult(
+						`Error: ask_user_questions requires non-empty options for every question (question "${q.id}" has none)`,
+						params.questions,
+					);
+				}
+			}
+
+			if (!ctx.hasUI) {
+				const { tryRemoteQuestions } = await import("./remote-questions/manager.js");
+				const remoteResult = await tryRemoteQuestions(params.questions, signal);
+				if (remoteResult) return { ...remoteResult, details: remoteResult.details as unknown };
+				return errorResult("Error: UI not available (non-interactive mode)", params.questions);
+			}
+
+			// Delegate to shared interview UI
+			const result = await showInterviewRound(params.questions, {}, ctx as any);
+
+			// RPC mode fallback: custom() returns undefined, so showInterviewRound
+			// may return undefined. Fall back to sequential ctx.ui.select() calls.
+			if (!result) {
+				const answers: Record<string, { answers: string[] }> = {};
+				for (const q of params.questions) {
+					const options = q.options.map((o) => o.label);
+					if (!q.allowMultiple) {
+						options.push(OTHER_OPTION_LABEL);
+					}
+					const selected = await ctx.ui.select(
+						`${q.header}: ${q.question}`,
+						options,
+						{ signal, ...(q.allowMultiple ? { allowMultiple: true } : {}) },
+					);
+					if (selected === undefined) {
+						return errorResult("ask_user_questions was cancelled", params.questions);
+					}
+					answers[q.id] = {
+						answers: Array.isArray(selected) ? selected : [selected],
+					};
+				}
+				const roundResult: RoundResult = {
+					endInterview: false,
+					answers: Object.fromEntries(
+						Object.entries(answers).map(([id, a]) => [
+							id,
+							{ selected: a.answers.length === 1 ? a.answers[0] : a.answers, notes: "" },
+						]),
+					),
+				};
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify({ answers }) }],
+					details: {
+						questions: params.questions,
+						response: roundResult,
+						cancelled: false,
+					} satisfies LocalResultDetails,
+				};
+			}
+
+			// Check if cancelled (empty answers = user exited)
+			const hasAnswers = Object.keys(result.answers).length > 0;
+			if (!hasAnswers) {
+				return {
+					content: [{ type: "text", text: "ask_user_questions was cancelled before receiving a response" }],
+					details: { questions: params.questions, response: null, cancelled: true } satisfies LocalResultDetails,
+				};
+			}
+
+			return {
+				content: [{ type: "text", text: formatForLLM(result) }],
+				details: { questions: params.questions, response: result, cancelled: false } satisfies LocalResultDetails,
+			};
+		},
+
+		// ─── Rendering ────────────────────────────────────────────────────────
+
+		renderCall(args, theme) {
+			const qs = (args.questions as Question[]) || [];
+			let text = theme.fg("toolTitle", theme.bold("ask_user_questions "));
+			text += theme.fg("muted", `${qs.length} question${qs.length !== 1 ? "s" : ""}`);
+			if (qs.length > 0) {
+				const headers = qs.map((q) => q.header).join(", ");
+				text += theme.fg("dim", ` (${headers})`);
+			}
+			for (const q of qs) {
+				const multiSel = !!q.allowMultiple;
+				text += `\n  ${theme.fg("text", q.question)}`;
+				const optLabels = multiSel
+					? (q.options || []).map((o: QuestionOption) => o.label)
+					: [...(q.options || []).map((o: QuestionOption) => o.label), OTHER_OPTION_LABEL];
+				const prefix = multiSel ? "☐" : "";
+				const numbered = optLabels.map((l, i) => `${prefix}${i + 1}. ${l}`).join(", ");
+				text += `\n  ${theme.fg("dim", numbered)}`;
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as AskUserQuestionsDetails | undefined;
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+
+			// Remote channel result (discriminated on details.remote === true)
+			if (details.remote) {
+				if (details.timed_out) {
+					return new Text(
+						`${theme.fg("warning", `${details.channel} — timed out`)}${details.threadUrl ? theme.fg("dim", ` ${details.threadUrl}`) : ""}`,
+						0,
+						0,
+					);
+				}
+
+				const questions = (details.questions ?? []) as Question[];
+				const lines: string[] = [];
+				lines.push(theme.fg("dim", details.channel));
+				if (details.response) {
+					for (const q of questions) {
+						const answer = details.response.answers[q.id];
+						if (!answer) {
+							lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
+							continue;
+						}
+						const answerText = answer.answers.length > 0 ? answer.answers.join(", ") : "(custom)";
+						let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
+						if (answer.user_note) {
+							line += ` ${theme.fg("muted", `[note: ${answer.user_note}]`)}`;
+						}
+						lines.push(line);
+					}
+				}
+				return new Text(lines.join("\n"), 0, 0);
+			}
+
+			if (details.cancelled || !details.response) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+
+			const lines: string[] = [];
+			for (const q of details.questions) {
+				const answer = (details.response as RoundResult).answers[q.id];
+				if (!answer) {
+					lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
+					continue;
+				}
+				const selected = answer.selected;
+				const notes = answer.notes;
+				const multiSel = !!q.allowMultiple;
+				const answerText = multiSel && Array.isArray(selected)
+					? selected.join(", ")
+					: (Array.isArray(selected) ? selected[0] : selected) ?? "(no answer)";
+				let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
+				if (notes) {
+					line += ` ${theme.fg("muted", `[note: ${notes}]`)}`;
+				}
+				lines.push(line);
+			}
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+}

package/dist/resources/extensions/async-jobs/async-bash-tool.ts

@@ -0,0 +1,211 @@
+/**
+ * async_bash tool — run a bash command in the background.
+ *
+ * Registers the command with the AsyncJobManager and returns a job ID
+ * immediately. The LLM can continue working and check results later
+ * with await_job.
+ */
+
+import type { ToolDefinition } from "@gsd/pi-coding-agent";
+import {
+	getShellConfig,
+	sanitizeCommand,
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+} from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import type { AsyncJobManager } from "./job-manager.js";
+
+const schema = Type.Object({
+	command: Type.String({ description: "Bash command to execute in the background" }),
+	timeout: Type.Optional(
+		Type.Number({ description: "Timeout in seconds (optional)" }),
+	),
+	label: Type.Optional(
+		Type.String({ description: "Short label for the job (shown in /jobs). Defaults to a truncated version of the command." }),
+	),
+});
+
+function getTempFilePath(): string {
+	const id = randomBytes(8).toString("hex");
+	return join(tmpdir(), `pi-async-bash-${id}.log`);
+}
+
+/**
+ * Kill a process and its children. Uses process group kill on Unix.
+ */
+function killTree(pid: number): void {
+	try {
+		// Kill the process group (negative PID)
+		process.kill(-pid, "SIGTERM");
+	} catch {
+		try {
+			process.kill(pid, "SIGTERM");
+		} catch {
+			// Already exited
+		}
+	}
+}
+
+export function createAsyncBashTool(
+	getManager: () => AsyncJobManager,
+	getCwd: () => string,
+): ToolDefinition<typeof schema> {
+	return {
+		name: "async_bash",
+		label: "Background Bash",
+		description:
+			`Run a bash command in the background. Returns a job ID immediately so you can continue working. ` +
+			`Use await_job to get results or cancel_job to stop. Ideal for long-running builds, tests, or installs. ` +
+			`Output is truncated to the last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB.`,
+		promptSnippet: "Run a bash command in the background, returning a job ID immediately.",
+		promptGuidelines: [
+			"Use async_bash for commands that take more than a few seconds (builds, tests, installs, large git operations).",
+			"After starting async jobs, continue with other work and use await_job when you need the results.",
+			"Use cancel_job to stop a running background job.",
+			"Check /jobs to see all running and recent background jobs.",
+		],
+		parameters: schema,
+		async execute(_toolCallId, params) {
+			const manager = getManager();
+			const cwd = getCwd();
+			const { command, timeout, label } = params;
+			const shortCmd = label ?? (command.length > 60 ? command.slice(0, 57) + "..." : command);
+
+			const jobId = manager.register("bash", shortCmd, (signal) => {
+				return executeBashInBackground(command, cwd, signal, timeout);
+			});
+
+			return {
+				content: [{
+					type: "text",
+					text: [
+						`Background job started: **${jobId}**`,
+						`Command: \`${shortCmd}\``,
+						"",
+						"Use `await_job` to get results when ready, or `cancel_job` to stop.",
+					].join("\n"),
+				}],
+			};
+		},
+	};
+}
+
+/**
+ * Execute a bash command, collecting output. Returns the text result.
+ */
+function executeBashInBackground(
+	command: string,
+	cwd: string,
+	signal: AbortSignal,
+	timeout?: number,
+): Promise<string> {
+	return new Promise<string>((resolve, reject) => {
+		const { shell, args } = getShellConfig();
+		const resolvedCommand = sanitizeCommand(command);
+
+		const child = spawn(shell, [...args, resolvedCommand], {
+			cwd,
+			detached: true,
+			env: { ...process.env },
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		let timedOut = false;
+		let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+
+		if (timeout !== undefined && timeout > 0) {
+			timeoutHandle = setTimeout(() => {
+				timedOut = true;
+				if (child.pid) killTree(child.pid);
+			}, timeout * 1000);
+		}
+
+		const chunks: Buffer[] = [];
+		let totalBytes = 0;
+		let spillFilePath: string | undefined;
+		let spillStream: ReturnType<typeof createWriteStream> | undefined;
+		const MAX_BUFFER = DEFAULT_MAX_BYTES * 2;
+
+		const onData = (data: Buffer) => {
+			totalBytes += data.length;
+
+			if (totalBytes > DEFAULT_MAX_BYTES && !spillFilePath) {
+				spillFilePath = getTempFilePath();
+				spillStream = createWriteStream(spillFilePath);
+				for (const chunk of chunks) spillStream.write(chunk);
+			}
+			if (spillStream) spillStream.write(data);
+
+			chunks.push(data);
+			let chunksBytes = chunks.reduce((s, c) => s + c.length, 0);
+			while (chunksBytes > MAX_BUFFER && chunks.length > 1) {
+				const removed = chunks.shift()!;
+				chunksBytes -= removed.length;
+			}
+		};
+
+		if (child.stdout) child.stdout.on("data", onData);
+		if (child.stderr) child.stderr.on("data", onData);
+
+		const onAbort = () => {
+			if (child.pid) killTree(child.pid);
+		};
+
+		if (signal.aborted) {
+			onAbort();
+		} else {
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		child.on("error", (err) => {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			signal.removeEventListener("abort", onAbort);
+			reject(err);
+		});
+
+		child.on("close", (code) => {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			signal.removeEventListener("abort", onAbort);
+			if (spillStream) spillStream.end();
+
+			if (signal.aborted) {
+				const output = Buffer.concat(chunks).toString("utf-8");
+				resolve(output ? `${output}\n\nCommand aborted` : "Command aborted");
+				return;
+			}
+
+			if (timedOut) {
+				const output = Buffer.concat(chunks).toString("utf-8");
+				resolve(output ? `${output}\n\nCommand timed out after ${timeout} seconds` : `Command timed out after ${timeout} seconds`);
+				return;
+			}
+
+			const fullOutput = Buffer.concat(chunks).toString("utf-8");
+
+			const lines = fullOutput.split("\n");
+			let text: string;
+			if (lines.length > DEFAULT_MAX_LINES) {
+				text = lines.slice(-DEFAULT_MAX_LINES).join("\n");
+				if (spillFilePath) {
+					text += `\n\n[Showing last ${DEFAULT_MAX_LINES} of ${lines.length} lines. Full output: ${spillFilePath}]`;
+				} else {
+					text += `\n\n[Showing last ${DEFAULT_MAX_LINES} of ${lines.length} lines]`;
+				}
+			} else {
+				text = fullOutput || "(no output)";
+			}
+
+			if (code !== 0 && code !== null) {
+				text += `\n\nCommand exited with code ${code}`;
+			}
+
+			resolve(text);
+		});
+	});
+}

package/dist/resources/extensions/async-jobs/await-tool.ts

@@ -0,0 +1,101 @@
+/**
+ * await_job tool — wait for one or more background jobs to complete.
+ *
+ * If specific job IDs are provided, waits for those jobs.
+ * If omitted, waits for any running job to complete.
+ */
+
+import type { ToolDefinition } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { AsyncJobManager, Job } from "./job-manager.js";
+
+const schema = Type.Object({
+	jobs: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Job IDs to wait for. Omit to wait for any running job.",
+		}),
+	),
+});
+
+export function createAwaitTool(getManager: () => AsyncJobManager): ToolDefinition<typeof schema> {
+	return {
+		name: "await_job",
+		label: "Await Background Job",
+		description:
+			"Wait for background jobs to complete. Provide specific job IDs or omit to wait for the next job that finishes. Returns results of completed jobs.",
+		parameters: schema,
+		async execute(_toolCallId, params) {
+			const manager = getManager();
+			const { jobs: jobIds } = params;
+
+			let watched: Job[];
+			if (jobIds && jobIds.length > 0) {
+				watched = [];
+				const notFound: string[] = [];
+				for (const id of jobIds) {
+					const job = manager.getJob(id);
+					if (job) {
+						watched.push(job);
+					} else {
+						notFound.push(id);
+					}
+				}
+				if (notFound.length > 0 && watched.length === 0) {
+					return {
+						content: [{ type: "text", text: `No jobs found: ${notFound.join(", ")}` }],
+					};
+				}
+			} else {
+				watched = manager.getRunningJobs();
+				if (watched.length === 0) {
+					return {
+						content: [{ type: "text", text: "No running background jobs." }],
+					};
+				}
+			}
+
+			// If all watched jobs are already done, return immediately
+			const running = watched.filter((j) => j.status === "running");
+			if (running.length === 0) {
+				const result = formatResults(watched);
+				manager.acknowledgeDeliveries(watched.map((j) => j.id));
+				return { content: [{ type: "text", text: result }] };
+			}
+
+			// Wait for at least one to complete
+			await Promise.race(running.map((j) => j.promise));
+
+			// Collect all completed results (more may have finished while waiting)
+			const completed = watched.filter((j) => j.status !== "running");
+			manager.acknowledgeDeliveries(completed.map((j) => j.id));
+
+			const stillRunning = watched.filter((j) => j.status === "running");
+			let result = formatResults(completed);
+			if (stillRunning.length > 0) {
+				result += `\n\n**Still running:** ${stillRunning.map((j) => `${j.id} (${j.label})`).join(", ")}`;
+			}
+
+			return { content: [{ type: "text", text: result }] };
+		},
+	};
+}
+
+function formatResults(jobs: Job[]): string {
+	if (jobs.length === 0) return "No completed jobs.";
+
+	const parts: string[] = [];
+	for (const job of jobs) {
+		const elapsed = ((Date.now() - job.startTime) / 1000).toFixed(1);
+		const header = `### ${job.id} — ${job.label} (${job.status}, ${elapsed}s)`;
+
+		if (job.status === "completed") {
+			parts.push(`${header}\n\n${job.resultText ?? "(no output)"}`);
+		} else if (job.status === "failed") {
+			parts.push(`${header}\n\nError: ${job.errorText ?? "unknown error"}`);
+		} else if (job.status === "cancelled") {
+			parts.push(`${header}\n\nCancelled.`);
+		}
+	}
+
+	return parts.join("\n\n---\n\n");
+}