@oh-my-pi/pi-agent-core 18.3.2 → 18.3.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.3.3] - 2026-09-27
+
+### Added
+
+- Added live steering support, allowing models to receive and act on user steering messages during an active stream.
+
 ## [18.3.2] - 2026-09-25
 
 ### Fixed

package/dist/types/agent-loop.d.ts

@@ -5,7 +5,7 @@
 import { type AssistantMessage, type Context, EventStream, type ToolResultMessage } from "@oh-my-pi/pi-ai";
 import { type Dialect } from "@oh-my-pi/pi-ai/dialect";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector.js";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, SteeringQueueState, StreamFn } from "./types.js";
 /** Stop-details marker for a provider error after assistant content/tool args already streamed. */
 export declare const STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL = "stream_interrupted_after_content";
 /**
@@ -106,6 +106,13 @@ export interface NormalizeToolsOptions {
     pruneDescriptions?: boolean;
 }
 export declare function normalizeTools(tools: AgentContext["tools"], options: NormalizeToolsOptions): Context["tools"];
+/**
+ * Classify the first `count` steering messages for a tool-batch interrupt:
+ * any user-authored message wins, then agent-attributed user messages, else
+ * system steering (advisor cards, hidden directives). Shared by the agent's
+ * queue peek and the loop's live-taken steering.
+ */
+export declare function steeringQueueState(messages: readonly AgentMessage[], count?: number): SteeringQueueState;
 /** Resolve the human-readable reason an abort carried. A caller that aborts via
  *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`
  *  (e.g. the coding agent's user-interrupt label) gets that text surfaced on the

package/dist/types/agent.d.ts

@@ -411,6 +411,14 @@ export declare class Agent {
     addBeforeQueuedMessageDequeueHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
     /** Register an independently removable hook that runs immediately before each model call. */
     addBeforeModelCallHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
+    /**
+     * Take back live-steered messages ahead of an abort (Esc restores them to the editor):
+     * the aborted run then neither records nor requeues them.
+     */
+    withdrawLiveSteering(): AgentMessage[];
+    /** Steering live steering took for the streaming response; the transcript records it once
+     *  that response (or its tool batch) ends, which is when the model switches to it. */
+    peekLiveSteeredMessages(): AgentMessage[];
     setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
