@oh-my-pi/pi-coding-agent 1.337.0

package/src/core/system-prompt.ts

@@ -0,0 +1,439 @@
+/**
+ * System prompt construction and project context loading
+ */
+
+import chalk from "chalk";
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+import { getAgentDir, getDocsPath, getExamplesPath, getReadmePath } from "../config.js";
+import type { SkillsSettings } from "./settings-manager.js";
+import { formatSkillsForPrompt, loadSkills, type Skill } from "./skills.js";
+import type { ToolName } from "./tools/index.js";
+
+/**
+ * Execute a git command synchronously and return stdout or null on failure.
+ */
+function execGit(args: string[], cwd: string): string | null {
+	const result = Bun.spawnSync(["git", ...args], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+	if (result.exitCode !== 0) return null;
+	return result.stdout.toString().trim() || null;
+}
+
+/**
+ * Load git context for the system prompt.
+ * Returns formatted git status or null if not in a git repo.
+ */
+export function loadGitContext(cwd: string): string | null {
+	// Check if inside a git repo
+	const isGitRepo = execGit(["rev-parse", "--is-inside-work-tree"], cwd);
+	if (isGitRepo !== "true") return null;
+
+	// Get current branch
+	const currentBranch = execGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+	if (!currentBranch) return null;
+
+	// Detect main branch (check for 'main' first, then 'master')
+	let mainBranch = "main";
+	const mainExists = execGit(["rev-parse", "--verify", "main"], cwd);
+	if (mainExists === null) {
+		const masterExists = execGit(["rev-parse", "--verify", "master"], cwd);
+		if (masterExists !== null) mainBranch = "master";
+	}
+
+	// Get git status (porcelain format for parsing)
+	const gitStatus = execGit(["status", "--porcelain"], cwd);
+	const statusText = gitStatus?.trim() || "(clean)";
+
+	// Get recent commits
+	const recentCommits = execGit(["log", "--oneline", "-5"], cwd);
+	const commitsText = recentCommits?.trim() || "(no commits)";
+
+	return `This is the git status at the start of the conversation. Note that this status is a snapshot in time, and will not update during the conversation.
+Current branch: ${currentBranch}
+
+Main branch (you will usually use this for PRs): ${mainBranch}
+
+Status:
+${statusText}
+
+Recent commits:
+${commitsText}`;
+}
+
+/** Tool descriptions for system prompt */
+const toolDescriptions: Record<ToolName, string> = {
+	ask: "Ask user for input or clarification",
+	read: "Read file contents",
+	bash: "Execute bash commands (git, npm, docker, 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",
+	lsp: "PREFERRED for semantic code queries: go-to-definition, find-all-references, hover (type info), call hierarchy. Returns precise, deterministic results. Use BEFORE grep for symbol lookups.",
+	notebook: "Edit Jupyter notebook cells",
+	task: "Spawn a sub-agent to handle complex tasks",
+	web_fetch: "Fetch and render URLs into clean text for LLM consumption",
+	web_search: "Search the web for information",
+};
+
+/**
+ * Generate anti-bash rules section if the agent has both bash and specialized tools.
+ * Only include rules for tools that are actually available.
+ */
+function generateAntiBashRules(tools: ToolName[]): string | null {
+	const hasBash = tools.includes("bash");
+	if (!hasBash) return null;
+
+	const hasRead = tools.includes("read");
+	const hasGrep = tools.includes("grep");
+	const hasFind = tools.includes("find");
+	const hasLs = tools.includes("ls");
+	const hasEdit = tools.includes("edit");
+	const hasLsp = tools.includes("lsp");
+
+	// Only show rules if we have specialized tools that should be preferred
+	const hasSpecializedTools = hasRead || hasGrep || hasFind || hasLs || hasEdit;
+	if (!hasSpecializedTools) return null;
+
+	const lines: string[] = [];
+	lines.push("## Tool Usage Rules — MANDATORY\n");
+	lines.push("### Forbidden Bash Patterns");
+	lines.push("NEVER use bash for these operations:\n");
+
+	if (hasRead) lines.push("- **File reading**: Use `read` instead of cat/head/tail/less/more");
+	if (hasGrep) lines.push("- **Content search**: Use `grep` instead of grep/rg/ag/ack");
+	if (hasFind) lines.push("- **File finding**: Use `find` instead of find/fd/locate");
+	if (hasLs) lines.push("- **Directory listing**: Use `ls` instead of bash ls");
+	if (hasEdit) lines.push("- **File editing**: Use `edit` instead of sed/awk/perl -pi/echo >/cat <<EOF");
+
+	lines.push("\n### Tool Preference (highest → lowest priority)");
+	const ladder: string[] = [];
+	if (hasLsp) ladder.push("lsp (go-to-definition, references, type info) — DETERMINISTIC");
+	if (hasGrep) ladder.push("grep (text/regex search)");
+	if (hasFind) ladder.push("find (locate files by pattern)");
+	if (hasRead) ladder.push("read (view file contents)");
+	if (hasEdit) ladder.push("edit (precise text replacement)");
+	ladder.push("bash (ONLY for git, npm, docker, make, cargo, etc.)");
+	lines.push(ladder.map((t, i) => `${i + 1}. ${t}`).join("\n"));
+
+	// Add LSP guidance if available
+	if (hasLsp) {
+		lines.push("\n### LSP — Preferred for Semantic Queries");
+		lines.push("Use `lsp` instead of grep/bash when you need:");
+		lines.push("- **Where is X defined?** → `lsp definition`");
+		lines.push("- **What calls X?** → `lsp incoming_calls`");
+		lines.push("- **What does X call?** → `lsp outgoing_calls`");
+		lines.push("- **What type is X?** → `lsp hover`");
+		lines.push("- **What symbols are in this file?** → `lsp symbols`");
+		lines.push("- **Find symbol across codebase** → `lsp workspace_symbols`\n");
+	}
+
+	// Add search-first protocol
+	if (hasGrep || hasFind) {
+		lines.push("\n### Search-First Protocol");
+		lines.push("Before reading any file:");
+		if (hasFind) lines.push("1. Unknown structure → `find` to see file layout");
+		if (hasGrep) lines.push("2. Known location → `grep` for specific symbol/error");
+		if (hasRead) lines.push("3. Use `read offset/limit` for line ranges, not entire large files");
+		lines.push("4. Never read a large file hoping to find something — search first");
+	}
+
+	return lines.join("\n");
+}
+
+/** Resolve input as file path or literal string */
+export function resolvePromptInput(input: string | undefined, description: string): string | undefined {
+	if (!input) {
+		return undefined;
+	}
+
+	if (existsSync(input)) {
+		try {
+			return readFileSync(input, "utf-8");
+		} catch (error) {
+			console.error(chalk.yellow(`Warning: Could not read ${description} file ${input}: ${error}`));
+			return input;
+		}
+	}
+
+	return input;
+}
+
+/** Look for AGENTS.md or CLAUDE.md in a directory (prefers AGENTS.md) */
+function loadContextFileFromDir(dir: string): { path: string; content: string } | null {
+	const candidates = ["AGENTS.md", "CLAUDE.md"];
+	for (const filename of candidates) {
+		const filePath = join(dir, filename);
+		if (existsSync(filePath)) {
+			try {
+				return {
+					path: filePath,
+					content: readFileSync(filePath, "utf-8"),
+				};
+			} catch (error) {
+				console.error(chalk.yellow(`Warning: Could not read ${filePath}: ${error}`));
+			}
+		}
+	}
+	return null;
+}
+
+export interface LoadContextFilesOptions {
+	/** Working directory to start walking up from. Default: process.cwd() */
+	cwd?: string;
+	/** Agent config directory for global context. Default: from getAgentDir() */
+	agentDir?: string;
+}
+
+/**
+ * Load all project context files in order:
+ * 1. Global: agentDir/AGENTS.md or CLAUDE.md
+ * 2. Parent directories (top-most first) down to cwd
+ * Each returns {path, content} for separate messages
+ */
+export function loadProjectContextFiles(
+	options: LoadContextFilesOptions = {},
+): Array<{ path: string; content: string }> {
+	const resolvedCwd = options.cwd ?? process.cwd();
+	const resolvedAgentDir = options.agentDir ?? getAgentDir();
+
+	const contextFiles: Array<{ path: string; content: string }> = [];
+	const seenPaths = new Set<string>();
+
+	// 1. Load global context from agentDir
+	const globalContext = loadContextFileFromDir(resolvedAgentDir);
+	if (globalContext) {
+		contextFiles.push(globalContext);
+		seenPaths.add(globalContext.path);
+	}
+
+	// 2. Walk up from cwd to root, collecting all context files
+	const ancestorContextFiles: Array<{ path: string; content: string }> = [];
+
+	let currentDir = resolvedCwd;
+	const root = resolve("/");
+
+	while (true) {
+		const contextFile = loadContextFileFromDir(currentDir);
+		if (contextFile && !seenPaths.has(contextFile.path)) {
+			// Add to beginning so we get top-most parent first
+			ancestorContextFiles.unshift(contextFile);
+			seenPaths.add(contextFile.path);
+		}
+
+		// Stop if we've reached root
+		if (currentDir === root) break;
+
+		// Move up one directory
+		const parentDir = resolve(currentDir, "..");
+		if (parentDir === currentDir) break; // Safety check
+		currentDir = parentDir;
+	}
+
+	// Add ancestor files in order (top-most → cwd)
+	contextFiles.push(...ancestorContextFiles);
+
+	return contextFiles;
+}
+
+export interface BuildSystemPromptOptions {
+	/** Custom system prompt (replaces default). */
+	customPrompt?: string;
+	/** Tools to include in prompt. Default: [read, bash, edit, write] */
+	selectedTools?: ToolName[];
+	/** Text to append to system prompt. */
+	appendSystemPrompt?: string;
+	/** Skills settings for discovery. */
+	skillsSettings?: SkillsSettings;
+	/** Working directory. Default: process.cwd() */
+	cwd?: string;
+	/** Agent config directory. Default: from getAgentDir() */
+	agentDir?: string;
+	/** Pre-loaded context files (skips discovery if provided). */
+	contextFiles?: Array<{ path: string; content: string }>;
+	/** Pre-loaded skills (skips discovery if provided). */
+	skills?: Skill[];
+}
+
+/** Build the system prompt with tools, guidelines, and context */
+export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {
+	const {
+		customPrompt,
+		selectedTools,
+		appendSystemPrompt,
+		skillsSettings,
+		cwd,
+		agentDir,
+		contextFiles: providedContextFiles,
+		skills: providedSkills,
+	} = options;
+	const resolvedCwd = cwd ?? process.cwd();
+	const resolvedCustomPrompt = resolvePromptInput(customPrompt, "system prompt");
+	const resolvedAppendPrompt = resolvePromptInput(appendSystemPrompt, "append system prompt");
+
+	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 = resolvedAppendPrompt ? `\n\n${resolvedAppendPrompt}` : "";
+
+	// Resolve context files: use provided or discover
+	const contextFiles = providedContextFiles ?? loadProjectContextFiles({ cwd: resolvedCwd, agentDir });
+
+	// Resolve skills: use provided or discover
+	const skills =
+		providedSkills ??
+		(skillsSettings?.enabled !== false ? loadSkills({ ...skillsSettings, cwd: resolvedCwd, agentDir }).skills : []);
+
+	if (resolvedCustomPrompt) {
+		let prompt = resolvedCustomPrompt;
+
+		if (appendSection) {
+			prompt += appendSection;
+		}
+
+		// Append project context files
+		if (contextFiles.length > 0) {
+			prompt += "\n\n# Project Context\n\n";
+			prompt += "The following project context files have been loaded:\n\n";
+			for (const { path: filePath, content } of contextFiles) {
+				prompt += `## ${filePath}\n\n${content}\n\n`;
+			}
+		}
+
+		// Append git context if in a git repo
+		const gitContext = loadGitContext(resolvedCwd);
+		if (gitContext) {
+			prompt += `\n\n# Git Status\n\n${gitContext}`;
+		}
+
+		// 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
+	const tools = selectedTools || (["read", "bash", "edit", "write"] as ToolName[]);
+	const toolsList = tools.map((t) => `- ${t}: ${toolDescriptions[t]}`).join("\n");
+
+	// Generate anti-bash rules (returns null if not applicable)
+	const antiBashSection = generateAntiBashRules(tools);
+
+	// Build guidelines based on which tools are actually available
+	const guidelinesList: string[] = [];
+
+	const hasBash = tools.includes("bash");
+	const hasEdit = tools.includes("edit");
+	const hasWrite = tools.includes("write");
+	const hasRead = tools.includes("read");
+
+	// Read-only mode notice (no bash, edit, or write)
+	if (!hasBash && !hasEdit && !hasWrite) {
+		guidelinesList.push("You are in READ-ONLY mode - you cannot modify files or execute arbitrary commands");
+	}
+
+	// Bash without edit/write = read-only bash mode
+	if (hasBash && !hasEdit && !hasWrite) {
+		guidelinesList.push(
+			"Use bash ONLY for read-only operations (git log, gh issue view, curl, etc.) - do NOT modify any files",
+		);
+	}
+
+	// Read before edit guideline
+	if (hasRead && hasEdit) {
+		guidelinesList.push("Use read to examine files before editing");
+	}
+
+	// Edit guideline
+	if (hasEdit) {
+		guidelinesList.push(
+			"Use edit for precise changes (old text must match exactly, fuzzy matching handles whitespace)",
+		);
+	}
+
+	// Write guideline
+	if (hasWrite) {
+		guidelinesList.push("Use write only for new files or complete rewrites");
+	}
+
+	// Output guideline (only when actually writing/executing)
+	if (hasEdit || hasWrite) {
+		guidelinesList.push(
+			"When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did",
+		);
+	}
+
+	// Always include these
+	guidelinesList.push("Be concise in your responses");
+	guidelinesList.push("Show file paths clearly when working with files");
+
+	const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
+
+	// Build the prompt with anti-bash rules prominently placed
+	let prompt = `You are an expert coding assistant. You help users with coding tasks by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+${toolsList}
+${antiBashSection ? `\n${antiBashSection}\n` : ""}
+Guidelines:
+${guidelines}
+
+Documentation:
+- Main documentation: ${readmePath}
+- Additional docs: ${docsPath}
+- Examples: ${examplesPath} (hooks, custom tools, SDK)
+- When asked to create: custom models/providers (README.md), hooks (docs/hooks.md, examples/hooks/), custom tools (docs/custom-tools.md, docs/tui.md, examples/custom-tools/), themes (docs/theme.md), skills (docs/skills.md)
+- Always read the doc, examples, AND follow .md cross-references before implementing`;
+
+	if (appendSection) {
+		prompt += appendSection;
+	}
+
+	// Append project context files
+	if (contextFiles.length > 0) {
+		prompt += "\n\n# Project Context\n\n";
+		prompt += "The following project context files have been loaded:\n\n";
+		for (const { path: filePath, content } of contextFiles) {
+			prompt += `## ${filePath}\n\n${content}\n\n`;
+		}
+	}
+
+	// Append git context if in a git repo
+	const gitContext = loadGitContext(resolvedCwd);
+	if (gitContext) {
+		prompt += `\n\n# Git Status\n\n${gitContext}`;
+	}
+
+	// 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/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/src/core/tools/ask.ts

@@ -0,0 +1,211 @@
+/**
+ * Ask Tool - Interactive user prompting during execution
+ *
+ * Use this tool when you need to ask the user questions during execution.
+ * This allows you to:
+ *   1. Gather user preferences or requirements
+ *   2. Clarify ambiguous instructions
+ *   3. Get decisions on implementation choices as you work
+ *   4. Offer choices to the user about what direction to take
+ *
+ * Usage notes:
+ *   - Users will always be able to select "Other" to provide custom text input
+ *   - Use multi: true to allow multiple answers to be selected for a question
+ *   - If you recommend a specific option, make that the first option in the list
+ *     and add "(Recommended)" at the end of the label
+ */
+
+import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+const OptionItem = Type.Object({
+	label: Type.String({ description: "Display label for this option" }),
+});
+
+const askSchema = Type.Object({
+	question: Type.String({ description: "The question to ask the user" }),
+	options: Type.Array(OptionItem, {
+		description: "Available options for the user to choose from.",
+		minItems: 1,
+	}),
+	multi: Type.Optional(
+		Type.Boolean({
+			description: "Allow multiple options to be selected (default: false)",
+			default: false,
+		}),
+	),
+});
+
+export interface AskToolDetails {
+	question: string;
+	options: string[];
+	multi: boolean;
+	selectedOptions: string[];
+	customInput?: string;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const OTHER_OPTION = "Other (type your own)";
+const DONE_OPTION = "✓ Done selecting";
+
+const DESCRIPTION = `Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- Users will always be able to select "Other" to provide custom text input
+- Use multi: true to allow multiple answers to be selected for a question
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+
+Example usage:
+
+<example>
+assistant: Let me ask which features you want to include.
+assistant: Uses the ask tool:
+{
+  "question": "Which features should I implement?",
+  "options": [
+    {"label": "Authentication"},
+    {"label": "API endpoints"},
+    {"label": "Database models"},
+    {"label": "Unit tests"},
+    {"label": "Documentation"}
+  ],
+  "multi": true
+}
+</example>`;
+
+// =============================================================================
+// Tool Implementation
+// =============================================================================
+
+export function createAskTool(_cwd: string): AgentTool<typeof askSchema, AskToolDetails> {
+	return {
+		name: "ask",
+		label: "Ask",
+		description: DESCRIPTION,
+		parameters: askSchema,
+
+		async execute(
+			_toolCallId: string,
+			params: { question: string; options: Array<{ label: string }>; multi?: boolean },
+			_signal?: AbortSignal,
+			_onUpdate?: AgentToolUpdateCallback<AskToolDetails>,
+			context?: AgentToolContext,
+		) {
+			const { question, options, multi = false } = params;
+			const optionLabels = options.map((o) => o.label);
+
+			// Headless fallback - return error if no UI available
+			if (!context?.hasUI || !context.ui) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Error: User prompt requires interactive mode",
+						},
+					],
+					details: {
+						question,
+						options: optionLabels,
+						multi,
+						selectedOptions: [],
+					},
+				};
+			}
+
+			const { ui } = context;
+			let selectedOptions: string[] = [];
+			let customInput: string | undefined;
+
+			if (multi) {
+				// Multi-select: show checkboxes in the label to indicate selection state
+				const selected = new Set<string>();
+
+				while (true) {
+					// Build options with checkbox indicators
+					const opts: string[] = [];
+
+					// Add "Done" option if any selected
+					if (selected.size > 0) {
+						opts.push(DONE_OPTION);
+					}
+
+					// Add all options with [X] or [ ] prefix
+					for (const opt of optionLabels) {
+						const checkbox = selected.has(opt) ? "[X]" : "[ ]";
+						opts.push(`${checkbox} ${opt}`);
+					}
+
+					// Add "Other" option
+					opts.push(OTHER_OPTION);
+
+					const prefix = selected.size > 0 ? `(${selected.size} selected) ` : "";
+					const choice = await ui.select(`${prefix}${question}`, opts);
+
+					if (choice === undefined || choice === DONE_OPTION) break;
+
+					if (choice === OTHER_OPTION) {
+						const input = await ui.input("Enter your response:");
+						if (input) customInput = input;
+						break;
+					}
+
+					// Toggle selection - extract the actual option name
+					const optMatch = choice.match(/^\[.\] (.+)$/);
+					if (optMatch) {
+						const opt = optMatch[1];
+						if (selected.has(opt)) {
+							selected.delete(opt);
+						} else {
+							selected.add(opt);
+						}
+					}
+				}
+				selectedOptions = Array.from(selected);
+			} else {
+				// Single select with "Other" option
+				const choice = await ui.select(question, [...optionLabels, OTHER_OPTION]);
+				if (choice === OTHER_OPTION) {
+					const input = await ui.input("Enter your response:");
+					if (input) customInput = input;
+				} else if (choice) {
+					selectedOptions = [choice];
+				}
+			}
+
+			const details: AskToolDetails = {
+				question,
+				options: optionLabels,
+				multi,
+				selectedOptions,
+				customInput,
+			};
+
+			let responseText: string;
+			if (customInput) {
+				responseText = `User provided custom input: ${customInput}`;
+			} else if (selectedOptions.length > 0) {
+				responseText = multi
+					? `User selected: ${selectedOptions.join(", ")}`
+					: `User selected: ${selectedOptions[0]}`;
+			} else {
+				responseText = "User cancelled the selection";
+			}
+
+			return { content: [{ type: "text" as const, text: responseText }], details };
+		},
+	};
+}
+
+/** Default ask tool using process.cwd() - for backwards compatibility (no UI) */
+export const askTool = createAskTool(process.cwd());