@oh-my-pi/pi-agent-core 16.1.16 → 16.1.17

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.1.17] - 2026-06-24
+
+### Fixed
+
+- Hardened the agent-loop cooperative yield against backward wall-clock jumps. A stale future timestamp left in the shared yield gate (NTP step, or a fake-timer test mocking `Date.now`) could make `yieldIfDue()` gate forever and stop yielding to the event loop; the gate now treats a backward clock delta as due and re-anchors. The gate is exposed as an injectable `YieldGate` (with `yieldIfDue()` retained as the shared singleton) so it can be exercised without mocking process-global timers.
+
 ## [16.1.16] - 2026-06-23
 
 ### Added

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

@@ -29,9 +29,28 @@ export declare class EventLoopKeepalive {
     [Symbol.dispose](): void;
 }
 /**
- * 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
- * this freely; only the slow path actually sleeps.
+ * Cooperative yield gate. Sleeps for at least {@link YieldGateOptions.sleepMs}
+ * but at most once every {@link YieldGateOptions.intervalMs}; hot-path callers
+ * invoke it freely and only the slow path actually sleeps.
+ *
+ * The clock and sleep are injectable so tests drive the gate logic without
+ * touching process-global `Date.now`/`scheduler.wait` — globals a concurrent
+ * test file can restore mid-run, which previously made the shared gate flake.
+ */
+export interface YieldGateOptions {
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    intervalMs?: number;
+    sleepMs?: number;
+}
+export declare class YieldGate {
+    #private;
+    constructor(opts?: YieldGateOptions);
+    yieldIfDue(signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most once
+ * every {@link YIELD_INTERVAL_MS} across all callers.
  */
 export declare function yieldIfDue(): Promise<void>;
 export declare class ExponentialYield {

package/package.json

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

package/src/utils/yield.ts

@@ -45,13 +45,6 @@ export class EventLoopKeepalive {
 const YIELD_SLEEP_MS = 20;
 const YIELD_INTERVAL_MS = 50;
 
-/**
- * Wall-clock timestamp of the last completed yield. Module-level so that
- * tight loops sharing this helper collectively respect the gate, not just
- * one caller at a time.
- */
-let lastYieldAt = 0;
-
 /**
  * Sleep for at least `ms` milliseconds of wall-clock time.
  * Retries the wait if it returns prematurely (which can happen when napi
@@ -76,15 +69,59 @@ async function sleepAtLeast(ms: number, signal?: AbortSignal): Promise<void> {
 }
 
 /**
- * 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
- * this freely; only the slow path actually sleeps.
+ * Cooperative yield gate. Sleeps for at least {@link YieldGateOptions.sleepMs}
+ * but at most once every {@link YieldGateOptions.intervalMs}; hot-path callers
+ * invoke it freely and only the slow path actually sleeps.
+ *
+ * The clock and sleep are injectable so tests drive the gate logic without
+ * touching process-global `Date.now`/`scheduler.wait` — globals a concurrent
+ * test file can restore mid-run, which previously made the shared gate flake.
+ */
+export interface YieldGateOptions {
+	now?: () => number;
+	sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+	intervalMs?: number;
+	sleepMs?: number;
+}
+
+export class YieldGate {
+	#lastYieldAt = 0;
+	readonly #now: () => number;
+	readonly #sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+	readonly #intervalMs: number;
+	readonly #sleepMs: number;
+
+	constructor(opts: YieldGateOptions = {}) {
+		this.#now = opts.now ?? (() => Date.now());
+		this.#sleep = opts.sleep ?? sleepAtLeast;
+		this.#intervalMs = opts.intervalMs ?? YIELD_INTERVAL_MS;
+		this.#sleepMs = opts.sleepMs ?? YIELD_SLEEP_MS;
+	}
+
+	async yieldIfDue(signal?: AbortSignal): Promise<void> {
+		const now = this.#now();
+		const elapsed = now - this.#lastYieldAt;
+		// `elapsed < 0` means the wall clock moved backward relative to the last
+		// yield (NTP step, fake-timer test, or a stale future timestamp left by
+		// another caller): treat it as due and re-anchor rather than gate forever.
+		if (elapsed >= 0 && elapsed < this.#intervalMs) return;
+		await this.#sleep(this.#sleepMs, signal);
+		this.#lastYieldAt = this.#now();
+	}
+}
+
+/**
+ * Process-wide gate shared by all hot-path callers so tight loops collectively
+ * respect the interval rather than each sleeping independently.
+ */
+const sharedYieldGate = new YieldGate();
+
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most once
+ * every {@link YIELD_INTERVAL_MS} across all callers.
  */
-export async function yieldIfDue(): Promise<void> {
-	const now = Date.now();
-	if (now - lastYieldAt < YIELD_INTERVAL_MS) return;
-	await sleepAtLeast(YIELD_SLEEP_MS);
-	lastYieldAt = Date.now();
+export function yieldIfDue(): Promise<void> {
+	return sharedYieldGate.yieldIfDue();
 }
 
 // ---------------------------------------------------------------------------