@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/{agent-core/src → agent/src/loop}/agent-loop.ts

@@ -6,11 +6,10 @@
 import {
 	type AssistantMessage,
 	type Context,
-	EventStream,
 	streamSimple,
 	type ToolResultMessage,
 	validateToolArguments,
-} from "@aicontainer/ai";
+} from "@ragents/ai";
 import type {
 	AgentContext,
 	AgentEvent,
@@ -24,9 +23,6 @@ import type {
 
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 
-/** Interim tool result text for a call that keeps running after steering arrived. */
-export const BACKGROUNDED_TOOL_RESULT_TEXT = "[tool still running in background; result will follow]";
-
 /** User message that follows a stop without text and without tool call, typically reasoning-only output. */
 export const EMPTY_RESPONSE_NUDGE =
 	"Deine Antwort enthielt weder Text noch Werkzeugaufruf. Antworte jetzt mit dem nächsten Werkzeugaufruf oder Deiner Antwort.";
@@ -47,74 +43,6 @@ function failEmptyResponse(message: AssistantMessage, failOnEmpty: boolean): Ass
 		: message;
 }
 
-/**
- * Start an agent loop with a new prompt message.
- * The prompt is added to the context and events are emitted for it.
- */
-export function agentLoop(
-	prompts: AgentMessage[],
-	context: AgentContext,
-	config: AgentLoopConfig,
-	signal?: AbortSignal,
-	streamFn?: StreamFn,
-): EventStream<AgentEvent, AgentMessage[]> {
-	const stream = createAgentStream();
-
-	void runAgentLoop(
-		prompts,
-		context,
-		config,
-		async (event) => {
-			stream.push(event);
-		},
-		signal,
-		streamFn,
-	).then((messages) => {
-		stream.end(messages);
-	});
-
-	return stream;
-}
-
-/**
- * Continue an agent loop from the current context without adding a new message.
- * Used for retries - context already has user message or tool results.
- *
- * **Important:** The last message in context must convert to a `user` or `toolResult` message
- * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
- * This cannot be validated here since `convertToLlm` is only called once per turn.
- */
-export function agentLoopContinue(
-	context: AgentContext,
-	config: AgentLoopConfig,
-	signal?: AbortSignal,
-	streamFn?: StreamFn,
-): EventStream<AgentEvent, AgentMessage[]> {
-	if (context.messages.length === 0) {
-		throw new Error("Cannot continue: no messages in context");
-	}
-
-	if (context.messages[context.messages.length - 1].role === "assistant") {
-		throw new Error("Cannot continue from message role: assistant");
-	}
-
-	const stream = createAgentStream();
-
-	void runAgentLoopContinue(
-		context,
-		config,
-		async (event) => {
-			stream.push(event);
-		},
-		signal,
-		streamFn,
-	).then((messages) => {
-		stream.end(messages);
-	});
-
-	return stream;
-}
-
 export async function runAgentLoop(
 	prompts: AgentMessage[],
 	context: AgentContext,
@@ -165,15 +93,8 @@ export async function runAgentLoopContinue(
 	return newMessages;
 }
 
-function createAgentStream(): EventStream<AgentEvent, AgentMessage[]> {
-	return new EventStream<AgentEvent, AgentMessage[]>(
-		(event: AgentEvent) => event.type === "agent_end",
-		(event: AgentEvent) => (event.type === "agent_end" ? event.messages : []),
-	);
-}
-
 /**
- * Main loop logic shared by agentLoop and agentLoopContinue.
+ * Main loop logic shared by runAgentLoop and runAgentLoopContinue.
  */
 async function runLoop(
 	initialContext: AgentContext,
@@ -187,122 +108,127 @@ async function runLoop(
 	let config = initialConfig;
 	let firstTurn = true;
 	let emptyStreak = 0;
-	// Check for steering messages at start (user may have typed while waiting)
+	let hasMoreToolCalls = true;
 	let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
 
-	// Outer loop: continues when queued follow-up messages arrive after agent would stop
-	while (true) {
-		let hasMoreToolCalls = true;
+	while (hasMoreToolCalls || pendingMessages.length > 0) {
+		if (!firstTurn) {
+			await emit({ type: "turn_start" });
+		} else {
+			firstTurn = false;
+		}
 
-		// Inner loop: process tool calls and steering messages
-		while (hasMoreToolCalls || pendingMessages.length > 0) {
-			if (!firstTurn) {
-				await emit({ type: "turn_start" });
-			} else {
-				firstTurn = false;
+		// Process pending messages (inject before next assistant response)
+		if (pendingMessages.length > 0) {
+			for (const message of pendingMessages) {
+				await emit({ type: "message_start", message });
+				await emit({ type: "message_end", message });
+				currentContext.messages.push(message);
+				newMessages.push(message);
 			}
+			pendingMessages = [];
+		}
 
-			// Process pending messages (inject before next assistant response)
-			if (pendingMessages.length > 0) {
-				for (const message of pendingMessages) {
-					await emit({ type: "message_start", message });
-					await emit({ type: "message_end", message });
-					currentContext.messages.push(message);
-					newMessages.push(message);
-				}
-				pendingMessages = [];
-			}
+		// Stream assistant response
+		const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn, emptyStreak > 0);
+		newMessages.push(message);
 
-			// Stream assistant response
-			const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn, emptyStreak > 0);
-			newMessages.push(message);
+		if (message.stopReason === "error" || message.stopReason === "aborted") {
+			await emit({ type: "turn_end", message, toolResults: [] });
+			await emit({ type: "agent_end", messages: newMessages });
+			return;
+		}
 
-			if (message.stopReason === "error" || message.stopReason === "aborted") {
-				await emit({ type: "turn_end", message, toolResults: [] });
-				await emit({ type: "agent_end", messages: newMessages });
-				return;
+		emptyStreak = isEmptyResponse(message) ? emptyStreak + 1 : 0;
+
+		// Check for tool calls
+		const toolCalls = message.content.filter((c) => c.type === "toolCall");
+
+		const toolResults: ToolResultMessage[] = [];
+		hasMoreToolCalls = false;
+		if (toolCalls.length > 0) {
+			// A "length" stop means the output was cut off by the token limit, so
+			// every tool call in the message may carry truncated arguments. Fail
+			// them all instead of executing potentially borked calls.
+			const executedToolBatch =
+				message.stopReason === "length"
+					? await failToolCallsFromTruncatedMessage(toolCalls, emit)
+					: await executeToolCalls(currentContext, message, config, signal, emit);
+			toolResults.push(...executedToolBatch.messages);
+			hasMoreToolCalls = !executedToolBatch.terminate;
+
+			for (const result of toolResults) {
+				currentContext.messages.push(result);
+				newMessages.push(result);
 			}
+		}
 
-			emptyStreak = isEmptyResponse(message) ? emptyStreak + 1 : 0;
-
-			// Check for tool calls
-			const toolCalls = message.content.filter((c) => c.type === "toolCall");
-
-			const toolResults: ToolResultMessage[] = [];
-			hasMoreToolCalls = false;
-			if (toolCalls.length > 0) {
-				// A "length" stop means the output was cut off by the token limit, so
-				// every tool call in the message may carry truncated arguments. Fail
-				// them all instead of executing potentially borked calls.
-				const executedToolBatch =
-					message.stopReason === "length"
-						? await failToolCallsFromTruncatedMessage(toolCalls, emit)
-						: await executeToolCalls(currentContext, message, config, signal, emit);
-				toolResults.push(...executedToolBatch.messages);
-				hasMoreToolCalls = !executedToolBatch.terminate;
-
-				for (const result of toolResults) {
-					currentContext.messages.push(result);
-					newMessages.push(result);
-				}
-			}
+		await emit({ type: "turn_end", message, toolResults });
 
-			await emit({ type: "turn_end", message, toolResults });
+		const nextTurnContext = {
+			message,
+			toolResults,
+			context: currentContext,
+			newMessages,
+		};
+		const nextTurnSnapshot = await config.prepareNextTurn?.(nextTurnContext);
+		if (nextTurnSnapshot) {
+			currentContext = nextTurnSnapshot.context ?? currentContext;
+			config = {
+				...config,
+				model: nextTurnSnapshot.model ?? config.model,
+				reasoning:
+					nextTurnSnapshot.thinkingLevel === undefined
+						? config.reasoning
+						: nextTurnSnapshot.thinkingLevel === "off"
+							? undefined
+							: nextTurnSnapshot.thinkingLevel,
+			};
+		}
 
-			const nextTurnContext = {
+		if (
+			await config.shouldStopAfterTurn?.({
 				message,
 				toolResults,
 				context: currentContext,
 				newMessages,
-			};
-			const nextTurnSnapshot = await config.prepareNextTurn?.(nextTurnContext);
-			if (nextTurnSnapshot) {
-				currentContext = nextTurnSnapshot.context ?? currentContext;
-				config = {
-					...config,
-					model: nextTurnSnapshot.model ?? config.model,
-					reasoning:
-						nextTurnSnapshot.thinkingLevel === undefined
-							? config.reasoning
-							: nextTurnSnapshot.thinkingLevel === "off"
-								? undefined
-								: nextTurnSnapshot.thinkingLevel,
-				};
-			}
-
-			if (
-				await config.shouldStopAfterTurn?.({
-					message,
-					toolResults,
-					context: currentContext,
-					newMessages,
-				})
-			) {
-				await emit({ type: "agent_end", messages: newMessages });
-				return;
-			}
-
-			pendingMessages = (await config.getSteeringMessages?.()) || [];
-			if (emptyStreak > 0) {
-				pendingMessages.push({ role: "user", content: EMPTY_RESPONSE_NUDGE, timestamp: Date.now() });
-			}
+			})
+		) {
+			await emit({ type: "agent_end", messages: newMessages });
+			return;
 		}
 
-		// 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;
+		pendingMessages = (await config.getSteeringMessages?.()) || [];
+		if (emptyStreak > 0) {
+			pendingMessages.push({ role: "user", content: EMPTY_RESPONSE_NUDGE, timestamp: Date.now() });
 		}
-
-		// No more messages, exit
-		break;
 	}
 
 	await emit({ type: "agent_end", messages: newMessages });
 }
 
+/** The loop ends like an aborted stream, but no request reaches the model. */
+function abortedBeforeRequest(config: AgentLoopConfig): AssistantMessage {
+	return {
+		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",
+		errorMessage: "Request was aborted before it reached the model",
+		timestamp: Date.now(),
+	};
+}
+
 /**
  * Stream an assistant response from the LLM.
  * This is where AgentMessage[] gets transformed to Message[] for the LLM.
@@ -337,6 +263,14 @@ async function streamAssistantResponse(
 	const resolvedApiKey =
 		(config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;
 
+	if (signal?.aborted) {
+		const aborted = abortedBeforeRequest(config);
+		context.messages.push(aborted);
+		await emit({ type: "message_start", message: { ...aborted } });
+		await emit({ type: "message_end", message: aborted });
+		return aborted;
+	}
+
 	const response = await streamFunction(config.model, llmContext, {
 		...config,
 		apiKey: resolvedApiKey,
@@ -490,11 +424,15 @@ async function executeToolCallsSequential(
 				isError: preparation.isError,
 			};
 		} else {
-			const executed = await executeToolCallOrBackground(preparation, config, signal, emit);
-			finalized =
-				executed.backgrounded === true
-					? { toolCall, result: executed.result, isError: executed.isError }
-					: await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
+			const executed = await executePreparedToolCall(preparation, signal, emit);
+			finalized = await finalizeExecutedToolCall(
+				currentContext,
+				assistantMessage,
+				preparation,
+				executed,
+				config,
+				signal,
+			);
 		}
 
 		await emitToolExecutionEnd(finalized, emit);
@@ -548,11 +486,15 @@ async function executeToolCallsParallel(
 		}
 
 		finalizedCalls.push(async () => {
-			const executed = await executeToolCallOrBackground(preparation, config, signal, emit);
-			const finalized =
-				executed.backgrounded === true
-					? { toolCall: preparation.toolCall, result: executed.result, isError: executed.isError }
-					: await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
+			const executed = await executePreparedToolCall(preparation, signal, emit);
+			const finalized = await finalizeExecutedToolCall(
+				currentContext,
+				assistantMessage,
+				preparation,
+				executed,
+				config,
+				signal,
+			);
 			await emitToolExecutionEnd(finalized, emit);
 			return finalized;
 		});
@@ -640,31 +582,6 @@ async function prepareToolCall(
 
 		const preparedToolCall = prepareToolCallArguments(tool, toolCall);
 		const validatedArgs = validateToolArguments(tool, preparedToolCall);
-		if (config.beforeToolCall) {
-			const beforeResult = await config.beforeToolCall(
-				{
-					assistantMessage,
-					toolCall,
-					args: validatedArgs,
-					context: currentContext,
-				},
-				signal,
-			);
-			if (signal?.aborted) {
-				return {
-					kind: "immediate",
-					result: createErrorToolResult("Operation aborted"),
-					isError: true,
-				};
-			}
-			if (beforeResult?.block) {
-				return {
-					kind: "immediate",
-					result: createErrorToolResult(beforeResult.reason || "Tool execution was blocked"),
-					isError: true,
-				};
-			}
-		}
 		if (signal?.aborted) {
 			return {
 				kind: "immediate",
@@ -687,73 +604,10 @@ async function prepareToolCall(
 	}
 }
 
-/** Resolves when steering is queued; null when the config does not support backgrounding. */
-function watchSteering(config: AgentLoopConfig): { promise: Promise<void>; cancel: () => void } | null {
-	const { hasPendingSteering, onSteeringQueued, onBackgroundToolResult } = config;
-	if (!hasPendingSteering || !onSteeringQueued || !onBackgroundToolResult) {
-		return null;
-	}
-	let cancel = () => {};
-	const promise = new Promise<void>((resolve) => {
-		if (hasPendingSteering()) {
-			resolve();
-			return;
-		}
-		cancel = onSteeringQueued(resolve);
-	});
-	return { promise, cancel };
-}
-
-type ToolCallExecution = ExecutedToolCallOutcome & { backgrounded?: boolean };
-
-/**
- * Execute a prepared tool call, racing it against steering arrival.
- * When steering wins, the call keeps running untouched: an interim result is returned
- * immediately and the real result is handed to `onBackgroundToolResult` on completion.
- */
-async function executeToolCallOrBackground(
-	prepared: PreparedToolCall,
-	config: AgentLoopConfig,
-	signal: AbortSignal | undefined,
-	emit: AgentEventSink,
-): Promise<ToolCallExecution> {
-	const watch = watchSteering(config);
-	let backgrounded = false;
-	const execution = executePreparedToolCall(prepared, signal, emit, () => backgrounded);
-	if (!watch) {
-		return execution;
-	}
-
-	try {
-		const winner = await Promise.race([
-			execution.then((executed) => ({ executed })),
-			watch.promise.then(() => null),
-		]);
-		if (winner) {
-			return winner.executed;
-		}
-		backgrounded = true;
-		void execution.then((executed) => {
-			config.onBackgroundToolResult?.(prepared.toolCall, executed.result, executed.isError);
-		});
-		return {
-			result: {
-				content: [{ type: "text", text: BACKGROUNDED_TOOL_RESULT_TEXT }],
-				details: { backgrounded: true },
-			},
-			isError: false,
-			backgrounded: true,
-		};
-	} finally {
-		watch.cancel();
-	}
-}
-
 async function executePreparedToolCall(
 	prepared: PreparedToolCall,
 	signal: AbortSignal | undefined,
 	emit: AgentEventSink,
-	suppressUpdates?: () => boolean,
 ): Promise<ExecutedToolCallOutcome> {
 	const updateEvents: Promise<void>[] = [];
 	let acceptingUpdates = true;
@@ -764,7 +618,7 @@ async function executePreparedToolCall(
 			prepared.args as never,
 			signal,
 			(partialResult) => {
-				if (!acceptingUpdates || suppressUpdates?.() === true) return;
+				if (!acceptingUpdates) return;
 				updateEvents.push(
 					Promise.resolve(
 						emit({
@@ -861,8 +715,7 @@ function createToolResultMessage(finalized: FinalizedToolCallOutcome): ToolResul
 		role: "toolResult",
 		toolCallId: finalized.toolCall.id,
 		toolName: finalized.toolCall.name,
-		// Untyped tools (JS extensions) can return results without content; normalize
-		// so the null never enters session history or provider payloads.
+		// Untyped tools can return results without content; the null never enters the context.
 		content: finalized.result.content ?? [],
 		details: finalized.result.details,
 		...(finalized.result.addedToolNames?.length ? { addedToolNames: finalized.result.addedToolNames } : {}),