@plannotator/pi-extension 0.27.5 → 0.27.7

package/README.md

@@ -270,6 +270,8 @@ Plannotator does not send `Continue with the approved plan`, enter its executing
 
 Run `/plannotator-annotate <file.md>` to open any markdown file in the annotation UI. Useful for reviewing documentation or design specs with the agent.
 
+URL targets work too. A loopback `http` URL that answers with an HTML page (a running dev app, e.g. `http://localhost:5173`) opens **live**: the app is served through a local reverse proxy and annotated in place, with HMR and WebSockets passed through. `--static` forces the classic markdown conversion; `--app` requires a live session and errors instead of falling back. Live sessions are unavailable in remote mode (`PLANNOTATOR_REMOTE`).
+
 ### Annotate last message
 
 Run `/plannotator-last` to annotate the agent's most recent response. The message opens in the annotation UI where you can highlight text, add comments, and send structured feedback back to the agent.

package/generated/ai/providers/child-io.ts

@@ -0,0 +1,93 @@
+// @generated — DO NOT EDIT. Source: packages/ai/providers/child-io.ts
+/**
+ * Stdio guards for the JSONL/JSON-RPC child processes the AI providers drive.
+ *
+ * Both `PiProcessNode` (pi-sdk-node.ts) and `CodexAppServerProcess`
+ * (codex-app-server.ts) talk to a nested agent over pipes, and a pipe can
+ * break at any instant — the child exits, is killed, or closes stdin while a
+ * command is in flight. Two Node behaviors turn that ordinary condition into
+ * a host-killing crash:
+ *
+ *  1. `stream.write()` on a broken pipe reports `EPIPE` either synchronously
+ *     (throw) or asynchronously (an `error` event on the stream), and which
+ *     one you get is a timing race. A `destroyed` check before the write
+ *     cannot close that race: the child can close the pipe between the check
+ *     and the write.
+ *  2. An `error` event on a Node stream (or on the `ChildProcess` itself)
+ *     with NO listener is re-thrown as an `uncaughtException`. Inside an
+ *     embedded extension that is not "the provider failed" — it terminates
+ *     the HOST agent process.
+ *
+ * That is issue #1378: a Plannotator plan review opened from Pi on Windows
+ * took the whole Pi host down with `write EPIPE` out of `PiProcessNode.send()`.
+ * Windows only made it likelier to land on the async path during teardown;
+ * the mechanism is platform-independent.
+ *
+ * The contract these helpers enforce: a broken pipe is a PROVIDER failure.
+ * It never escalates past the provider, it is reported exactly like any other
+ * process end (in-flight requests reject, listeners see the process end), and
+ * the provider is left dead so the next query re-spawns it.
+ */
+
+import type { ChildProcess } from "node:child_process";
+
+/** Normalize an unknown thrown/emitted value to an Error. */
+export function toChildError(err: unknown): Error {
+	return err instanceof Error ? err : new Error(String(err));
+}
+
+/**
+ * Attach `error` listeners to the child process and every piped stream so a
+ * broken pipe can never reach `uncaughtException`.
+ *
+ * Call this immediately after `spawn()` returns — before awaiting the spawn
+ * handshake — so a stream that fails during startup is already covered. The
+ * spawn handshake may register its own one-shot `error` listener; Node allows
+ * several, and `onFailure` is expected to be idempotent.
+ */
+export function guardChildStreams(
+	proc: ChildProcess,
+	label: string,
+	onFailure: (error: Error) => void,
+): void {
+	const report = (stream: string) => (err: unknown) => {
+		onFailure(new Error(`${label} ${stream} failed: ${toChildError(err).message}`));
+	};
+	proc.on("error", report("process"));
+	proc.stdin?.on("error", report("stdin"));
+	proc.stdout?.on("error", report("stdout"));
+	proc.stderr?.on("error", report("stderr"));
+}
+
+/**
+ * Write one already-newline-terminated line to a child's stdin.
+ *
+ * Returns the Error the write failed with, or `null` when the bytes were
+ * accepted by the stream. Failures that only surface later (the write
+ * callback, or an `error` event covered by {@link guardChildStreams}) are
+ * reported through `onAsyncFailure` instead, so BOTH the sync-throw and the
+ * async-event paths end up at the caller's failure handling.
+ */
+export function writeChildLine(
+	proc: ChildProcess | null,
+	line: string,
+	label: string,
+	onAsyncFailure: (error: Error) => void,
+): Error | null {
+	const stdin = proc?.stdin;
+	if (!stdin || stdin.destroyed || stdin.writableEnded) {
+		return new Error(`${label} stdin is closed`);
+	}
+	try {
+		stdin.write(line, (err) => {
+			if (err) {
+				onAsyncFailure(
+					new Error(`${label} stdin write failed: ${toChildError(err).message}`),
+				);
+			}
+		});
+	} catch (err) {
+		return new Error(`${label} stdin write failed: ${toChildError(err).message}`);
+	}
+	return null;
+}