@@ -476,6 +484,11 @@ export declare class Agent {
      *  single source of truth. Includes exclusively claimed originals while
      *  preparation is pending, so editor restoration can cancel their delivery. */
     peekSteeringQueue(): readonly AgentMessage[];
+    /** Dequeued messages not yet in the transcript, e.g. steering a provider
+     *  took into its in-flight response via live steering. Aborting the run
+     *  requeues them, so the session's empty-submit interrupt counts them as
+     *  pending input even though {@link peekSteeringQueue} no longer does. */
+    peekUndeliveredQueuedMessages(): AgentMessage[];
     /** Non-consuming view of the pending follow-up queue. See
      *  {@link peekSteeringQueue}. */
     peekFollowUpQueue(): readonly AgentMessage[];

package/dist/types/types.d.ts

@@ -240,6 +240,13 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * {@link getSteeringMessages}.
      */
     waitForSteeringMessages?: (signal?: AbortSignal) => Promise<void>;
+    /**
+     * Called when live steering dequeues messages via {@link getSteeringMessages}
+     * for the response being streamed. The loop records them in the transcript
+     * after that response (or its tool batch); an abort before then leaves them
+     * unrecorded for the host to requeue.
+     */
+    onLiveSteeringTaken?: (messages: AgentMessage[]) => void;
     /**
      * Peeks whether IRC messages should interrupt an interruptible waiting tool.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.3.2",
+	"version": "18.3.3",
 	"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.3.2",
-		"@oh-my-pi/pi-catalog": "18.3.2",
-		"@oh-my-pi/pi-natives": "18.3.2",
-		"@oh-my-pi/pi-utils": "18.3.2",
-		"@oh-my-pi/pi-wire": "18.3.2",
-		"@oh-my-pi/snapcompact": "18.3.2",
+		"@oh-my-pi/pi-ai": "18.3.3",
+		"@oh-my-pi/pi-catalog": "18.3.3",
+		"@oh-my-pi/pi-natives": "18.3.3",
+		"@oh-my-pi/pi-utils": "18.3.3",
+		"@oh-my-pi/pi-wire": "18.3.3",
+		"@oh-my-pi/snapcompact": "18.3.3",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.3.2",
+		"@oh-my-pi/omptype": "18.3.3",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -1247,6 +1247,7 @@ async function runLoopBody(
 				config,
 				telemetry,
 				invokeAgentSpan,
+				[],
 			);
 			for (const result of executionResult.toolResults) {
 				currentContext.messages.push(result);
@@ -1619,6 +1620,7 @@ async function runLoopBody(
 						config,
 						telemetry,
 						invokeAgentSpan,
+						[...liveAccepted, ...liveDeferred],
 					);
 					toolResults.push(...executionResult.toolResults);
 
@@ -1800,6 +1802,27 @@ interface PreparedProviderCall {
 	liveSteering?: LiveSteeringChannel;
 }
 
+/**
+ * Classify the first `count` steering messages for a tool-batch interrupt:
+ * any user-authored message wins, then agent-attributed user messages, else
+ * system steering (advisor cards, hidden directives). Shared by the agent's
+ * queue peek and the loop's live-taken steering.
+ */
+export function steeringQueueState(messages: readonly AgentMessage[], count = messages.length): SteeringQueueState {
+	if (count === 0) return { queued: false };
+	let hasAgentSteering = false;
+	for (let i = 0; i < count; i++) {
+		const message = messages[i];
+		const role = "role" in message ? message.role : undefined;
+		const attribution = "attribution" in message ? message.attribution : undefined;
+		if (attribution === "user") return { queued: true, source: "user" };
+		if (role !== "user") continue;
+		if (attribution !== "agent") return { queued: true, source: "user" };
+		hasAgentSteering = true;
+	}
+	return { queued: true, source: hasAgentSteering ? "agent" : "system" };
+}
+
 /**
  * Offer queued steering to a provider that can deliver it into the response it
  * is streaming. Latency decides whether steering lands before the model commits
@@ -1818,7 +1841,11 @@ function openLiveSteering(
 	const bound = (signal: AbortSignal): AbortSignal => (loopSignal ? AbortSignal.any([signal, loopSignal]) : signal);
 	return new LiveSteeringChannel({
 		wait: signal => waitForSteeringMessages(bound(signal)),
-		take: signal => getSteeringMessages(bound(signal)),
+		take: async signal => {
+			const messages = await getSteeringMessages(bound(signal));
+			if (messages.length > 0) config.onLiveSteeringTaken?.(messages);
+			return messages;
+		},
 		toProvider: async (messages, signal) => {
 			const transformed = config.transformContext
 				? await config.transformContext(messages, bound(signal))
@@ -3002,6 +3029,9 @@ async function executeToolCalls(
 	config: AgentLoopConfig,
 	telemetry: AgentTelemetry | undefined,
 	invokeAgentSpan: Span | undefined,
+	// Steering the provider took off the queue during the response that emitted
+	// this batch; it injects at this batch's boundary like queued steering.
+	liveSteering: readonly AgentMessage[],
 ): Promise<{ toolResults: ToolResultMessage[]; additionalContext?: string }> {
 	const tools = currentContext.tools;
 	const {
@@ -3143,7 +3173,10 @@ async function executeToolCalls(
 		// injection boundary below; polling it here would strand or drop messages.
 		let steeringQueued = false;
 		let steeringSource: SteeringInterruptSource | undefined;
-		if (hasSteeringMessages) {
+		if (liveSteering.length > 0) {
+			steeringQueued = true;
+			steeringSource = steeringQueueState(liveSteering).source;
+		} else if (hasSteeringMessages) {
 			const queuedState = await hasSteeringMessages();
 			if (typeof queuedState === "boolean") {
 				steeringQueued = queuedState;
@@ -3490,6 +3523,9 @@ async function executeToolCalls(
 	const watchSteeringWhileRunning =
 		(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.
+	if (liveSteering.length > 0) await checkSteering();
 	const eventDrivenSteeringWatch =
 		watchSteeringWhileRunning && config.waitForSteeringMessages !== undefined && hasSteeringMessages !== undefined;
 	const steeringWatchAbortController = new AbortController();

package/src/agent.ts

@@ -34,6 +34,7 @@ import {
 	normalizeMessagesForProvider,
 	normalizeTools,
 	resolveOwnedDialectFromEnv,
+	steeringQueueState,
 	unpairedToolCallTail,
 } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
@@ -411,6 +412,14 @@ export class Agent {
 	#steeringQueue: AgentMessage[] = [];
 	#followUpQueue: AgentMessage[] = [];
 	#queuedMessageClaims: Partial<Record<QueuedMessageQueue, QueuedMessageClaim>> = {};
+	/**
+	 * Steering live steering took for the in-flight response (`onLiveSteeringTaken`) that the
+	 * transcript has not recorded yet, whether or not the provider accepted it. Kept apart from
+	 * {@link #queuedMessageDeliveries}: the loop drops it on abort instead of recording it, so queue
+	 * replacement must not drop it too; the run's end requeues whatever it did not record, and
+	 * {@link withdrawLiveSteering} takes it back ahead of an abort.
+	 */
+	#liveSteered: { message: AgentMessage; controller: AbortController | undefined }[] = [];
 	/** Dequeued originals remain recoverable until their transcript events arrive. */
 	#queuedMessageDeliveries = new Set<{
 		queue: QueuedMessageQueue;
@@ -992,8 +1001,14 @@ export class Agent {
 	}
 
 	#restoreUndeliveredQueuedMessages(controller: AbortController): void {
-		if (this.#queuedMessageDeliveries.size === 0) return;
+		if (this.#queuedMessageDeliveries.size === 0 && this.#liveSteered.length === 0) return;
 		const restored: Record<QueuedMessageQueue, AgentMessage[]> = { steering: [], followUp: [] };
+		// Live steering was taken before anything the run still holds undelivered.
+		this.#liveSteered = this.#liveSteered.filter(entry => {
+			if (entry.controller !== controller) return true;
+			restored.steering.push(entry.message);
+			return false;
+		});
 		for (const delivery of this.#queuedMessageDeliveries) {
 			if (delivery.controller !== controller) continue;
 			this.#queuedMessageDeliveries.delete(delivery);
@@ -1008,6 +1023,40 @@ export class Agent {
 		if (restored.followUp.length > 0) this.#followUpQueue = [...restored.followUp, ...this.#followUpQueue];
 	}
 
+	/** Move steering live steering took out of the queue-delivery records into {@link #liveSteered}. */
+	#adoptLiveSteering(taken: readonly AgentMessage[]): void {
+		for (const delivery of this.#queuedMessageDeliveries) {
+			const pending = delivery.messages.slice(delivery.next);
+			const kept = pending.filter(message => !taken.includes(message));
+			if (kept.length === pending.length) continue;
+			for (const message of pending) {
+				if (taken.includes(message)) this.#liveSteered.push({ message, controller: delivery.controller });
+			}
+			if (kept.length === 0) {
+				this.#queuedMessageDeliveries.delete(delivery);
+			} else {
+				delivery.messages = kept;
+				delivery.next = 0;
+			}
+		}
+	}
+
+	/**
+	 * Take back live-steered messages ahead of an abort (Esc restores them to the editor):
+	 * the aborted run then neither records nor requeues them.
+	 */
+	withdrawLiveSteering(): AgentMessage[] {
+		const messages = this.peekLiveSteeredMessages();
+		this.#liveSteered = [];
+		return messages;
+	}
+
+	/** Steering live steering took for the streaming response; the transcript records it once
+	 *  that response (or its tool batch) ends, which is when the model switches to it. */
+	peekLiveSteeredMessages(): AgentMessage[] {
+		return this.#liveSteered.map(entry => entry.message);
+	}
+
 	setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void {
 		this.#onResponse = fn;
 	}
@@ -1147,6 +1196,11 @@ export class Agent {
 
 	appendMessage(m: AgentMessage) {
 		this.#state.messages.push(m);
+		const live = this.#liveSteered.findIndex(entry => entry.message === m);
+		if (live >= 0) {
+			this.#liveSteered.splice(live, 1);
+			return;
+		}
 		for (const delivery of this.#queuedMessageDeliveries) {
 			if (delivery.messages[delivery.next] !== m) continue;
 			if (++delivery.next === delivery.messages.length) this.#queuedMessageDeliveries.delete(delivery);
@@ -1202,6 +1256,7 @@ export class Agent {
 	clearAllQueues() {
 		this.#steeringQueue = [];
 		this.#followUpQueue = [];
+		this.#liveSteered = [];
 		this.#cancelQueuedMessagePreparation("steering");
 		this.#cancelQueuedMessagePreparation("followUp");
 		this.#notifySteeringWaiters();
@@ -1227,6 +1282,18 @@ export class Agent {
 		return claim ? [...claim.messages, ...this.#steeringQueue] : this.#steeringQueue;
 	}
 
+	/** Dequeued messages not yet in the transcript, e.g. steering a provider
+	 *  took into its in-flight response via live steering. Aborting the run
+	 *  requeues them, so the session's empty-submit interrupt counts them as
+	 *  pending input even though {@link peekSteeringQueue} no longer does. */
+	peekUndeliveredQueuedMessages(): AgentMessage[] {
+		const messages = this.peekLiveSteeredMessages();
+		for (const delivery of this.#queuedMessageDeliveries) {
+			for (let i = delivery.next; i < delivery.messages.length; i++) messages.push(delivery.messages[i]);
+		}
+		return messages;
+	}
+
 	/** Non-consuming view of the pending follow-up queue. See
 	 *  {@link peekSteeringQueue}. */
 	peekFollowUpQueue(): readonly AgentMessage[] {
@@ -1702,28 +1769,15 @@ export class Agent {
 				}
 				return this.#dequeueSteeringMessagesAfterHooks(signal ?? loopSignal);
 			},
-			hasSteeringMessages: () => {
-				if (this.#steeringQueue.length === 0) {
-					return { queued: false };
-				}
-				const messageCount = this.#steeringMode === "one-at-a-time" ? 1 : this.#steeringQueue.length;
-				let hasAgentSteering = false;
-				for (let i = 0; i < messageCount; i++) {
-					const message = this.#steeringQueue[i];
-					const role = "role" in message ? message.role : undefined;
-					const attribution = "attribution" in message ? message.attribution : undefined;
-					if (attribution === "user") {
-						return { queued: true, source: "user" };
-					}
-					if (role !== "user") continue;
-					if (attribution !== "agent") {
-						return { queued: true, source: "user" };
-					}
-					hasAgentSteering = true;
-				}
-				return { queued: true, source: hasAgentSteering ? "agent" : "system" };
-			},
+			hasSteeringMessages: () =>
+				steeringQueueState(
+					this.#steeringQueue,
+					this.#steeringMode === "one-at-a-time"
+						? Math.min(1, this.#steeringQueue.length)
+						: this.#steeringQueue.length,
+				),
 			waitForSteeringMessages: signal => this.#waitForSteeringMessages(signal),
+			onLiveSteeringTaken: messages => this.#adoptLiveSteering(messages),
 			hasIrcInterrupts: this.hasIrcInterrupts,
 			hasBackgroundCompletions: this.hasBackgroundCompletions,
 			getFollowUpMessages: signal => this.#dequeueFollowUpMessagesAfterHooks(signal ?? loopSignal),

package/src/types.ts

@@ -298,6 +298,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	waitForSteeringMessages?: (signal?: AbortSignal) => Promise<void>;
 
+	/**
+	 * Called when live steering dequeues messages via {@link getSteeringMessages}
+	 * for the response being streamed. The loop records them in the transcript
+	 * after that response (or its tool batch); an abort before then leaves them
+	 * unrecorded for the host to requeue.
+	 */
+	onLiveSteeringTaken?: (messages: AgentMessage[]) => void;
+
 	/**
 	 * Peeks whether IRC messages should interrupt an interruptible waiting tool.
 	 *