@ank1015/providers 0.0.1

package/src/agent/agent-loop.ts

@@ -0,0 +1,275 @@
+import { EventStream } from "../utils/event-stream";
+import { UserMessage, Api, NativeAssistantMessage, Context, AssistantMessage, ToolResultMessage } from "../types";
+import { AgentContext, AgentEvent, AgentLoopConfig, AgentTool, AgentToolResult, QueuedMessage } from "./types";
+import { stream as streamLLM } from "../stream";
+import { validateToolArguments } from "../utils/validation";
+
+// Main prompt function - returns a stream of events
+export function agentLoop<TApi extends Api>(
+	prompt: UserMessage,
+	context: AgentContext,
+	config: AgentLoopConfig<TApi>,
+	signal?: AbortSignal,
+): EventStream<AgentEvent, AgentContext["messages"]> {
+
+	// Convert AgentContext to Context for stream
+	// Use a copy of messages to avoid mutating the original context
+	const stream = new EventStream<AgentEvent, AgentContext["messages"]>();
+
+	// Run the prompt async
+	(async () => {
+		// Track new messages generated during this prompt
+		const newMessages: AgentContext["messages"] = [];
+		// Create user message for the prompt
+		const messages = [...context.messages, prompt];
+		newMessages.push(prompt);
+
+		stream.push({ type: "agent_start" });
+		stream.push({ type: "turn_start" });
+		stream.push({ type: "message_start", message: prompt });
+		stream.push({ type: "message_end", message: prompt });
+
+		// Update context with new messages
+		const currentContext: AgentContext = {
+			...context,
+			messages,
+		};
+
+		// Keep looping while we have tool calls or queued messages
+		let hasMoreToolCalls = true;
+		let firstTurn = true;
+		let queuedMessages: QueuedMessage<any>[] = [];
+
+		// Safely get queued messages, handling any errors
+		try {
+			queuedMessages = (await config.getQueuedMessages?.()) || [];
+		} catch (error) {
+			console.warn("Error getting queued messages:", error instanceof Error ? error.message : String(error));
+			// Continue with empty queued messages
+		}
+
+		while (hasMoreToolCalls || queuedMessages.length > 0) {
+			if (!firstTurn) {
+				stream.push({ type: "turn_start" });
+			} else {
+				firstTurn = false;
+			}
+
+			// Process queued messages first (inject before next assistant response)
+			if (queuedMessages.length > 0) {
+				for (const { original, llm } of queuedMessages) {
+					stream.push({ type: "message_start", message: original });
+					stream.push({ type: "message_end", message: original });
+					if (llm) {
+						currentContext.messages.push(llm);
+						newMessages.push(llm);
+					}
+				}
+				queuedMessages = [];
+			}
+
+			// Stream assistant response
+			const {finalAssistantMessage, finalMessage} = await streamAssistantResponse(currentContext, config, signal, stream);
+			newMessages.push(finalMessage);
+			currentContext.messages.push(finalMessage);  // ✅ Add to context so LLM sees its previous responses!
+
+			// Check if assistant message is valid
+			if (!finalAssistantMessage) {
+				// This should never happen, but handle it gracefully
+				stream.push({ type: "agent_end", messages: newMessages, status: "error" });
+				stream.end(newMessages);
+				return;
+			}
+
+			if(finalAssistantMessage.stopReason === 'aborted' || finalAssistantMessage.stopReason === "error"){
+				stream.push({ type: "turn_end", message:finalAssistantMessage, toolResults: [] });
+				stream.push({
+					type: "agent_end",
+					messages: newMessages,
+					status: finalAssistantMessage.stopReason === 'aborted' ? "aborted" : "error"
+				});
+				stream.end(newMessages);
+				return;
+			}
+
+			// Check for tool calls
+			const toolCalls = finalAssistantMessage.content.filter((c) => c.type === "toolCall");
+			hasMoreToolCalls = toolCalls.length > 0;
+
+			const toolResults: ToolResultMessage[] = [];
+			if (hasMoreToolCalls) {
+				// Execute tool calls
+				toolResults.push(...(await executeToolCalls(currentContext.tools, finalAssistantMessage, signal, stream)));
+				currentContext.messages.push(...toolResults);
+				newMessages.push(...toolResults);
+			}
+			stream.push({ type: "turn_end", message: finalAssistantMessage, toolResults: toolResults });
+
+			// Get queued messages after turn completes
+			try {
+				queuedMessages = (await config.getQueuedMessages?.()) || [];
+			} catch (error) {
+				console.warn("Error getting queued messages:", error instanceof Error ? error.message : String(error));
+				queuedMessages = [];
+			}
+		}
+		stream.push({ type: "agent_end", messages: newMessages, status: "completed" });
+		stream.end(newMessages);
+	})()
+
+	return stream;
+}
+
+interface StreamAssistantResult {
+	finalMessage: NativeAssistantMessage,
+	finalAssistantMessage: AssistantMessage
+}
+
+// Helper functions
+async function streamAssistantResponse<TApi extends Api>(
+	context: AgentContext,
+	config: AgentLoopConfig<TApi>,
+	signal: AbortSignal | undefined,
+	stream: EventStream<AgentEvent, AgentContext["messages"]>,
+): Promise<StreamAssistantResult> {
+
+	// Convert AgentContext to Context for stream
+	// Use a copy of messages to avoid mutating the original context
+
+	const processedMessages = config.preprocessor
+		? await config.preprocessor(context.messages, signal)
+		: [...context.messages];
+
+	const processedContext: Context = {
+		systemPrompt: context.systemPrompt,
+		messages: [...processedMessages],
+		tools: context.tools
+	}
+
+	const response = streamLLM(config.model, processedContext, {...config.providerOptions , signal});
+
+	let partialMessage: AssistantMessage | null = null;
+	let addedPartial = false;
+
+	for await (const event of response) {
+		switch (event.type) {
+			case "start":
+				partialMessage = event.partial;
+				// context.messages.push(partialMessage);
+				addedPartial = true;
+				stream.push({ type: "message_start", message: { ...partialMessage } });
+				break;
+
+			case "text_start":
+			case "text_delta":
+			case "text_end":
+			case "thinking_start":
+			case "thinking_delta":
+			case "thinking_end":
+			case "toolcall_start":
+			case "toolcall_delta":
+			case "toolcall_end":
+				if (partialMessage) {
+					partialMessage = event.partial;
+					// context.messages[context.messages.length - 1] = partialMessage;
+					stream.push({ type: "message_update", assistantMessageEvent: event, message: { ...partialMessage } });
+				}
+				break;
+
+			case "done":
+			case "error": {
+				const finalAssistantMessage = event.type === 'error' ? event.error : event.message
+				if (!addedPartial) {
+					stream.push({ type: "message_start", message: { ...finalAssistantMessage } });
+				}
+				stream.push({ type: "message_end", message: finalAssistantMessage });
+
+				const finalMessage = await response.result();
+				return {finalMessage, finalAssistantMessage}
+			}
+		}
+	}
+	const finalMessage = await response.result();
+	return {finalAssistantMessage: partialMessage!, finalMessage}
+}
+
+async function executeToolCalls<T>(
+	tools: readonly AgentTool<any, T>[] | undefined,
+	assistantMessage: AssistantMessage,
+	signal: AbortSignal | undefined,
+	stream: EventStream<AgentEvent, AgentContext["messages"]>,
+): Promise<ToolResultMessage<T>[]> {
+	
+	const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
+	const results: ToolResultMessage<any>[] = [];
+
+	for (const toolCall of toolCalls) {
+		const tool = tools?.find((t) => t.name === toolCall.name);
+
+		stream.push({
+			type: "tool_execution_start",
+			toolCallId: toolCall.id!,
+			toolName: toolCall.name,
+			args: toolCall.arguments,
+		});
+		let resultOrError: AgentToolResult<T> | string;
+		let isError = false;
+
+		let errorDetails: ToolResultMessage["error"] | undefined;
+
+		try {
+			if (!tool) {
+				const availableTools = tools?.map((t) => t.name).join(", ") || "none";
+				throw new Error(
+					`Tool "${toolCall.name}" not found. Available tools: ${availableTools}`
+				);
+			}
+
+			// Validate arguments using shared validation function
+			const validatedArgs = validateToolArguments(tool, toolCall);
+
+			// Execute with validated, typed arguments
+			resultOrError = await tool.execute(toolCall.id!, validatedArgs, signal);
+		} catch (e) {
+			resultOrError = e instanceof Error ? e.message : String(e);
+			isError = true;
+			// Preserve full error details for debugging
+			if (e instanceof Error) {
+				errorDetails = {
+					message: e.message,
+					name: e.name,
+					stack: e.stack,
+				};
+			}
+		}
+
+		stream.push({
+			type: "tool_execution_end",
+			toolCallId: toolCall.id!,
+			toolName: toolCall.name,
+			result: resultOrError,
+			isError,
+		});
+
+		// Convert result to content blocks
+		const content: ToolResultMessage<T>["content"] =
+			typeof resultOrError === "string" ? [{ type: "text", content: resultOrError }] : resultOrError.content;
+
+		const toolResultMessage: ToolResultMessage<T> = {
+			role: "toolResult",
+			toolCallId: toolCall.id,
+			toolName: toolCall.name,
+			content,
+			details: typeof resultOrError === "string" ? ({} as T) : resultOrError.details,
+			isError,
+			error: errorDetails,
+			timestamp: Date.now(),
+		};
+
+		results.push(toolResultMessage);
+		stream.push({ type: "message_start", message: toolResultMessage });
+		stream.push({ type: "message_end", message: toolResultMessage });
+	}
+
+	return results;
+}

