@oh-my-pi/pi-utils 18.4.2 → 18.4.3

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [18.4.3] - 2026-09-28
+
+### Added
+
+- Added an optional `onDone` callback to `readSseJsonOrText` that reports the `[DONE]` sentinel without attaching a raw-event observer ([#13650](https://github.com/can1357/oh-my-pi/pull/13650) by [@H4vC](https://github.com/H4vC)).
+
+### Changed
+
+- SSE events read without raw capture now share one frozen empty `raw` array instead of allocating one per event ([#13650](https://github.com/can1357/oh-my-pi/pull/13650) by [@H4vC](https://github.com/H4vC)).
+
+### Fixed
+
+- Fixed the unsettled-command report overriding an explicit non-zero exit code with 1 and printing a spurious "ended before completing" line ([#13623](https://github.com/can1357/oh-my-pi/pull/13623) by [@H4vC](https://github.com/H4vC))
+
 ## [18.4.2] - 2026-09-28
 
 ### Added

package/dist/types/stream.d.ts

@@ -74,7 +74,13 @@ export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signa
  * which is the safe direction — each is classified as text rather than trusted as
  * an event object.
  */
-export declare function readSseJsonOrText<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T | string>;
+export declare function readSseJsonOrText<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver, 
+/**
+ * Called when iteration ends on the OpenAI `[DONE]` sentinel. Lets a
+ * consumer tell a server-agreed end from a bare EOF without attaching an
+ * `onEvent` observer (which turns on per-line raw capture).
+ */
+onDone?: () => void): AsyncGenerator<T | string>;
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *
@@ -95,12 +101,13 @@ export interface ServerSentEvent {
      * Decoded wire lines for this event (`event:`/`data:`/etc.), for the
      * diagnostic pipeline. Populated only when the reader opts in via
      * {@link ReadSseEventsOptions.captureRaw} (or attaches an `onSseEvent`
-     * observer to the JSON readers, which opt in automatically); otherwise
-     * `[]`. Direct `readSseEvents` callers that need wire text must pass
+     * observer to the JSON readers, which opt in automatically); otherwise a
+     * shared, frozen empty array — copy or reassign it, never mutate it in
+     * place. Direct `readSseEvents` callers that need wire text must pass
      * `{ captureRaw: true }` — the field is allocation-free by default so
      * the token path pays no per-frame array/slice cost.
      */
-    raw: string[];
+    raw: readonly string[];
     id?: string;
     retry?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.4.2",
+	"version": "18.4.3",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.4.2"
+		"@oh-my-pi/pi-natives": "18.4.3"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/postmortem.ts

@@ -406,8 +406,14 @@ export function reportUnsettledEntry(work: Promise<unknown>, describe?: () => st
 			drained = false;
 		}, 0).unref();
 	});
-	process.once("exit", () => {
+	process.once("exit", code => {
 		if (!pending || !drained) return;
+		// A non-zero code is already a failure verdict — an explicit
+		// `process.exit(n)` (possibly on the same loop turn as a Windows
+		// mid-I/O `beforeExit`, before the clearing timer runs) or an
+		// `exitCode` the command set. Overwriting it with 1 and a second
+		// "ended before completing" line only obscures the real error.
+		if (code !== 0) return;
 		const command = describe?.();
 		const subject = command ? `\`${APP_NAME} ${command}\`` : "command";
 		const message = `${subject} ended before completing: the event loop drained while it was still pending (rerun with PI_DEBUG_STARTUP=1 to see the last phase reached)`;

package/src/stream.ts

@@ -292,13 +292,14 @@ type SseFrame<T> = { ok: true; value: T } | { ok: false; raw: string; error: Syn
 /**
  * Shared `data:`-line framing for {@link readSseJson} and
  * {@link readSseJsonOrText}: skips empty events, stops at the OpenAI `[DONE]`
- * sentinel, notifies the diagnostic observer, and treats a container-shaped
- * stream tail as a clean end of iteration.
+ * sentinel (reporting it through `onDone`), notifies the diagnostic observer,
+ * and treats a container-shaped stream tail as a clean end of iteration.
  */
 async function* readSseFrames<T>(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
 	onEvent?: SseEventObserver,
+	onDone?: () => void,
 ): AsyncGenerator<SseFrame<T>> {
 	// The diagnostic observer is the only reader of `raw`; capture it exactly
 	// when one is attached so the hot path stays allocation-free.
@@ -307,7 +308,10 @@ async function* readSseFrames<T>(
 		notifySseEventObserver(onEvent, sse);
 		const data = sse.data;
 		if (data === "" || data === "[DONE]") {
-			if (data === "[DONE]") return;
+			if (data === "[DONE]") {
+				onDone?.();
+				return;
+			}
 			continue;
 		}
 		try {
@@ -358,8 +362,14 @@ export async function* readSseJsonOrText<T>(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
 	onEvent?: SseEventObserver,
+	/**
+	 * Called when iteration ends on the OpenAI `[DONE]` sentinel. Lets a
+	 * consumer tell a server-agreed end from a bare EOF without attaching an
+	 * `onEvent` observer (which turns on per-line raw capture).
+	 */
+	onDone?: () => void,
 ): AsyncGenerator<T | string> {
-	for await (const frame of readSseFrames<T>(stream, signal, onEvent)) {
+	for await (const frame of readSseFrames<T>(stream, signal, onEvent, onDone)) {
 		if (!frame.ok) yield frame.raw;
 		else yield frame.value;
 	}
@@ -385,12 +395,13 @@ export interface ServerSentEvent {
 	 * Decoded wire lines for this event (`event:`/`data:`/etc.), for the
 	 * diagnostic pipeline. Populated only when the reader opts in via
 	 * {@link ReadSseEventsOptions.captureRaw} (or attaches an `onSseEvent`
-	 * observer to the JSON readers, which opt in automatically); otherwise
-	 * `[]`. Direct `readSseEvents` callers that need wire text must pass
+	 * observer to the JSON readers, which opt in automatically); otherwise a
+	 * shared, frozen empty array — copy or reassign it, never mutate it in
+	 * place. Direct `readSseEvents` callers that need wire text must pass
 	 * `{ captureRaw: true }` — the field is allocation-free by default so
 	 * the token path pays no per-frame array/slice cost.
 	 */
-	raw: string[];
+	raw: readonly string[];
 	id?: string;
 	retry?: number;
 }
@@ -414,6 +425,13 @@ interface SseEventState {
 // an ASCII line-ending byte, which cannot split a multi-byte UTF-8 sequence.
 const SSE_DECODER = new TextDecoder("utf-8");
 
+/**
+ * `raw` of every event dispatched with capture off. Shared instead of one
+ * fresh array per event; frozen so an in-place mutation throws rather than
+ * leaking lines into every other event (consumers copy or reassign `raw`).
+ */
+const EMPTY_RAW: readonly string[] = Object.freeze<string[]>([]);
+
 function flushSseEvent(state: SseEventState): ServerSentEvent | null {
 	if (state.event === null && state.data === null && state.id === undefined && state.retry === undefined) {
 		if (state.raw !== null) state.raw = [];
@@ -422,7 +440,7 @@ function flushSseEvent(state: SseEventState): ServerSentEvent | null {
 	const event: ServerSentEvent = {
 		event: state.event,
 		data: state.data ?? "",
-		raw: state.raw ?? [],
+		raw: state.raw ?? EMPTY_RAW,
 	};
 	if (state.id !== undefined) event.id = state.id;
 	if (state.retry !== undefined) event.retry = state.retry;