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

package/src/core/tools/review.ts

@@ -0,0 +1,275 @@
+/**
+ * Review tools - report_finding and submit_review
+ *
+ * Used by the reviewer agent to report findings in a structured way.
+ * Both tools are hidden by default - only enabled when explicitly listed in agent's tools.
+ */
+
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-tui";
+import { Container, Spacer, Text } from "@oh-my-pi/pi-tui";
+import { Type } from "@sinclair/typebox";
+import type { Theme } from "../../modes/interactive/theme/theme";
+import { theme } from "../../modes/interactive/theme/theme";
+
+const PRIORITY_LABELS: Record<number, string> = {
+	0: "P0",
+	1: "P1",
+	2: "P2",
+	3: "P3",
+};
+
+const _PRIORITY_DESCRIPTIONS: Record<number, string> = {
+	0: "Drop everything to fix. Blocking release, operations, or major usage.",
+	1: "Urgent. Should be addressed in the next cycle.",
+	2: "Normal. To be fixed eventually.",
+	3: "Low. Nice to have.",
+};
+
+// report_finding schema
+const ReportFindingParams = Type.Object({
+	title: Type.String({
+		description: "≤80 chars, imperative, prefixed with [P0-P3]. E.g., '[P1] Un-padding slices along wrong dimension'",
+	}),
+	body: Type.String({
+		description: "Markdown explaining why this is a problem. One paragraph max.",
+	}),
+	priority: Type.Union([Type.Literal(0), Type.Literal(1), Type.Literal(2), Type.Literal(3)], {
+		description: "0=P0 (critical), 1=P1 (urgent), 2=P2 (normal), 3=P3 (low)",
+	}),
+	confidence: Type.Number({
+		minimum: 0,
+		maximum: 1,
+		description: "Confidence score 0.0-1.0",
+	}),
+	file_path: Type.String({ description: "Absolute path to the file" }),
+	line_start: Type.Number({ description: "Start line of the issue" }),
+	line_end: Type.Number({ description: "End line of the issue" }),
+});
+
+interface ReportFindingDetails {
+	title: string;
+	body: string;
+	priority: number;
+	confidence: number;
+	file_path: string;
+	line_start: number;
+	line_end: number;
+}
+
+export const reportFindingTool: AgentTool<typeof ReportFindingParams, ReportFindingDetails, Theme> = {
+	name: "report_finding",
+	label: "Report Finding",
+	description: "Report a code review finding. Use this for each issue found. Call submit_review when done.",
+	parameters: ReportFindingParams,
+	hidden: true,
+
+	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		const { title, body, priority, confidence, file_path, line_start, line_end } = params;
+		const location = `${file_path}:${line_start}${line_end !== line_start ? `-${line_end}` : ""}`;
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Finding recorded: ${PRIORITY_LABELS[priority]} ${title}\nLocation: ${location}\nConfidence: ${(confidence * 100).toFixed(0)}%`,
+				},
+			],
+			details: { title, body, priority, confidence, file_path, line_start, line_end },
+		};
+	},
+
+	renderCall(args, theme): Component {
+		const priority = PRIORITY_LABELS[args.priority as number] ?? "P?";
+		const color = args.priority === 0 ? "error" : args.priority === 1 ? "warning" : "muted";
+		const titleText = String(args.title).replace(/^\[P\d\]\s*/, "");
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("report_finding "))}${theme.fg(color, `[${priority}]`)} ${theme.fg("dim", titleText)}`,
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, _options, theme): Component {
+		const { details } = result;
+		if (!details) {
+			const text = result.content[0];
+			return new Text(text?.type === "text" ? text.text : "", 0, 0);
+		}
+
+		const priority = PRIORITY_LABELS[details.priority] ?? "P?";
+		const color = details.priority === 0 ? "error" : details.priority === 1 ? "warning" : "muted";
+		const location = `${details.file_path}:${details.line_start}${details.line_end !== details.line_start ? `-${details.line_end}` : ""}`;
+
+		return new Text(
+			`${theme.fg("success", theme.status.success)} ${theme.fg(color, `[${priority}]`)} ${theme.fg("dim", location)}`,
+			0,
+			0,
+		);
+	},
+};
+
+// submit_review schema
+const SubmitReviewParams = Type.Object({
+	overall_correctness: Type.Union([Type.Literal("correct"), Type.Literal("incorrect")], {
+		description: "Whether the patch is correct (no bugs, tests won't break)",
+	}),
+	explanation: Type.String({
+		description: "1-3 sentence explanation justifying the verdict",
+	}),
+	confidence: Type.Number({
+		minimum: 0,
+		maximum: 1,
+		description: "Overall confidence score 0.0-1.0",
+	}),
+});
+
+interface SubmitReviewDetails {
+	overall_correctness: "correct" | "incorrect";
+	explanation: string;
+	confidence: number;
+}
+
+export const submitReviewTool: AgentTool<typeof SubmitReviewParams, SubmitReviewDetails, Theme> = {
+	name: "submit_review",
+	label: "Submit Review",
+	description: "Submit the final review verdict. Call this after all findings have been reported.",
+	parameters: SubmitReviewParams,
+	hidden: true,
+
+	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		const { overall_correctness, explanation, confidence } = params;
+
+		let summary = `## Review Summary\n\n`;
+		summary += `**Verdict:** ${overall_correctness === "correct" ? `${theme.status.success} Patch is correct` : `${theme.status.error} Patch is incorrect`}\n`;
+		summary += `**Confidence:** ${(confidence * 100).toFixed(0)}%\n\n`;
+		summary += explanation;
+
+		return {
+			content: [{ type: "text", text: summary }],
+			details: { overall_correctness, explanation, confidence },
+		};
+	},
+
+	renderCall(args, theme): Component {
+		const verdict = args.overall_correctness === "correct" ? "correct" : "incorrect";
+		const color = args.overall_correctness === "correct" ? "success" : "error";
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("submit_review "))}${theme.fg(color, verdict)} ${theme.fg("dim", `(${((args.confidence as number) * 100).toFixed(0)}%)`)}`,
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, { expanded }, theme): Component {
+		const { details } = result;
+		if (!details) {
+			const text = result.content[0];
+			return new Text(text?.type === "text" ? text.text : "", 0, 0);
+		}
+
+		const container = new Container();
+		const verdictColor = details.overall_correctness === "correct" ? "success" : "error";
+		const verdictIcon = details.overall_correctness === "correct" ? theme.status.success : theme.status.error;
+
+		container.addChild(
+			new Text(
+				`${theme.fg(verdictColor, verdictIcon)} Patch is ${theme.fg(verdictColor, details.overall_correctness)} ${theme.fg("dim", `(${(details.confidence * 100).toFixed(0)}% confidence)`)}`,
+				0,
+				0,
+			),
+		);
+
+		if (expanded) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(theme.fg("dim", details.explanation), 0, 0));
+		}
+
+		return container;
+	},
+};
+
+export function createReportFindingTool(): AgentTool<typeof ReportFindingParams, ReportFindingDetails, Theme> {
+	return reportFindingTool;
+}
+
+export function createSubmitReviewTool(): AgentTool<typeof SubmitReviewParams, SubmitReviewDetails, Theme> {
+	return submitReviewTool;
+}
+
+// Re-export types for external use
+export type { ReportFindingDetails, SubmitReviewDetails };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Subprocess tool handlers - registered for extraction/rendering in task tool
+// ─────────────────────────────────────────────────────────────────────────────
+
+import path from "node:path";
+import { subprocessToolRegistry } from "./task/subprocess-tool-registry";
+
+// Register report_finding handler
+subprocessToolRegistry.register<ReportFindingDetails>("report_finding", {
+	extractData: (event) => event.result?.details as ReportFindingDetails | undefined,
+
+	renderInline: (data, theme) => {
+		const priority = PRIORITY_LABELS[data.priority] ?? "P?";
+		const color = data.priority === 0 ? "error" : data.priority === 1 ? "warning" : "muted";
+		const titleText = data.title.replace(/^\[P\d\]\s*/, "");
+		const loc = `${path.basename(data.file_path)}:${data.line_start}`;
+		return new Text(`${theme.fg(color, `[${priority}]`)} ${titleText} ${theme.fg("dim", loc)}`, 0, 0);
+	},
+
+	renderFinal: (allData, theme, expanded) => {
+		const container = new Container();
+		const displayCount = expanded ? allData.length : Math.min(3, allData.length);
+
+		for (let i = 0; i < displayCount; i++) {
+			const data = allData[i];
+			const priority = PRIORITY_LABELS[data.priority] ?? "P?";
+			const color = data.priority === 0 ? "error" : data.priority === 1 ? "warning" : "muted";
+			const titleText = data.title.replace(/^\[P\d\]\s*/, "");
+			const loc = `${path.basename(data.file_path)}:${data.line_start}`;
+
+			container.addChild(
+				new Text(`  ${theme.fg(color, `[${priority}]`)} ${titleText} ${theme.fg("dim", loc)}`, 0, 0),
+			);
+
+			if (expanded && data.body) {
+				container.addChild(new Text(`    ${theme.fg("dim", data.body)}`, 0, 0));
+			}
+		}
+
+		if (allData.length > displayCount) {
+			container.addChild(
+				new Text(
+					theme.fg("dim", `  ${theme.format.ellipsis} ${allData.length - displayCount} more findings`),
+					0,
+					0,
+				),
+			);
+		}
+
+		return container;
+	},
+});
+
+// Register submit_review handler
+subprocessToolRegistry.register<SubmitReviewDetails>("submit_review", {
+	extractData: (event) => event.result?.details as SubmitReviewDetails | undefined,
+
+	// Terminate subprocess after review is submitted
+	shouldTerminate: () => true,
+
+	renderInline: (data, theme) => {
+		const verdictColor = data.overall_correctness === "correct" ? "success" : "error";
+		const verdictIcon = data.overall_correctness === "correct" ? theme.status.success : theme.status.error;
+		return new Text(
+			`${theme.fg(verdictColor, verdictIcon)} Review: ${theme.fg(verdictColor, data.overall_correctness)} (${(data.confidence * 100).toFixed(0)}%)`,
+			0,
+			0,
+		);
+	},
+
+	// Note: renderFinal is NOT used for submit_review - we use the combined
+	// renderReviewResult in render.ts to show verdict + findings together
+});

package/src/core/tools/rulebook.ts

@@ -0,0 +1,124 @@
+/**
+ * Rulebook Tool
+ *
+ * Allows the agent to fetch full content of rules that have descriptions.
+ * Rules are listed in the system prompt with name + description; this tool
+ * retrieves the complete rule content on demand.
+ */
+
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import type { Rule } from "../../capability/rule";
+
+export interface RulebookToolDetails {
+	type: "rulebook";
+	ruleName: string;
+	found: boolean;
+	content?: string;
+}
+
+const rulebookSchema = Type.Object({
+	name: Type.String({ description: "The name of the rule to fetch" }),
+});
+
+/**
+ * Create a rulebook tool with access to discovered rules.
+ * @param rules - Array of discovered rules (non-TTSR rules with descriptions)
+ */
+export function createRulebookTool(rules: Rule[]): AgentTool<typeof rulebookSchema> {
+	// Build lookup map for O(1) access
+	const ruleMap = new Map<string, Rule>();
+	for (const rule of rules) {
+		ruleMap.set(rule.name, rule);
+	}
+
+	const ruleNames = rules.map((r) => r.name);
+
+	return {
+		name: "rulebook",
+		label: "Rulebook",
+		description: `Fetch the full content of a project rule by name. Use this when a rule listed in <available_rules> is relevant to your current task. Available: ${ruleNames.join(", ") || "(none)"}`,
+		parameters: rulebookSchema,
+		execute: async (_toolCallId: string, { name }: { name: string }) => {
+			const rule = ruleMap.get(name);
+
+			if (!rule) {
+				const available = ruleNames.join(", ");
+				return {
+					content: [{ type: "text", text: `Rule "${name}" not found. Available rules: ${available || "(none)"}` }],
+					details: {
+						type: "rulebook",
+						ruleName: name,
+						found: false,
+					} satisfies RulebookToolDetails,
+				};
+			}
+
+			return {
+				content: [{ type: "text", text: `# Rule: ${rule.name}\n\n${rule.content}` }],
+				details: {
+					type: "rulebook",
+					ruleName: name,
+					found: true,
+					content: rule.content,
+				} satisfies RulebookToolDetails,
+			};
+		},
+	};
+}
+
+/**
+ * Filter rules to only those suitable for the rulebook (have descriptions, no TTSR trigger).
+ */
+export function filterRulebookRules(rules: Rule[]): Rule[] {
+	return rules.filter((rule) => {
+		// Exclude TTSR rules (handled separately by streaming)
+		if (rule.ttsrTrigger) return false;
+		// Exclude always-apply rules (already in context)
+		if (rule.alwaysApply) return false;
+		// Must have a description for agent to know when to fetch
+		if (!rule.description) return false;
+		return true;
+	});
+}
+
+/**
+ * Format rules for inclusion in the system prompt.
+ * Lists rule names and descriptions so the agent knows what's available.
+ */
+export function formatRulesForPrompt(rules: Rule[]): string {
+	if (rules.length === 0) {
+		return "";
+	}
+
+	const lines = [
+		"\n\n## Available Rules",
+		"",
+		"The following project rules are available. Use the `rulebook` tool to fetch a rule's full content when it's relevant to your task.",
+		"",
+		"<available_rules>",
+	];
+
+	for (const rule of rules) {
+		lines.push("  <rule>");
+		lines.push(`    <name>${escapeXml(rule.name)}</name>`);
+		lines.push(`    <description>${escapeXml(rule.description || "")}</description>`);
+		if (rule.globs && rule.globs.length > 0) {
+			lines.push(`    <globs>${escapeXml(rule.globs.join(", "))}</globs>`);
+		}
+		lines.push("  </rule>");
+	}
+
+	lines.push("</available_rules>");
+
+	return lines.join("\n");
+}
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}

