@oh-my-pi/pi-utils 14.7.1 → 14.7.3

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "14.7.1",
+	"version": "14.7.3",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -38,7 +38,7 @@
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.13",
-		"@oh-my-pi/pi-natives": "14.7.1"
+		"@oh-my-pi/pi-natives": "14.7.3"
 	},
 	"engines": {
 		"bun": ">=1.3.7"

package/src/dirs.ts

@@ -192,6 +192,12 @@ class DirResolver {
 
 let dirs = new DirResolver(process.env.PI_CODING_AGENT_DIR);
 
+// Anchor home for the resolver. Captured at module load to stay stable across
+// test mocks of `os.homedir()`. `getPluginsDir(home)` compares against this so
+// production callers (`home === RESOLVER_HOME`) hit the XDG-aware resolver while
+// tests passing a temp HOME short-circuit to a deterministic path.
+const RESOLVER_HOME = os.homedir();
+
 // =============================================================================
 // Root directories
 // =============================================================================
@@ -236,8 +242,20 @@ export function getLogPath(date = new Date()): string {
 	return path.join(getLogsDir(), `${APP_NAME}.${date.toISOString().slice(0, 10)}.log`);
 }
 
-/** Get the plugins directory (~/.omp/plugins). */
-export function getPluginsDir(): string {
+/**
+ * Get the plugins directory (~/.omp/plugins or its XDG equivalent).
+ *
+ * No-arg form (production callers) goes through the XDG-aware DirResolver so
+ * reads and writes always agree. The optional `home` parameter is for test
+ * isolation: when it differs from `os.homedir()` it short-circuits the resolver
+ * and returns `<home>/<configDir>/plugins` so tests with a temp HOME get a
+ * deterministic path. Passing `os.homedir()` explicitly is identical to the
+ * no-arg form — XDG semantics are preserved.
+ */
+export function getPluginsDir(home?: string): string {
+	if (home !== undefined && home !== RESOLVER_HOME) {
+		return path.join(home, getConfigDirName(), "plugins");
+	}
 	return dirs.rootSubdir("plugins", "data");
 }
 
@@ -281,6 +299,11 @@ export function getPythonEnvDir(): string {
 	return dirs.rootSubdir("python-env", "data");
 }
 
+/** Get the shared Python gateway state directory (~/.omp/agent/python-gateway; XDG default: $XDG_STATE_HOME/omp/python-gateway). */
+export function getPythonGatewayDir(): string {
+	return dirs.agentSubdir(undefined, "python-gateway", "state");
+}
+
 /** Get the puppeteer sandbox directory (~/.omp/puppeteer). */
 export function getPuppeteerDir(): string {
 	return dirs.rootSubdir("puppeteer", "cache");

package/src/stream.ts

@@ -76,31 +76,6 @@ export async function* readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?:
 // SSE (Server-Sent Events)
 // =============================================================================
 
-/** Byte lookup table: 1 = whitespace, 0 = not. */
-const WS = new Uint8Array(256);
-WS[0x09] = 1; // tab
-WS[0x0a] = 1; // LF
-WS[0x0d] = 1; // CR
-WS[0x20] = 1; // space
-
-const createPattern = (prefix: string) => {
-	const pre = Buffer.from(prefix, "utf-8");
-	return {
-		strip(buf: Uint8Array): number | null {
-			const n = pre.length;
-			if (buf.length < n) return null;
-			if (pre.equals(buf.subarray(0, n))) {
-				return n;
-			}
-			return null;
-		},
-	};
-};
-
-const PAT_DATA = createPattern("data:");
-
-const PAT_DONE = createPattern("[DONE]");
-
 class ConcatSink {
 	#space?: Buffer;
 	#length = 0;
@@ -208,11 +183,15 @@ class ConcatSink {
 	}
 }
 
-const kDoneError = new Error("SSE stream done");
-
 /**
  * Stream parsed JSON objects from SSE `data:` lines.
  *
+ * Thin wrapper over {@link readSseEvents}: yields one parsed JSON value per
+ * dispatched SSE event, skipping events with empty `data` and stopping at the
+ * OpenAI-style `[DONE]` sentinel. If your consumer doesn't care about `event:`
+ * names or doesn't need a custom parse step, use this; otherwise call
+ * `readSseEvents` directly.
+ *
  * @example
  * ```ts
  * for await (const obj of readSseJson(response.body!)) {
@@ -221,61 +200,150 @@ const kDoneError = new Error("SSE stream done");
  * ```
  */
 export async function* readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T> {
-	const lineBuffer = new ConcatSink();
-	const jsonBuffer = new ConcatSink();
+	for await (const sse of readSseEvents(stream, signal)) {
+		const data = sse.data;
+		if (data === "" || data === "[DONE]") {
+			if (data === "[DONE]") return;
+			continue;
+		}
+		yield JSON.parse(data) as T;
+	}
+}
 
-	// pipeThrough with { signal } makes the stream abort-aware: the pipe
-	// cancels the source and errors the output when the signal fires,
-	// so for-await-of exits cleanly without manual reader/listener management.
-	stream = createAbortableStream(stream, signal);
-	try {
-		const processLine = function* (line: Uint8Array) {
-			// Strip trailing spaces including \r.
-			let end = line.length;
-			while (end && WS[line[end - 1]]) {
-				--end;
-			}
-			if (!end) return; // blank line
+/**
+ * A single Server-Sent Event dispatched on a blank-line boundary.
+ *
+ * - `event` is the value of the most recent `event:` field, or `null` if none.
+ * - `data` is the concatenation (joined by `\n`) of every `data:` field in the
+ *   event, exactly as required by the SSE spec.
+ * - `raw` is the list of decoded non-empty lines that made up the event,
+ *   preserved for diagnostic context (error reporting, debugging). The
+ *   dispatching blank line is not included.
+ */
+export interface ServerSentEvent {
+	event: string | null;
+	data: string;
+	raw: string[];
+}
 
-			const trimmed = end === line.length ? line : line.subarray(0, end);
+interface SseEventState {
+	event: string | null;
+	// `data` accumulates across multiple `data:` lines per the SSE spec, joined
+	// by `\n`. We keep the running string here and append as lines arrive instead
+	// of buffering an array and joining at flush. `null` means "no data: field
+	// seen yet" (distinct from a `data:` field with an empty value).
+	data: string | null;
+	raw: string[];
+}
 
-			// Check "data:" prefix and optional space afterwards.
-			let beg = PAT_DATA.strip(trimmed);
-			if (beg === null) return;
-			while (beg < end && WS[trimmed[beg]]) {
-				++beg;
-			}
-			if (beg >= end) return;
+// 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");
 
-			// Fast-path: the OpenAI-style done marker isn't JSON.
-			const donePrefix = PAT_DONE.strip(trimmed.subarray(beg, end));
-			if (donePrefix !== null && donePrefix === end - beg) {
-				throw kDoneError;
-			}
+function decodeSseLineBytes(line: Uint8Array, end: number): string {
+	return end === line.length ? SSE_LINE_DECODER.decode(line) : SSE_LINE_DECODER.decode(line.subarray(0, end));
+}
 
-			yield* jsonBuffer.pullJSONL<T>(trimmed, beg, end);
-		};
-		for await (const chunk of stream) {
+function flushSseEvent(state: SseEventState): ServerSentEvent | null {
+	if (state.event === null && state.data === null) return null;
+	const event: ServerSentEvent = {
+		event: state.event,
+		data: state.data ?? "",
+		raw: state.raw,
+	};
+	state.event = null;
+	state.data = null;
+	state.raw = [];
+	return event;
+}
+
+function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent | null {
+	// `appendAndFlushLines` splits 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);
+
+	// Comment line: keep in `raw` for diagnostic context, skip parsing.
+	if (line[0] === 0x3a /* ':' */) {
+		state.raw.push(decodeSseLineBytes(line, end));
+		return null;
+	}
+
+	const text = decodeSseLineBytes(line, end);
+	state.raw.push(text);
+
+	const colon = text.indexOf(":");
+	const fieldName = colon === -1 ? text : text.slice(0, colon);
+	let value = colon === -1 ? "" : text.slice(colon + 1);
+	if (value.charCodeAt(0) === 0x20 /* ' ' */) value = value.slice(1);
+
+	if (fieldName === "event") {
+		state.event = value;
+	} else if (fieldName === "data") {
+		if (state.data === null) {
+			state.data = value;
+		} else {
+			state.data += "\n";
+			state.data += value;
+		}
+	}
+	// `id` and `retry` are intentionally ignored — the providers we consume
+	// don't use them, and the underlying transport handles reconnects itself.
+	return null;
+}
+
+/**
+ * Stream raw Server-Sent Events from an HTTP response body.
+ *
+ * Yields one `ServerSentEvent` per blank-line dispatch. The consumer is
+ * responsible for parsing `data` (e.g. JSON, plain text, error envelope).
+ * 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.
+ *
+ * @example
+ * ```ts
+ * for await (const sse of readSseEvents(response.body!)) {
+ *   if (sse.event === "ping") continue;
+ *   const obj = JSON.parse(sse.data);
+ * }
+ * ```
+ */
+export async function* readSseEvents(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+): AsyncGenerator<ServerSentEvent> {
+	const lineBuffer = new ConcatSink();
+	const state: SseEventState = { event: null, data: null, raw: [] };
+	const source = createAbortableStream(stream, signal);
+	try {
+		for await (const chunk of source) {
 			for (const line of lineBuffer.appendAndFlushLines(chunk)) {
-				yield* processLine(line);
+				const event = pushSseLine(line, state);
+				if (event) yield event;
 			}
 		}
+		// Treat any trailing partial line (no terminating LF) as a complete line.
 		if (!lineBuffer.isEmpty) {
 			const tail = lineBuffer.flush();
 			if (tail) {
 				lineBuffer.clear();
-				yield* processLine(tail);
+				const event = pushSseLine(tail, state);
+				if (event) yield event;
 			}
 		}
+		// Real services don't always close on a blank line — flush any pending event.
+		const trailing = flushSseEvent(state);
+		if (trailing) yield trailing;
 	} catch (err) {
-		if (err === kDoneError) return;
-		// Abort errors are expected — just stop the generator.
 		if (signal?.aborted) return;
 		throw err;
 	}
-	if (!jsonBuffer.isEmpty) {
-		throw new Error("SSE stream ended unexpectedly");
-	}
 }
 
 /**