gsd-pi 2.5.1 → 2.7.0

package/packages/pi-coding-agent/src/core/system-prompt.ts

@@ -0,0 +1,218 @@
+/**
+ * System prompt construction and project context loading
+ */
+
+import { getDocsPath, getExamplesPath, getReadmePath } from "../config.js";
+import { formatSkillsForPrompt, type Skill } from "./skills.js";
+
+/** Tool descriptions for system prompt */
+const toolDescriptions: Record<string, string> = {
+	read: "Read file contents",
+	bash: "Execute bash commands (ls, grep, find, etc.)",
+	edit: "Make surgical edits to files (find exact text and replace)",
+	write: "Create or overwrite files",
+	grep: "Search file contents for patterns (respects .gitignore)",
+	find: "Find files by glob pattern (respects .gitignore)",
+	ls: "List directory contents",
+};
+
+export interface BuildSystemPromptOptions {
+	/** Custom system prompt (replaces default). */
+	customPrompt?: string;
+	/** Tools to include in prompt. Default: [read, bash, edit, write] */
+	selectedTools?: string[];
+	/** Optional one-line tool snippets keyed by tool name. */
+	toolSnippets?: Record<string, string>;
+	/** Additional guideline bullets appended to the default system prompt guidelines. */
+	promptGuidelines?: string[];
+	/** Text to append to system prompt. */
+	appendSystemPrompt?: string;
+	/** Working directory. Default: process.cwd() */
+	cwd?: string;
+	/** Pre-loaded context files. */
+	contextFiles?: Array<{ path: string; content: string }>;
+	/** Pre-loaded skills. */
+	skills?: Skill[];
+}
+
+/** Build the system prompt with tools, guidelines, and context */
+export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {
+	const {
+		customPrompt,
+		selectedTools,
+		toolSnippets,
+		promptGuidelines,
+		appendSystemPrompt,
+		cwd,
+		contextFiles: providedContextFiles,
+		skills: providedSkills,
+	} = options;
+	const resolvedCwd = cwd ?? process.cwd();
+
+	const now = new Date();
+	const dateTime = now.toLocaleString("en-US", {
+		weekday: "long",
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		timeZoneName: "short",
+	});
+
+	const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
+
+	const contextFiles = providedContextFiles ?? [];
+	const skills = providedSkills ?? [];
+
+	if (customPrompt) {
+		let prompt = customPrompt;
+
+		if (appendSection) {
+			prompt += appendSection;
+		}
+
+		// Append project context files
+		if (contextFiles.length > 0) {
+			prompt += "\n\n# Project Context\n\n";
+			prompt += "Project-specific instructions and guidelines:\n\n";
+			for (const { path: filePath, content } of contextFiles) {
+				prompt += `## ${filePath}\n\n${content}\n\n`;
+			}
+		}
+
+		// Append skills section (only if read tool is available)
+		const customPromptHasRead = !selectedTools || selectedTools.includes("read");
+		if (customPromptHasRead && skills.length > 0) {
+			prompt += formatSkillsForPrompt(skills);
+		}
+
+		// Add date/time and working directory last
+		prompt += `\nCurrent date and time: ${dateTime}`;
+		prompt += `\nCurrent working directory: ${resolvedCwd}`;
+
+		return prompt;
+	}
+
+	// Get absolute paths to documentation and examples
+	const readmePath = getReadmePath();
+	const docsPath = getDocsPath();
+	const examplesPath = getExamplesPath();
+
+	// Build tools list based on selected tools.
+	// Built-ins use toolDescriptions. Custom tools can provide one-line snippets.
+	const tools = selectedTools || ["read", "bash", "edit", "write"];
+	const toolsList =
+		tools.length > 0
+			? tools
+					.map((name) => {
+						const snippet = toolSnippets?.[name] ?? toolDescriptions[name] ?? name;
+						return `- ${name}: ${snippet}`;
+					})
+					.join("\n")
+			: "(none)";
+
+	// Build guidelines based on which tools are actually available
+	const guidelinesList: string[] = [];
+	const guidelinesSet = new Set<string>();
+	const addGuideline = (guideline: string): void => {
+		if (guidelinesSet.has(guideline)) {
+			return;
+		}
+		guidelinesSet.add(guideline);
+		guidelinesList.push(guideline);
+	};
+
+	const hasBash = tools.includes("bash");
+	const hasEdit = tools.includes("edit");
+	const hasWrite = tools.includes("write");
+	const hasGrep = tools.includes("grep");
+	const hasFind = tools.includes("find");
+	const hasLs = tools.includes("ls");
+	const hasRead = tools.includes("read");
+
+	// File exploration guidelines
+	if (hasBash && !hasGrep && !hasFind && !hasLs) {
+		addGuideline("Use bash for file operations like ls, rg, find");
+	} else if (hasBash && (hasGrep || hasFind || hasLs)) {
+		addGuideline("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
+	}
+
+	// Read before edit guideline
+	if (hasRead && hasEdit) {
+		addGuideline("Use read to examine files before editing. You must use this tool instead of cat or sed.");
+	}
+
+	// Edit guideline
+	if (hasEdit) {
+		addGuideline("Use edit for precise changes (old text must match exactly)");
+	}
+
+	// Write guideline
+	if (hasWrite) {
+		addGuideline("Use write only for new files or complete rewrites");
+	}
+
+	// Output guideline (only when actually writing or executing)
+	if (hasEdit || hasWrite) {
+		addGuideline(
+			"When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did",
+		);
+	}
+
+	for (const guideline of promptGuidelines ?? []) {
+		const normalized = guideline.trim();
+		if (normalized.length > 0) {
+			addGuideline(normalized);
+		}
+	}
+
+	// Always include these
+	addGuideline("Be concise in your responses");
+	addGuideline("Show file paths clearly when working with files");
+
+	const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
+
+	let prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+${toolsList}
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+${guidelines}
+
+Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
+- Main documentation: ${readmePath}
+- Additional docs: ${docsPath}
+- Examples: ${examplesPath} (extensions, custom tools, SDK)
+- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
+- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
+- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
+
+	if (appendSection) {
+		prompt += appendSection;
+	}
+
+	// Append project context files
+	if (contextFiles.length > 0) {
+		prompt += "\n\n# Project Context\n\n";
+		prompt += "Project-specific instructions and guidelines:\n\n";
+		for (const { path: filePath, content } of contextFiles) {
+			prompt += `## ${filePath}\n\n${content}\n\n`;
+		}
+	}
+
+	// Append skills section (only if read tool is available)
+	if (hasRead && skills.length > 0) {
+		prompt += formatSkillsForPrompt(skills);
+	}
+
+	// Add date/time and working directory last
+	prompt += `\nCurrent date and time: ${dateTime}`;
+	prompt += `\nCurrent working directory: ${resolvedCwd}`;
+
+	return prompt;
+}

package/packages/pi-coding-agent/src/core/timings.ts

@@ -0,0 +1,25 @@
+/**
+ * Central timing instrumentation for startup profiling.
+ * Enable with PI_TIMING=1 environment variable.
+ */
+
+const ENABLED = process.env.PI_TIMING === "1";
+const timings: Array<{ label: string; ms: number }> = [];
+let lastTime = Date.now();
+
+export function time(label: string): void {
+	if (!ENABLED) return;
+	const now = Date.now();
+	timings.push({ label, ms: now - lastTime });
+	lastTime = now;
+}
+
+export function printTimings(): void {
+	if (!ENABLED || timings.length === 0) return;
+	console.error("\n--- Startup Timings ---");
+	for (const t of timings) {
+		console.error(`  ${t.label}: ${t.ms}ms`);
+	}
+	console.error(`  TOTAL: ${timings.reduce((a, b) => a + b.ms, 0)}ms`);
+	console.error("------------------------\n");
+}

package/packages/pi-coding-agent/src/core/tools/bash.ts

@@ -0,0 +1,347 @@
+import { randomBytes } from "node:crypto";
+import { createWriteStream, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentTool } from "@gsd/pi-agent-core";
+import { type Static, Type } from "@sinclair/typebox";
+import { spawn } from "child_process";
+import { getShellConfig, getShellEnv, killProcessTree } from "../../utils/shell.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateTail } from "./truncate.js";
+
+// Cached Win32 FFI handles for restoring VT input after child processes
+let _vtHandles: { GetConsoleMode: any; SetConsoleMode: any; handle: any } | null = null;
+function restoreWindowsVTInput(): void {
+	if (process.platform !== "win32") return;
+	try {
+		if (!_vtHandles) {
+			const cjsRequire = createRequire(import.meta.url);
+			const koffi = cjsRequire("koffi");
+			const k32 = koffi.load("kernel32.dll");
+			const GetStdHandle = k32.func("void* __stdcall GetStdHandle(int)");
+			const GetConsoleMode = k32.func("bool __stdcall GetConsoleMode(void*, _Out_ uint32_t*)");
+			const SetConsoleMode = k32.func("bool __stdcall SetConsoleMode(void*, uint32_t)");
+			const handle = GetStdHandle(-10);
+			_vtHandles = { GetConsoleMode, SetConsoleMode, handle };
+		}
+		const ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200;
+		const mode = new Uint32Array(1);
+		_vtHandles.GetConsoleMode(_vtHandles.handle, mode);
+		if (!(mode[0]! & ENABLE_VIRTUAL_TERMINAL_INPUT)) {
+			_vtHandles.SetConsoleMode(_vtHandles.handle, mode[0]! | ENABLE_VIRTUAL_TERMINAL_INPUT);
+		}
+	} catch { /* koffi not available */ }
+}
+
+/**
+ * Generate a unique temp file path for bash output
+ */
+function getTempFilePath(): string {
+	const id = randomBytes(8).toString("hex");
+	return join(tmpdir(), `pi-bash-${id}.log`);
+}
+
+const bashSchema = Type.Object({
+	command: Type.String({ description: "Bash command to execute" }),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
+});
+
+export type BashToolInput = Static<typeof bashSchema>;
+
+export interface BashToolDetails {
+	truncation?: TruncationResult;
+	fullOutputPath?: string;
+}
+
+/**
+ * Pluggable operations for the bash tool.
+ * Override these to delegate command execution to remote systems (e.g., SSH).
+ */
+export interface BashOperations {
+	/**
+	 * Execute a command and stream output.
+	 * @param command - The command to execute
+	 * @param cwd - Working directory
+	 * @param options - Execution options
+	 * @returns Promise resolving to exit code (null if killed)
+	 */
+	exec: (
+		command: string,
+		cwd: string,
+		options: {
+			onData: (data: Buffer) => void;
+			signal?: AbortSignal;
+			timeout?: number;
+			env?: NodeJS.ProcessEnv;
+		},
+	) => Promise<{ exitCode: number | null }>;
+}
+
+/**
+ * Default bash operations using local shell
+ */
+const defaultBashOperations: BashOperations = {
+	exec: (command, cwd, { onData, signal, timeout, env }) => {
+		return new Promise((resolve, reject) => {
+			const { shell, args } = getShellConfig();
+
+			if (!existsSync(cwd)) {
+				reject(new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`));
+				return;
+			}
+
+			const child = spawn(shell, [...args, command], {
+				cwd,
+				detached: true,
+				env: env ?? getShellEnv(),
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+
+			let timedOut = false;
+
+			// Set timeout if provided
+			let timeoutHandle: NodeJS.Timeout | undefined;
+			if (timeout !== undefined && timeout > 0) {
+				timeoutHandle = setTimeout(() => {
+					timedOut = true;
+					if (child.pid) {
+						killProcessTree(child.pid);
+					}
+				}, timeout * 1000);
+			}
+
+			// Stream stdout and stderr
+			if (child.stdout) {
+				child.stdout.on("data", onData);
+			}
+			if (child.stderr) {
+				child.stderr.on("data", onData);
+			}
+
+			// Handle shell spawn errors
+			child.on("error", (err) => {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+				if (signal) signal.removeEventListener("abort", onAbort);
+				reject(err);
+			});
+
+			// Handle abort signal - kill entire process tree
+			const onAbort = () => {
+				if (child.pid) {
+					killProcessTree(child.pid);
+				}
+			};
+
+			if (signal) {
+				if (signal.aborted) {
+					onAbort();
+				} else {
+					signal.addEventListener("abort", onAbort, { once: true });
+				}
+			}
+
+			// Handle process exit
+			child.on("close", (code) => {
+				restoreWindowsVTInput();
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+				if (signal) signal.removeEventListener("abort", onAbort);
+
+				if (signal?.aborted) {
+					reject(new Error("aborted"));
+					return;
+				}
+
+				if (timedOut) {
+					reject(new Error(`timeout:${timeout}`));
+					return;
+				}
+
+				resolve({ exitCode: code });
+			});
+		});
+	},
+};
+
+export interface BashSpawnContext {
+	command: string;
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+}
+
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+
+function resolveSpawnContext(command: string, cwd: string, spawnHook?: BashSpawnHook): BashSpawnContext {
+	const baseContext: BashSpawnContext = {
+		command,
+		cwd,
+		env: { ...getShellEnv() },
+	};
+
+	return spawnHook ? spawnHook(baseContext) : baseContext;
+}
+
+export interface BashToolOptions {
+	/** Custom operations for command execution. Default: local shell */
+	operations?: BashOperations;
+	/** Command prefix prepended to every command (e.g., "shopt -s expand_aliases" for alias support) */
+	commandPrefix?: string;
+	/** Hook to adjust command, cwd, or env before execution */
+	spawnHook?: BashSpawnHook;
+}
+
+export function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema> {
+	const ops = options?.operations ?? defaultBashOperations;
+	const commandPrefix = options?.commandPrefix;
+	const spawnHook = options?.spawnHook;
+
+	return {
+		name: "bash",
+		label: "bash",
+		description: `Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
+		parameters: bashSchema,
+		execute: async (
+			_toolCallId: string,
+			{ command, timeout }: { command: string; timeout?: number },
+			signal?: AbortSignal,
+			onUpdate?,
+		) => {
+			// Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
+			const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
+			const spawnContext = resolveSpawnContext(resolvedCommand, cwd, spawnHook);
+
+			return new Promise((resolve, reject) => {
+				// We'll stream to a temp file if output gets large
+				let tempFilePath: string | undefined;
+				let tempFileStream: ReturnType<typeof createWriteStream> | undefined;
+				let totalBytes = 0;
+
+				// Keep a rolling buffer of the last chunk for tail truncation
+				const chunks: Buffer[] = [];
+				let chunksBytes = 0;
+				// Keep more than we need so we have enough for truncation
+				const maxChunksBytes = DEFAULT_MAX_BYTES * 2;
+
+				const handleData = (data: Buffer) => {
+					totalBytes += data.length;
+
+					// Start writing to temp file once we exceed the threshold
+					if (totalBytes > DEFAULT_MAX_BYTES && !tempFilePath) {
+						tempFilePath = getTempFilePath();
+						tempFileStream = createWriteStream(tempFilePath);
+						// Write all buffered chunks to the file
+						for (const chunk of chunks) {
+							tempFileStream.write(chunk);
+						}
+					}
+
+					// Write to temp file if we have one
+					if (tempFileStream) {
+						tempFileStream.write(data);
+					}
+
+					// Keep rolling buffer of recent data
+					chunks.push(data);
+					chunksBytes += data.length;
+
+					// Trim old chunks if buffer is too large
+					while (chunksBytes > maxChunksBytes && chunks.length > 1) {
+						const removed = chunks.shift()!;
+						chunksBytes -= removed.length;
+					}
+
+					// Stream partial output to callback (truncated rolling buffer)
+					if (onUpdate) {
+						const fullBuffer = Buffer.concat(chunks);
+						const fullText = fullBuffer.toString("utf-8");
+						const truncation = truncateTail(fullText);
+						onUpdate({
+							content: [{ type: "text", text: truncation.content || "" }],
+							details: {
+								truncation: truncation.truncated ? truncation : undefined,
+								fullOutputPath: tempFilePath,
+							},
+						});
+					}
+				};
+
+				ops.exec(spawnContext.command, spawnContext.cwd, {
+					onData: handleData,
+					signal,
+					timeout,
+					env: spawnContext.env,
+				})
+					.then(({ exitCode }) => {
+						// Close temp file stream
+						if (tempFileStream) {
+							tempFileStream.end();
+						}
+
+						// Combine all buffered chunks
+						const fullBuffer = Buffer.concat(chunks);
+						const fullOutput = fullBuffer.toString("utf-8");
+
+						// Apply tail truncation
+						const truncation = truncateTail(fullOutput);
+						let outputText = truncation.content || "(no output)";
+
+						// Build details with truncation info
+						let details: BashToolDetails | undefined;
+
+						if (truncation.truncated) {
+							details = {
+								truncation,
+								fullOutputPath: tempFilePath,
+							};
+
+							// Build actionable notice
+							const startLine = truncation.totalLines - truncation.outputLines + 1;
+							const endLine = truncation.totalLines;
+
+							if (truncation.lastLinePartial) {
+								// Edge case: last line alone > 30KB
+								const lastLineSize = formatSize(Buffer.byteLength(fullOutput.split("\n").pop() || "", "utf-8"));
+								outputText += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${tempFilePath}]`;
+							} else if (truncation.truncatedBy === "lines") {
+								outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${tempFilePath}]`;
+							} else {
+								outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${tempFilePath}]`;
+							}
+						}
+
+						if (exitCode !== 0 && exitCode !== null) {
+							outputText += `\n\nCommand exited with code ${exitCode}`;
+							reject(new Error(outputText));
+						} else {
+							resolve({ content: [{ type: "text", text: outputText }], details });
+						}
+					})
+					.catch((err: Error) => {
+						// Close temp file stream
+						if (tempFileStream) {
+							tempFileStream.end();
+						}
+
+						// Combine all buffered chunks for error output
+						const fullBuffer = Buffer.concat(chunks);
+						let output = fullBuffer.toString("utf-8");
+
+						if (err.message === "aborted") {
+							if (output) output += "\n\n";
+							output += "Command aborted";
+							reject(new Error(output));
+						} else if (err.message.startsWith("timeout:")) {
+							const timeoutSecs = err.message.split(":")[1];
+							if (output) output += "\n\n";
+							output += `Command timed out after ${timeoutSecs} seconds`;
+							reject(new Error(output));
+						} else {
+							reject(err);
+						}
+					});
+			});
+		},
+	};
+}
+
+/** Default bash tool using process.cwd() - for backwards compatibility */
+export const bashTool = createBashTool(process.cwd());