@bdsqqq/pi 0.0.1

package/dist/core/pi-spawn.d.ts

@@ -0,0 +1,62 @@
+import { Message } from "@mariozechner/pi-ai";
+
+//#region packages/core/pi-spawn/index.d.ts
+interface UsageStats {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+interface PiSpawnResult {
+  exitCode: number;
+  messages: Message[];
+  stderr: string;
+  usage: UsageStats;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+interface PiSpawnConfig {
+  cwd: string;
+  task: string;
+  model?: string;
+  builtinTools?: string[];
+  extensionTools?: string[];
+  systemPromptBody?: string;
+  signal?: AbortSignal;
+  onUpdate?: (result: PiSpawnResult) => void;
+  sessionId?: string;
+  repo?: string;
+  /**
+  * inject a follow-up user message after the agent's first turn.
+  *
+  * uses pi's RPC mode instead of print mode. the follow-up is queued
+  * eagerly at startup (not delivered until idle), so the agent loop's
+  * getFollowUpMessages() finds it after exploration completes. the
+  * process is killed after the second end_turn.
+  *
+  * primary use case: code_review — agent explores the diff first,
+  * then receives the report format instructions.
+  */
+  followUp?: string;
+}
+declare function zeroUsage(): UsageStats;
+/**
+* resolve a prompt from either an inline string or a file.
+*
+* precedence: promptString (if non-empty) → readAgentPrompt(promptFile).
+* lets extensions externalize prompt content via config while
+* keeping sops-managed .md files as the default source.
+*/
+declare function resolvePrompt(promptString: string, promptFile: string): string;
+/**
+* read an agent prompt .md file, strip frontmatter, return body.
+* looks in ~/.pi/agent/agents/{filename}.
+*/
+declare function readAgentPrompt(filename: string): string;
+declare function piSpawn(config: PiSpawnConfig): Promise<PiSpawnResult>;
+//#endregion
+export { PiSpawnConfig, PiSpawnResult, UsageStats, piSpawn, readAgentPrompt, resolvePrompt, zeroUsage };

package/dist/core/pi-spawn.js

@@ -0,0 +1,244 @@
+import { interpolatePromptVars } from "./interpolate.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import * as os from "node:os";
+//#region packages/core/pi-spawn/index.ts
+/**
+* shared pi process spawning for dedicated sub-agent tools.
+*
+* extracts the spawn-parse-collect loop from the generic subagent
+* extension into a reusable function. each dedicated tool (finder,
+* oracle, Task) calls piSpawn() with its own config.
+*
+* uses shared interpolation from @bds_pi/interpolate for template variables
+* ({cwd}, {roots}, {date}, etc.) in system prompts.
+*/
+function writePromptToTempFile(label, prompt) {
+	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+	const safeName = label.replace(/[^\w.-]+/g, "_");
+	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+	fs.writeFileSync(filePath, prompt, {
+		encoding: "utf-8",
+		mode: 384
+	});
+	return {
+		dir: tmpDir,
+		filePath
+	};
+}
+function zeroUsage() {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		cost: 0,
+		contextTokens: 0,
+		turns: 0
+	};
+}
+/**
+* resolve a prompt from either an inline string or a file.
+*
+* precedence: promptString (if non-empty) → readAgentPrompt(promptFile).
+* lets extensions externalize prompt content via config while
+* keeping sops-managed .md files as the default source.
+*/
+function resolvePrompt(promptString, promptFile) {
+	if (promptString) return promptString;
+	return readAgentPrompt(promptFile);
+}
+/**
+* read an agent prompt .md file, strip frontmatter, return body.
+* looks in ~/.pi/agent/agents/{filename}.
+*/
+function readAgentPrompt(filename) {
+	const promptPath = path.join(os.homedir(), ".pi", "agent", "agents", filename);
+	try {
+		const content = fs.readFileSync(promptPath, "utf-8");
+		if (content.startsWith("---")) {
+			const endIdx = content.indexOf("\n---", 3);
+			if (endIdx !== -1) return content.slice(endIdx + 4).trim();
+		}
+		return content;
+	} catch {
+		return "";
+	}
+}
+async function piSpawn(config) {
+	const useRpc = !!config.followUp;
+	const args = useRpc ? [
+		"--mode",
+		"rpc",
+		"--no-session"
+	] : [
+		"--mode",
+		"json",
+		"-p",
+		"--no-session"
+	];
+	if (config.model) args.push("--model", config.model);
+	if (config.builtinTools !== void 0) if (config.builtinTools.length === 0) args.push("--no-tools");
+	else args.push("--tools", config.builtinTools.join(","));
+	let tmpPromptDir = null;
+	let tmpPromptPath = null;
+	const result = {
+		exitCode: 0,
+		messages: [],
+		stderr: "",
+		usage: zeroUsage()
+	};
+	try {
+		if (config.systemPromptBody?.trim()) {
+			const tmp = writePromptToTempFile("subagent", interpolatePromptVars(config.systemPromptBody, config.cwd, {
+				sessionId: config.sessionId,
+				repo: config.repo
+			}));
+			tmpPromptDir = tmp.dir;
+			tmpPromptPath = tmp.filePath;
+			args.push("--append-system-prompt", tmpPromptPath);
+		}
+		if (!useRpc) args.push(`Task: ${config.task}`);
+		const spawnEnv = { ...process.env };
+		if (config.extensionTools !== void 0) if (config.extensionTools.length === 0) spawnEnv.PI_INCLUDE_TOOLS = "NONE";
+		else spawnEnv.PI_INCLUDE_TOOLS = config.extensionTools.join(",");
+		let wasAborted = false;
+		const debugEnabled = !!process.env.PI_SPAWN_DEBUG;
+		const debug = (label, data) => {
+			if (!debugEnabled) return;
+			const suffix = data ? ` ${JSON.stringify(data)}` : "";
+			process.stderr.write(`[pi-spawn] ${label}${suffix}\n`);
+		};
+		result.exitCode = await new Promise((resolve) => {
+			const proc = spawn("pi", args, {
+				cwd: config.cwd,
+				shell: false,
+				stdio: [
+					useRpc ? "pipe" : "ignore",
+					"pipe",
+					"pipe"
+				],
+				env: spawnEnv
+			});
+			let endTurnCount = 0;
+			if (useRpc && proc.stdin) {
+				const promptCmd = JSON.stringify({
+					type: "prompt",
+					message: `Task: ${config.task}`
+				});
+				debug("send_prompt");
+				proc.stdin.write(promptCmd + "\n");
+				if (config.followUp) {
+					const followUpCmd = JSON.stringify({
+						type: "follow_up",
+						message: config.followUp
+					});
+					debug("send_follow_up");
+					proc.stdin.write(followUpCmd + "\n");
+				}
+			}
+			let buffer = "";
+			const processLine = (line) => {
+				if (!line.trim()) return;
+				let event;
+				try {
+					event = JSON.parse(line);
+				} catch {
+					return;
+				}
+				if (event.type === "response") return;
+				if (event.type === "message_end" && event.message) {
+					const msg = event.message;
+					result.messages.push(msg);
+					if (msg.role === "assistant") {
+						result.usage.turns++;
+						const usage = msg.usage;
+						if (usage) {
+							result.usage.input += usage.input || 0;
+							result.usage.output += usage.output || 0;
+							result.usage.cacheRead += usage.cacheRead || 0;
+							result.usage.cacheWrite += usage.cacheWrite || 0;
+							result.usage.cost += usage.cost?.total || 0;
+							result.usage.contextTokens = usage.totalTokens || 0;
+						}
+						if (!result.model && msg.model) result.model = msg.model;
+						if (msg.stopReason) result.stopReason = msg.stopReason;
+						if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+						const stopReason = msg.stopReason;
+						const isTurnEnd = stopReason === "end_turn" || stopReason === "stop";
+						const expectedTurns = config.followUp ? 2 : 1;
+						debug("turn_end", {
+							stopReason,
+							isTurnEnd,
+							endTurnCount,
+							expectedTurns
+						});
+						if (useRpc && isTurnEnd) {
+							endTurnCount++;
+							if (endTurnCount >= expectedTurns) {
+								debug("kill_after_turn", { endTurnCount });
+								proc.kill("SIGTERM");
+								setTimeout(() => {
+									if (!proc.killed) proc.kill("SIGKILL");
+								}, 5e3);
+							}
+						}
+						if (useRpc && (stopReason === "error" || stopReason === "aborted")) {
+							debug("kill_after_error", { stopReason });
+							proc.kill("SIGTERM");
+							setTimeout(() => {
+								if (!proc.killed) proc.kill("SIGKILL");
+							}, 5e3);
+						}
+					}
+					if (config.onUpdate) config.onUpdate({ ...result });
+				}
+				if (event.type === "tool_result_end" && event.message) {
+					result.messages.push(event.message);
+					if (config.onUpdate) config.onUpdate({ ...result });
+				}
+			};
+			proc.stdout.on("data", (data) => {
+				buffer += data.toString();
+				const lines = buffer.split("\n");
+				buffer = lines.pop() || "";
+				for (const line of lines) processLine(line);
+			});
+			proc.stderr.on("data", (data) => {
+				result.stderr += data.toString();
+			});
+			proc.on("close", (code) => {
+				if (buffer.trim()) processLine(buffer);
+				resolve(code ?? 0);
+			});
+			proc.on("error", () => resolve(1));
+			if (config.signal) {
+				const killProc = () => {
+					wasAborted = true;
+					proc.kill("SIGTERM");
+					setTimeout(() => {
+						if (!proc.killed) proc.kill("SIGKILL");
+					}, 5e3);
+				};
+				if (config.signal.aborted) killProc();
+				else config.signal.addEventListener("abort", killProc, { once: true });
+			}
+		});
+		if (wasAborted) {
+			result.exitCode = 1;
+			result.stopReason = "aborted";
+		}
+		if (useRpc && result.exitCode !== 0 && (result.stopReason === "end_turn" || result.stopReason === "stop")) result.exitCode = 0;
+		return result;
+	} finally {
+		if (tmpPromptPath) try {
+			fs.unlinkSync(tmpPromptPath);
+		} catch {}
+		if (tmpPromptDir) try {
+			fs.rmdirSync(tmpPromptDir);
+		} catch {}
+	}
+}
+//#endregion
+export { piSpawn, readAgentPrompt, resolvePrompt, zeroUsage };

package/dist/core/prompt-patch.d.ts

@@ -0,0 +1,11 @@
+import { ToolDefinition } from "@mariozechner/pi-coding-agent";
+
+//#region packages/core/prompt-patch/index.d.ts
+/**
+* derives promptSnippet and promptGuidelines from a tool's description
+* so tools don't need to define them manually. snippet = first paragraph,
+* guidelines = lines starting with "- ".
+*/
+declare function withPromptPatch(tool: ToolDefinition): ToolDefinition;
+//#endregion
+export { withPromptPatch };

package/dist/core/prompt-patch.js

@@ -0,0 +1,16 @@
+//#region packages/core/prompt-patch/index.ts
+/**
+* derives promptSnippet and promptGuidelines from a tool's description
+* so tools don't need to define them manually. snippet = first paragraph,
+* guidelines = lines starting with "- ".
+*/
+function withPromptPatch(tool) {
+	const snippet = (tool.description?.split("\n\n")[0] ?? "").trim();
+	const guidelines = (tool.description ?? "").split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- "));
+	const patched = { ...tool };
+	if (!patched.promptSnippet) patched.promptSnippet = snippet;
+	if (!patched.promptGuidelines && guidelines.length > 0) patched.promptGuidelines = guidelines;
+	return patched;
+}
+//#endregion
+export { withPromptPatch };

package/dist/core/show-renderer.d.ts

@@ -0,0 +1,10 @@
+import { Excerpt } from "./show.js";
+
+//#region packages/core/show-renderer/index.d.ts
+interface ShowRenderer {
+  render: (width: number) => string[];
+  invalidate: () => void;
+}
+declare function makeShowRenderer(text: string, excerpts: Excerpt[]): ShowRenderer;
+//#endregion
+export { ShowRenderer, makeShowRenderer };

package/dist/core/show-renderer.js

@@ -0,0 +1,39 @@
+import { show } from "./show.js";
+//#region packages/core/show-renderer/index.ts
+/**
+* makeShowRenderer — wraps show() in the width-aware caching pattern required
+* by the pi TUI renderer contract.
+*
+* pi calls render(width) on every frame and invalidate() when the component
+* must be re-evaluated. caching by width avoids recomputing visual-line
+* breaks on every frame (show() is O(lines)).
+*
+* usage:
+*   renderResult(result, { expanded }, theme) {
+*     const text = result.content?.[0]?.text ?? "";
+*     if (expanded) return new Text(text, 0, 0);
+*     return makeShowRenderer(text, [
+*       { focus: "head", context: 3 },
+*       { focus: "tail", context: 5 },
+*     ]);
+*   }
+*/
+function makeShowRenderer(text, excerpts) {
+	let cachedWidth;
+	let cachedLines;
+	return {
+		render(width) {
+			if (cachedLines === void 0 || cachedWidth !== width) {
+				cachedLines = show(text, excerpts, width).visualLines;
+				cachedWidth = width;
+			}
+			return cachedLines;
+		},
+		invalidate() {
+			cachedWidth = void 0;
+			cachedLines = void 0;
+		}
+	};
+}
+//#endregion
+export { makeShowRenderer };

package/dist/core/show.d.ts

@@ -0,0 +1,29 @@
+//#region packages/core/show/index.d.ts
+interface Excerpt {
+  focus: number | "head" | "tail";
+  context: number;
+}
+interface WindowResult<T> {
+  items: T[];
+  skippedRanges: Array<[number, number]>;
+}
+/**
+* generic excerpt windowing. picks items to keep based on excerpts,
+* inserts caller-provided elision markers for gaps.
+*
+* if excerpts is empty, returns all items unchanged.
+*/
+declare function windowItems<T>(items: T[], excerpts: Excerpt[], makeElision: (count: number) => T): WindowResult<T>;
+interface ShowResult {
+  /** visual lines to render, with "... (N lines) ..." elision markers for gaps */
+  visualLines: string[];
+  /** ranges of visual lines omitted, as [startInclusive, endExclusive] pairs */
+  skippedRanges: Array<[number, number]>;
+}
+/**
+* text-specific windowing: expands text to visual lines via pi-tui Text,
+* then applies excerpt windowing.
+*/
+declare function show(text: string, excerpts: Excerpt[], width: number, paddingX?: number): ShowResult;
+//#endregion
+export { Excerpt, ShowResult, WindowResult, show, windowItems };

package/dist/core/show.js

@@ -0,0 +1,288 @@
+import { Text } from "@mariozechner/pi-tui";
+//#region packages/core/show/index.ts
+/**
+* show — excerpt-based windowing for tool output.
+*
+* two layers:
+*   windowItems<T>() — generic windowing primitive. operates on any array.
+*   show()           — text-specific wrapper: Text.render() → windowItems<string>().
+*
+* focus semantics:
+*   "head"  — first `context` items (one-sided from start)
+*   "tail"  — last `context` items (one-sided from end)
+*   N       — ±context items around index N (symmetric)
+*
+* multiple excerpts are sorted and merged when overlapping or adjacent.
+* gaps get an elision marker via the caller-provided makeElision factory.
+*/
+/**
+* generic excerpt windowing. picks items to keep based on excerpts,
+* inserts caller-provided elision markers for gaps.
+*
+* if excerpts is empty, returns all items unchanged.
+*/
+function windowItems(items, excerpts, makeElision) {
+	const total = items.length;
+	if (total === 0 || excerpts.length === 0) return {
+		items: [...items],
+		skippedRanges: []
+	};
+	const ranges = excerpts.map(({ focus, context }) => {
+		if (focus === "head") return [0, Math.min(context - 1, total - 1)];
+		else if (focus === "tail") return [Math.max(0, total - context), total - 1];
+		else return [Math.max(0, focus - context), Math.min(total - 1, focus + context)];
+	});
+	ranges.sort((a, b) => a[0] - b[0]);
+	const merged = [];
+	for (const range of ranges) {
+		const lastMerged = merged[merged.length - 1];
+		if (merged.length === 0 || !lastMerged || range[0] > lastMerged[1] + 1) merged.push([range[0], range[1]]);
+		else lastMerged[1] = Math.max(lastMerged[1], range[1]);
+	}
+	const result = [];
+	const skippedRanges = [];
+	let cursor = 0;
+	for (const [start, end] of merged) {
+		if (cursor < start) {
+			skippedRanges.push([cursor, start]);
+			result.push(makeElision(start - cursor));
+		}
+		for (let i = start; i <= end; i++) {
+			const item = items[i];
+			if (item !== void 0) result.push(item);
+		}
+		cursor = end + 1;
+	}
+	if (cursor < total) {
+		skippedRanges.push([cursor, total]);
+		result.push(makeElision(total - cursor));
+	}
+	return {
+		items: result,
+		skippedRanges
+	};
+}
+/**
+* text-specific windowing: expands text to visual lines via pi-tui Text,
+* then applies excerpt windowing.
+*/
+function show(text, excerpts, width, paddingX = 0) {
+	if (!text) return {
+		visualLines: [],
+		skippedRanges: []
+	};
+	const allVisualLines = new Text(text, paddingX, 0).render(width);
+	if (excerpts.length === 0) return {
+		visualLines: allVisualLines,
+		skippedRanges: []
+	};
+	const result = windowItems(allVisualLines, excerpts, (count) => `... (${count} ${count === 1 ? "line" : "lines"}) ...`);
+	return {
+		visualLines: result.items,
+		skippedRanges: result.skippedRanges
+	};
+}
+if (import.meta.vitest) {
+	const { describe, it, expect } = import.meta.vitest;
+	describe("windowItems", () => {
+		it("returns all items when no excerpts", () => {
+			const result = windowItems([
+				"a",
+				"b",
+				"c"
+			], [], (n) => `...${n}...`);
+			expect(result.items).toEqual([
+				"a",
+				"b",
+				"c"
+			]);
+			expect(result.skippedRanges).toEqual([]);
+		});
+		it("returns empty array for empty input", () => {
+			const result = windowItems([], [{
+				focus: 0,
+				context: 2
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual([]);
+			expect(result.skippedRanges).toEqual([]);
+		});
+		it("extracts head excerpt", () => {
+			const result = windowItems([
+				"a",
+				"b",
+				"c",
+				"d",
+				"e"
+			], [{
+				focus: "head",
+				context: 2
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual([
+				"a",
+				"b",
+				"...3..."
+			]);
+			expect(result.skippedRanges).toEqual([[2, 5]]);
+		});
+		it("extracts tail excerpt", () => {
+			const result = windowItems([
+				"a",
+				"b",
+				"c",
+				"d",
+				"e"
+			], [{
+				focus: "tail",
+				context: 2
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual([
+				"...3...",
+				"d",
+				"e"
+			]);
+			expect(result.skippedRanges).toEqual([[0, 3]]);
+		});
+		it("extracts symmetric excerpt around index", () => {
+			const result = windowItems([
+				"a",
+				"b",
+				"c",
+				"d",
+				"e"
+			], [{
+				focus: 2,
+				context: 1
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual([
+				"...1...",
+				"b",
+				"c",
+				"d",
+				"...1..."
+			]);
+			expect(result.skippedRanges).toEqual([[0, 1], [4, 5]]);
+		});
+		it("merges overlapping excerpts", () => {
+			const result = windowItems([
+				"a",
+				"b",
+				"c",
+				"d",
+				"e",
+				"f"
+			], [{
+				focus: 1,
+				context: 1
+			}, {
+				focus: 3,
+				context: 1
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual([
+				"a",
+				"b",
+				"c",
+				"d",
+				"e",
+				"...1..."
+			]);
+			expect(result.skippedRanges).toEqual([[5, 6]]);
+		});
+		it("merges adjacent excerpts", () => {
+			const result = windowItems([
+				"a",
+				"b",
+				"c",
+				"d",
+				"e"
+			], [{
+				focus: 0,
+				context: 0
+			}, {
+				focus: 1,
+				context: 0
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual([
+				"a",
+				"b",
+				"...3..."
+			]);
+			expect(result.skippedRanges).toEqual([[2, 5]]);
+		});
+		it("clamps head context to available items", () => {
+			const result = windowItems(["a", "b"], [{
+				focus: "head",
+				context: 5
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual(["a", "b"]);
+			expect(result.skippedRanges).toEqual([]);
+		});
+		it("clamps tail context to available items", () => {
+			const result = windowItems(["a", "b"], [{
+				focus: "tail",
+				context: 5
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual(["a", "b"]);
+			expect(result.skippedRanges).toEqual([]);
+		});
+		it("clamps symmetric context to bounds", () => {
+			const result = windowItems([
+				"a",
+				"b",
+				"c"
+			], [{
+				focus: 0,
+				context: 5
+			}], (n) => `...${n}...`);
+			expect(result.items).toEqual([
+				"a",
+				"b",
+				"c"
+			]);
+			expect(result.skippedRanges).toEqual([]);
+		});
+	});
+	describe("show", () => {
+		it("returns empty for empty text", () => {
+			const result = show("", [{
+				focus: "head",
+				context: 2
+			}], 80);
+			expect(result.visualLines).toEqual([]);
+			expect(result.skippedRanges).toEqual([]);
+		});
+		it("returns all lines when no excerpts", () => {
+			const result = show("a\nb\nc", [], 80);
+			expect(result.visualLines.length).toBe(3);
+			expect(result.visualLines[0]?.trim()).toBe("a");
+			expect(result.visualLines[1]?.trim()).toBe("b");
+			expect(result.visualLines[2]?.trim()).toBe("c");
+			expect(result.skippedRanges).toEqual([]);
+		});
+		it("applies head excerpt to visual lines", () => {
+			const result = show("line1\nline2\nline3\nline4\nline5", [{
+				focus: "head",
+				context: 2
+			}], 80);
+			expect(result.visualLines.length).toBe(3);
+			expect(result.visualLines[0]?.trim()).toBe("line1");
+			expect(result.visualLines[1]?.trim()).toBe("line2");
+			expect(result.visualLines[2]).toBe("... (3 lines) ...");
+			expect(result.skippedRanges).toEqual([[2, 5]]);
+		});
+		it("uses singular 'line' for single skipped line", () => {
+			const result = show("line1\nline2\nline3", [{
+				focus: "head",
+				context: 2
+			}], 80);
+			expect(result.visualLines.length).toBe(3);
+			expect(result.visualLines[0]?.trim()).toBe("line1");
+			expect(result.visualLines[1]?.trim()).toBe("line2");
+			expect(result.visualLines[2]).toBe("... (1 line) ...");
+		});
+		it("wraps long lines at width", () => {
+			expect(show("a".repeat(100), [], 50).visualLines.length).toBeGreaterThan(1);
+		});
+	});
+}
+//#endregion
+export { show, windowItems };