@oh-my-pi/pi-utils 15.13.2 → 15.13.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [15.13.3] - 2026-06-15
+
+### Added
+
+- Added `installWorkerInbox(port)` / `consumeWorkerInbox()` to `@oh-my-pi/pi-utils/worker-host`. A self-dispatching CLI host that imports a Bun worker module dynamically attaches the worker's real `message` listener after Bun flushes the messages the parent posted before spawn, dropping a synchronously-posted `init`. The host installs this buffering inbox synchronously in the entry's sync prefix so a listener exists at flush time; the worker module consumes it and binds the real handler, replaying anything buffered.
+
 ## [15.13.1] - 2026-06-15
 
 ### Added

package/dist/types/worker-host.d.ts

@@ -2,3 +2,46 @@
 export declare function declareWorkerHostEntry(): void;
 /** Main-module path of the self-dispatching CLI host, or null outside it. */
 export declare function workerHostEntry(): string | null;
+/**
+ * Buffers messages a Bun worker thread receives before its real handler is
+ * attached, then hands them off once it is.
+ *
+ * Bun delivers messages the parent posted before the worker spawned exactly
+ * once — when the worker entry module's top-level evaluation completes — to the
+ * `message` listeners present at that moment. A worker whose handler attaches
+ * via a later `await import(...)` therefore misses that flush. The
+ * self-dispatching CLI host imports each worker module dynamically from inside
+ * its argv dispatch, so the worker's own `parentPort.on("message")` lands after
+ * the flush and the parent's synchronously-posted `init` handshake is dropped —
+ * every run then stalls until the init timeout fires and silently falls back to
+ * the inline worker (issue: eval cells always taking the full timeout).
+ *
+ * The host calls {@link installWorkerInbox} synchronously in the entry's sync
+ * prefix (before importing the worker module) so a `parentPort` listener exists
+ * at flush time; the worker module then {@link consumeWorkerInbox}es it and
+ * binds the real handler, replaying anything buffered. Re-dispatching through
+ * `parentPort.emit("message", …)` is not an option — Bun's port is an
+ * `EventTarget` whose `emit` throws — so the inbox calls the handler directly.
+ */
+export interface WorkerInbox {
+    /** Route buffered and subsequent messages to `handler`; returns an unbind fn. */
+    bind(handler: (message: unknown) => void): () => void;
+}
+/** Minimal `parentPort` surface the inbox needs (Node/Bun `MessagePort`). */
+interface MessageListenerPort {
+    on(event: "message", listener: (value: unknown) => void): unknown;
+}
+/**
+ * Attach a buffering `message` listener on `port` synchronously and stash the
+ * resulting inbox for the worker module to {@link consumeWorkerInbox}. MUST be
+ * called in the entry module's synchronous prefix — before the worker module is
+ * imported — so the listener exists when Bun flushes pre-spawn messages.
+ */
+export declare function installWorkerInbox(port: MessageListenerPort): WorkerInbox;
+/**
+ * Take the inbox installed by {@link installWorkerInbox} for this worker, or
+ * `null` when the worker module was loaded directly (no host pre-buffering, so
+ * the module's own synchronous top-level listener already wins the flush).
+ */
+export declare function consumeWorkerInbox(): WorkerInbox | null;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.13.2",
+	"version": "15.13.3",
 	"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": "15.13.2",
+		"@oh-my-pi/pi-natives": "15.13.3",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/worker-host.ts

@@ -17,3 +17,74 @@ export function declareWorkerHostEntry(): void {
 export function workerHostEntry(): string | null {
 	return workerHostMain;
 }
+
+/**
+ * Buffers messages a Bun worker thread receives before its real handler is
+ * attached, then hands them off once it is.
+ *
+ * Bun delivers messages the parent posted before the worker spawned exactly
+ * once — when the worker entry module's top-level evaluation completes — to the
+ * `message` listeners present at that moment. A worker whose handler attaches
+ * via a later `await import(...)` therefore misses that flush. The
+ * self-dispatching CLI host imports each worker module dynamically from inside
+ * its argv dispatch, so the worker's own `parentPort.on("message")` lands after
+ * the flush and the parent's synchronously-posted `init` handshake is dropped —
+ * every run then stalls until the init timeout fires and silently falls back to
+ * the inline worker (issue: eval cells always taking the full timeout).
+ *
+ * The host calls {@link installWorkerInbox} synchronously in the entry's sync
+ * prefix (before importing the worker module) so a `parentPort` listener exists
+ * at flush time; the worker module then {@link consumeWorkerInbox}es it and
+ * binds the real handler, replaying anything buffered. Re-dispatching through
+ * `parentPort.emit("message", …)` is not an option — Bun's port is an
+ * `EventTarget` whose `emit` throws — so the inbox calls the handler directly.
+ */
+export interface WorkerInbox {
+	/** Route buffered and subsequent messages to `handler`; returns an unbind fn. */
+	bind(handler: (message: unknown) => void): () => void;
+}
+
+/** Minimal `parentPort` surface the inbox needs (Node/Bun `MessagePort`). */
+interface MessageListenerPort {
+	on(event: "message", listener: (value: unknown) => void): unknown;
+}
+
+let pendingInbox: WorkerInbox | null = null;
+
+/**
+ * Attach a buffering `message` listener on `port` synchronously and stash the
+ * resulting inbox for the worker module to {@link consumeWorkerInbox}. MUST be
+ * called in the entry module's synchronous prefix — before the worker module is
+ * imported — so the listener exists when Bun flushes pre-spawn messages.
+ */
+export function installWorkerInbox(port: MessageListenerPort): WorkerInbox {
+	const queue: unknown[] = [];
+	let handler: ((message: unknown) => void) | null = null;
+	port.on("message", (data: unknown) => {
+		if (handler) handler(data);
+		else queue.push(data);
+	});
+	const inbox: WorkerInbox = {
+		bind(next) {
+			handler = next;
+			for (const data of queue) next(data);
+			queue.length = 0;
+			return () => {
+				if (handler === next) handler = null;
+			};
+		},
+	};
+	pendingInbox = inbox;
+	return inbox;
+}
+
+/**
+ * Take the inbox installed by {@link installWorkerInbox} for this worker, or
+ * `null` when the worker module was loaded directly (no host pre-buffering, so
+ * the module's own synchronous top-level listener already wins the flush).
+ */
+export function consumeWorkerInbox(): WorkerInbox | null {
+	const inbox = pendingInbox;
+	pendingInbox = null;
+	return inbox;
+}