@oh-my-pi/pi-agent-core 18.13.0 → 18.13.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [18.13.2] - 2026-10-27
+
+### Added
+
+- `AgentTool` gained the optional `handlesToolInterrupt` flag: an interruptible tool that sets it (such as `wait`) still runs, without blocking, when a loop-owned interrupt is already queued, so it can drain the queued wake event instead of being skipped; user cancellation still skips it ([#17174](https://github.com/can1357/oh-my-pi/pull/17174) by [@alphastorm](https://github.com/alphastorm))
+
+## [18.13.1] - 2026-10-27
+
+### Added
+
+- Hosts can distinguish safely paused agents from turns still draining with `Agent.isPaused` ([#17073](https://github.com/can1357/oh-my-pi/pull/17073) by [@anatoli-tsinovoy](https://github.com/anatoli-tsinovoy)).
+
 ## [18.13.0] - 2026-10-26
 
 ### Added

package/dist/types/agent.d.ts

@@ -240,6 +240,8 @@ export interface AgentPromptOptions {
 }
 export declare class Agent {
     #private;
+    /** True while this unfinished turn is safely parked by the process pause gate. */
+    get isPaused(): boolean;
     streamFn: StreamFn;
     getApiKey?: (model: Model) => Promise<ApiKey | undefined> | ApiKey | undefined;
     /** Prepare actual queue deliveries after dequeue gates; commit runs only while ownership remains valid. */

package/dist/types/speculative-execution.d.ts

@@ -23,6 +23,9 @@ export declare class SpeculativeOperationCoordinator {
     #private;
     readonly config: SpeculativeToolExecutionConfig;
     readonly environment?: CoordinatorEnvironment | undefined;
+    /** Observer of existing speculative execution draining; no separate work ledger. */
+    onIdle?: () => void;
+    get isRunning(): boolean;
     constructor(config: SpeculativeToolExecutionConfig, environment?: CoordinatorEnvironment | undefined);
     get maxInFlight(): number;
     get size(): number;

package/dist/types/types.d.ts

@@ -126,6 +126,8 @@ export interface SteeringQueueState {
  */
 export interface AgentLoopConfig extends SimpleStreamOptions {
     model: Model;
+    /** Reports whether this loop has reached a safe process-pause boundary. */
+    onPauseChange?: (paused: boolean) => void;
     /**
      * When to interrupt tool execution for steering messages.
      * - "immediate" = cut interruptible waits short and raise the cooperative
@@ -221,7 +223,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      *
      * Polled while a tool batch runs (in "wait" mode, only when the batch holds an
      * interruptible tool) to decide whether to abort in-flight and skip
-     * not-yet-started *interruptible* waits;
+     * not-yet-started *interruptible* waits, unless they handle queued interrupts;
      * every other already-emitted call still executes and the message injects
      * at the batch boundary. The queue keeps
      * owning its messages until the loop reaches the next injection boundary and
@@ -1054,6 +1056,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * batch boundary. Honored in both `interruptMode`s.
      */
     interruptible?: boolean | ((args: Partial<Static<TParameters>>) => boolean);
+    /**
+     * An interruptible tool can execute with an already-aborted
+     * `TOOL_INTERRUPT_ABORT_REASON` signal to drain caller-owned wake events.
+     * It must not block when that signal is aborted. External/user cancellation
+     * still prevents execution. Omitted tools keep the usual pre-start skip.
+     */
+    handlesToolInterrupt?: boolean;
     /**
      * Controls how the INTENT_FIELD (`i`) is handled for this tool.
      * - `"require"` (default): `i` is injected and required in the parameter schema.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.13.0",
+	"version": "18.13.2",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -38,16 +38,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.13.0",
-		"@oh-my-pi/pi-catalog": "18.13.0",
-		"@oh-my-pi/pi-natives": "18.13.0",
-		"@oh-my-pi/pi-utils": "18.13.0",
-		"@oh-my-pi/pi-wire": "18.13.0",
-		"@oh-my-pi/snapcompact": "18.13.0",
+		"@oh-my-pi/pi-ai": "18.13.2",
+		"@oh-my-pi/pi-catalog": "18.13.2",
+		"@oh-my-pi/pi-natives": "18.13.2",
+		"@oh-my-pi/pi-utils": "18.13.2",
+		"@oh-my-pi/pi-wire": "18.13.2",
+		"@oh-my-pi/snapcompact": "18.13.2",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.13.0",
+		"@oh-my-pi/omptype": "18.13.2",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -110,6 +110,17 @@ import {
 	SPECULATIVE_STREAM_SESSION,
 } from "./types";
 import { yieldIfDue } from "./utils/yield";
+
+async function waitForProcessPause(config: AgentLoopConfig, signal?: AbortSignal): Promise<void> {
+	try {
+		while (agentPauseGate.paused && !signal?.aborted) {
+			config.onPauseChange?.(true);
+			await agentPauseGate.waitUntilResumed(signal);
+		}
+	} finally {
+		config.onPauseChange?.(false);
+	}
+}
 /** Stop-details marker for a provider error after assistant content/tool args already streamed. */
 export const STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL = "stream_interrupted_after_content";
 
@@ -1331,7 +1342,7 @@ async function runLoopBody(
 				// 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 (agentPauseGate.paused) await waitForProcessPause(config, signal);
 
 				// Build the provider-bound context before opening the turn. Queue
 				// messages are added now but their events remain deferred until
@@ -1443,6 +1454,7 @@ async function runLoopBody(
 				let recovered: HarmonyRecoveredToolCall | undefined;
 				let message: AssistantMessage;
 				try {
+					if (agentPauseGate.paused) await waitForProcessPause(config, signal);
 					message = await streamAssistantResponse(
 						currentContext,
 						config,
@@ -3349,6 +3361,7 @@ async function executeToolCalls(
 			tool,
 			args,
 			interruptible,
+			handlesToolInterrupt: interruptible && tool?.handlesToolInterrupt === true,
 			signal: interruptible ? interruptibleSignal : nonInterruptibleSignal,
 			started: false,
 			result: undefined as AgentToolResult<any> | undefined,
@@ -3367,6 +3380,22 @@ async function executeToolCalls(
 		};
 	});
 
+	// Derive batch readiness from existing dispatch records, not extra participants.
+	const refreshPauseState = (): void => {
+		config.onPauseChange?.(
+			agentPauseGate.paused &&
+				!signal?.aborted &&
+				!speculationCoordinator?.isRunning &&
+				records.some(record => !record.started && !record.skipped && !record.toolResultMessage) &&
+				!records.some(record => record.started && !record.toolResultMessage),
+		);
+	};
+	if (speculationCoordinator) speculationCoordinator.onIdle = refreshPauseState;
+
+	const isToolAborted = (record: (typeof records)[number]): boolean =>
+		signal?.aborted === true ||
+		(record.signal.aborted && !(record.handlesToolInterrupt && record.signal.reason === TOOL_INTERRUPT_ABORT_REASON));
+
 	const checkAsideInterrupts = async (): Promise<void> => {
 		// Asides only fire once: an interrupt already recorded on interruptState
 		// must not re-abort, and (unlike steering) never re-consumes a queue.
@@ -3429,9 +3458,9 @@ async function executeToolCalls(
 			// interruptMode is "wait") raises the cooperative soft signal for
 			// everything else: the boundary dequeue
 			// below injects the message as soon as running tools finish (or
-			// background themselves), and not-yet-started interruptible waits
-			// are skipped. Idempotent — a second steer poll after the abort is
-			// a no-op.
+			// background themselves). Not-yet-started interruptible tools are
+			// skipped unless they can drain the queued wake. Idempotent — a
+			// second steer poll after the abort is a no-op.
 			if (!steeringAbortController.signal.aborted) {
 				interruptState.triggered = true;
 				interruptState.source = steeringSource ?? "unknown";
@@ -3494,8 +3523,8 @@ async function executeToolCalls(
 	};
 
 	const runTool = async (record: (typeof records)[number], index: number): Promise<void> => {
-		// A pending interrupt preempts not-yet-started *interruptible* waits so
-		// the message injects promptly instead of sitting out a `wait`.
+		// A pending interrupt preempts not-yet-started interruptible tools,
+		// except receivers that drain the wake with an already-aborted signal.
 		// Non-interruptible work is never skipped, whatever the source: the
 		// expensive part — generating the call — is already paid, the tool
 		// itself is cheap, and a skip only makes the model re-emit the same
@@ -3505,7 +3534,7 @@ async function executeToolCalls(
 		// the parent steers mid-stream (#10645). The steer still injects at the
 		// batch boundary; the cooperative soft signal lets long-running tools
 		// step aside on their own.
-		if (interruptState.triggered && record.interruptible) {
+		if (interruptState.triggered && record.interruptible && !record.handlesToolInterrupt) {
 			// Skip both span emission and the collector orphan record here. The
 			// tail sweep below (after `Promise.allSettled`) is the single path
 			// that handles "no result message was produced" — it calls
@@ -3517,7 +3546,11 @@ async function executeToolCalls(
 		// 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);
+		while (agentPauseGate.paused && !record.signal.aborted) {
+			refreshPauseState();
+			await agentPauseGate.waitUntilResumed(record.signal);
+		}
+		config.onPauseChange?.(false);
 
 		const { toolCall, tool } = record;
 		// Validation (and the beforeToolCall hook) ran in the prepare phase; a
@@ -3535,14 +3568,14 @@ async function executeToolCalls(
 			return;
 		}
 		const effectiveArgs = record.args;
-		if (record.signal.aborted) {
+		if (isToolAborted(record)) {
 			record.skipped = true;
 			recordSkippedTool(telemetry, {
 				toolCallId: toolCall.id,
 				toolName: toolCall.name,
 				status: "aborted",
 			});
-			emitToolResult(record, createToolSignalAbortedResult(record.signal), true);
+			emitToolResult(record, createToolSignalAbortedResult(signal?.aborted ? signal : record.signal), true);
 			return;
 		}
 		record.started = true;
@@ -3570,17 +3603,19 @@ async function executeToolCalls(
 		let caughtError: unknown;
 		let completedToolExecution = false;
 		let executionStarted = false;
+		const abortBeforeToolExecution = (): boolean => {
+			if (!isToolAborted(record)) return false;
+			result = createToolSignalAbortedResult(signal?.aborted ? signal : record.signal);
+			isError = true;
+			return true;
+		};
 
 		await runInActiveSpan(toolSpan, async () => {
 			try {
 				if (!tool) {
 					throw new Error(formatToolNotFoundMessage(toolCall.name, tools, suggestFallbackToolNames?.()));
 				}
-				if (record.signal.aborted) {
-					result = createToolSignalAbortedResult(record.signal);
-					isError = true;
-					return;
-				}
+				if (abortBeforeToolExecution()) return;
 
 				if (record.prepareError !== undefined) throw record.prepareError;
 				if (record.blocked) {
@@ -3591,6 +3626,9 @@ async function executeToolCalls(
 					record.executionArgs ??
 					(transformToolCallArguments ? transformToolCallArguments(effectiveArgs, toolCall.name) : effectiveArgs);
 				record.args = executionArgs;
+				// A transform or awaited claim can cancel the external run after
+				// a queued wake already fixed the combined signal's reason.
+				if (abortBeforeToolExecution()) return;
 
 				const speculativeOutcome = speculationCoordinator
 					? await speculationCoordinator.claim(tool, toolCall, executionArgs)
@@ -3607,6 +3645,7 @@ async function executeToolCalls(
 				}
 
 				if (!completedToolExecution) {
+					if (abortBeforeToolExecution()) return;
 					// The cooperative steering signal and the passive-context sink
 					// ride the loop-owned ToolCallContext (surfacing as
 					// `ctx.toolCall.*`); the host surfaces the sink on the context it
@@ -3631,9 +3670,12 @@ async function executeToolCalls(
 					} else if (streamSession && !streamSession.contextIndependent) {
 						await streamSession.discard("outer tool context cannot carry stream speculation");
 					}
-					executionStarted = true;
 					let rawResult: unknown;
 					try {
+						// Context construction and stream cleanup can also cancel;
+						// nothing may await or call host code after this final check.
+						if (abortBeforeToolExecution()) return;
+						executionStarted = true;
 						rawResult = await tool.execute(
 							toolCall.id,
 							executionArgs,
@@ -3713,10 +3755,10 @@ async function executeToolCalls(
 		const interrupted = interruptState.triggered;
 		const perToolAborted = record.signal.aborted;
 		const abortedDuringExecution = perToolAborted && isError && !completedToolExecution;
-		if (record.interruptible && interrupted && abortedDuringExecution) {
+		if (record.interruptible && interrupted && abortedDuringExecution && !signal?.aborted) {
 			// Queued steering/asides abort only interruptible tools. An external
-			// user abort can also fail a non-interruptible tool (e.g. cancelled
-			// ask); keep its actual error instead of attributing it to the queue.
+			// user abort takes priority even if a queued interrupt fixed the
+			// combined signal's reason first; keep the actual cancellation error.
 			record.skipped = true;
 			emitToolResult(record, createSkippedToolResult(interruptState.source, executionStarted), true);
 		} else {
@@ -3773,7 +3815,7 @@ async function executeToolCalls(
 		(softInterrupts || records.some(record => record.interruptible)) &&
 		(hasSteeringMessages !== undefined || hasAsidePeek);
 	// Live-taken steering is already pending: interrupt before any call starts
-	// so not-yet-started interruptible waits are skipped outright.
+	// so interruptible tools skip or drain the queued wake without blocking.
 	if (liveSteering.length > 0) await checkSteering();
 	const eventDrivenSteeringWatch =
 		watchSteeringWhileRunning && config.waitForSteeringMessages !== undefined && hasSteeringMessages !== undefined;
@@ -3851,7 +3893,13 @@ async function executeToolCalls(
 			concurrency = concurrencyMode ?? "shared";
 		}
 		const start = concurrency === "exclusive" ? Promise.all([lastExclusive, ...sharedTasks]) : lastExclusive;
-		const task = start.then(() => runTool(record, index));
+		const task = start.then(async () => {
+			try {
+				await runTool(record, index);
+			} finally {
+				refreshPauseState();
+			}
+		});
 		tasks.push(task);
 		if (concurrency === "exclusive") {
 			lastExclusive = task;
@@ -3863,6 +3911,8 @@ async function executeToolCalls(
 	try {
 		await Promise.allSettled(tasks);
 	} finally {
+		if (speculationCoordinator) speculationCoordinator.onIdle = undefined;
+		config.onPauseChange?.(false);
 		steeringWatchAbortController.abort();
 		await steeringWatchPromise?.catch(() => undefined);
 		clearInterval(steeringWatchTimer);

package/src/agent.ts

@@ -39,6 +39,7 @@ import {
 	unpairedToolCallTail,
 } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
+import { agentPauseGate } from "./pause";
 import { isProviderRefusalMessage } from "./replay-policy";
 import { SentToolDefinitions } from "./sent-tool-definitions";
 import { Tokenizer } from "./tokenizer";
@@ -474,6 +475,12 @@ export class Agent {
 	#cwdResolver?: () => string | undefined;
 
 	#runningPrompt?: Promise<void>;
+	#isPaused = false;
+
+	/** True while this unfinished turn is safely parked by the process pause gate. */
+	get isPaused(): boolean {
+		return this.#isPaused && agentPauseGate.paused && !this.#abortController?.signal.aborted;
+	}
 	#resolveRunningPrompt?: () => void;
 	#kimiApiFormat?: "openai" | "anthropic";
 	#preferWebsockets?: boolean;
@@ -1783,6 +1790,7 @@ export class Agent {
 		this.#state.isStreaming = true;
 		this.#state.streamMessage = null;
 		this.#state.error = undefined;
+		this.#isPaused = false;
 
 		// Clear Cursor tool result buffer at start of each run
 		this.#cursorToolResultBuffer = [];
@@ -1955,6 +1963,9 @@ export class Agent {
 			onAssistantMessageEvent: this.#onAssistantMessageEvent,
 			onHarmonyLeak: this.#onHarmonyLeak,
 			onTurnEnd: (messages, signal, context) => this.#onTurnEnd?.(messages, signal, context),
+			onPauseChange: paused => {
+				this.#isPaused = paused;
+			},
 			getToolChoice,
 			softToolRequirementState: this.#softToolRequirementState,
 			onToolChoiceRejected: () => {
@@ -2205,6 +2216,7 @@ export class Agent {
 				this.#emit({ type: "agent_end", messages: [errorMsg] });
 			}
 		} finally {
+			this.#isPaused = false;
 			this.#restoreUndeliveredQueuedMessages(loopAbortController);
 			resolveRun?.();
 			if (this.#abortController === loopAbortController) {

package/src/speculative-execution.ts

@@ -239,6 +239,12 @@ export class SpeculativeOperationCoordinator {
 	#closed = false;
 	#admissionsFinalized = false;
 	#running = 0;
+	/** Observer of existing speculative execution draining; no separate work ledger. */
+	onIdle?: () => void;
+
+	get isRunning(): boolean {
+		return this.#running > 0;
+	}
 
 	constructor(
 		readonly config: SpeculativeToolExecutionConfig,
@@ -955,6 +961,7 @@ export class SpeculativeOperationCoordinator {
 			} finally {
 				this.#running--;
 				this.#drain();
+				if (this.#running === 0) this.onIdle?.();
 			}
 		})();
 	}

package/src/types.ts

@@ -175,6 +175,9 @@ export interface SteeringQueueState {
 export interface AgentLoopConfig extends SimpleStreamOptions {
 	model: Model;
 
+	/** Reports whether this loop has reached a safe process-pause boundary. */
+	onPauseChange?: (paused: boolean) => void;
+
 	/**
 	 * When to interrupt tool execution for steering messages.
 	 * - "immediate" = cut interruptible waits short and raise the cooperative
@@ -280,7 +283,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 *
 	 * Polled while a tool batch runs (in "wait" mode, only when the batch holds an
 	 * interruptible tool) to decide whether to abort in-flight and skip
-	 * not-yet-started *interruptible* waits;
+	 * not-yet-started *interruptible* waits, unless they handle queued interrupts;
 	 * every other already-emitted call still executes and the message injects
 	 * at the batch boundary. The queue keeps
 	 * owning its messages until the loop reaches the next injection boundary and
@@ -1191,6 +1194,13 @@ export interface AgentTool<
 	 * batch boundary. Honored in both `interruptMode`s.
 	 */
 	interruptible?: boolean | ((args: Partial<Static<TParameters>>) => boolean);
+	/**
+	 * An interruptible tool can execute with an already-aborted
+	 * `TOOL_INTERRUPT_ABORT_REASON` signal to drain caller-owned wake events.
+	 * It must not block when that signal is aborted. External/user cancellation
+	 * still prevents execution. Omitted tools keep the usual pre-start skip.
+	 */
+	handlesToolInterrupt?: boolean;
 	/**
 	 * Controls how the INTENT_FIELD (`i`) is handled for this tool.
 	 * - `"require"` (default): `i` is injected and required in the parameter schema.