package/src/core/tools/task/agents.ts

@@ -0,0 +1,158 @@
+/**
+ * Bundled agent definitions.
+ *
+ * Agents are embedded at build time via Bun's import with { type: "text" }.
+ */
+
+// Embed agent markdown files at build time
+import browserMd from "../../../prompts/browser.md" with { type: "text" };
+import exploreMd from "../../../prompts/explore.md" with { type: "text" };
+import planMd from "../../../prompts/plan.md" with { type: "text" };
+import reviewerMd from "../../../prompts/reviewer.md" with { type: "text" };
+import taskMd from "../../../prompts/task.md" with { type: "text" };
+import type { AgentDefinition, AgentSource } from "./types";
+
+const EMBEDDED_AGENTS: { name: string; content: string }[] = [
+	{ name: "browser.md", content: browserMd },
+	{ name: "explore.md", content: exploreMd },
+	{ name: "plan.md", content: planMd },
+	{ name: "reviewer.md", content: reviewerMd },
+	{ name: "task.md", content: taskMd },
+];
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ */
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+	const frontmatter: Record<string, string> = {};
+	const normalized = content.replace(/\r\n/g, "\n");
+
+	if (!normalized.startsWith("---")) {
+		return { frontmatter, body: normalized };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, body: normalized };
+	}
+
+	const frontmatterBlock = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	for (const line of frontmatterBlock.split("\n")) {
+		const match = line.match(/^([\w-]+):\s*(.*)$/);
+		if (match) {
+			let value = match[2].trim();
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			frontmatter[match[1]] = value;
+		}
+	}
+
+	return { frontmatter, body };
+}
+
+/**
+ * Parse an agent from embedded content.
+ */
+function parseAgent(fileName: string, content: string, source: AgentSource): AgentDefinition | null {
+	const { frontmatter, body } = parseFrontmatter(content);
+
+	if (!frontmatter.name || !frontmatter.description) {
+		return null;
+	}
+
+	const tools = frontmatter.tools
+		?.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+
+	// Parse spawns field
+	let spawns: string[] | "*" | undefined;
+	if (frontmatter.spawns !== undefined) {
+		const spawnsRaw = frontmatter.spawns.trim();
+		if (spawnsRaw === "*") {
+			spawns = "*";
+		} else if (spawnsRaw) {
+			spawns = spawnsRaw
+				.split(",")
+				.map((s) => s.trim())
+				.filter(Boolean);
+			if (spawns.length === 0) spawns = undefined;
+		}
+	}
+
+	// Backward compat: infer spawns: "*" when tools includes "task"
+	if (spawns === undefined && tools?.includes("task")) {
+		spawns = "*";
+	}
+
+	const recursive =
+		frontmatter.recursive === undefined ? false : frontmatter.recursive === "true" || frontmatter.recursive === "1";
+
+	return {
+		name: frontmatter.name,
+		description: frontmatter.description,
+		tools: tools && tools.length > 0 ? tools : undefined,
+		spawns,
+		model: frontmatter.model,
+		recursive,
+		systemPrompt: body,
+		source,
+		filePath: `embedded:${fileName}`,
+	};
+}
+
+/** Cache for bundled agents */
+let bundledAgentsCache: AgentDefinition[] | null = null;
+
+/**
+ * Load all bundled agents from embedded content.
+ * Results are cached after first load.
+ */
+export function loadBundledAgents(): AgentDefinition[] {
+	if (bundledAgentsCache !== null) {
+		return bundledAgentsCache;
+	}
+
+	const agents: AgentDefinition[] = [];
+
+	for (const { name, content } of EMBEDDED_AGENTS) {
+		const agent = parseAgent(name, content, "bundled");
+		if (agent) {
+			agents.push(agent);
+		}
+	}
+
+	bundledAgentsCache = agents;
+	return agents;
+}
+
+/**
+ * Get a bundled agent by name.
+ */
+export function getBundledAgent(name: string): AgentDefinition | undefined {
+	return loadBundledAgents().find((a) => a.name === name);
+}
+
+/**
+ * Get all bundled agents as a map keyed by name.
+ */
+export function getBundledAgentsMap(): Map<string, AgentDefinition> {
+	const map = new Map<string, AgentDefinition>();
+	for (const agent of loadBundledAgents()) {
+		map.set(agent.name, agent);
+	}
+	return map;
+}
+
+/**
+ * Clear the bundled agents cache (for testing).
+ */
+export function clearBundledAgentsCache(): void {
+	bundledAgentsCache = null;
+}
+
+// Re-export for backward compatibility
+export const BUNDLED_AGENTS = loadBundledAgents;

