@plannotator/pi-extension 0.16.7 → 0.17.0

package/server/agent-jobs.ts

@@ -20,6 +20,7 @@ import {
 	AGENT_HEARTBEAT_COMMENT,
 	AGENT_HEARTBEAT_INTERVAL_MS,
 } from "../generated/agent-jobs.js";
+import { formatClaudeLogEvent } from "../generated/claude-review.js";
 import { json, parseBody } from "./helpers.js";
 
 // ---------------------------------------------------------------------------
@@ -53,6 +54,18 @@ export interface AgentJobHandlerOptions {
 	mode: "plan" | "review" | "annotate";
 	getServerUrl: () => string;
 	getCwd: () => string;
+	/** Server-side command builder for known providers (codex, claude). */
+	buildCommand?: (provider: string) => Promise<{
+		command: string[];
+		outputPath?: string;
+		captureStdout?: boolean;
+		stdinPrompt?: string;
+		cwd?: string;
+		prompt?: string;
+		label?: string;
+	} | null>;
+	/** Called when a job completes successfully — parse results and push annotations. */
+	onJobComplete?: (job: AgentJobInfo, meta: { outputPath?: string; stdout?: string; cwd?: string }) => void | Promise<void>;
 }
 
 export function createAgentJobHandler(options: AgentJobHandlerOptions) {
@@ -60,6 +73,7 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 
 	// --- State ---
 	const jobs = new Map<string, { info: AgentJobInfo; proc: ChildProcess | null }>();
+	const jobOutputPaths = new Map<string, string>();
 	const subscribers = new Set<ServerResponse>();
 	let version = 0;
 
@@ -67,7 +81,6 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 	const capabilities: AgentCapability[] = [
 		{ id: "claude", name: "Claude Code", available: whichCmd("claude") },
 		{ id: "codex", name: "Codex CLI", available: whichCmd("codex") },
-		{ id: "shell", name: "Shell Command", available: true },
 	];
 	const capabilitiesResponse: AgentCapabilities = {
 		mode,
@@ -93,6 +106,8 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 		provider: string,
 		command: string[],
 		label: string,
+		outputPath?: string,
+		spawnOptions?: { captureStdout?: boolean; stdinPrompt?: string; cwd?: string; prompt?: string },
 	): AgentJobInfo {
 		const id = crypto.randomUUID();
 		const source = jobSource(id);
@@ -105,14 +120,23 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 			status: "starting",
 			startedAt: Date.now(),
 			command,
+			cwd: getCwd(),
 		};
 
 		let proc: ChildProcess | null = null;
 
 		try {
+			const spawnCwd = spawnOptions?.cwd ?? getCwd();
+			const captureStdout = spawnOptions?.captureStdout ?? false;
+			const hasStdinPrompt = !!spawnOptions?.stdinPrompt;
+
 			proc = spawn(command[0], command.slice(1), {
-				cwd: getCwd(),
-				stdio: ["ignore", "ignore", "pipe"],
+				cwd: spawnCwd,
+				stdio: [
+					hasStdinPrompt ? "pipe" : "ignore",
+					captureStdout ? "pipe" : "ignore",
+					"pipe",
+				],
 				env: {
 					...process.env,
 					PLANNOTATOR_AGENT_SOURCE: source,
@@ -120,20 +144,80 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 				},
 			});
 
+			// Write prompt to stdin and close (for providers that read prompt from stdin)
+			if (hasStdinPrompt && proc.stdin) {
+				proc.stdin.write(spawnOptions!.stdinPrompt!);
+				proc.stdin.end();
+			}
+
 			info.status = "running";
+			info.cwd = spawnCwd;
+			if (spawnOptions?.prompt) info.prompt = spawnOptions.prompt;
 			jobs.set(id, { info, proc });
+			if (outputPath) jobOutputPaths.set(id, outputPath);
+			if (spawnOptions?.cwd) jobOutputPaths.set(`${id}:cwd`, spawnOptions.cwd);
 			broadcast({ type: "job:started", job: { ...info } });
 
-			// Accumulate stderr continuously (must attach before exit fires)
+			// --- Stdout capture (Claude JSONL streaming) ---
+			let stdoutBuf = "";
+			if (captureStdout && proc.stdout) {
+				proc.stdout.on("data", (chunk: Buffer) => {
+					const text = chunk.toString();
+					stdoutBuf += text;
+
+					// Forward JSONL lines as log events
+					const lines = text.split('\n');
+					for (const line of lines) {
+						if (!line.trim()) continue;
+						if (provider === "claude") {
+							const formatted = formatClaudeLogEvent(line);
+							if (formatted !== null) {
+								broadcast({ type: "job:log", jobId: id, delta: formatted + '\n' });
+							}
+							continue;
+						}
+						try {
+							const event = JSON.parse(line);
+							if (event.type === 'result') continue;
+						} catch { /* not JSON — forward as raw log */ }
+						broadcast({ type: "job:log", jobId: id, delta: line + '\n' });
+					}
+				});
+			}
+
+			// --- Stderr: buffer tail for errors + live log streaming ---
 			let stderrBuf = "";
+			let logPending = "";
+			let logFlushTimer: ReturnType<typeof setTimeout> | null = null;
+
 			if (proc.stderr) {
 				proc.stderr.on("data", (chunk: Buffer) => {
-					stderrBuf = (stderrBuf + chunk.toString()).slice(-500);
+					const text = chunk.toString();
+					stderrBuf = (stderrBuf + text).slice(-500);
+					logPending += text;
+
+					if (!logFlushTimer) {
+						logFlushTimer = setTimeout(() => {
+							if (logPending) {
+								broadcast({ type: "job:log", jobId: id, delta: logPending });
+								logPending = "";
+							}
+							logFlushTimer = null;
+						}, 200);
+					}
 				});
 			}
 
-			// Monitor process exit
-			proc.on("exit", (exitCode) => {
+			// Monitor process close (fires after stdio streams are fully drained,
+			// unlike 'exit' which fires before — critical for stdout capture)
+			proc.on("close", async (exitCode) => {
+				// Flush remaining stderr
+				if (logFlushTimer) { clearTimeout(logFlushTimer); logFlushTimer = null; }
+				if (logPending) {
+					broadcast({ type: "job:log", jobId: id, delta: logPending });
+					logPending = "";
+				}
+
 				const entry = jobs.get(id);
 				if (!entry || isTerminalStatus(entry.info.status)) return;
 
@@ -145,6 +229,23 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 					entry.info.error = stderrBuf;
 				}
 
+				// Ingest results before broadcasting completion
+				const jobOutputPath = jobOutputPaths.get(id);
+				const jobCwd = jobOutputPaths.get(`${id}:cwd`);
+				if (exitCode === 0 && options.onJobComplete) {
+					try {
+						await options.onJobComplete(entry.info, {
+							outputPath: jobOutputPath,
+							stdout: captureStdout ? stdoutBuf : undefined,
+							cwd: jobCwd,
+						});
+					} catch {
+						// Result ingestion failure shouldn't prevent job completion broadcast
+					}
+				}
+				jobOutputPaths.delete(id);
+				jobOutputPaths.delete(`${id}:cwd`);
+
 				broadcast({ type: "job:completed", job: { ...entry.info } });
 			});
 
@@ -185,6 +286,8 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 
 		entry.info.status = "killed";
 		entry.info.endedAt = Date.now();
+		jobOutputPaths.delete(id);
+		jobOutputPaths.delete(`${id}:cwd`);
 		broadcast({ type: "job:completed", job: { ...entry.info } });
 		return true;
 	}
@@ -276,10 +379,11 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 			if (url.pathname === JOBS && req.method === "POST") {
 				try {
 					const body = await parseBody(req);
-					const provider = typeof body.provider === "string" ? body.provider : "shell";
-					const rawCommand = Array.isArray(body.command) ? body.command : [];
-					const command = rawCommand.filter((c: unknown): c is string => typeof c === "string");
-					const label = typeof body.label === "string" ? body.label : `${provider} agent`;
+					const provider = typeof body.provider === "string" ? body.provider : "";
+					let rawCommand = Array.isArray(body.command) ? body.command : [];
+					let command = rawCommand.filter((c: unknown): c is string => typeof c === "string");
+					let label = typeof body.label === "string" ? body.label : `${provider} agent`;
+					let outputPath: string | undefined;
 
 					// Validate provider is a known, available capability
 					const cap = capabilities.find((c) => c.id === provider);
@@ -288,12 +392,35 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 						return true;
 					}
 
+					// Try server-side command building for known providers
+					let captureStdout = false;
+					let stdinPrompt: string | undefined;
+					let spawnCwd: string | undefined;
+					let promptText: string | undefined;
+					if (options.buildCommand) {
+						const built = await options.buildCommand(provider);
+						if (built) {
+							command = built.command;
+							outputPath = built.outputPath;
+							captureStdout = built.captureStdout ?? false;
+							stdinPrompt = built.stdinPrompt;
+							spawnCwd = built.cwd;
+							promptText = built.prompt;
+							if (built.label) label = built.label;
+						}
+					}
+
 					if (command.length === 0) {
 						json(res, { error: 'Missing "command" array' }, 400);
 						return true;
 					}
 
-					const job = spawnJob(provider, command, label);
+					const job = spawnJob(provider, command, label, outputPath, {
+						captureStdout,
+						stdinPrompt,
+						cwd: spawnCwd,
+						prompt: promptText,
+					});
 					json(res, { job }, 201);
 				} catch {
 					json(res, { error: "Invalid JSON" }, 400);

package/server/external-annotations.ts

@@ -49,6 +49,14 @@ export function createExternalAnnotationHandler(mode: "plan" | "review") {
 	});
 
 	return {
+		/** Push annotations directly into the store (bypasses HTTP, reuses same validation). */
+		addAnnotations(body: unknown): { ids: string[] } | { error: string } {
+			const parsed = transform(body);
+			if ("error" in parsed) return { error: parsed.error };
+			const created = store.add(parsed.annotations);
+			return { ids: created.map((a: { id: string }) => a.id) };
+		},
+
 		async handle(
 			req: IncomingMessage,
 			res: ServerResponse,

package/server/network.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { getServerPort, isRemoteSession } from "./network";
+
+const savedEnv: Record<string, string | undefined> = {};
+const envKeys = ["PLANNOTATOR_REMOTE", "PLANNOTATOR_PORT", "SSH_TTY", "SSH_CONNECTION"];
+
+function clearEnv() {
+	for (const key of envKeys) {
+		savedEnv[key] = process.env[key];
+		delete process.env[key];
+	}
+}
+
+afterEach(() => {
+	for (const key of envKeys) {
+		if (savedEnv[key] !== undefined) {
+			process.env[key] = savedEnv[key];
+		} else {
+			delete process.env[key];
+		}
+	}
+});
+
+describe("pi remote detection", () => {
+	test("false by default", () => {
+		clearEnv();
+		expect(isRemoteSession()).toBe(false);
+	});
+
+	test("true when PLANNOTATOR_REMOTE=1", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "1";
+		expect(isRemoteSession()).toBe(true);
+	});
+
+	test("true when PLANNOTATOR_REMOTE=true", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "true";
+		expect(isRemoteSession()).toBe(true);
+	});
+
+	test("false when PLANNOTATOR_REMOTE=0", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "0";
+		expect(isRemoteSession()).toBe(false);
+	});
+
+	test("false when PLANNOTATOR_REMOTE=false", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "false";
+		expect(isRemoteSession()).toBe(false);
+	});
+
+	test("PLANNOTATOR_REMOTE=false overrides SSH_TTY", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "false";
+		process.env.SSH_TTY = "/dev/pts/0";
+		expect(isRemoteSession()).toBe(false);
+	});
+
+	test("PLANNOTATOR_REMOTE=0 overrides SSH_CONNECTION", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "0";
+		process.env.SSH_CONNECTION = "192.168.1.1 12345 192.168.1.2 22";
+		expect(isRemoteSession()).toBe(false);
+	});
+
+	test("true when SSH_TTY is set and env var is unset", () => {
+		clearEnv();
+		process.env.SSH_TTY = "/dev/pts/0";
+		expect(isRemoteSession()).toBe(true);
+	});
+});
+
+describe("pi port selection", () => {
+	test("uses random local port when false overrides SSH", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "false";
+		process.env.SSH_TTY = "/dev/pts/0";
+		expect(getServerPort()).toEqual({ port: 0, portSource: "random" });
+	});
+
+	test("uses default remote port when SSH is detected", () => {
+		clearEnv();
+		process.env.SSH_CONNECTION = "192.168.1.1 12345 192.168.1.2 22";
+		expect(getServerPort()).toEqual({ port: 19432, portSource: "remote-default" });
+	});
+
+	test("PLANNOTATOR_PORT still takes precedence", () => {
+		clearEnv();
+		process.env.PLANNOTATOR_REMOTE = "false";
+		process.env.SSH_TTY = "/dev/pts/0";
+		process.env.PLANNOTATOR_PORT = "9999";
+		expect(getServerPort()).toEqual({ port: 9999, portSource: "env" });
+	});
+});

