deepagentsdk 0.12.0 → 0.14.0

package/dist/adapters/elements/index.mjs

@@ -1,320 +1,507 @@
-import { n as createDeepAgent } from "../../agent-CrH-He58.mjs";
-import { useCallback, useMemo, useRef, useState } from "react";
+import { convertToModelMessages, createUIMessageStream, createUIMessageStreamResponse } from "ai";
 
-//#region src/adapters/elements/messageAdapter.ts
+//#region src/adapters/elements/createElementsRouteHandler.ts
 /**
-* Converts agent event log to UIMessage format expected by Elements
+* Server-side route handler adapter for AI SDK Elements
 *
-* @param events - Array of agent events from useAgent hook
-* @param streamingText - Current streaming text (if any)
-* @param uiStatus - Current UI status
-* @returns Array of UIMessage objects for Elements Message component
+* Creates a Next.js/Express-compatible route handler that runs DeepAgent
+* and returns UI Message Stream compatible responses with full event visibility.
 *
-* Conversion logic:
-* 1. Group events by role (user/assistant)
-* 2. Convert each event type to appropriate UIMessagePart
-* 3. Handle streaming text as in-progress message
-* 4. Preserve event order and tool call/result pairing
+* This handler streams all DeepAgent event types (26+) including:
+* - Text and tool events (standard protocol)
+* - File system operations
+* - Command execution
+* - Web requests and searches
+* - Subagent lifecycle
+* - State changes (todos, checkpoints)
+*
+* @example
+* ```typescript
+* // app/api/chat/route.ts (Next.js App Router)
+* import { createDeepAgent } from 'deepagentsdk';
+* import { createElementsRouteHandler } from 'deepagentsdk/adapters/elements';
+* import { anthropic } from '@ai-sdk/anthropic';
+*
+* const agent = createDeepAgent({
+*   model: anthropic('claude-sonnet-4-20250514'),
+* });
+*
+* export const POST = createElementsRouteHandler({ agent });
+* ```
+*
+* @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
 */
-function convertEventsToUIMessages(events, streamingText, uiStatus) {
-	const messages = [];
-	let currentAssistantParts = [];
-	let messageIdCounter = 0;
-	const generateMessageId = () => {
-		return `msg-${Date.now()}-${++messageIdCounter}`;
-	};
-	for (const eventLog of events) {
-		const event = eventLog.event;
-		switch (event.type) {
-			case "user-message":
-				if (currentAssistantParts.length > 0) {
-					messages.push({
-						id: generateMessageId(),
-						role: "assistant",
-						parts: currentAssistantParts,
-						status: "ready"
-					});
-					currentAssistantParts = [];
-				}
-				messages.push({
-					id: eventLog.id,
-					role: "user",
-					parts: [{
-						type: "text",
-						text: event.content
-					}],
-					status: "ready"
-				});
-				break;
-			case "text-segment":
-				currentAssistantParts.push({
-					type: "text",
-					text: event.text
-				});
-				break;
-			case "tool-call":
-				currentAssistantParts.push({
-					type: "tool-call",
-					toolCallId: event.toolCallId,
-					toolName: event.toolName,
-					args: event.args
-				});
-				break;
-			case "tool-result":
-				currentAssistantParts.push({
-					type: "tool-result",
-					toolCallId: event.toolCallId,
-					toolName: event.toolName,
-					result: event.result,
-					isError: event.isError
-				});
-				break;
-			default: break;
-		}
-	}
-	if (streamingText || currentAssistantParts.length > 0) {
-		if (streamingText) currentAssistantParts.push({
-			type: "text",
-			text: streamingText
-		});
-		let messageStatus = "ready";
-		if (uiStatus === "streaming") messageStatus = "streaming";
-		else if (uiStatus === "submitted") messageStatus = "submitted";
-		else if (uiStatus === "error") messageStatus = "error";
-		messages.push({
-			id: generateMessageId(),
-			role: "assistant",
-			parts: currentAssistantParts,
-			status: messageStatus
-		});
-	}
-	return messages;
-}
 /**
-* Extracts tool parts from the most recent assistant message
+* Creates a route handler that processes chat requests using DeepAgent
+* and streams all 26+ event types in UI Message Stream Protocol format.
+*
+* The returned handler:
+* - Accepts POST requests with { messages: UIMessage[] } body
+* - Runs DeepAgent with the conversation history
+* - Streams responses in UI Message Stream Protocol format
+* - Works with useChat hook from @ai-sdk/react
+* - Provides full visibility into agent behavior (file ops, web requests, subagents, etc.)
 *
-* @param messages - UIMessage array
-* @returns Array of tool parts (tool-call and tool-result)
+* @param options - Configuration options
+* @returns A request handler function compatible with Next.js/Express
 */
