@oh-my-pi/pi-agent-core 16.4.3 → 16.4.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.4.5] - 2026-07-11
+
+### Added
+
+- Added a process-global pause gate (`agentPauseGate`) to safely pause agent loops before model calls or tool executions, allowing them to be resumed later or aborted cleanly.
+
 ## [16.4.3] - 2026-07-11
 
 ### Fixed

package/dist/types/index.d.ts

@@ -2,6 +2,7 @@ export * from "./agent.js";
 export * from "./agent-loop.js";
 export * from "./append-only-context.js";
 export * from "./compaction.js";
+export * from "./pause.js";
 export * from "./proxy.js";
 export * from "./replay-policy.js";
 export * from "./run-collector.js";

package/dist/types/pause.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Process-global pause gate for agent loops.
+ *
+ * Every agent in a process — main session, in-process subagents, advisor —
+ * funnels through {@link ../agent-loop!agentLoop}, which polls this gate at its
+ * two action boundaries: before each model call and before each tool call
+ * starts. Engaging the gate therefore freezes all of them at the next safe
+ * point without aborting anything: in-flight provider streams and
+ * already-started tool executions run to completion, then every loop parks
+ * until {@link AgentPauseGate.resume}. Queued steering/follow-up messages stay
+ * queued and deliver normally after resume.
+ *
+ * A run's own `AbortSignal` still unwinds a parked loop immediately: the park
+ * releases on abort (without releasing the gate), so cancelling one run never
+ * requires resuming the whole process.
+ *
+ * Hosts drive the singleton {@link agentPauseGate} (e.g. the TUI `/pause`
+ * command); library code only ever reads it.
+ */
+/** Listener invoked with the new state on every pause/resume transition. */
+export type AgentPauseListener = (paused: boolean) => void;
+/** Freeze switch shared by every agent loop in the process. See module docs. */
+export declare class AgentPauseGate {
+    #private;
+    /** True while the gate is engaged. */
+    get paused(): boolean;
+    /** Epoch ms when the current pause began; undefined when running. */
+    get pausedAt(): number | undefined;
+    /** Engage the gate. Returns false (and does nothing) when already paused. */
+    pause(): boolean;
+    /**
+     * Release the gate, waking every parked loop. Returns the pause duration in
+     * ms, or undefined when the gate was not engaged.
+     */
+    resume(): number | undefined;
+    /** Subscribe to pause/resume transitions. Returns an unsubscribe function. */
+    onChange(listener: AgentPauseListener): () => void;
+    /**
+     * Park until the gate is released. Resolves immediately when not paused.
+     * An abort on `signal` releases only this wait — the gate stays engaged —
+     * so a cancelled run unwinds while the rest of the process stays frozen.
+     */
+    waitUntilResumed(signal?: AbortSignal): Promise<void>;
+}
+/** The process-wide gate polled by the agent loop. */
+export declare const agentPauseGate: AgentPauseGate;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "16.4.3",
+	"version": "16.4.5",
 	"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.4.3",
