@oh-my-pi/pi-utils 16.5.2 → 17.0.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [17.0.1] - 2026-07-16
+
+### Fixed
+
+- Added scoped graceful handling for stdio-write EPIPE rejections so protocol servers can await postmortem cleanup when their peer disconnects ([#4788](https://github.com/can1357/oh-my-pi/issues/4788)).
+
+## [17.0.0] - 2026-07-15
+
+### Fixed
+
+- Improved SSE streaming performance by batching complete lines into a single UTF-8 decode per chunk, reducing decoder overhead.
+- Fixed an issue in `parseFrontmatter` where a single malformed YAML line would corrupt sibling values by parsing each line independently.
+
 ## [16.5.2] - 2026-07-14
 
 ### Fixed

package/dist/types/postmortem.d.ts

@@ -8,14 +8,23 @@ export declare enum Reason {
     UNHANDLED_REJECTION = "unhandled_rejection",// Unhandled promise rejection
     MANUAL = "manual"
 }
+/** Origin of an EPIPE raised by a process communication channel. */
+export type BrokenPipeSource = "ipc-send" | "stdio-write";
 /**
- * Detect an EPIPE rejection that originated from an IPC `send()` to a worker
- * subprocess (`syscall: "send"`), as opposed to a stdin/stdout pipe write
- * (`syscall: "write"`). Only the IPC-send path can break an optional worker
- * subsystem without affecting the main process, so only this shape is safe to
- * swallow at the global `unhandledRejection` level. See issue #2997.
+ * Classify EPIPE errors from worker IPC and stdio without treating unrelated
+ * broken pipes as globally recoverable.
  */
+export declare function classifyBrokenPipe(err: Error): BrokenPipeSource | undefined;
+/** Whether an EPIPE came from an IPC `send()` to an optional worker. */
 export declare function isIpcSendEpipe(err: Error): boolean;
+/**
+ * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
+ *
+ * Stdio protocol servers call this for their process lifetime so a closed
+ * client pipe runs registered cleanup callbacks instead of the fatal path.
+ * The returned callback removes the registration.
+ */
+export declare function registerStdioDisconnectHandling(): () => void;
 /**
  * Mark an error as expected cleanup fallout so the global fatal handlers
  * downgrade it to a log line instead of tearing down the process. Use for

package/dist/types/stream.d.ts

@@ -41,9 +41,8 @@ export interface ServerSentEvent {
  * Use `readSseJson` instead when every event is a single `data:` JSON object
  * and you don't need access to the `event:` field.
  *
- * Internally backed by a Buffer-based line reader (`ConcatSink`) so chunk
- * concatenation is O(n) and never triggers per-line string slicing of the
- * accumulated buffer.
+ * Internally backed by a Buffer-based reader (`ConcatSink`) that batches all
+ * complete lines in each source chunk into one UTF-8 decode.
  *
  * @example
  * ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "16.5.2",
+	"version": "17.0.1",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.5.2",
+		"@oh-my-pi/pi-natives": "17.0.1",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
 		"winston-daily-rotate-file": "^5.0.0"

package/src/frontmatter.ts

@@ -149,12 +149,25 @@ export function parseFrontmatter(
 			throw err;
 		}
 
-		// Simple YAML parsing - just key: value pairs
+		// Simple key: value fallback. Reparse each value on its own so one
+		// malformed line (e.g. `scope: "text","thinking"`) can't leave sibling
+		// values wrapped in literal quotes; values that don't parse as YAML fall
+		// back to the raw trimmed string (issue #4796).
 		for (const line of metadata.split("\n")) {
 			const match = line.match(/^([\w-]+):\s*(.*)$/);
-			if (match) {
-				frontmatter[match[1]] = match[2].trim();
+			if (!match) continue;
+			const raw = match[2].trim();
+			let value: unknown = raw;
+			if (raw.length > 0) {
+				try {
+					const parsed = YAML.parse(raw);
+					if (parsed !== null && typeof parsed !== "object") value = parsed;
+					else if (Array.isArray(parsed)) value = parsed;
+				} catch {
+					// keep the raw string
+				}
 			}
+			frontmatter[match[1]] = value;
 		}
 
 		return { frontmatter: normalizeKeys(frontmatter) as Record<string, unknown>, body };

package/src/postmortem.ts

@@ -27,6 +27,8 @@ const callbackList: ((reason: Reason) => Promise<void> | void)[] = [];
 // Tracks cleanup run state (to prevent recursion/reentry issues)
 let cleanupStage: "idle" | "running" | "complete" = "idle";
 const CLEANUP_DEADLINE_MS = 10_000;
+let cleanupPromise: Promise<void> | undefined;
+let stdioDisconnectRegistrations = 0;
 
 /**
  * Internal: runs all registered cleanup callbacks for the given reason.
@@ -40,7 +42,7 @@ function runCleanup(reason: Reason): Promise<void> {
 			cleanupStage = "running";
 			break;
 		case "running":
-			return Promise.resolve();
+			return cleanupPromise ?? Promise.resolve();
 		case "complete":
 			return Promise.resolve();
 	}
@@ -67,9 +69,10 @@ function runCleanup(reason: Reason): Promise<void> {
 		deadline.resolve();
 	}, CLEANUP_DEADLINE_MS);
 	deadlineTimer.unref();
-	return Promise.race([cleanupSettled, deadline.promise]).finally(() => {
+	cleanupPromise = Promise.race([cleanupSettled, deadline.promise]).finally(() => {
 		clearTimeout(deadlineTimer);
 	});
+	return cleanupPromise;
 }
 
 // Register signal and error event handlers to trigger cleanup before exit.
@@ -77,17 +80,40 @@ function runCleanup(reason: Reason): Promise<void> {
 // Worker thread: exit only (workers use self.addEventListener for exceptions)
 let inspectorOpened = false;
 
+/** Origin of an EPIPE raised by a process communication channel. */
+export type BrokenPipeSource = "ipc-send" | "stdio-write";
+
 /**
- * Detect an EPIPE rejection that originated from an IPC `send()` to a worker
- * subprocess (`syscall: "send"`), as opposed to a stdin/stdout pipe write
- * (`syscall: "write"`). Only the IPC-send path can break an optional worker
- * subsystem without affecting the main process, so only this shape is safe to
- * swallow at the global `unhandledRejection` level. See issue #2997.
+ * Classify EPIPE errors from worker IPC and stdio without treating unrelated
+ * broken pipes as globally recoverable.
  */
+export function classifyBrokenPipe(err: Error): BrokenPipeSource | undefined {
+	if (!("code" in err) || err.code !== "EPIPE" || !("syscall" in err)) return undefined;
+	if (err.syscall === "send") return "ipc-send";
+	if (err.syscall === "write") return "stdio-write";
+	return undefined;
+}
+
+/** Whether an EPIPE came from an IPC `send()` to an optional worker. */
 export function isIpcSendEpipe(err: Error): boolean {
-	const code = (err as { code?: unknown }).code;
-	const syscall = (err as { syscall?: unknown }).syscall;
-	return code === "EPIPE" && syscall === "send";
+	return classifyBrokenPipe(err) === "ipc-send";
+}
+
+/**
+ * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
+ *
+ * Stdio protocol servers call this for their process lifetime so a closed
+ * client pipe runs registered cleanup callbacks instead of the fatal path.
+ * The returned callback removes the registration.
+ */
+export function registerStdioDisconnectHandling(): () => void {
+	let registered = true;
+	stdioDisconnectRegistrations++;
+	return () => {
+		if (!registered) return;
+		registered = false;
+		stdioDisconnectRegistrations--;
+	};
 }
 
 // Well-known key marking an error as an *expected* teardown artifact (e.g. a
@@ -179,6 +205,7 @@ if (isMainThread) {
 		})
 		.on("unhandledRejection", async reason => {
 			const err = reason instanceof Error ? reason : new Error(String(reason));
+			const brokenPipeSource = classifyBrokenPipe(err);
 			// EPIPE from an IPC `send()` (`syscall: "send"`) originates from a
 			// worker subprocess whose pipe broke between the exit being observed
 			// and the next `proc.send()` — a race window that Bun surfaces as an
@@ -188,10 +215,15 @@ if (isMainThread) {
 			// send pipe must never take down the whole session. Log and continue
 			// instead of exiting; the owning client detects the dead worker via
 			// its own `onExit`/error path and respawns or disables it. See #2997.
-			if (isIpcSendEpipe(err)) {
+			if (brokenPipeSource === "ipc-send") {
 				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
 				return;
 			}
+			if (brokenPipeSource === "stdio-write" && stdioDisconnectRegistrations > 0) {
+				logger.warn("Stdio peer disconnected; shutting down gracefully", { err });
+				await quit(0);
+				return;
+			}
 			if (isExpectedCleanupError(reason)) {
 				logger.warn("Ignoring expected cleanup rejection", { err });
 				return;

package/src/stream.ts

@@ -150,6 +150,29 @@ class ConcatSink {
 			}
 		}
 	}
+
+	appendAndFlushText(chunk: Uint8Array, decoder: TextDecoder): string | undefined {
+		const lastNewline = chunk.lastIndexOf(LF);
+		if (lastNewline === -1) {
+			this.append(chunk);
+			return undefined;
+		}
+
+		const completeEnd = lastNewline + 1;
+		let text: string;
+		if (this.isEmpty) {
+			const complete = completeEnd === chunk.length ? chunk : chunk.subarray(0, completeEnd);
+			text = decoder.decode(complete);
+		} else {
+			this.append(completeEnd === chunk.length ? chunk : chunk.subarray(0, completeEnd));
+			text = decoder.decode(this.flush());
+			this.clear();
+		}
+		if (completeEnd < chunk.length) {
+			this.append(chunk.subarray(completeEnd));
+		}
+		return text;
+	}
 	*pullJSONL<T>(chunk: Uint8Array, beg: number, end: number) {
 		if (this.isEmpty) {
 			const { values, error, read, done } = parseJsonlChunkCompat(chunk, beg, end);
@@ -275,14 +298,9 @@ interface SseEventState {
 	raw: string[];
 }
 
-// Single decoder reused for all line decodes. Safe because lines are split on
-// LF (0x0a) which is always a single-byte ASCII char in UTF-8 and never appears
-// inside a multi-byte sequence — so each line is itself a complete UTF-8 run.
-const SSE_LINE_DECODER = new TextDecoder("utf-8");
-
-function decodeSseLineBytes(line: Uint8Array, end: number): string {
-	return end === line.length ? SSE_LINE_DECODER.decode(line) : SSE_LINE_DECODER.decode(line.subarray(0, end));
-}
+// Complete lines are decoded in one batch per source chunk. Each batch ends on
+// LF, which cannot split a multi-byte UTF-8 sequence.
+const SSE_DECODER = new TextDecoder("utf-8");
 
 function flushSseEvent(state: SseEventState): ServerSentEvent | null {
 	if (state.event === null && state.data === null) {
@@ -300,25 +318,25 @@ function flushSseEvent(state: SseEventState): ServerSentEvent | null {
 	return event;
 }
 
-function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent | null {
-	// `appendAndFlushLines` splits on LF only; strip a trailing CR so CRLF sources
+function pushSseLine(line: string, state: SseEventState): ServerSentEvent | null {
+	// Complete-line batches split on LF only; strip a trailing CR so CRLF sources
 	// don't leak `\r` into field values.
-	let end = line.length;
-	if (end > 0 && line[end - 1] === 0x0d /* '\r' */) end--;
-	if (end === 0) return flushSseEvent(state);
+	if (line.charCodeAt(line.length - 1) === 0x0d /* '\r' */) {
+		line = line.slice(0, -1);
+	}
+	if (line.length === 0) return flushSseEvent(state);
 
 	// Comment line: keep in `raw` for diagnostic context, skip parsing.
-	if (line[0] === 0x3a /* ':' */) {
-		state.raw.push(decodeSseLineBytes(line, end));
+	if (line.charCodeAt(0) === 0x3a /* ':' */) {
+		state.raw.push(line);
 		return null;
 	}
 
-	const text = decodeSseLineBytes(line, end);
-	state.raw.push(text);
+	state.raw.push(line);
 
-	const colon = text.indexOf(":");
-	const fieldName = colon === -1 ? text : text.slice(0, colon);
-	let value = colon === -1 ? "" : text.slice(colon + 1);
+	const colon = line.indexOf(":");
+	const fieldName = colon === -1 ? line : line.slice(0, colon);
+	let value = colon === -1 ? "" : line.slice(colon + 1);
 	if (value.charCodeAt(0) === 0x20 /* ' ' */) value = value.slice(1);
 
 	if (fieldName === "event") {
@@ -344,9 +362,8 @@ function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent |
  * Use `readSseJson` instead when every event is a single `data:` JSON object
  * and you don't need access to the `event:` field.
  *
- * Internally backed by a Buffer-based line reader (`ConcatSink`) so chunk
- * concatenation is O(n) and never triggers per-line string slicing of the
- * accumulated buffer.
+ * Internally backed by a Buffer-based reader (`ConcatSink`) that batches all
+ * complete lines in each source chunk into one UTF-8 decode.
  *
  * @example
  * ```ts
@@ -365,9 +382,14 @@ export async function* readSseEvents(
 	const source = abortableSource(stream, signal);
 	try {
 		for await (const chunk of source) {
-			for (const line of lineBuffer.appendAndFlushLines(chunk)) {
-				const event = pushSseLine(line, state);
+			const text = lineBuffer.appendAndFlushText(chunk, SSE_DECODER);
+			if (text === undefined) continue;
+			let start = 0;
+			while (start < text.length) {
+				const newline = text.indexOf("\n", start);
+				const event = pushSseLine(text.slice(start, newline), state);
 				if (event) yield event;
+				start = newline + 1;
 			}
 		}
 		// Treat any trailing partial line (no terminating LF) as a complete line.
@@ -375,7 +397,7 @@ export async function* readSseEvents(
 			const tail = lineBuffer.flush();
 			if (tail) {
 				lineBuffer.clear();
-				const event = pushSseLine(tail, state);
+				const event = pushSseLine(SSE_DECODER.decode(tail), state);
 				if (event) {
 					trailingEvents.add(event);
 					yield event;