@plannotator/pi-extension 0.16.7 → 0.17.1

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): {