@oh-my-pi/pi-agent-core 3.15.0 → 3.20.0

package/README.md

@@ -224,26 +224,31 @@ const unsubscribe = agent.subscribe((event) => {
 unsubscribe();
 ```
 
-## Message Queue
+## Steering & Follow-up
 
-Queue messages to inject during tool execution (for user interruptions):
+Queue messages to inject during tool execution (steering) or after the agent would otherwise stop (follow-up):
 
 ```typescript
-agent.setQueueMode("one-at-a-time");
+agent.setSteeringMode("one-at-a-time");
+agent.setInterruptMode("immediate");
 
 // While agent is running tools
-agent.queueMessage({
+agent.steer({
 	role: "user",
 	content: "Stop! Do this instead.",
 	timestamp: Date.now(),
 });
-```
 
-When queued messages are detected after a tool completes:
+// Queue a follow-up to run after the current turn completes
+agent.followUp({
+	role: "user",
+	content: "After that, summarize the changes.",
+	timestamp: Date.now(),
+});
+```
 
-1. Remaining tools are skipped with error results
-2. Queued message is injected
-3. LLM responds to the interruption
+Steering messages are checked after each tool call by default. Set `interruptMode` to `"wait"` to defer
+steering until the current turn completes.
 
 ## Custom Message Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "3.15.0",
+	"version": "3.20.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -13,8 +13,8 @@
 		"test": "vitest --run"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "3.15.0",
-		"@oh-my-pi/pi-tui": "3.15.0"
+		"@oh-my-pi/pi-ai": "3.20.0",
+		"@oh-my-pi/pi-tui": "3.20.0"
 	},
 	"keywords": [
 		"ai",

package/src/agent-loop.ts

@@ -109,73 +109,90 @@ async function runLoop(
 	stream: EventStream<AgentEvent, AgentMessage[]>,
 	streamFn?: StreamFn,
 ): Promise<void> {
-	let hasMoreToolCalls = true;
 	let firstTurn = true;
-	let queuedMessages: AgentMessage[] = (await config.getQueuedMessages?.()) || [];
-	let queuedAfterTools: AgentMessage[] | null = null;
-
-	while (hasMoreToolCalls || queuedMessages.length > 0) {
-		if (!firstTurn) {
-			stream.push({ type: "turn_start" });
-		} else {
-			firstTurn = false;
-		}
+	// Check for steering messages at start (user may have typed while waiting)
+	let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
+
+	// Outer loop: continues when queued follow-up messages arrive after agent would stop
+	while (true) {
+		let hasMoreToolCalls = true;
+		let steeringAfterTools: AgentMessage[] | null = null;
+
+		// Inner loop: process tool calls and steering messages
+		while (hasMoreToolCalls || pendingMessages.length > 0) {
+			if (!firstTurn) {
+				stream.push({ type: "turn_start" });
+			} else {
+				firstTurn = false;
+			}
 
-		// Process queued messages (inject before next assistant response)
-		if (queuedMessages.length > 0) {
-			for (const message of queuedMessages) {
-				stream.push({ type: "message_start", message });
-				stream.push({ type: "message_end", message });
-				currentContext.messages.push(message);
-				newMessages.push(message);
+			// Process pending messages (inject before next assistant response)
+			if (pendingMessages.length > 0) {
+				for (const message of pendingMessages) {
+					stream.push({ type: "message_start", message });
+					stream.push({ type: "message_end", message });
+					currentContext.messages.push(message);
+					newMessages.push(message);
+				}
+				pendingMessages = [];
 			}
-			queuedMessages = [];
-		}
 
-		// Stream assistant response
-		const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);
-		newMessages.push(message);
+			// Stream assistant response
+			const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);
+			newMessages.push(message);
 
-		if (message.stopReason === "error" || message.stopReason === "aborted") {
-			stream.push({ type: "turn_end", message, toolResults: [] });
-			stream.push({ type: "agent_end", messages: newMessages });
-			stream.end(newMessages);
-			return;
-		}
+			if (message.stopReason === "error" || message.stopReason === "aborted") {
+				stream.push({ type: "turn_end", message, toolResults: [] });
+				stream.push({ type: "agent_end", messages: newMessages });
+				stream.end(newMessages);
+				return;
+			}
 
-		// Check for tool calls
-		const toolCalls = message.content.filter((c) => c.type === "toolCall");
-		hasMoreToolCalls = toolCalls.length > 0;
+			// Check for tool calls
+			const toolCalls = message.content.filter((c) => c.type === "toolCall");
+			hasMoreToolCalls = toolCalls.length > 0;
+
+			const toolResults: ToolResultMessage[] = [];
+			if (hasMoreToolCalls) {
+				const toolExecution = await executeToolCalls(
+					currentContext.tools,
+					message,
+					signal,
+					stream,
+					config.getSteeringMessages,
+					config.getToolContext,
+					config.interruptMode,
+				);
+				toolResults.push(...toolExecution.toolResults);
+				steeringAfterTools = toolExecution.steeringMessages ?? null;
+
+				for (const result of toolResults) {
+					currentContext.messages.push(result);
+					newMessages.push(result);
+				}
+			}
 
-		const toolResults: ToolResultMessage[] = [];
-		if (hasMoreToolCalls) {
-			const toolExecution = await executeToolCalls(
-				currentContext.tools,
-				message,
-				signal,
-				stream,
-				config.getQueuedMessages,
-				config.getToolContext,
-				config.interruptMode,
-			);
-			toolResults.push(...toolExecution.toolResults);
-			queuedAfterTools = toolExecution.queuedMessages ?? null;
+			stream.push({ type: "turn_end", message, toolResults });
 
-			for (const result of toolResults) {
-				currentContext.messages.push(result);
-				newMessages.push(result);
+			// Get steering messages after turn completes
+			if (steeringAfterTools && steeringAfterTools.length > 0) {
+				pendingMessages = steeringAfterTools;
+				steeringAfterTools = null;
+			} else {
+				pendingMessages = (await config.getSteeringMessages?.()) || [];
 			}
 		}
 
-		stream.push({ type: "turn_end", message, toolResults });
-
-		// Get queued messages after turn completes
-		if (queuedAfterTools && queuedAfterTools.length > 0) {
-			queuedMessages = queuedAfterTools;
-			queuedAfterTools = null;
-		} else {
-			queuedMessages = (await config.getQueuedMessages?.()) || [];
+		// Agent would stop here. Check for follow-up messages.
+		const followUpMessages = (await config.getFollowUpMessages?.()) || [];
+		if (followUpMessages.length > 0) {
+			// Set as pending so inner loop processes them
+			pendingMessages = followUpMessages;
+			continue;
 		}
+
+		// No more messages, exit
+		break;
 	}
 
 	stream.push({ type: "agent_end", messages: newMessages });
@@ -225,9 +242,35 @@ async function streamAssistantResponse(
 	let addedPartial = false;
 
 	for await (const event of response) {
-		// Check abort early - allows TTSR and other abort sources to break immediately
+		// Check for abort signal before processing each event
 		if (signal?.aborted) {
-			break;
+			const abortedMessage: AssistantMessage = partialMessage
+				? { ...partialMessage, stopReason: "aborted" }
+				: {
+						role: "assistant",
+						content: [],
+						api: config.model.api,
+						provider: config.model.provider,
+						model: config.model.id,
+						usage: {
+							input: 0,
+							output: 0,
+							cacheRead: 0,
+							cacheWrite: 0,
+							totalTokens: 0,
+							cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+						},
+						stopReason: "aborted",
+						timestamp: Date.now(),
+					};
+			if (addedPartial) {
+				context.messages[context.messages.length - 1] = abortedMessage;
+			} else {
+				context.messages.push(abortedMessage);
+				stream.push({ type: "message_start", message: { ...abortedMessage } });
+			}
+			stream.push({ type: "message_end", message: abortedMessage });
+			return abortedMessage;
 		}
 
 		switch (event.type) {
@@ -273,22 +316,6 @@ async function streamAssistantResponse(
 				return finalMessage;
 			}
 		}
-
-		// Check abort after processing - allows handlers to abort mid-stream
-		if (signal?.aborted) {
-			break;
-		}
-	}
-
-	// If we broke out due to abort, return an aborted message
-	if (signal?.aborted && partialMessage) {
-		const abortedMessage: AssistantMessage = {
-			...partialMessage,
-			stopReason: "aborted",
-		};
-		context.messages[context.messages.length - 1] = abortedMessage;
-		stream.push({ type: "message_end", message: abortedMessage });
-		return abortedMessage;
 	}
 
 	return await response.result();
@@ -302,13 +329,14 @@ async function executeToolCalls(
 	assistantMessage: AssistantMessage,
 	signal: AbortSignal | undefined,
 	stream: EventStream<AgentEvent, AgentMessage[]>,
-	getQueuedMessages?: AgentLoopConfig["getQueuedMessages"],
+	getSteeringMessages?: AgentLoopConfig["getSteeringMessages"],
 	getToolContext?: AgentLoopConfig["getToolContext"],
-	interruptMode?: AgentLoopConfig["interruptMode"],
-): Promise<{ toolResults: ToolResultMessage[]; queuedMessages?: AgentMessage[] }> {
+	interruptMode: AgentLoopConfig["interruptMode"] = "immediate",
+): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> {
 	const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
 	const results: ToolResultMessage[] = [];
-	let queuedMessages: AgentMessage[] | undefined;
+	let steeringMessages: AgentMessage[] | undefined;
+	const shouldInterruptImmediately = interruptMode !== "wait";
 
 	for (let index = 0; index < toolCalls.length; index++) {
 		const toolCall = toolCalls[index];
@@ -322,17 +350,14 @@ async function executeToolCalls(
 		});
 
 		let result: AgentToolResult<any>;
+		let isError = false;
 
-		const details: { toolCallId: string; toolName: string; isError?: boolean } = {
-			toolCallId: toolCall.id,
-			toolName: toolCall.name,
-		};
 		try {
 			if (!tool) throw new Error(`Tool ${toolCall.name} not found`);
 
 			const validatedArgs = validateToolArguments(tool, toolCall);
-			const toolContext = getToolContext?.();
 
+			const toolContext = getToolContext ? getToolContext() : undefined;
 			result = await tool.execute(
 				toolCall.id,
 				validatedArgs,
@@ -353,33 +378,36 @@ async function executeToolCalls(
 				content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
 				details: {},
 			};
-			details.isError = true;
+			isError = true;
 		}
 
 		stream.push({
 			type: "tool_execution_end",
+			toolCallId: toolCall.id,
+			toolName: toolCall.name,
 			result,
-			...details,
+			isError,
 		});
 
 		const toolResultMessage: ToolResultMessage = {
 			role: "toolResult",
+			toolCallId: toolCall.id,
+			toolName: toolCall.name,
 			content: result.content,
 			details: result.details,
+			isError,
 			timestamp: Date.now(),
-			...details,
 		};
 
 		results.push(toolResultMessage);
 		stream.push({ type: "message_start", message: toolResultMessage });
 		stream.push({ type: "message_end", message: toolResultMessage });
 
-		// Check for queued messages - skip remaining tools if user interrupted
-		// Only interrupt mid-execution if interruptMode is "immediate" (default)
-		if (interruptMode !== "wait" && getQueuedMessages) {
-			const queued = await getQueuedMessages();
-			if (queued.length > 0) {
-				queuedMessages = queued;
+		// Check for steering messages - skip remaining tools if user interrupted
+		if (shouldInterruptImmediately && getSteeringMessages) {
+			const steering = await getSteeringMessages();
+			if (steering.length > 0) {
+				steeringMessages = steering;
 				const remainingCalls = toolCalls.slice(index + 1);
 				for (const skipped of remainingCalls) {
 					results.push(skipToolCall(skipped, stream));
@@ -389,7 +417,7 @@ async function executeToolCalls(
 		}
 	}
 
-	return { toolResults: results, queuedMessages };
+	return { toolResults: results, steeringMessages };
 }
 
 function skipToolCall(

package/src/agent.ts

@@ -48,13 +48,19 @@ export interface AgentOptions {
 	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
 
 	/**
-	 * Queue mode: "all" = send all queued messages at once, "one-at-a-time" = one per turn
+	 * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
 	 */
-	queueMode?: "all" | "one-at-a-time";
+	steeringMode?: "all" | "one-at-a-time";
 
 	/**
-	 * Interrupt mode: "immediate" = check queue after each tool (interrupt remaining),
-	 * "wait" = only process queue after turn completes
+	 * Follow-up mode: "all" = send all follow-up messages at once, "one-at-a-time" = one per turn
+	 */
+	followUpMode?: "all" | "one-at-a-time";
+
+	/**
+	 * When to interrupt tool execution for steering messages.
+	 * - "immediate": check after each tool call (default)
+	 * - "wait": defer steering until the current turn completes
 	 */
 	interruptMode?: "immediate" | "wait";
 
@@ -71,6 +77,7 @@ export interface AgentOptions {
 
 	/**
 	 * Provides tool execution context, resolved per tool call.
+	 * Use for late-bound UI or session state access.
 	 */
 	getToolContext?: () => AgentToolContext | undefined;
 }
@@ -92,8 +99,10 @@ export class Agent {
 	private abortController?: AbortController;
 	private convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	private transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
-	private messageQueue: AgentMessage[] = [];
-	private queueMode: "all" | "one-at-a-time";
+	private steeringQueue: AgentMessage[] = [];
+	private followUpQueue: AgentMessage[] = [];
+	private steeringMode: "all" | "one-at-a-time";
+	private followUpMode: "all" | "one-at-a-time";
 	private interruptMode: "immediate" | "wait";
 	public streamFn: StreamFn;
 	public getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
@@ -105,7 +114,8 @@ export class Agent {
 		this._state = { ...this._state, ...opts.initialState };
 		this.convertToLlm = opts.convertToLlm || defaultConvertToLlm;
 		this.transformContext = opts.transformContext;
-		this.queueMode = opts.queueMode || "one-at-a-time";
+		this.steeringMode = opts.steeringMode || "one-at-a-time";
+		this.followUpMode = opts.followUpMode || "one-at-a-time";
 		this.interruptMode = opts.interruptMode || "immediate";
 		this.streamFn = opts.streamFn || streamSimple;
 		this.getApiKey = opts.getApiKey;
@@ -134,12 +144,20 @@ export class Agent {
 		this._state.thinkingLevel = l;
 	}
 
-	setQueueMode(mode: "all" | "one-at-a-time") {
-		this.queueMode = mode;
+	setSteeringMode(mode: "all" | "one-at-a-time") {
+		this.steeringMode = mode;
+	}
+
+	getSteeringMode(): "all" | "one-at-a-time" {
+		return this.steeringMode;
 	}
 
-	getQueueMode(): "all" | "one-at-a-time" {
-		return this.queueMode;
+	setFollowUpMode(mode: "all" | "one-at-a-time") {
+		this.followUpMode = mode;
+	}
+
+	getFollowUpMode(): "all" | "one-at-a-time" {
+		return this.followUpMode;
 	}
 
 	setInterruptMode(mode: "immediate" | "wait") {
@@ -162,24 +180,49 @@ export class Agent {
 		this._state.messages = [...this._state.messages, m];
 	}
 
-	queueMessage(m: AgentMessage) {
-		this.messageQueue.push(m);
+	popMessage(): AgentMessage | undefined {
+		const messages = this._state.messages.slice(0, -1);
+		const removed = this._state.messages.at(-1);
+		this._state.messages = messages;
+
+		if (removed && this._state.streamMessage === removed) {
+			this._state.streamMessage = null;
+		}
+
+		return removed;
 	}
 
-	clearMessageQueue() {
-		this.messageQueue = [];
+	/**
+	 * Queue a steering message to interrupt the agent mid-run.
+	 * Delivered after current tool execution, skips remaining tools.
+	 */
+	steer(m: AgentMessage) {
+		this.steeringQueue.push(m);
 	}
 
-	clearMessages() {
-		this._state.messages = [];
+	/**
+	 * Queue a follow-up message to be processed after the agent finishes.
+	 * Delivered only when agent has no more tool calls or steering messages.
+	 */
+	followUp(m: AgentMessage) {
+		this.followUpQueue.push(m);
 	}
 
-	/** Remove and return the last message from the message list */
-	popMessage(): AgentMessage | undefined {
-		if (this._state.messages.length === 0) return undefined;
-		const popped = this._state.messages[this._state.messages.length - 1];
-		this._state.messages = this._state.messages.slice(0, -1);
-		return popped;
+	clearSteeringQueue() {
+		this.steeringQueue = [];
+	}
+
+	clearFollowUpQueue() {
+		this.followUpQueue = [];
+	}
+
+	clearAllQueues() {
+		this.steeringQueue = [];
+		this.followUpQueue = [];
+	}
+
+	clearMessages() {
+		this._state.messages = [];
 	}
 
 	abort() {
@@ -196,13 +239,20 @@ export class Agent {
 		this._state.streamMessage = null;
 		this._state.pendingToolCalls = new Set<string>();
 		this._state.error = undefined;
-		this.messageQueue = [];
+		this.steeringQueue = [];
+		this.followUpQueue = [];
 	}
 
 	/** Send a prompt with an AgentMessage */
 	async prompt(message: AgentMessage | AgentMessage[]): Promise<void>;
 	async prompt(input: string, images?: ImageContent[]): Promise<void>;
 	async prompt(input: string | AgentMessage | AgentMessage[], images?: ImageContent[]) {
+		if (this._state.isStreaming) {
+			throw new Error(
+				"Agent is already processing a prompt. Use steer() or followUp() to queue messages, or wait for completion.",
+			);
+		}
+
 		const model = this._state.model;
 		if (!model) throw new Error("No model configured");
 
@@ -231,6 +281,10 @@ export class Agent {
 
 	/** Continue from current context (for retry after overflow) */
 	async continue() {
+		if (this._state.isStreaming) {
+			throw new Error("Agent is already processing. Wait for completion before continuing.");
+		}
+
 		const messages = this._state.messages;
 		if (messages.length === 0) {
 			throw new Error("No messages to continue from");
@@ -276,23 +330,37 @@ export class Agent {
 		const config: AgentLoopConfig = {
 			model,
 			reasoning,
+			interruptMode: this.interruptMode,
 			convertToLlm: this.convertToLlm,
 			transformContext: this.transformContext,
 			getApiKey: this.getApiKey,
 			getToolContext: this.getToolContext,
-			interruptMode: this.interruptMode,
-			getQueuedMessages: async () => {
-				if (this.queueMode === "one-at-a-time") {
-					if (this.messageQueue.length > 0) {
-						const first = this.messageQueue[0];
-						this.messageQueue = this.messageQueue.slice(1);
+			getSteeringMessages: async () => {
+				if (this.steeringMode === "one-at-a-time") {
+					if (this.steeringQueue.length > 0) {
+						const first = this.steeringQueue[0];
+						this.steeringQueue = this.steeringQueue.slice(1);
+						return [first];
+					}
+					return [];
+				} else {
+					const steering = this.steeringQueue.slice();
+					this.steeringQueue = [];
+					return steering;
+				}
+			},
+			getFollowUpMessages: async () => {
+				if (this.followUpMode === "one-at-a-time") {
+					if (this.followUpQueue.length > 0) {
+						const first = this.followUpQueue[0];
+						this.followUpQueue = this.followUpQueue.slice(1);
 						return [first];
 					}
 					return [];
 				} else {
-					const queued = this.messageQueue.slice();
-					this.messageQueue = [];
-					return queued;
+					const followUp = this.followUpQueue.slice();
+					this.followUpQueue = [];
+					return followUp;
 				}
 			},
 		};

package/src/types.ts

@@ -22,6 +22,13 @@ export type StreamFn = (
 export interface AgentLoopConfig extends SimpleStreamOptions {
 	model: Model<any>;
 
+	/**
+	 * When to interrupt tool execution for steering messages.
+	 * - "immediate": check after each tool call (default)
+	 * - "wait": defer steering until the current turn completes
+	 */
+	interruptMode?: "immediate" | "wait";
+
 	/**
 	 * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
 	 *
@@ -32,7 +39,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * @example
 	 * ```typescript
 	 * convertToLlm: (messages) => messages.flatMap(m => {
-	 *   if (m.role === "hookMessage") {
+	 *   if (m.role === "custom") {
 	 *     // Convert custom message to user message
 	 *     return [{ role: "user", content: m.content, timestamp: m.timestamp }];
 	 *   }
@@ -75,20 +82,22 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
 
 	/**
-	 * Returns queued messages to inject into the conversation.
+	 * Returns steering messages to inject into the conversation mid-run.
 	 *
-	 * Called after each turn to check for user interruptions or injected messages.
-	 * If messages are returned, they're added to the context before the next LLM call.
+	 * Called after each tool execution to check for user interruptions unless interruptMode is "wait".
+	 * If messages are returned, remaining tool calls are skipped and
+	 * these messages are added to the context before the next LLM call.
 	 */
-	getQueuedMessages?: () => Promise<AgentMessage[]>;
+	getSteeringMessages?: () => Promise<AgentMessage[]>;
 
 	/**
-	 * Controls when queued messages interrupt tool execution.
+	 * Returns follow-up messages to process after the agent would otherwise stop.
 	 *
-	 * - "immediate" (default): Check queue after each tool, interrupt remaining tools if messages exist
-	 * - "wait": Only process queued messages after the entire turn completes
+	 * Called when the agent has no more tool calls and no steering messages.
+	 * If messages are returned, they're added to the context and the agent
+	 * continues with another turn.
 	 */
-	interruptMode?: "immediate" | "wait";
+	getFollowUpMessages?: () => Promise<AgentMessage[]>;
 
 	/**
 	 * Provides tool execution context, resolved per tool call.
@@ -159,6 +168,8 @@ export interface RenderResultOptions {
 	expanded: boolean;
 	/** Whether this is a partial/streaming result */
 	isPartial: boolean;
+	/** Current spinner frame index for animated elements (optional) */
+	spinnerFrame?: number;
 }
 
 /**