package/generated/ai/providers/codex-app-server.ts

@@ -44,8 +44,10 @@ import {
   killWindowsProcessTree,
   resolveWindowsCommandShim,
 } from "./command-path.ts";
+import { guardChildStreams, writeChildLine } from "./child-io.ts";
 
 const PROVIDER_NAME = "codex-sdk";
+const CODEX_PROCESS_LABEL = "Codex app-server";
 const DEFAULT_MODEL = "gpt-5.6-sol";
 const CLIENT_NAME = "plannotator";
 /** Kill an idle app-server process after this long with no query. */
@@ -335,6 +337,10 @@ class CodexAppServerProcess {
     }
 
     this.proc = proc;
+    // Cover every pipe BEFORE the spawn handshake: an `error` event on a child
+    // stream with no listener becomes an uncaughtException and kills the host
+    // process, not just this provider (#1378).
+    guardChildStreams(proc, CODEX_PROCESS_LABEL, (error) => this.failProcess(error));
     proc.once("exit", () => {
       this.handleProcessEnd(new Error("Codex app-server exited unexpectedly"));
     });
@@ -378,6 +384,23 @@ class CodexAppServerProcess {
     this.send({ method: "initialized", params: {} });
   }
 
+  /**
+   * A pipe to the child broke: resolve it as a provider failure and reap the
+   * child, leaving `alive` false so the next query re-spawns (#1378).
+   */
+  private failProcess(error: Error): void {
+    const proc = this.proc;
+    this.startPromise = null;
+    this.handleProcessEnd(error);
+    if (proc) {
+      try {
+        if (!killWindowsProcessTree(proc.pid)) proc.kill();
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+
   private handleProcessEnd(error: Error): void {
     if (!this.proc && this.pendingRequests.size === 0) return;
     this._alive = false;
@@ -439,9 +462,22 @@ class CodexAppServerProcess {
     }
   }
 
+  /**
+   * Send a JSON-RPC message without waiting for a response.
+   *
+   * A closed or broken stdin is a provider failure, never a throw at the
+   * caller and never an unhandled stream error: both the synchronous throw
+   * and the asynchronous `error`/write-callback paths land in failProcess,
+   * which rejects anything in flight.
+   */
   send(message: RpcMessage): void {
-    if (!this.proc?.stdin || this.proc.stdin.destroyed) return;
-    this.proc.stdin.write(`${JSON.stringify(message)}\n`);
+    const error = writeChildLine(
+      this.proc,
+      `${JSON.stringify(message)}\n`,
+      CODEX_PROCESS_LABEL,
+      (err) => this.failProcess(err),
+    );
+    if (error) this.failProcess(error);
   }
 
   sendAndWait(message: RpcMessage, timeoutMs = RPC_TIMEOUT_MS): Promise<RpcMessage> {

package/generated/ai/providers/pi-sdk-node.ts

@@ -25,11 +25,13 @@ import {
 	killWindowsProcessTree,
 	resolveWindowsCommandShim,
 } from "./command-path.ts";
+import { guardChildStreams, writeChildLine } from "./child-io.ts";
 
 // Re-export mapPiEvent from shared (runtime-agnostic)
 export { mapPiEvent } from "./pi-events.ts";
 
 const PROVIDER_NAME = "pi-sdk";
+const PI_PROCESS_LABEL = "Pi process";
 
 // ---------------------------------------------------------------------------
 // JSONL subprocess wrapper (Node.js)
@@ -37,7 +39,8 @@ const PROVIDER_NAME = "pi-sdk";
 
 type EventListener = (event: Record<string, unknown>) => void;
 
-class PiProcessNode {
+/** Exported for the stdio-failure regression tests (#1378). */
+export class PiProcessNode {
 	private proc: ChildProcess | null = null;
 	private listeners: EventListener[] = [];
 	private pendingRequests = new Map<
@@ -62,9 +65,12 @@ class PiProcessNode {
 		let proc: ChildProcess;
 		try {
 			const [file, ...args] = command;
+			// stderr is "ignore", not "pipe": we never read it, and an
+			// un-drained stderr pipe deadlocks the child once its buffer fills
+			// (same reasoning as codex-app-server.ts).
 			proc = spawn(file, args, {
 				cwd,
-				stdio: ["pipe", "pipe", "pipe"],
+				stdio: ["pipe", "pipe", "ignore"],
 			});
 		} catch (err) {
 			const error = err instanceof Error ? err : new Error(String(err));
@@ -73,6 +79,10 @@ class PiProcessNode {
 		}
 
 		this.proc = proc;
+		// Cover every pipe BEFORE the spawn handshake: an `error` event on a
+		// child stream with no listener becomes an uncaughtException and kills
+		// the host agent process, not just this provider (#1378).
+		guardChildStreams(proc, PI_PROCESS_LABEL, (error) => this.failProcess(error));
 		proc.once("exit", () => {
 			this.handleProcessEnd(new Error("Pi process exited unexpectedly"));
 		});
@@ -99,6 +109,24 @@ class PiProcessNode {
 		});
 	}
 
+	/**
+	 * A pipe to the child broke. Resolve it as a provider failure: reject
+	 * everything in flight, tell listeners the process ended, and reap the
+	 * child so it cannot linger with an unusable RPC channel. `alive` flips
+	 * false, so the next query re-spawns a fresh process.
+	 */
+	private failProcess(error: Error): void {
+		const proc = this.proc;
+		this.handleProcessEnd(error);
+		if (proc) {
+			try {
+				if (!killWindowsProcessTree(proc.pid)) proc.kill();
+			} catch {
+				// Already gone.
+			}
+		}
+	}
+
 	private handleProcessEnd(error: Error): void {
 		if (!this.proc && this.pendingRequests.size === 0) return;
 
@@ -153,9 +181,23 @@ class PiProcessNode {
 		}
 	}
 
+	/**
+	 * Send a command without waiting for a response.
+	 *
+	 * A closed or broken stdin is a provider failure, never a throw at the
+	 * caller and never an unhandled stream error: both the synchronous throw
+	 * and the asynchronous `error`/write-callback paths land in failProcess,
+	 * which rejects anything in flight (including the `sendAndWait` request
+	 * this call may be carrying).
+	 */
 	send(command: Record<string, unknown>): void {
-		if (!this.proc?.stdin || this.proc.stdin.destroyed) return;
-		this.proc.stdin.write(`${JSON.stringify(command)}\n`);
+		const error = writeChildLine(
+			this.proc,
+			`${JSON.stringify(command)}\n`,
+			PI_PROCESS_LABEL,
+			(err) => this.failProcess(err),
+		);
+		if (error) this.failProcess(error);
 	}
 
 	sendAndWait(

package/generated/ai/providers/pi-sdk.ts

@@ -58,11 +58,14 @@ class PiProcess {
 				"rpc",
 			];
 		try {
+			// stderr is "ignore", not "pipe": we never read it, and an
+			// un-drained stderr pipe deadlocks the child once its buffer fills
+			// (same reasoning as codex-app-server.ts).
 			this.proc = Bun.spawn(command, {
 				cwd,
 				stdin: "pipe",
 				stdout: "pipe",
-				stderr: "pipe",
+				stderr: "ignore",
 			});
 		} catch (err) {
 			const error = err instanceof Error ? err : new Error(String(err));
@@ -78,6 +81,22 @@ class PiProcess {
 		});
 	}
 
+	/**
+	 * A pipe to the child broke: resolve it as a provider failure and reap the
+	 * child, leaving `alive` false so the next query re-spawns.
+	 */
+	private failProcess(error: Error): void {
+		const proc = this.proc;
+		this.handleProcessEnd(error);
+		if (proc) {
+			try {
+				if (!killWindowsProcessTree(proc.pid)) proc.kill();
+			} catch {
+				// Already gone.
+			}
+		}
+	}
+
 	private handleProcessEnd(error: Error): void {
 		if (!this.proc && this.pendingRequests.size === 0) return;
 
@@ -144,13 +163,42 @@ class PiProcess {
 		}
 	}
 
-	/** Send a command without waiting for a response. */
+	/**
+	 * Send a command without waiting for a response.
+	 *
+	 * The write is guarded for the same reason the Node variant's is (#1378):
+	 * the child can close the pipe between the liveness check and the write,
+	 * and a raw EPIPE escaping here would surface as a synchronous throw at
+	 * the caller (or an unhandled rejection out of flush()) instead of a
+	 * provider failure. Failing the process rejects anything in flight.
+	 */
 	send(command: Record<string, unknown>): void {
-		if (!this.proc?.stdin || typeof this.proc.stdin === "number") return;
+		const stdin = this.proc?.stdin;
+		if (!stdin || typeof stdin === "number") {
+			this.failProcess(new Error("Pi process stdin is closed"));
+			return;
+		}
 		// Bun.spawn stdin is a FileSink with .write(), not a WritableStream
-		const sink = this.proc.stdin as { write(data: string): void; flush(): void };
-		sink.write(`${JSON.stringify(command)}\n`);
-		sink.flush();
+		const sink = stdin as { write(data: string): void; flush(): unknown };
+		try {
+			sink.write(`${JSON.stringify(command)}\n`);
+			const flushed = sink.flush();
+			if (flushed && typeof (flushed as Promise<number>).then === "function") {
+				(flushed as Promise<number>).catch((err: unknown) => {
+					this.failProcess(
+						new Error(
+							`Pi process stdin write failed: ${err instanceof Error ? err.message : String(err)}`,
+						),
+					);
+				});
+			}
+		} catch (err) {
+			this.failProcess(
+				new Error(
+					`Pi process stdin write failed: ${err instanceof Error ? err.message : String(err)}`,
+				),
+			);
+		}
 	}
 
 	/** Send a command and wait for the correlated response. */

package/generated/annotate-args.ts

@@ -47,6 +47,10 @@ export interface ParsedAnnotateArgs {
   renderHtml: boolean;
   renderMarkdown: boolean;
   noJina: boolean;
+  /** --app: force a live app session (recognized only with `liveFlags`). */
+  app: boolean;
+  /** --static: force the classic conversion pipeline (only with `liveFlags`). */
+  static: boolean;
 }
 
 type Segment = { type: "ws" | "tok"; text: string };
@@ -60,9 +64,27 @@ const FLAG_MAP = {
   "--no-jina": "noJina",
 } as const satisfies Record<string, keyof Omit<ParsedAnnotateArgs, "filePath" | "rawFilePath">>;
 
-export function parseAnnotateArgs(raw: string): ParsedAnnotateArgs {
+/** Live-mode flags, recognized only where the host actually supports live
+ * app sessions (`liveFlags: true` — Pi today). A host that cannot act on
+ * --app must NOT silently strip it: leaving the token in the path keeps the
+ * legacy "File not found: --app ..." error, which is honest about the flag
+ * being unsupported there. */
+const LIVE_FLAG_MAP = {
+  "--app": "app",
+  "--static": "static",
+} as const satisfies Record<string, keyof Omit<ParsedAnnotateArgs, "filePath" | "rawFilePath">>;
+
+export interface ParseAnnotateArgsOptions {
+  /** Recognize --app / --static (hosts with live app annotation support). */
+  liveFlags?: boolean;
+}
+
+export function parseAnnotateArgs(raw: string, opts?: ParseAnnotateArgsOptions): ParsedAnnotateArgs {
   const s = (raw ?? "").trim();
-  const flags = { gate: false, json: false, hook: false, renderHtml: false, renderMarkdown: false, noJina: false };
+  const flags = { gate: false, json: false, hook: false, renderHtml: false, renderMarkdown: false, noJina: false, app: false, static: false };
+  const flagMap: Record<string, keyof typeof flags> = opts?.liveFlags
+    ? { ...FLAG_MAP, ...LIVE_FLAG_MAP }
+    : { ...FLAG_MAP };
 
   const segments: Segment[] = [];
   for (let i = 0; i < s.length;) {
@@ -76,7 +98,7 @@ export function parseAnnotateArgs(raw: string): ParsedAnnotateArgs {
   for (let j = 0; j < segments.length; j++) {
     const seg = segments[j];
     if (seg.type !== "tok") continue;
-    const key = FLAG_MAP[seg.text as keyof typeof FLAG_MAP];
+    const key = flagMap[seg.text];
     if (!key) continue;
 
     flags[key] = true;