@oh-my-pi/pi-agent-core 15.5.4 → 15.5.6

package/dist/types/index.d.ts

@@ -8,3 +8,4 @@ export * from "./run-collector";
 export * from "./telemetry";
 export * from "./thinking";
 export * from "./types";
+export * from "./utils/yield";

package/dist/types/utils/yield.d.ts

@@ -1,20 +1,45 @@
 /**
  * Cooperative yield utility for preventing Bun event-loop busy-wait.
  *
- * Bun 1.3.x (JavaScriptCore) does not automatically yield to the kernel when
- * the microtask queue is continuously non-empty.  In long-running agent loops
- * (LLM streaming, tool execution) this causes ~100% CPU usage even when the
- * process is simply waiting for I/O.
- *
- * `yieldIfDue()` uses a compensated sleep that retries `scheduler.wait()`
- * until the requested wall-clock duration has actually elapsed.  This is
- * necessary because napi callbacks (e.g. `Shell.run` chunk callbacks via
- * `uv_async_send`) can wake the event loop prematurely, causing the timer
- * to return after only ~1–2 ms regardless of the requested duration.
- *
- * The minimum effective sleep is ~20 ms per yield; at ~30 yield calls/second
- * this gives 600 ms/second of kernel sleep → ~40% CPU under active load.
+ * ## Root Cause
+ *
+ * Bun 1.3.x (JavaScriptCore) event loop busy-waits (spins in userspace)
+ * when the only pending work is an unresolved Promise — even if there are
+ * active I/O watchers (stdin, child process pipes, etc.).  The event loop
+ * continuously polls for microtask resolution instead of blocking in
+ * `epoll_wait`, consuming ~100% of a CPU core.
+ *
+ * This affects any `await` on a never-resolved Promise, including:
+ * - `Promise.withResolvers()` used for user input callbacks
+ * - `await proc.exited` for long-running child processes
+ * - Agent loop iterations waiting for the next tool call
+ *
+ * ## Fix
+ *
+ * A recurring `setInterval` keeps the event loop sleeping in `epoll_wait`.
+ * The `EventLoopKeepalive` class and `keepaliveWhile()` wrapper provide a
+ * clean way to install and clean up this keepalive timer.
+ *
+ * The older `yieldIfDue()` and `ExponentialYield` approaches (compensated
+ * sleep loops) are retained for the agent-loop hot-path where Promises
+ * resolve frequently and the keepalive alone is insufficient.
+ */
+/**
+ * Await a Promise with an event-loop keepalive active.
+ *
+ * This is the primary fix for Bun's busy-wait on unresolved Promises.
+ * Use it wherever you `await` a Promise that may remain unresolved for
+ * an extended period (user input, long-running subprocess, etc.).
+ *
+ * ```ts
+ * // Before (100% CPU while waiting):
+ * const input = await mode.getUserInput();
+ *
+ * // After (proper epoll_wait sleep):
+ * const input = await keepaliveWhile(mode.getUserInput());
+ * ```
  */
+export declare function keepaliveWhile<T>(promise: Promise<T>): Promise<T>;
 /**
  * Yield to the Bun event loop, sleeping for at least 20 ms — but at most
  * once every {@link YIELD_INTERVAL_MS}. Callers in hot paths can invoke

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "15.5.4",
+	"version": "15.5.6",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "15.5.4",
-		"@oh-my-pi/pi-natives": "15.5.4",
-		"@oh-my-pi/pi-utils": "15.5.4",
+		"@oh-my-pi/pi-ai": "15.5.6",
+		"@oh-my-pi/pi-natives": "15.5.6",
+		"@oh-my-pi/pi-utils": "15.5.6",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent.ts

@@ -1,6 +1,8 @@
 /** Agent class that uses the agent-loop directly.
  * No transport abstraction - calls streamSimple via the loop.
  */