package/server/network.ts

@@ -11,13 +11,30 @@ const DEFAULT_REMOTE_PORT = 19432;
 
 /**
  * Check if running in a remote session (SSH, devcontainer, etc.)
- * Honors PLANNOTATOR_REMOTE env var, or detects SSH_TTY/SSH_CONNECTION.
+ * Honors PLANNOTATOR_REMOTE as a tri-state override, or detects SSH_TTY/SSH_CONNECTION.
  */
-function isRemoteSession(): boolean {
+function getRemoteOverride(): boolean | null {
 	const remote = process.env.PLANNOTATOR_REMOTE;
+	if (remote === undefined) {
+		return null;
+	}
+
 	if (remote === "1" || remote?.toLowerCase() === "true") {
 		return true;
 	}
+
+	if (remote === "0" || remote?.toLowerCase() === "false") {
+		return false;
+	}
+
+	return null;
+}
+
+export function isRemoteSession(): boolean {
+	const remoteOverride = getRemoteOverride();
+	if (remoteOverride !== null) {
+		return remoteOverride;
+	}
 	// Legacy SSH detection
 	if (process.env.SSH_TTY || process.env.SSH_CONNECTION) {
 		return true;
@@ -32,7 +49,7 @@ function isRemoteSession(): boolean {
  * - Local sessions use random port
  * Returns { port, portSource } so caller can notify user if needed.
  */
-function getServerPort(): {
+export function getServerPort(): {
 	port: number;
 	portSource: "env" | "remote-default" | "random";
 } {
@@ -98,7 +115,7 @@ export async function listenOnPort(
 
 /**
  * Open URL in system browser (Node-compatible, no Bun $ dependency).
- * Honors PLANNOTATOR_BROWSER and BROWSER env vars, matching packages/server/browser.ts.
+ * Honors PLANNOTATOR_BROWSER and BROWSER env vars.
  * Returns { opened: true } if browser was opened, { opened: false, isRemote: true, url } if remote session.
  */
 export function openBrowser(url: string): {

package/server/serverReview.ts

@@ -56,6 +56,20 @@ import {
 	submitPRReview,
 } from "./pr.js";
 import { getRepoInfo } from "./project.js";
+import {
+	CODEX_REVIEW_SYSTEM_PROMPT,
+	buildCodexReviewUserMessage,
+	buildCodexCommand,
+	generateOutputPath,
+	parseCodexOutput,
+	transformReviewFindings,
+} from "../generated/codex-review.js";
+import {
+	CLAUDE_REVIEW_PROMPT,
+	buildClaudeCommand,
+	parseClaudeStreamOutput,
+	transformClaudeFindings,
+} from "../generated/claude-review.js";
 
 export interface ReviewServerResult {
 	port: number;
@@ -154,15 +168,84 @@ export async function startReviewServer(options: {
 
 	// Agent jobs — background process manager (late-binds serverUrl via getter)
 	let serverUrl = "";
+	// Worktree-aware cwd resolver — shared by getCwd, buildCommand, and onJobComplete
+	function resolveAgentCwd(): string {
+		if (currentDiffType.startsWith("worktree:")) {
+			const parsed = parseWorktreeDiffType(currentDiffType);
+			if (parsed) return parsed.path;
+		}
+		return options.gitContext?.cwd ?? process.cwd();
+	}
 	const agentJobs = createAgentJobHandler({
 		mode: "review",
 		getServerUrl: () => serverUrl,
-		getCwd: () => {
-			if (currentDiffType.startsWith("worktree:")) {
-				const parsed = parseWorktreeDiffType(currentDiffType);
-				if (parsed) return parsed.path;
+		getCwd: resolveAgentCwd,
+
+		async buildCommand(provider) {
+			const cwd = resolveAgentCwd();
+			const hasLocalAccess = !!options.gitContext;
+			const userMessage = buildCodexReviewUserMessage(
+				currentPatch,
+				currentDiffType,
+				{ defaultBranch: options.gitContext?.defaultBranch, hasLocalAccess },
+				options.prMetadata,
+			);
+
+			if (provider === "codex") {
+				const outputPath = generateOutputPath();
+				const prompt = CODEX_REVIEW_SYSTEM_PROMPT + "\n\n---\n\n" + userMessage;
+				const command = await buildCodexCommand({ cwd, outputPath, prompt });
+				return { command, outputPath, prompt, label: "Codex Review" };
+			}
+
+			if (provider === "claude") {
+				const prompt = CLAUDE_REVIEW_PROMPT + "\n\n---\n\n" + userMessage;
+				const { command, stdinPrompt } = buildClaudeCommand(prompt);
+				return { command, stdinPrompt, prompt, cwd, label: "Claude Code Review", captureStdout: true };
+			}
+
+			return null;
+		},
+
+		async onJobComplete(job, meta) {
+			const cwd = resolveAgentCwd();
+
+			if (job.provider === "codex" && meta.outputPath) {
+				const output = await parseCodexOutput(meta.outputPath);
+				if (!output) return;
+
+				job.summary = {
+					correctness: output.overall_correctness,
+					explanation: output.overall_explanation,
+					confidence: output.overall_confidence_score,
+				};
+
+				if (output.findings.length > 0) {
+					const annotations = transformReviewFindings(output.findings, job.source, cwd, "Codex");
+					const result = externalAnnotations.addAnnotations({ annotations });
+					if ("error" in result) console.error(`[codex-review] addAnnotations error:`, result.error);
+				}
+				return;
+			}
+
+			if (job.provider === "claude" && meta.stdout) {
+				const output = parseClaudeStreamOutput(meta.stdout);
+				if (!output) return;
+
+				const total = output.summary.important + output.summary.nit + output.summary.pre_existing;
+				job.summary = {
+					correctness: output.summary.important === 0 ? "Correct" : "Issues Found",
+					explanation: `${output.summary.important} important, ${output.summary.nit} nit, ${output.summary.pre_existing} pre-existing`,
+					confidence: total === 0 ? 1.0 : Math.max(0, 1.0 - (output.summary.important * 0.2)),
+				};
+
+				if (output.findings.length > 0) {
+					const annotations = transformClaudeFindings(output.findings, job.source, cwd);
+					const result = externalAnnotations.addAnnotations({ annotations });
+					if ("error" in result) console.error(`[claude-review] addAnnotations error:`, result.error);
+				}
+				return;
 			}
-			return options.gitContext?.cwd ?? process.cwd();
 		},
 	});
 	const sharingEnabled =
@@ -448,8 +531,9 @@ export async function startReviewServer(options: {
 
 			if (isPRMode && prRef && prMeta) {
 				try {
+					const oldSha = prMeta.mergeBaseSha ?? prMeta.baseSha;
 					const [oldContent, newContent] = await Promise.all([
-						fetchPRFileContent(prRef, prMeta.baseSha, oldPath || filePath),
+						fetchPRFileContent(prRef, oldSha, oldPath || filePath),
 						fetchPRFileContent(prRef, prMeta.headSha, filePath),
 					]);
 					json(res, { oldContent, newContent });