package/src/core/tools/task/artifacts.ts

@@ -0,0 +1,114 @@
+/**
+ * Session artifacts for subagent outputs.
+ *
+ * When a session exists, writes agent outputs to a sibling directory.
+ * Otherwise uses temp files that are cleaned up after execution.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/**
+ * Derive artifacts directory from session file path.
+ *
+ * /path/to/sessions/project/2026-01-01T14-28-11-636Z_uuid.jsonl
+ *   → /path/to/sessions/project/2026-01-01T14-28-11-636Z_uuid/
+ */
+export function getArtifactsDir(sessionFile: string | null): string | null {
+	if (!sessionFile) return null;
+	// Strip .jsonl extension to get directory path
+	if (sessionFile.endsWith(".jsonl")) {
+		return sessionFile.slice(0, -6);
+	}
+	return sessionFile;
+}
+
+/**
+ * Ensure artifacts directory exists.
+ */
+export function ensureArtifactsDir(dir: string): void {
+	if (!fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+	}
+}
+
+/**
+ * Generate artifact file paths for an agent run.
+ */
+export function getArtifactPaths(
+	dir: string,
+	agentName: string,
+	index: number,
+): { inputPath: string; outputPath: string; jsonlPath: string } {
+	const base = `${agentName}_${index}`;
+	return {
+		inputPath: path.join(dir, `${base}.in.md`),
+		outputPath: path.join(dir, `${base}.out.md`),
+		jsonlPath: path.join(dir, `${base}.jsonl`),
+	};
+}
+
+/**
+ * Write artifacts for an agent run.
+ */
+export async function writeArtifacts(
+	dir: string,
+	agentName: string,
+	index: number,
+	input: string,
+	output: string,
+	jsonlEvents?: string[],
+): Promise<{ inputPath: string; outputPath: string; jsonlPath?: string }> {
+	ensureArtifactsDir(dir);
+
+	const paths = getArtifactPaths(dir, agentName, index);
+
+	// Write input
+	await fs.promises.writeFile(paths.inputPath, input, "utf-8");
+
+	// Write output
+	await fs.promises.writeFile(paths.outputPath, output, "utf-8");
+
+	// Write JSONL if events provided
+	if (jsonlEvents && jsonlEvents.length > 0) {
+		await fs.promises.writeFile(paths.jsonlPath, jsonlEvents.join("\n"), "utf-8");
+		return paths;
+	}
+
+	return { inputPath: paths.inputPath, outputPath: paths.outputPath };
+}
+
+/**
+ * Create a temporary artifacts directory.
+ */
+export function createTempArtifactsDir(runId?: string): string {
+	const id = runId || `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+	const dir = path.join(os.tmpdir(), `omp-task-${id}`);
+	ensureArtifactsDir(dir);
+	return dir;
+}
+
+/**
+ * Clean up temporary artifacts.
+ */
+export async function cleanupTempArtifacts(paths: string[]): Promise<void> {
+	for (const p of paths) {
+		try {
+			await fs.promises.unlink(p);
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}
+
+/**
+ * Clean up a temporary directory and its contents.
+ */
+export async function cleanupTempDir(dir: string): Promise<void> {
+	try {
+		await fs.promises.rm(dir, { recursive: true, force: true });
+	} catch {
+		// Ignore cleanup errors
+	}
+}