@f5-sales-demo/pi-agent-core 22.4.11 → 22.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/pi-agent-core",
-	"version": "22.4.11",
+	"version": "22.5.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -35,8 +35,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@f5-sales-demo/pi-ai": "22.4.11",
-		"@f5-sales-demo/pi-utils": "22.4.11"
+		"@f5-sales-demo/pi-ai": "22.5.0",
+		"@f5-sales-demo/pi-utils": "22.5.0"
 	},
 	"devDependencies": {
 		"@sinclair/typebox": "0.34.52",

package/src/agent-loop.ts

@@ -11,6 +11,7 @@ import {
 	validateToolArguments,
 } from "@f5-sales-demo/pi-ai";
 import { logger } from "@f5-sales-demo/pi-utils";
+import { LiveSteeringChannel } from "./live-steering";
 import emptyToolSuccess from "./prompts/empty-tool-success.md" with { type: "text" };
 import { AgentToolError } from "./tool-error";
 import type {
@@ -312,6 +313,23 @@ async function runLoop(
 	stream: EventStream<AgentEvent, AgentMessage[]>,
 	streamFn?: StreamFn,
 ): Promise<void> {
+	const completedTools = new Map<string, ToolResultMessage>();
+	const toolKey = (call: Extract<AssistantMessage["content"][number], { type: "toolCall" }>) =>
+		JSON.stringify([config.model.provider, config.model.api, config.model.id, call.id, call.name, call.arguments]);
+	const priorCalls = new Map<string, string>();
+	for (const message of currentContext.messages) {
+		if (
+			message.role === "assistant" &&
+			message.provider === config.model.provider &&
+			message.api === config.model.api &&
+			message.model === config.model.id
+		)
+			for (const call of message.content) if (call.type === "toolCall") priorCalls.set(call.id, toolKey(call));
+		if (message.role === "toolResult" && !message.isError) {
+			const key = priorCalls.get(message.toolCallId);
+			if (key) completedTools.set(key, message);
+		}
+	}
 	let firstTurn = true;
 	// Check for steering messages at start (user may have typed while waiting)
 	let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
@@ -344,9 +362,45 @@ async function runLoop(
 				await logger.ttftAttr("ttft.sync-context", () => config.syncContextBeforeModelCall!(currentContext));
 			}
 
-			// Stream assistant response
-			const message = await streamAssistantResponse(currentContext, newMessages, config, signal, stream, streamFn);
+			// Offer opt-in, plain user steering to the active provider without consuming other message kinds.
+			const live =
+				(config.model.compat as import("@f5-sales-demo/pi-ai").OpenAIResponsesCompat | undefined)
+					?.supportsWebSocketSteering &&
+				config.waitForSteeringMessages &&
+				config.getSteeringMessages &&
+				!exactToolName(config.getToolChoice?.() ?? config.toolChoice)
+					? new LiveSteeringChannel({
+							wait: config.waitForSteeringMessages,
+							take: () => config.getSteeringMessages!(),
+							toProvider: async messages => {
+								const converted = await config.convertToLlm(messages);
+								if (converted.some(message => message.role !== "user")) return undefined;
+								return converted as import("@f5-sales-demo/pi-ai").UserMessage[];
+							},
+						})
+					: undefined;
+			const message = await streamAssistantResponse(
+				currentContext,
+				newMessages,
+				live ? { ...config, liveSteering: live } : config,
+				signal,
+				stream,
+				streamFn,
+			);
 			newMessages.push(message);
+			if (live) {
+				if (message.stopReason === "error" || message.stopReason === "aborted")
+					config.restoreSteeringMessages?.([...live.accepted, ...live.deferred]);
+				else {
+					for (const accepted of live.accepted) {
+						currentContext.messages.push(accepted);
+						newMessages.push(accepted);
+						stream.push({ type: "message_start", message: accepted });
+						stream.push({ type: "message_end", message: accepted });
+					}
+					config.restoreSteeringMessages?.(live.deferred);
+				}
+			}
 			let steeringMessagesFromExecution: AgentMessage[] | undefined;
 
 			if (message.stopReason === "error" || message.stopReason === "aborted") {
@@ -369,10 +423,10 @@ async function runLoop(
 
 			// Check for tool calls
 			const toolCalls = message.content.filter(c => c.type === "toolCall");
-			hasMoreToolCalls = toolCalls.length > 0;
+			hasMoreToolCalls = toolCalls.length > 0 || Boolean(live?.accepted.length);
 
 			const toolResults: ToolResultMessage[] = [];
-			if (hasMoreToolCalls) {
+			if (toolCalls.length > 0) {
 				const executionResult = await executeToolCalls(
 					currentContext.tools,
 					message,
@@ -383,12 +437,15 @@ async function runLoop(
 					config.getToolContext,
 					config.transformToolCallArguments,
 					config.intentTracing,
+					completedTools,
+					toolKey,
 				);
 
 				toolResults.push(...executionResult.toolResults);
 				steeringMessagesFromExecution = executionResult.steeringMessages;
 
 				for (const result of toolResults) {
+					if (currentContext.messages.includes(result)) continue;
 					currentContext.messages.push(result);
 					newMessages.push(result);
 				}
@@ -629,9 +686,17 @@ async function executeToolCalls(
 	getToolContext?: AgentLoopConfig["getToolContext"],
 	transformToolCallArguments?: AgentLoopConfig["transformToolCallArguments"],
 	intentTracing?: AgentLoopConfig["intentTracing"],
+	completedTools = new Map<string, ToolResultMessage>(),
+	toolKey: (call: Extract<AssistantMessage["content"][number], { type: "toolCall" }>) => string = call => call.id,
 ): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> {
 	type ToolCallContent = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
-	const toolCalls = assistantMessage.content.filter((c): c is ToolCallContent => c.type === "toolCall");
+	const toolCalls = [
+		...new Map(
+			assistantMessage.content
+				.filter((c): c is ToolCallContent => c.type === "toolCall")
+				.map(call => [toolKey(call), call]),
+		).values(),
+	];
 	const emittedToolResults: ToolResultMessage[] = [];
 	const toolCallInfos = toolCalls.map(call => ({ id: call.id, name: call.name }));
 	const batchId = `${assistantMessage.timestamp ?? Date.now()}_${toolCalls[0]?.id ?? "batch"}`;
@@ -703,6 +768,8 @@ async function executeToolCalls(
 		});
 
 		const toolResultMessage: ToolResultMessage = {
+			...(toolCall.customInputProperty ? { customTool: true } : {}),
+			...(toolCall.toolSearch ? { toolSearch: true, tools: normalizedResult.tools ?? [] } : {}),
 			role: "toolResult",
 			toolCallId: toolCall.id,
 			toolName: toolCall.name,
@@ -716,6 +783,7 @@ async function executeToolCalls(
 		record.isError = isError;
 		record.toolResultMessage = toolResultMessage;
 		record.resultEmitted = true;
+		if (!isError) completedTools.set(toolKey(toolCall), toolResultMessage);
 		emittedToolResults.push(toolResultMessage);
 
 		stream.push({ type: "message_start", message: toolResultMessage });
@@ -723,6 +791,13 @@ async function executeToolCalls(
 	};
 
 	const runTool = async (record: (typeof records)[number], index: number): Promise<void> => {
+		const completed = completedTools.get(toolKey(record.toolCall));
+		if (completed) {
+			record.toolResultMessage = completed;
+			record.resultEmitted = true;
+			emittedToolResults.push(completed);
+			return;
+		}
 		if (interruptState.triggered) {
 			record.skipped = true;
 			return;

package/src/agent.ts

@@ -260,6 +260,7 @@ export class Agent {
 	#contextMessages?: AgentLoopConfig["getContextMessages"];
 	#transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
 	#steeringQueue: AgentMessage[] = [];
+	#steeringWaiters = new Set<() => void>();
 	#followUpQueue: AgentMessage[] = [];
 	#steeringMode: "all" | "one-at-a-time";
 	#followUpMode: "all" | "one-at-a-time";
@@ -565,6 +566,7 @@ export class Agent {
 	 */
 	steer(m: AgentMessage) {
 		this.#steeringQueue.push(m);
+		for (const wake of this.#steeringWaiters) wake();
 	}
 
 	/**
@@ -839,6 +841,21 @@ export class Agent {
 				intentTracing: this.#intentTracing,
 				onAssistantMessageEvent: this.#onAssistantMessageEvent,
 				getToolChoice,
+				waitForSteeringMessages: signal => {
+					if (this.#steeringQueue.length || signal.aborted) return Promise.resolve();
+					return new Promise<void>(resolve => {
+						const wake = () => {
+							this.#steeringWaiters.delete(wake);
+							signal.removeEventListener("abort", wake);
+							resolve();
+						};
+						this.#steeringWaiters.add(wake);
+						signal.addEventListener("abort", wake, { once: true });
+					});
+				},
+				restoreSteeringMessages: messages => {
+					this.#steeringQueue.unshift(...messages);
+				},
 				getSteeringMessages: async () => {
 					if (skipInitialSteeringPoll) {
 						skipInitialSteeringPoll = false;

package/src/live-steering.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent side of provider live steering ({@link LiveSteering}).
+ *
+ * A provider that can put user input into the response it is streaming (OpenAI
+ * Responses `response.steer`) pulls queued steering through a
+ * {@link LiveSteeringChannel}. The loop records what the provider accepted right
+ * after that response, so the transcript matches what the model saw; anything
+ * it declined is injected at the next boundary like ordinary steering.
+ */
+import type { LiveSteerClaim, LiveSteering, UserMessage } from "@f5-sales-demo/pi-ai";
+import { logger } from "@f5-sales-demo/pi-utils";
+import type { AgentMessage } from "./types";
+
+/** Steering-queue access for one provider call, supplied by the agent loop. */
+export interface LiveSteeringQueue {
+	/** Resolves once steering is queued or `signal` aborts; never consumes. */
+	wait(signal: AbortSignal): Promise<void>;
+	/** Dequeues the next steering batch. */
+	take(signal: AbortSignal): Promise<AgentMessage[]>;
+	/**
+	 * Provider view of `messages` appended to the in-flight call's context, or
+	 * `undefined` when that view is not purely user messages.
+	 */
+	toProvider(messages: AgentMessage[], signal: AbortSignal): Promise<UserMessage[] | undefined>;
+}
+
+/** One provider call's {@link LiveSteering} source. */
+export class LiveSteeringChannel implements LiveSteering {
+	/** Steering the provider delivered into the in-flight response, in queue order. */
+	readonly accepted: AgentMessage[] = [];
+	/** Steering taken from the queue but not delivered; always queued after {@link accepted}. */
+	readonly deferred: AgentMessage[] = [];
+	readonly #queue: LiveSteeringQueue;
+
+	constructor(queue: LiveSteeringQueue) {
+		this.#queue = queue;
+	}
+
+	wait(signal: AbortSignal): Promise<void> {
+		// Once input is deferred, later input must follow it at the boundary;
+		// delivering it live would reorder the user's messages.
+		if (this.deferred.length === 0) return this.#queue.wait(signal);
+		if (signal.aborted) return Promise.resolve();
+		const { promise, resolve } = Promise.withResolvers<void>();
+		signal.addEventListener("abort", () => resolve(), { once: true });
+		return promise;
+	}
+
+	async claim(signal: AbortSignal): Promise<LiveSteerClaim | undefined> {
+		if (this.deferred.length > 0 || signal.aborted) return undefined;
+		let messages: AgentMessage[];
+		try {
+			messages = await this.#queue.take(signal);
+		} catch (error) {
+			// The queue restores what it could not hand over.
+			logger.debug("Live steering dequeue failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return undefined;
+		}
+		if (messages.length === 0) return undefined;
+		let providerMessages: UserMessage[] | undefined;
+		try {
+			providerMessages = await this.#queue.toProvider(messages, signal);
+		} catch (error) {
+			logger.debug("Live steering conversion failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+		if (!providerMessages) {
+			this.deferred.push(...messages);
+			return undefined;
+		}
+		let settled = false;
+		return {
+			messages: providerMessages,
+			accept: () => {
+				if (settled) return;
+				settled = true;
+				this.accepted.push(...messages);
+			},
+			reject: () => {
+				if (settled) return;
+				settled = true;
+				this.deferred.push(...messages);
+			},
+		};
+	}
+}

package/src/types.ts

@@ -102,6 +102,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * these messages are added to the context before the next LLM call.
 	 */
 	getSteeringMessages?: () => Promise<AgentMessage[]>;
+	waitForSteeringMessages?: (signal: AbortSignal) => Promise<void>;
+	restoreSteeringMessages?: (messages: AgentMessage[]) => void;
 
 	/**
 	 * Returns follow-up messages to process after the agent would otherwise stop.
@@ -198,6 +200,8 @@ export interface AgentState {
 }
 
 export interface AgentToolResult<T = any, _TInput = unknown> {
+	/** Trusted schemas loaded by client tool search. */
+	tools?: import("@f5-sales-demo/pi-ai").Tool[];
 	// Content blocks supporting text and images
 	content: (TextContent | ImageContent)[];
 	// Details to be displayed in a UI or logged
@@ -261,6 +265,8 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 	 * - "exclusive": runs alone; other tools wait until it finishes
 	 */
 	concurrency?: "shared" | "exclusive";
+	/** Opt-in host-managed asynchronous execution. Ordinary tools remain synchronous. */
+	async?: boolean;
 	/** If true, argument validation errors are non-fatal: raw args are passed to execute() instead of returning an error to the LLM. */
 	lenientArgValidation?: boolean;
 	execute: AgentToolExecFn<TParameters, TDetails, TTheme>;