-function extractToolParts(messages) {
-	const lastAssistantMessage = [...messages].reverse().find((m) => m.role === "assistant");
-	if (!lastAssistantMessage) return [];
-	return lastAssistantMessage.parts.filter((part) => part.type === "tool-call" || part.type === "tool-result").map((part) => {
-		if (part.type === "tool-call") return {
-			type: "tool-call",
-			toolCallId: part.toolCallId,
-			toolName: part.toolName,
-			args: part.args
-		};
-		else return {
-			type: "tool-result",
-			toolCallId: part.toolCallId,
-			toolName: part.toolName,
-			result: part.result,
-			isError: part.isError
-		};
-	});
+function createElementsRouteHandler(options) {
+	const { agent, onRequest, initialState = {
+		todos: [],
+		files: {}
+	}, threadId, maxSteps, generateId } = options;
+	return async (req) => {
+		if (onRequest) try {
+			await onRequest(req);
+		} catch (error) {
+			return new Response(JSON.stringify({ error: error instanceof Error ? error.message : "Request rejected" }), {
+				status: 401,
+				headers: { "Content-Type": "application/json" }
+			});
+		}
+		let requestBody;
+		try {
+			requestBody = await req.json();
+		} catch {
+			return new Response(JSON.stringify({ error: "Invalid JSON body" }), {
+				status: 400,
+				headers: { "Content-Type": "application/json" }
+			});
+		}
+		const { messages } = requestBody;
+		if (!messages || !Array.isArray(messages)) return new Response(JSON.stringify({ error: "messages array is required" }), {
+			status: 400,
+			headers: { "Content-Type": "application/json" }
+		});
+		const modelMessages = await convertToModelMessages(messages);
+		const genId = generateId || (() => crypto.randomUUID());
+		let currentTextId = null;
+		return createUIMessageStreamResponse({ stream: createUIMessageStream({
+			originalMessages: messages,
+			generateId: genId,
+			execute: async ({ writer }) => {
+				try {
+					for await (const event of agent.streamWithEvents({
+						messages: modelMessages,
+						state: initialState,
+						threadId,
+						maxSteps
+					})) {
+						const result = mapEventToProtocol(event, writer, genId, currentTextId);
+						if (typeof result === "string") currentTextId = result;
+						else if (result === null) currentTextId = null;
+					}
+					if (currentTextId) writer.write({
+						type: "text-end",
+						id: currentTextId
+					});
+				} catch (error) {
+					if (currentTextId) writer.write({
+						type: "text-end",
+						id: currentTextId
+					});
+					throw error;
+				}
+			},
+			onError: (error) => {
+				return error instanceof Error ? error.message : "Unknown error";
+			}
+		}) });
+	};
 }
-
-//#endregion
-//#region src/adapters/elements/statusAdapter.ts
 /**
-* Maps deepagentsdk AgentStatus to Elements UIStatus
+* Maps a DeepAgent event to a UI Message Stream Protocol event.
+*
+* This function handles all 26+ DeepAgent event types, mapping:
+* - Standard protocol events (text, tools, steps, errors)
+* - Custom data events (file operations, web requests, subagents, execution)
 *
-* @param agentStatus - The agent status from useAgent hook
-* @returns The corresponding UI status for Elements components
+* @param event - The DeepAgent event to map
+* @param writer - The UI message stream writer
+* @param genId - ID generator function
+* @param currentTextId - The current text part ID (for tracking streaming text)
+* @returns The new currentTextId value (string | null)
 *
-* Mapping rules:
-* - idle/done → ready (agent is waiting for input)
-* - thinking/tool-call/subagent → submitted (agent is processing)
-* - streaming → streaming (agent is generating text)
-* - error → error (an error occurred)
+* @example
+* ```typescript
+* // Handles text streaming with proper ID tracking
+* let textId: string | null = null;
+* textId = mapEventToProtocol({ type: 'text', text: 'Hello' }, writer, genId, textId);
+* // textId is now the ID of the active text part
+* ```
 */
-function mapAgentStatusToUIStatus(agentStatus) {
-	switch (agentStatus) {
-		case "thinking":
+function mapEventToProtocol(event, writer, genId, currentTextId) {
+	switch (event.type) {
+		case "step-start":
+			writer.write({ type: "start-step" });
+			return currentTextId;
+		case "step-finish":
+			writer.write({ type: "finish-step" });
+			return currentTextId;
+		case "text":
+			if (!currentTextId) {
+				const textId = genId();
+				writer.write({
+					type: "text-start",
+					id: textId
+				});
+				return textId;
+			}
+			writer.write({
+				type: "text-delta",
+				id: currentTextId,
+				delta: event.text
+			});
+			return currentTextId;
 		case "tool-call":
-		case "subagent": return "submitted";
-		case "streaming": return "streaming";
-		case "error": return "error";
-		case "idle":
+			if (currentTextId) {
+				writer.write({
+					type: "text-end",
+					id: currentTextId
+				});
+				currentTextId = null;
+			}
+			writer.write({
+				type: "tool-input-available",
+				toolCallId: event.toolCallId,
+				toolName: event.toolName,
+				input: event.args
+			});
+			return null;
+		case "tool-result":
+			if (event.isError) writer.write({
+				type: "tool-output-error",
+				toolCallId: event.toolCallId,
+				errorText: String(event.result)
+			});
+			else writer.write({
+				type: "tool-output-available",
+				toolCallId: event.toolCallId,
+				output: event.result
+			});
+			return currentTextId;
+		case "todos-changed":
+			writer.write({
+				type: "data",
+				name: "todos-changed",
+				data: { todos: event.todos }
+			});
+			return currentTextId;
+		case "file-write-start":
+			writer.write({
+				type: "data",
+				name: "file-write-start",
+				data: {
+					path: event.path,
+					content: event.content
+				}
+			});
+			return currentTextId;
+		case "file-written":
+			writer.write({
+				type: "data",
+				name: "file-written",
+				data: {
+					path: event.path,
+					content: event.content
+				}
+			});
+			return currentTextId;
+		case "file-edited":
+			writer.write({
+				type: "data",
+				name: "file-edited",
+				data: {
+					path: event.path,
+					occurrences: event.occurrences
+				}
+			});
+			return currentTextId;
+		case "file-read":
+			writer.write({
+				type: "data",
+				name: "file-read",
+				data: {
+					path: event.path,
+					lines: event.lines
+				}
+			});
+			return currentTextId;
+		case "ls":
+			writer.write({
+				type: "data",
+				name: "ls",
+				data: {
+					path: event.path,
+					count: event.count
+				}
+			});
+			return currentTextId;
+		case "glob":
+			writer.write({
+				type: "data",
+				name: "glob",
+				data: {
+					pattern: event.pattern,
+					count: event.count
+				}
+			});
+			return currentTextId;
+		case "grep":
+			writer.write({
+				type: "data",
+				name: "grep",
+				data: {
+					pattern: event.pattern,
+					count: event.count
+				}
+			});
+			return currentTextId;
+		case "execute-start":
+			writer.write({
+				type: "data",
+				name: "execute-start",
+				data: {
+					command: event.command,
+					sandboxId: event.sandboxId
+				}
+			});
+			return currentTextId;
+		case "execute-finish":
+			writer.write({
+				type: "data",
+				name: "execute-finish",
+				data: {
+					command: event.command,
+					exitCode: event.exitCode,
+					truncated: event.truncated,
+					sandboxId: event.sandboxId
+				}
+			});
+			return currentTextId;
+		case "web-search-start":
+			writer.write({
+				type: "data",
+				name: "web-search-start",
+				data: { query: event.query }
+			});
+			return currentTextId;
+		case "web-search-finish":
+			writer.write({
+				type: "data",
+				name: "web-search-finish",
+				data: {
+					query: event.query,
+					resultCount: event.resultCount
+				}
+			});
+			return currentTextId;
+		case "http-request-start":
+			writer.write({
+				type: "data",
+				name: "http-request-start",
+				data: {
+					url: event.url,
+					method: event.method
+				}
+			});
+			return currentTextId;
+		case "http-request-finish":
+			writer.write({
+				type: "data",
+				name: "http-request-finish",
+				data: {
+					url: event.url,
+					statusCode: event.statusCode
+				}
+			});
+			return currentTextId;
+		case "fetch-url-start":
+			writer.write({
+				type: "data",
+				name: "fetch-url-start",
+				data: { url: event.url }
+			});
+			return currentTextId;
+		case "fetch-url-finish":
+			writer.write({
+				type: "data",
+				name: "fetch-url-finish",
+				data: {
+					url: event.url,
+					success: event.success
+				}
+			});
+			return currentTextId;
+		case "subagent-start":
+			writer.write({
+				type: "data",
+				name: "subagent-start",
+				data: {
+					name: event.name,
+					task: event.task
+				}
+			});
+			return currentTextId;
+		case "subagent-finish":
+			writer.write({
+				type: "data",
+				name: "subagent-finish",
+				data: {
+					name: event.name,
+					result: event.result
+				}
+			});
+			return currentTextId;
+		case "subagent-step":
+			writer.write({
+				type: "data",
+				name: "subagent-step",
+				data: {
+					stepIndex: event.stepIndex,
+					toolCalls: event.toolCalls
+				}
+			});
+			return currentTextId;
+		case "checkpoint-saved":
+			writer.write({
+				type: "data",
+				name: "checkpoint-saved",
+				data: {
+					threadId: event.threadId,
+					step: event.step
+				}
+			});
+			return currentTextId;
+		case "checkpoint-loaded":
+			writer.write({
+				type: "data",
+				name: "checkpoint-loaded",
+				data: {
+					threadId: event.threadId,
+					step: event.step,
+					messagesCount: event.messagesCount
+				}
+			});
+			return currentTextId;
+		case "error":
+			if (currentTextId) {
+				writer.write({
+					type: "text-end",
+					id: currentTextId
+				});
+				currentTextId = null;
+			}
+			writer.write({
+				type: "error",
+				errorText: event.error.message
+			});
+			return null;
 		case "done":
-		default: return "ready";
+			if (currentTextId) {
+				writer.write({
+					type: "text-end",
+					id: currentTextId
+				});
+				currentTextId = null;
+			}
+			writer.write({
+				type: "finish",
+				finishReason: "stop"
+			});
+			return null;
+		default: return currentTextId;
 	}
 }
 
 //#endregion
-//#region src/adapters/elements/useElementsAdapter.ts
+//#region src/adapters/elements/messageConverters.ts
 /**
-* React hook adapter for AI SDK Elements
+* Message conversion utilities for AI SDK Elements adapter
 *
-* Provides Elements-compatible interface for deepagentsdk
+* Provides utilities for converting between UI message formats and model message formats.
+* The primary conversion is handled by AI SDK's `convertToModelMessages`, but these
+* utilities provide additional helpers for DeepAgent-specific needs.
 */
-let eventCounter = 0;
-function createEventId() {
-	return `event-${++eventCounter}`;
-}
 /**
-* Hook that adapts deepagentsdk to work with AI SDK Elements UI components
+* Re-export AI SDK's convertToModelMessages for convenience.
 *
-* @param options - Configuration options
-* @returns Elements-compatible interface
+* This function converts UIMessage[] (from useChat) to ModelMessage[]
+* (for agent consumption), handling:
+* - Role mapping (user/assistant)
+* - Tool call/result parts
+* - Text content extraction
 *
 * @example
-* ```tsx
-* import { useElementsAdapter } from 'deepagentsdk/elements';
-* import { Conversation, Message, PromptInput } from '@/components/ai-elements';
-*
-* function Chat() {
-*   const { uiMessages, sendMessage } = useElementsAdapter({
-*     model,
-*     backend
-*   });
+* ```typescript
+* import { convertUIMessagesToModelMessages } from 'deepagentsdk/adapters/elements';
 *
-*   return (
-*     <Conversation>
-*       {uiMessages.map(msg => <Message key={msg.id} from={msg.role} />)}
-*       <PromptInput onSubmit={sendMessage} />
-*     </Conversation>
-*   );
-* }
+* const modelMessages = await convertUIMessagesToModelMessages(uiMessages);
 * ```
 */
-function useElementsAdapter(options) {
-	const { model, backend, tools, maxSteps = 10, systemPrompt } = options;
-	const [status, setStatus] = useState("idle");
-	const [streamingText, setStreamingText] = useState("");
-	const [events, setEvents] = useState([]);
-	const [state, setState] = useState({
-		todos: [],
-		files: {}
-	});
-	const abortControllerRef = useRef(null);
-	const accumulatedTextRef = useRef("");
-	const agentRef = useRef(createDeepAgent({
-		model,
-		maxSteps,
-		systemPrompt,
-		backend,
-		tools
-	}));
-	const addEvent = useCallback((event) => {
-		setEvents((prev) => [...prev, {
-			id: createEventId(),
-			type: event.type,
-			event,
-			timestamp: /* @__PURE__ */ new Date()
-		}]);
-	}, []);
-	const flushTextSegment = useCallback(() => {
-		if (accumulatedTextRef.current.trim()) {
-			addEvent({
-				type: "text-segment",
-				text: accumulatedTextRef.current
-			});
-			accumulatedTextRef.current = "";
-			setStreamingText("");
-		}
-	}, [addEvent]);
-	const sendMessage = async (message) => {
-		if (!message.text.trim()) return;
-		setStatus("thinking");
-		setStreamingText("");
-		accumulatedTextRef.current = "";
-		addEvent({
-			type: "user-message",
-			content: message.text
-		});
-		abortControllerRef.current = new AbortController();
-		try {
-			for await (const event of agentRef.current.streamWithEvents({
-				messages: [{
-					role: "user",
-					content: message.text
-				}],
-				state,
-				abortSignal: abortControllerRef.current.signal
-			})) switch (event.type) {
-				case "text":
-					setStatus("streaming");
-					accumulatedTextRef.current += event.text;
-					setStreamingText(accumulatedTextRef.current);
-					break;
-				case "step-start":
-					if (event.stepNumber > 1) addEvent(event);
-					break;
-				case "tool-call":
-					flushTextSegment();
-					setStatus("tool-call");
-					addEvent(event);
-					break;
-				case "tool-result":
-					addEvent(event);
-					break;
-				case "todos-changed":
-					flushTextSegment();
-					setStatus("tool-call");
-					setState((prev) => ({
-						...prev,
-						todos: event.todos
-					}));
-					addEvent(event);
-					break;
-				case "done":
-					flushTextSegment();
-					setStatus("done");
-					setState(event.state);
-					addEvent(event);
-					break;
-				case "error":
-					flushTextSegment();
-					setStatus("error");
-					addEvent(event);
-					break;
-				default:
-					addEvent(event);
-					break;
-			}
-			setStatus("idle");
-		} catch (err) {
-			if (err.name === "AbortError") {
-				flushTextSegment();
-				setStatus("idle");
-			} else {
-				flushTextSegment();
-				setStatus("error");
-			}
-		} finally {
-			abortControllerRef.current = null;
-		}
-	};
-	const abort = useCallback(() => {
-		if (abortControllerRef.current) {
-			abortControllerRef.current.abort();
-			setStatus("idle");
+async function convertUIMessagesToModelMessages(messages) {
+	return await convertToModelMessages(messages);
+}
+/**
+* Extract the last user message text from a UIMessage array.
+* Useful for extracting the prompt from a conversation.
+*
+* @param messages - Array of UI messages
+* @returns The text content of the last user message, or undefined if none
+*/
+function extractLastUserMessage(messages) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg && msg.role === "user" && msg.parts) {
+			const textParts = msg.parts.filter((p) => p.type === "text");
+			if (textParts.length > 0) return textParts.map((p) => p.text).join("");
 		}
-	}, []);
-	const clear = useCallback(() => {
-		setEvents([]);
-		setStreamingText("");
-		setStatus("idle");
-	}, []);
-	const uiStatus = useMemo(() => mapAgentStatusToUIStatus(status), [status]);
-	const uiMessages = useMemo(() => convertEventsToUIMessages(events, streamingText, uiStatus), [
-		events,
-		streamingText,
-		uiStatus
-	]);
+	}
+}
+/**
+* Check if the messages contain any tool parts.
+* This is a simplified helper that checks for any tool-related parts.
+*
+* @param messages - Array of UI messages
+* @returns True if there are any tool-related parts in the messages
+*/
+function hasToolParts(messages) {
+	for (const msg of messages) {
+		if (!msg.parts) continue;
+		for (const part of msg.parts) if (part.type.startsWith("tool-") || part.type === "dynamic-tool") return true;
+	}
+	return false;
+}
+/**
+* Count the number of messages by role.
+*
+* @param messages - Array of UI messages
+* @returns Object with counts by role
+*/
+function countMessagesByRole(messages) {
+	let user = 0;
+	let assistant = 0;
+	let system = 0;
+	for (const msg of messages) if (msg.role === "user") user++;
+	else if (msg.role === "assistant") assistant++;
+	else if (msg.role === "system") system++;
 	return {
-		uiMessages,
-		uiStatus,
-		toolParts: useMemo(() => extractToolParts(uiMessages), [uiMessages]),
-		sendMessage,
-		abort,
-		clear
+		user,
+		assistant,
+		system
 	};
 }
+/**
+* Extract all text content from a message.
+*
+* @param message - A UI message
+* @returns Combined text from all text parts
+*/
+function extractTextFromMessage(message) {
+	if (!message.parts) return "";
+	return message.parts.filter((p) => p.type === "text").map((p) => p.text).join("");
+}
 
 //#endregion
-export { convertEventsToUIMessages, extractToolParts, mapAgentStatusToUIStatus, useElementsAdapter };
+export { convertUIMessagesToModelMessages, countMessagesByRole, createElementsRouteHandler, extractLastUserMessage, extractTextFromMessage, hasToolParts, mapEventToProtocol };
 //# sourceMappingURL=index.mjs.map