package/src/agent/types.ts

@@ -0,0 +1,80 @@
+import { Message, Tool, UserTextContent, UserImageContent, UserFileContent, ToolResultMessage, AssistantMessageEvent, AssistantMessage, Model, OptionsForApi, Api, UserMessage } from "../types";
+import type { Static, TSchema } from "@sinclair/typebox";
+
+
+export interface AgentToolResult<T> {
+	// Content blocks supporting text and images
+	content: (UserTextContent | UserImageContent | UserFileContent)[];
+	// Details to be displayed in a UI or logged
+	details: T;
+}
+
+// AgentTool extends Tool but adds the execute function
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
+	// A human-readable label for the tool to be displayed in UI
+	label: string;
+	execute: (
+		toolCallId: string,
+		params: Static<TParameters>,
+		signal?: AbortSignal,
+	) => Promise<AgentToolResult<TDetails>>;
+}
+
+// AgentContext is like Context but uses AgentTool
+export interface AgentContext {
+	systemPrompt?: string;
+	messages: Message[];
+	tools?: readonly AgentTool<any>[];
+}
+
+
+// Event types
+export type AgentEvent =
+	// Emitted when the agent starts. An agent can emit multiple turns
+	| { type: "agent_start" }
+	// Emitted when a turn starts. A turn can emit an optional user message (initial prompt), an assistant message (response) and multiple tool result messages
+	| { type: "turn_start" }
+	// Emitted when a user, assistant or tool result message starts
+	| { type: "message_start"; message: AssistantMessage | UserMessage | ToolResultMessage }
+	// Emitted when an asssitant messages is updated due to streaming
+	| { type: "message_update"; assistantMessageEvent: AssistantMessageEvent; message: AssistantMessage }
+	// Emitted when a user, assistant or tool result message is complete
+	| { type: "message_end"; message: AssistantMessage | UserMessage | ToolResultMessage }
+	// Emitted when a tool execution starts
+	| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
+	// Emitted when a tool execution completes
+	| {
+			type: "tool_execution_end";
+			toolCallId: string;
+			toolName: string;
+			result: AgentToolResult<any> | string;
+			isError: boolean;
+	  }
+	// Emitted when a full turn completes
+	| { type: "turn_end"; message: AssistantMessage; toolResults: ToolResultMessage[] }
+	// Emitted when the agent has completed all its turns. All messages from every turn are
+	// contained in messages, which can be appended to the context
+	| { type: "agent_end"; messages: AgentContext["messages"]; status: "completed" | "aborted" | "error" };
+
+// Queued message with optional LLM representation
+export interface QueuedMessage<TApp = Message> {
+	original: TApp; // Original message for UI events
+	llm?: Message; // Optional transformed message for loop context (undefined if filtered)
+}
+
+export type ReasoningEffort = "minimal" | "low" | "medium" | "high";
+
+export interface SimpleProviderOptions {
+	reasoning?: ReasoningEffort;
+	signal?: AbortSignal;
+	apiKey?: string;
+	maxTokens?: number;
+}
+
+// Configuration for agent loop execution
+export interface AgentLoopConfig<TApi extends Api> {
+	model: Model<TApi>;
+	preprocessor?: (messages: AgentContext["messages"], signal?: AbortSignal) => Promise<AgentContext["messages"]>;
+    providerOptions: OptionsForApi<TApi>,
+	getQueuedMessages?: <T>() => Promise<QueuedMessage<T>[]>;
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+// ============================================================================
+// Main Functions
+// ============================================================================
+export { stream } from "./stream";
+export { agentLoop } from "./agent/agent-loop";
+
+// ============================================================================
+// Core Types
+// ============================================================================
+export type {
+	// Message types
+	Message,
+	UserMessage,
+	ToolResultMessage,
+	NativeAssistantMessage,
+	NativeOpenAIMessage,
+
+	// Content types
+	UserTextContent,
+	UserImageContent,
+	UserFileContent,
+	AssistantTextContent,
+	AssistantThinkingContent,
+	AssistantToolCall,
+	AbstractedImageContent,
+
+	// Context and Configuration
+	Context,
+	Tool,
+	Api,
+	Model,
+
+	// Streaming types
+	AssistantMessage,
+	AssistantMessageEvent,
+	Usage,
+	StopReason,
+
+	// Provider options
+	OptionsForApi,
+	StreamFunction,
+} from "./types";
+
+// ============================================================================
+// Agent Types
+// ============================================================================
+export type {
+	// Agent-specific types
+	AgentContext,
+	AgentTool,
+	AgentToolResult,
+	AgentEvent,
+	AgentLoopConfig,
+	QueuedMessage,
+} from "./agent/types";
+
+// ============================================================================
+// Models and Registry
+// ============================================================================
+export { MODELS } from "./models.generated";
+export { calculateCost } from "./models";
+
+// ============================================================================
+// Utilities
+// ============================================================================
+export { defineTool } from "./types";
+export type { ToolName, ToolNames } from "./types";
+
+// ============================================================================
+// Event Streams
+// ============================================================================
+export { EventStream, AssistantMessageEventStream } from "./utils/event-stream";