-		"@oh-my-pi/pi-catalog": "16.4.3",
-		"@oh-my-pi/pi-natives": "16.4.3",
-		"@oh-my-pi/pi-utils": "16.4.3",
-		"@oh-my-pi/pi-wire": "16.4.3",
-		"@oh-my-pi/snapcompact": "16.4.3",
+		"@oh-my-pi/pi-ai": "16.4.5",
+		"@oh-my-pi/pi-catalog": "16.4.5",
+		"@oh-my-pi/pi-natives": "16.4.5",
+		"@oh-my-pi/pi-utils": "16.4.5",
+		"@oh-my-pi/pi-wire": "16.4.5",
+		"@oh-my-pi/snapcompact": "16.4.5",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -40,6 +40,7 @@ import {
 import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { sanitizeText, structuredCloneJSON } from "@oh-my-pi/pi-utils";
 import { INTENT_FIELD } from "@oh-my-pi/pi-wire";
+import { agentPauseGate } from "./pause";
 import { type AgentRunCoverage, type AgentRunSummary, ToolCallBlockedError } from "./run-collector";
 import {
 	type AgentTelemetry,
@@ -816,6 +817,10 @@ async function runLoopBody(
 				// Yield at the top of each iteration to prevent busy-wait when
 				// the agent loop is executing tool calls back-to-back.
 				await yieldIfDue();
+				// Park at the turn boundary while the process-wide pause gate is
+				// engaged (host /pause). An external abort releases the park so a
+				// cancelled run still unwinds while everything else stays frozen.
+				if (agentPauseGate.paused) await agentPauseGate.waitUntilResumed(signal);
 				if (!firstTurn) {
 					stream.push({ type: "turn_start" });
 				} else {
@@ -1922,6 +1927,10 @@ async function executeToolCalls(
 			record.skipped = true;
 			return;
 		}
+		// Park before starting this tool while the process-wide pause gate is
+		// engaged. Tools already executing are unaffected (pausing never aborts);
+		// a batch interrupted mid-pause unwinds via the signal checks below.
+		if (agentPauseGate.paused) await agentPauseGate.waitUntilResumed(record.signal);
 
 		const { toolCall, tool } = record;
 		let argsForExecution = toolCall.arguments as Record<string, unknown>;

package/src/index.ts

@@ -6,6 +6,8 @@ export * from "./agent-loop";
 export * from "./append-only-context";
 // Compaction
 export * from "./compaction";
+// Process-global pause gate
+export * from "./pause";
 // Proxy utilities
 export * from "./proxy";
 // Replay policy

package/src/pause.ts

@@ -0,0 +1,107 @@
+/**
+ * Process-global pause gate for agent loops.
+ *
+ * Every agent in a process — main session, in-process subagents, advisor —
+ * funnels through {@link ../agent-loop!agentLoop}, which polls this gate at its
+ * two action boundaries: before each model call and before each tool call
+ * starts. Engaging the gate therefore freezes all of them at the next safe
+ * point without aborting anything: in-flight provider streams and
+ * already-started tool executions run to completion, then every loop parks
+ * until {@link AgentPauseGate.resume}. Queued steering/follow-up messages stay
+ * queued and deliver normally after resume.
+ *
+ * A run's own `AbortSignal` still unwinds a parked loop immediately: the park
+ * releases on abort (without releasing the gate), so cancelling one run never
+ * requires resuming the whole process.
+ *
+ * Hosts drive the singleton {@link agentPauseGate} (e.g. the TUI `/pause`
+ * command); library code only ever reads it.
+ */
+
+/** Listener invoked with the new state on every pause/resume transition. */
+export type AgentPauseListener = (paused: boolean) => void;
+
+/** Freeze switch shared by every agent loop in the process. See module docs. */
+export class AgentPauseGate {
+	/** Pending while paused; resolved and cleared on resume. */
+	#gate: PromiseWithResolvers<void> | undefined;
+	#pausedAt = 0;
+	#listeners = new Set<AgentPauseListener>();
+
+	/** True while the gate is engaged. */
+	get paused(): boolean {
+		return this.#gate !== undefined;
+	}
+
+	/** Epoch ms when the current pause began; undefined when running. */
+	get pausedAt(): number | undefined {
+		return this.#gate ? this.#pausedAt : undefined;
+	}
+
+	/** Engage the gate. Returns false (and does nothing) when already paused. */
+	pause(): boolean {
+		if (this.#gate) return false;
+		this.#gate = Promise.withResolvers<void>();
+		this.#pausedAt = Date.now();
+		this.#notify(true);
+		return true;
+	}
+
+	/**
+	 * Release the gate, waking every parked loop. Returns the pause duration in
+	 * ms, or undefined when the gate was not engaged.
+	 */
+	resume(): number | undefined {
+		const gate = this.#gate;
+		if (!gate) return undefined;
+		this.#gate = undefined;
+		gate.resolve();
+		this.#notify(false);
+		return Date.now() - this.#pausedAt;
+	}
+
+	/** Subscribe to pause/resume transitions. Returns an unsubscribe function. */
+	onChange(listener: AgentPauseListener): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	/**
+	 * Park until the gate is released. Resolves immediately when not paused.
+	 * An abort on `signal` releases only this wait — the gate stays engaged —
+	 * so a cancelled run unwinds while the rest of the process stays frozen.
+	 */
+	async waitUntilResumed(signal?: AbortSignal): Promise<void> {
+		// Loop: resume() swaps the gate promise, so a pause re-engaged while a
+		// waiter is between awaits must re-park instead of slipping through.
+		while (this.#gate) {
+			if (signal?.aborted) return;
+			const gate = this.#gate.promise;
+			if (!signal) {
+				await gate;
+				continue;
+			}
+			const abort = Promise.withResolvers<void>();
+			const onAbort = () => abort.resolve();
+			signal.addEventListener("abort", onAbort, { once: true });
+			try {
+				await Promise.race([gate, abort.promise]);
+			} finally {
+				signal.removeEventListener("abort", onAbort);
+			}
+		}
+	}
+
+	#notify(paused: boolean): void {
+		for (const listener of this.#listeners) {
+			try {
+				listener(paused);
+			} catch {
+				// Host UI listeners must never break the gate.
+			}
+		}
+	}
+}
+
+/** The process-wide gate polled by the agent loop. */
+export const agentPauseGate = new AgentPauseGate();