+
+import { isPromise } from "node:util/types";
 import {
 	type AssistantMessage,
 	type AssistantMessageEvent,
@@ -1074,7 +1076,16 @@ export class Agent {
 
 	#emit(e: AgentEvent) {
 		for (const listener of this.#listeners) {
-			listener(e);
+			try {
+				const result = listener(e) as unknown;
+				if (isPromise(result)) {
+					result.catch(err => {
+						console.error("Agent listener rejected:", err instanceof Error ? err.message : err);
+					});
+				}
+			} catch (err) {
+				console.error("Agent listener threw:", err instanceof Error ? err.message : err);
+			}
 		}
 	}
 

package/src/index.ts

@@ -17,3 +17,5 @@ export * from "./telemetry";
 export * from "./thinking";
 // Types
 export * from "./types";
+// Yield utilities for Bun event-loop busy-wait prevention
+export * from "./utils/yield";

package/src/utils/yield.ts

@@ -1,23 +1,67 @@
 /**
  * Cooperative yield utility for preventing Bun event-loop busy-wait.
  *
- * Bun 1.3.x (JavaScriptCore) does not automatically yield to the kernel when
- * the microtask queue is continuously non-empty.  In long-running agent loops
- * (LLM streaming, tool execution) this causes ~100% CPU usage even when the
- * process is simply waiting for I/O.
+ * ## Root Cause
  *
- * `yieldIfDue()` uses a compensated sleep that retries `scheduler.wait()`
- * until the requested wall-clock duration has actually elapsed.  This is
- * necessary because napi callbacks (e.g. `Shell.run` chunk callbacks via
- * `uv_async_send`) can wake the event loop prematurely, causing the timer
- * to return after only ~1–2 ms regardless of the requested duration.
+ * Bun 1.3.x (JavaScriptCore) event loop busy-waits (spins in userspace)
+ * when the only pending work is an unresolved Promise — even if there are
+ * active I/O watchers (stdin, child process pipes, etc.).  The event loop
+ * continuously polls for microtask resolution instead of blocking in
+ * `epoll_wait`, consuming ~100% of a CPU core.
  *
- * The minimum effective sleep is ~20 ms per yield; at ~30 yield calls/second
- * this gives 600 ms/second of kernel sleep → ~40% CPU under active load.
+ * This affects any `await` on a never-resolved Promise, including:
+ * - `Promise.withResolvers()` used for user input callbacks
+ * - `await proc.exited` for long-running child processes
+ * - Agent loop iterations waiting for the next tool call
+ *
+ * ## Fix
+ *
+ * A recurring `setInterval` keeps the event loop sleeping in `epoll_wait`.
+ * The `EventLoopKeepalive` class and `keepaliveWhile()` wrapper provide a
+ * clean way to install and clean up this keepalive timer.
+ *
+ * The older `yieldIfDue()` and `ExponentialYield` approaches (compensated
+ * sleep loops) are retained for the agent-loop hot-path where Promises
+ * resolve frequently and the keepalive alone is insufficient.
  */
 
 import { scheduler } from "node:timers/promises";
 
+// ---------------------------------------------------------------------------
+// EventLoopKeepalive — the primary fix for idle-state busy-wait
+// ---------------------------------------------------------------------------
+
+const KEEPALIVE_INTERVAL_MS = 86_400_000; // 24 hours — re-armed each interval
+
+/**
+ * Await a Promise with an event-loop keepalive active.
+ *
+ * This is the primary fix for Bun's busy-wait on unresolved Promises.
+ * Use it wherever you `await` a Promise that may remain unresolved for
+ * an extended period (user input, long-running subprocess, etc.).
+ *
+ * ```ts
+ * // Before (100% CPU while waiting):
+ * const input = await mode.getUserInput();
+ *
+ * // After (proper epoll_wait sleep):
+ * const input = await keepaliveWhile(mode.getUserInput());
+ * ```
+ */
+export async function keepaliveWhile<T>(promise: Promise<T>): Promise<T> {
+	const ka = setInterval(() => {}, KEEPALIVE_INTERVAL_MS);
+	try {
+		ka.unref();
+		return await promise;
+	} finally {
+		clearInterval(ka);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// yieldIfDue — retained for agent-loop hot-path
+// ---------------------------------------------------------------------------
+
 const YIELD_SLEEP_MS = 20;
 const YIELD_INTERVAL_MS = 50;
 
@@ -63,7 +107,9 @@ export async function yieldIfDue(): Promise<void> {
 	lastYieldAt = Date.now();
 }
 
-// --- ExponentialYield ---
+// ---------------------------------------------------------------------------
+// ExponentialYield — retained for bash-executor long waits
+// ---------------------------------------------------------------------------
 
 const EXP_DEFAULT_MIN_MS = 20;
 const EXP_DEFAULT_MAX_MS = 10_000;