@better-agent/client 0.1.0-canary.0

package/dist/controller-Cf_JhTdJ.mjs

@@ -0,0 +1,2123 @@
+//#region src/core/browser-lifecycle.ts
+const markPageTeardown = () => {
+	if (typeof window !== "undefined") window.__baPageTeardown = true;
+};
+/** Installs one browser teardown tracker for refresh/navigation. */
+const ensureBrowserTeardownTracking = () => {
+	if (typeof window === "undefined") return;
+	window.__baPageTeardown ??= false;
+	if (window.__baPageTeardownInstalled) return;
+	window.__baPageTeardownInstalled = true;
+	window.addEventListener("pagehide", markPageTeardown);
+	window.addEventListener("beforeunload", markPageTeardown);
+};
+/** Returns true while the current browser page is being torn down. */
+const isBrowserPageTearingDown = () => typeof window !== "undefined" && window.__baPageTeardown === true;
+
+//#endregion
+//#region src/core/error.ts
+/** Internal error used to mark broken stream transport. */
+var StreamDisconnectError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.name = "StreamDisconnectError";
+		this.cause = cause;
+	}
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+const stripSurfacePrefix = (message) => message.replace(/^(run failed|stream failed):\s*/i, "");
+const extractMessage = (error) => {
+	if (error instanceof Error && typeof error.message === "string" && error.message.trim()) return stripSurfacePrefix(error.message);
+	if (!isRecord(error)) return void 0;
+	const message = typeof error.message === "string" && error.message || typeof error.detail === "string" && error.detail || typeof error.title === "string" && error.title;
+	return typeof message === "string" && message.trim().length > 0 ? stripSurfacePrefix(message) : void 0;
+};
+/** Normalizes unknown failures into `AgentClientError`. */
+const toAgentClientError = (error, fallbackMessage = "Run failed.") => {
+	if (error instanceof Error) {
+		const enriched = error;
+		enriched.message = stripSurfacePrefix(enriched.message);
+		if (typeof enriched.detail === "string" && enriched.detail.length > 0) enriched.detail = stripSurfacePrefix(enriched.detail);
+		if (enriched.raw === void 0) enriched.raw = error;
+		return enriched;
+	}
+	const message = extractMessage(error) ?? fallbackMessage;
+	const next = new Error(message);
+	next.raw = error;
+	if (!isRecord(error)) return next;
+	if (typeof error.code === "string") next.code = error.code;
+	if (typeof error.status === "number") next.status = error.status;
+	if (typeof error.retryable === "boolean") next.retryable = error.retryable;
+	if (typeof error.title === "string") next.title = error.title;
+	if (typeof error.detail === "string") next.detail = stripSurfacePrefix(error.detail);
+	if (typeof error.traceId === "string") next.traceId = error.traceId;
+	if (Array.isArray(error.issues)) next.issues = error.issues;
+	if (isRecord(error.context)) next.context = error.context;
+	if (Array.isArray(error.trace)) next.trace = error.trace;
+	return next;
+};
+/**
+* Resolves a user-facing message from an event error payload.
+*/
+const getEventErrorMessage = (error) => toAgentClientError(error).message;
+
+//#endregion
+//#region src/core/utils.ts
+const withProviderMetadata = (part) => part.providerMetadata !== void 0 && typeof part.providerMetadata === "object" && part.providerMetadata !== null ? { providerMetadata: part.providerMetadata } : {};
+/** Converts one persisted part into a UI part. */
+const contentPartToUIPart = (part) => {
+	if (typeof part !== "object" || part === null || typeof part.type !== "string") return null;
+	const record = part;
+	switch (record.type) {
+		case "text": return typeof record.text === "string" ? {
+			type: "text",
+			text: record.text,
+			...withProviderMetadata(record),
+			state: "complete"
+		} : null;
+		case "image": return {
+			type: "image",
+			source: record.source,
+			...withProviderMetadata(record),
+			state: "complete"
+		};
+		case "file": return {
+			type: "file",
+			source: record.source,
+			...withProviderMetadata(record),
+			state: "complete"
+		};
+		case "audio": return {
+			type: "audio",
+			source: record.source,
+			...withProviderMetadata(record),
+			state: "complete"
+		};
+		case "video": return {
+			type: "video",
+			source: record.source,
+			...withProviderMetadata(record),
+			state: "complete"
+		};
+		case "embedding": return Array.isArray(record.embedding) && record.embedding.every((value) => typeof value === "number") ? {
+			type: "embedding",
+			embedding: record.embedding,
+			...withProviderMetadata(record),
+			state: "complete"
+		} : null;
+		case "transcript": return typeof record.text === "string" ? {
+			type: "transcript",
+			text: record.text,
+			...Array.isArray(record.segments) ? { segments: record.segments } : {},
+			...withProviderMetadata(record),
+			state: "complete"
+		} : null;
+		case "reasoning": return typeof record.text === "string" && (record.visibility === "summary" || record.visibility === "full") ? {
+			type: "reasoning",
+			text: record.text,
+			visibility: record.visibility,
+			...typeof record.provider === "string" ? { provider: record.provider } : {},
+			...withProviderMetadata(record),
+			state: "complete"
+		} : null;
+		default: return null;
+	}
+};
+const toModelInputParts = (message) => {
+	const out = [];
+	for (const part of message.parts) {
+		const providerMetadata = "providerMetadata" in part ? part.providerMetadata : void 0;
+		if (part.type === "text") {
+			out.push({
+				type: "text",
+				text: part.text,
+				...providerMetadata !== void 0 ? { providerMetadata } : {}
+			});
+			continue;
+		}
+		if (part.type === "audio") {
+			if (part.source.kind === "url") {
+				out.push({
+					type: "audio",
+					source: {
+						kind: "url",
+						url: part.source.url
+					},
+					...providerMetadata !== void 0 ? { providerMetadata } : {}
+				});
+				continue;
+			}
+			out.push({
+				type: "audio",
+				source: {
+					kind: "base64",
+					data: part.source.data,
+					mimeType: part.source.mimeType ?? "audio/wav"
+				},
+				...providerMetadata !== void 0 ? { providerMetadata } : {}
+			});
+			continue;
+		}
+		if (part.type === "image") {
+			if (part.source.kind === "url") {
+				out.push({
+					type: "image",
+					source: {
+						kind: "url",
+						url: part.source.url
+					},
+					...providerMetadata !== void 0 ? { providerMetadata } : {}
+				});
+				continue;
+			}
+			out.push({
+				type: "image",
+				source: {
+					kind: "base64",
+					data: part.source.data,
+					mimeType: part.source.mimeType ?? "image/png"
+				},
+				...providerMetadata !== void 0 ? { providerMetadata } : {}
+			});
+			continue;
+		}
+		if (part.type === "file") {
+			if (part.source.kind === "url") {
+				out.push({
+					type: "file",
+					source: {
+						kind: "url",
+						url: part.source.url,
+						...part.source.mimeType ? { mimeType: part.source.mimeType } : {},
+						...part.source.filename ? { filename: part.source.filename } : {}
+					},
+					...providerMetadata !== void 0 ? { providerMetadata } : {}
+				});
+				continue;
+			}
+			if (part.source.kind === "provider-file") {
+				out.push({
+					type: "file",
+					source: {
+						kind: "provider-file",
+						ref: part.source.ref,
+						...part.source.mimeType ? { mimeType: part.source.mimeType } : {},
+						...part.source.filename ? { filename: part.source.filename } : {}
+					},
+					...providerMetadata !== void 0 ? { providerMetadata } : {}
+				});
+				continue;
+			}
+			out.push({
+				type: "file",
+				source: {
+					kind: "base64",
+					data: part.source.data,
+					mimeType: part.source.mimeType,
+					...part.source.filename ? { filename: part.source.filename } : {}
+				},
+				...providerMetadata !== void 0 ? { providerMetadata } : {}
+			});
+			continue;
+		}
+		if (part.type === "video") {
+			if (part.source.kind === "url") {
+				out.push({
+					type: "video",
+					source: {
+						kind: "url",
+						url: part.source.url
+					},
+					...providerMetadata !== void 0 ? { providerMetadata } : {}
+				});
+				continue;
+			}
+			out.push({
+				type: "video",
+				source: {
+					kind: "base64",
+					data: part.source.data,
+					mimeType: part.source.mimeType ?? "video/mp4"
+				},
+				...providerMetadata !== void 0 ? { providerMetadata } : {}
+			});
+			continue;
+		}
+		if (part.type === "embedding") {
+			out.push({
+				type: "embedding",
+				embedding: part.embedding,
+				...providerMetadata !== void 0 ? { providerMetadata } : {}
+			});
+			continue;
+		}
+		if (part.type === "transcript") {
+			out.push({
+				type: "transcript",
+				text: part.text,
+				...part.segments ? { segments: part.segments } : {},
+				...providerMetadata !== void 0 ? { providerMetadata } : {}
+			});
+			continue;
+		}
+		if (part.type === "reasoning") out.push({
+			type: "reasoning",
+			text: part.text,
+			visibility: part.visibility,
+			...part.provider ? { provider: part.provider } : {},
+			...providerMetadata !== void 0 ? { providerMetadata } : {}
+		});
+	}
+	return out;
+};
+/** Converts UI messages into model input messages. */
+const toModelMessages = (msgs) => msgs.flatMap((message) => {
+	const parts = toModelInputParts(message);
+	const items = [];
+	if (parts.length > 0) {
+		const hasNonText = parts.some((part) => part.type !== "text");
+		items.push({
+			type: "message",
+			role: message.role,
+			content: hasNonText || parts.length !== 1 || parts[0]?.type !== "text" ? parts : parts[0].text
+		});
+	}
+	const completedCalls = /* @__PURE__ */ new Map();
+	for (const part of message.parts) {
+		if (part.type !== "tool-call") continue;
+		const toolName = part.name;
+		if (toolName && (part.status === "success" || part.status === "error" || part.state === "completed")) completedCalls.set(part.callId, toolName);
+	}
+	for (const part of message.parts) {
+		if (part.type !== "tool-result") continue;
+		const toolName = completedCalls.get(part.callId);
+		if (!toolName || part.status !== "success" && part.status !== "error") continue;
+		items.push({
+			type: "tool-call",
+			name: toolName,
+			callId: part.callId,
+			result: part.result,
+			...part.status === "error" ? { isError: true } : {}
+		});
+	}
+	return items;
+});
+const contentToUIParts = (content) => {
+	if (typeof content === "string") return [{
+		type: "text",
+		text: content,
+		state: "complete"
+	}];
+	return content.map((part) => contentPartToUIPart(part)).filter((part) => part !== null);
+};
+/** Converts model input messages back into UI messages. */
+const fromModelMessages = (messages, options) => {
+	const generateId = options?.generateId ?? makeLocalMessageId;
+	const result = [];
+	let activeAssistantMessageIndex;
+	for (const item of messages) {
+		if (item.type === "message") {
+			const parts = contentToUIParts(item.content);
+			if (parts.length === 0) continue;
+			result.push({
+				localId: generateId(),
+				role: item.role ?? "user",
+				parts
+			});
+			activeAssistantMessageIndex = (item.role ?? "user") === "assistant" ? result.length - 1 : void 0;
+			continue;
+		}
+		const status = item.isError ? "error" : "success";
+		const toolParts = [{
+			type: "tool-call",
+			callId: item.callId,
+			name: item.name,
+			status,
+			state: "completed"
+		}, {
+			type: "tool-result",
+			callId: item.callId,
+			result: item.result,
+			status
+		}];
+		if (activeAssistantMessageIndex !== void 0) {
+			const message = result[activeAssistantMessageIndex];
+			if (message?.role === "assistant") {
+				result[activeAssistantMessageIndex] = {
+					...message,
+					parts: [...message.parts, ...toolParts]
+				};
+				continue;
+			}
+		}
+		result.push({
+			localId: generateId(),
+			role: "assistant",
+			parts: toolParts
+		});
+		activeAssistantMessageIndex = result.length - 1;
+	}
+	return result;
+};
+/** Converts durable conversation items back into UI messages. */
+const fromConversationItems = (items, options) => {
+	const generateId = options?.generateId ?? makeLocalMessageId;
+	const result = [];
+	let activeAssistantMessageIndex;
+	for (const item of items) {
+		if (item.type === "message") {
+			const parts = contentToUIParts(item.content);
+			if (parts.length === 0) continue;
+			result.push({
+				localId: generateId(),
+				role: item.role ?? "user",
+				parts
+			});
+			activeAssistantMessageIndex = (item.role ?? "user") === "assistant" ? result.length - 1 : void 0;
+			continue;
+		}
+		if ("arguments" in item) {
+			const part = {
+				type: "tool-call",
+				callId: item.callId,
+				name: item.name,
+				args: item.arguments,
+				status: "pending",
+				state: "input-complete"
+			};
+			if (activeAssistantMessageIndex !== void 0) {
+				const message = result[activeAssistantMessageIndex];
+				if (message?.role === "assistant") {
+					result[activeAssistantMessageIndex] = {
+						...message,
+						parts: [...message.parts, part]
+					};
+					continue;
+				}
+			}
+			result.push({
+				localId: generateId(),
+				role: "assistant",
+				parts: [part]
+			});
+			activeAssistantMessageIndex = result.length - 1;
+			continue;
+		}
+		let appendedToExistingMessage = false;
+		for (let index = result.length - 1; index >= 0; index -= 1) {
+			const message = result[index];
+			if (!message || message.role !== "assistant") continue;
+			const partIndex = message.parts.findIndex((part) => part.type === "tool-call" && part.callId === item.callId);
+			if (partIndex < 0) continue;
+			const existingPart = message.parts[partIndex];
+			if (!existingPart || existingPart.type !== "tool-call") break;
+			const status = item.isError ? "error" : "success";
+			const parts = message.parts.slice();
+			parts[partIndex] = {
+				...existingPart,
+				...existingPart.name === void 0 ? { name: item.name } : {},
+				status,
+				state: "completed"
+			};
+			parts.splice(partIndex + 1, 0, {
+				type: "tool-result",
+				callId: item.callId,
+				result: item.result,
+				status
+			});
+			result[index] = {
+				...message,
+				parts
+			};
+			appendedToExistingMessage = true;
+			break;
+		}
+		if (appendedToExistingMessage) continue;
+		const status = item.isError ? "error" : "success";
+		const toolParts = [{
+			type: "tool-call",
+			callId: item.callId,
+			name: item.name,
+			status,
+			state: "completed"
+		}, {
+			type: "tool-result",
+			callId: item.callId,
+			result: item.result,
+			status
+		}];
+		if (activeAssistantMessageIndex !== void 0) {
+			const message = result[activeAssistantMessageIndex];
+			if (message?.role === "assistant") {
+				result[activeAssistantMessageIndex] = {
+					...message,
+					parts: [...message.parts, ...toolParts]
+				};
+				continue;
+			}
+		}
+		result.push({
+			localId: generateId(),
+			role: "assistant",
+			parts: toolParts
+		});
+		activeAssistantMessageIndex = result.length - 1;
+	}
+	return result;
+};
+/** Creates a local message id. */
+const makeLocalMessageId = () => globalThis.crypto?.randomUUID?.() ?? `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+/** Normalizes optimistic message options. */
+const normalizeOptimisticUserMessageConfig = (optimisticUserMessage) => {
+	if (optimisticUserMessage === true) return {
+		enabled: true,
+		onError: "fail"
+	};
+	if (optimisticUserMessage === false) return {
+		enabled: false,
+		onError: "fail"
+	};
+	if (!optimisticUserMessage) return {
+		enabled: true,
+		onError: "fail"
+	};
+	return {
+		enabled: optimisticUserMessage.enabled ?? true,
+		onError: optimisticUserMessage.onError ?? "fail"
+	};
+};
+/** Deep-merges model option objects. Arrays are replaced, not merged. */
+const mergeModelOptions = (...parts) => {
+	const merged = {};
+	const mergeInto = (target, source) => {
+		for (const [key, value] of Object.entries(source)) {
+			const existing = target[key];
+			if (existing !== null && typeof existing === "object" && !Array.isArray(existing) && value !== null && typeof value === "object" && !Array.isArray(value)) target[key] = mergeInto({ ...existing }, value);
+			else target[key] = value;
+		}
+		return target;
+	};
+	for (const part of parts) if (part) mergeInto(merged, part);
+	return merged;
+};
+
+//#endregion
+//#region src/core/reducer.ts
+/** Applies one core event to the current message state. */
+const applyEvent = (state, event, options) => {
+	switch (event.type) {
+		case "RUN_STARTED":
+			if (!options?.synthesizeReplayUserMessage) return state;
+			return maybeInsertReplayUserMessage(state, event.runInput, event.runId);
+		case "TEXT_MESSAGE_START": {
+			const role = event.role ?? "assistant";
+			return ensureMessage(state, event.messageId, role);
+		}
+		case "TEXT_MESSAGE_CONTENT": return updateAssistantMessage(state, event.messageId, (msg) => appendText(msg, event.delta));
+		case "TEXT_MESSAGE_END": return updateAssistantMessage(state, event.messageId, (msg) => markLatestPartComplete(msg, "text"));
+		case "AUDIO_MESSAGE_START": {
+			const role = event.role ?? "assistant";
+			return ensureMessage(state, event.messageId, role);
+		}
+		case "AUDIO_MESSAGE_CONTENT": return updateAssistantMessage(state, event.messageId, (msg) => appendAudio(msg, event.delta));
+		case "AUDIO_MESSAGE_END": return updateAssistantMessage(state, event.messageId, (msg) => markLatestPartComplete(msg, "audio"));
+		case "IMAGE_MESSAGE_START": {
+			const role = event.role ?? "assistant";
+			return ensureMessage(state, event.messageId, role);
+		}
+		case "IMAGE_MESSAGE_CONTENT": return updateAssistantMessage(state, event.messageId, (msg) => appendImage(msg, event.delta));
+		case "IMAGE_MESSAGE_END": return updateAssistantMessage(state, event.messageId, (msg) => markLatestPartComplete(msg, "image"));
+		case "VIDEO_MESSAGE_START": {
+			const role = event.role ?? "assistant";
+			return ensureMessage(state, event.messageId, role);
+		}
+		case "VIDEO_MESSAGE_CONTENT": return updateAssistantMessage(state, event.messageId, (msg) => appendVideo(msg, event.delta));
+		case "VIDEO_MESSAGE_END": return updateAssistantMessage(state, event.messageId, (msg) => markLatestPartComplete(msg, "video"));
+		case "EMBEDDING_MESSAGE_START": {
+			const role = event.role ?? "assistant";
+			return ensureMessage(state, event.messageId, role);
+		}
+		case "EMBEDDING_MESSAGE_CONTENT": return updateAssistantMessage(state, event.messageId, (msg) => appendEmbedding(msg, event.delta));
+		case "EMBEDDING_MESSAGE_END": return updateAssistantMessage(state, event.messageId, (msg) => markLatestPartComplete(msg, "embedding"));
+		case "TRANSCRIPT_MESSAGE_START": {
+			const role = event.role ?? "assistant";
+			return ensureMessage(state, event.messageId, role);
+		}
+		case "TRANSCRIPT_MESSAGE_CONTENT": return updateAssistantMessage(state, event.messageId, (msg) => appendTranscriptText(msg, event.delta));
+		case "TRANSCRIPT_MESSAGE_SEGMENT": return updateAssistantMessage(state, event.messageId, (msg) => upsertTranscriptSegment(msg, event.segment));
+		case "TRANSCRIPT_MESSAGE_END": return updateAssistantMessage(state, event.messageId, (msg) => markLatestPartComplete(msg, "transcript"));
+		case "REASONING_MESSAGE_START": {
+			const role = event.role ?? "assistant";
+			return ensureAndUpdateMessage(state, event.messageId, role, (msg) => appendReasoningText(msg, "", event.visibility));
+		}
+		case "REASONING_MESSAGE_CONTENT": return updateAssistantMessage(state, event.messageId, (msg) => appendReasoningText(msg, event.delta, event.visibility));
+		case "REASONING_MESSAGE_END": return updateAssistantMessage(state, event.messageId, (msg) => markLatestPartComplete(msg, "reasoning"));
+		case "TOOL_CALL_START": return updateResolvedToolMessage(state, event.parentMessageId, event.toolCallId, (msg) => isToolCallCompleted(msg, event.toolCallId) ? msg : upsertToolPart(msg, "tool-call", event.toolCallId, {
+			name: event.toolCallName,
+			...event.toolTarget !== void 0 ? { toolTarget: event.toolTarget } : {},
+			status: "pending",
+			state: "awaiting-input"
+		}));
+		case "TOOL_CALL_ARGS": return updateResolvedToolMessage(state, event.parentMessageId, event.toolCallId, (msg) => isToolCallCompleted(msg, event.toolCallId) ? msg : upsertToolPart(msg, "tool-call", event.toolCallId, {
+			name: event.toolCallName,
+			...event.toolTarget !== void 0 ? { toolTarget: event.toolTarget } : {},
+			status: "pending",
+			state: "input-streaming"
+		}, (part) => part.type === "tool-call" ? {
+			...part,
+			args: (part.args ?? "") + event.delta
+		} : part));
+		case "TOOL_CALL_END": return updateResolvedToolMessage(state, event.parentMessageId, event.toolCallId, (msg) => {
+			if (isToolCallCompleted(msg, event.toolCallId)) return msg;
+			if (isApprovalLifecycleState(findToolCallPart(msg, event.toolCallId)?.state)) return msg;
+			return upsertToolPart(msg, "tool-call", event.toolCallId, {
+				name: event.toolCallName,
+				...event.toolTarget !== void 0 ? { toolTarget: event.toolTarget } : {},
+				status: "pending",
+				state: "input-complete"
+			});
+		});
+		case "TOOL_CALL_RESULT": return updateResolvedToolMessage(state, event.parentMessageId, event.toolCallId, (msg) => {
+			const status = event.isError ? "error" : "success";
+			return upsertToolPart(upsertToolPart(msg, "tool-result", event.toolCallId, {
+				result: event.result,
+				status
+			}), "tool-call", event.toolCallId, {
+				name: event.toolCallName,
+				...event.toolTarget !== void 0 ? { toolTarget: event.toolTarget } : {},
+				status,
+				state: "completed"
+			});
+		});
+		case "TOOL_APPROVAL_REQUIRED": return updateResolvedToolMessage(state, event.parentMessageId, event.toolCallId, (msg) => {
+			return updateToolApprovalMeta(upsertToolPart(msg, "tool-call", event.toolCallId, {
+				name: event.toolCallName,
+				...event.toolTarget !== void 0 ? { toolTarget: event.toolTarget } : {},
+				status: "pending",
+				state: "approval-requested"
+			}), event.toolCallId, {
+				input: event.toolInput,
+				...event.meta !== void 0 ? { meta: event.meta } : {}
+			});
+		});
+		case "TOOL_APPROVAL_UPDATED": return updateResolvedToolMessage(state, event.parentMessageId, event.toolCallId, (msg) => {
+			return updateToolApprovalMeta(upsertToolPart(msg, "tool-call", event.toolCallId, {
+				name: event.toolCallName,
+				...event.toolTarget !== void 0 ? { toolTarget: event.toolTarget } : {},
+				status: getApprovalStatus(event.state),
+				state: getApprovalPartState(event.state)
+			}), event.toolCallId, {
+				...event.toolInput !== void 0 ? { input: event.toolInput } : {},
+				...event.meta !== void 0 ? { meta: event.meta } : {},
+				...event.note !== void 0 ? { note: event.note } : {},
+				...event.actorId !== void 0 ? { actorId: event.actorId } : {}
+			});
+		});
+		default: return state;
+	}
+};
+/** Creates message state from UI messages. */
+const createMessageState = (initial = []) => {
+	const byLocalId = /* @__PURE__ */ new Map();
+	initial.forEach((m, i) => byLocalId.set(m.localId, i));
+	return {
+		messages: initial,
+		byLocalId
+	};
+};
+const findMessageLocalIdByToolCallId = (state, toolCallId) => {
+	for (let i = state.messages.length - 1; i >= 0; i -= 1) {
+		const message = state.messages[i];
+		if (!message) continue;
+		if (message.parts.some((part) => (part.type === "tool-call" || part.type === "tool-result") && part.callId === toolCallId)) return message.localId;
+	}
+};
+const findLatestAssistantMessageLocalId = (state) => {
+	for (let i = state.messages.length - 1; i >= 0; i -= 1) {
+		const message = state.messages[i];
+		if (message?.role === "assistant") return message.localId;
+	}
+};
+const resolveCurrentTurnAssistantLocalId = (state) => {
+	for (let i = state.messages.length - 1; i >= 0; i -= 1) {
+		const message = state.messages[i];
+		if (message?.role !== "user") continue;
+		const userLocalId = message.localId;
+		let latestAssistantAfterUser;
+		for (let j = i + 1; j < state.messages.length; j += 1) {
+			const candidate = state.messages[j];
+			if (candidate?.role === "assistant") latestAssistantAfterUser = candidate.localId;
+		}
+		return latestAssistantAfterUser ?? `assistant_turn:${userLocalId}`;
+	}
+};
+const resolveToolMessageLocalId = (state, parentMessageId, toolCallId) => {
+	if (parentMessageId) {
+		if (state.byLocalId.has(parentMessageId)) return parentMessageId;
+	}
+	return findMessageLocalIdByToolCallId(state, toolCallId) ?? resolveCurrentTurnAssistantLocalId(state) ?? findLatestAssistantMessageLocalId(state);
+};
+const maybeInsertReplayUserMessage = (state, runInput, runId) => {
+	const synthesized = toReplayUserMessage(runInput, runId);
+	if (!synthesized) return state;
+	if (state.byLocalId.has(synthesized.localId)) return state;
+	const latestUserMessage = findLatestUserMessage(state);
+	if (latestUserMessage && latestUserMessage.localId === synthesized.localId) return state;
+	return {
+		...state,
+		messages: [...state.messages, synthesized],
+		byLocalId: new Map(state.byLocalId).set(synthesized.localId, state.messages.length)
+	};
+};
+const toReplayUserMessage = (runInput, runId) => {
+	const input = runInput.input;
+	if (typeof input === "string") return {
+		localId: `user_run:${runId}`,
+		id: `user_run:${runId}`,
+		role: "user",
+		parts: [{
+			type: "text",
+			text: input,
+			state: "complete"
+		}],
+		status: "sent"
+	};
+	if (isReplayInputArray(input)) return toLatestReplayUserMessage(input, runId);
+	if (isSingleReplayMessageItem(input)) return toLatestReplayUserMessage([input], runId);
+};
+const toLatestReplayUserMessage = (input, runId) => {
+	const latestUserMessage = [...fromModelMessages(input, { generateId: (() => {
+		let index = 0;
+		return () => `user_run:${runId}:${(index++).toString(36)}`;
+	})() })].reverse().find((message) => message.role === "user");
+	if (!latestUserMessage) return;
+	return {
+		...latestUserMessage,
+		status: "sent"
+	};
+};
+const findLatestUserMessage = (state) => [...state.messages].reverse().find((message) => message.role === "user");
+const isSingleReplayMessageItem = (input) => {
+	if (typeof input !== "object" || input === null) return false;
+	const record = input;
+	return record.type === "message" && (record.role === void 0 || typeof record.role === "string") && (typeof record.content === "string" || Array.isArray(record.content));
+};
+const isReplayInputArray = (input) => Array.isArray(input);
+const ensureMessage = (state, localId, role) => {
+	if (state.byLocalId.has(localId)) return state;
+	const next = {
+		localId,
+		id: localId,
+		role,
+		parts: []
+	};
+	return {
+		...state,
+		messages: [...state.messages, next],
+		byLocalId: new Map(state.byLocalId).set(localId, state.messages.length)
+	};
+};
+const updateMessage = (state, localId, updater) => {
+	const idx = state.byLocalId.get(localId);
+	if (idx === void 0) return state;
+	const nextMessages = state.messages.slice();
+	const current = nextMessages[idx];
+	if (!current) return state;
+	nextMessages[idx] = updater(current);
+	return {
+		...state,
+		messages: nextMessages
+	};
+};
+const ensureAndUpdateMessage = (state, localId, role, updater) => updateMessage(ensureMessage(state, localId, role), localId, updater);
+const appendText = (msg, delta) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (last && last.type === "text" && last.state !== "complete") parts[parts.length - 1] = {
+		...last,
+		text: last.text + delta
+	};
+	else parts.push({
+		type: "text",
+		text: delta
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const appendAudio = (msg, delta) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (last?.type === "audio" && last.source.kind === "base64" && last.state !== "complete") parts[parts.length - 1] = {
+		...last,
+		source: {
+			kind: "base64",
+			data: `${last.source.data}${delta.data}`,
+			mimeType: delta.mimeType
+		}
+	};
+	else parts.push({
+		type: "audio",
+		source: {
+			kind: "base64",
+			data: delta.data,
+			mimeType: delta.mimeType
+		}
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const appendImage = (msg, delta) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (delta.kind === "base64" && last?.type === "image" && last.source.kind === "base64" && last.state !== "complete") parts[parts.length - 1] = {
+		...last,
+		source: {
+			kind: "base64",
+			data: `${last.source.data}${delta.data}`,
+			mimeType: delta.mimeType
+		}
+	};
+	else if (delta.kind === "url") parts.push({
+		type: "image",
+		source: {
+			kind: "url",
+			url: delta.url
+		}
+	});
+	else parts.push({
+		type: "image",
+		source: {
+			kind: "base64",
+			data: delta.data,
+			mimeType: delta.mimeType
+		}
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const appendVideo = (msg, delta) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (delta.kind === "base64" && last?.type === "video" && last.source.kind === "base64" && last.state !== "complete") parts[parts.length - 1] = {
+		...last,
+		source: {
+			kind: "base64",
+			data: `${last.source.data}${delta.data}`,
+			mimeType: delta.mimeType
+		}
+	};
+	else if (delta.kind === "url") parts.push({
+		type: "video",
+		source: {
+			kind: "url",
+			url: delta.url
+		}
+	});
+	else parts.push({
+		type: "video",
+		source: {
+			kind: "base64",
+			data: delta.data,
+			mimeType: delta.mimeType
+		}
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const appendEmbedding = (msg, delta) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (last?.type === "embedding" && last.state !== "complete") parts[parts.length - 1] = {
+		...last,
+		embedding: [...last.embedding, ...delta]
+	};
+	else parts.push({
+		type: "embedding",
+		embedding: delta
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const appendTranscriptText = (msg, delta) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (last?.type === "transcript" && last.state !== "complete") parts[parts.length - 1] = {
+		...last,
+		text: last.text + delta
+	};
+	else parts.push({
+		type: "transcript",
+		text: delta
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const appendReasoningText = (msg, delta, visibility, provider) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (last?.type === "reasoning" && last.state !== "complete" && last.visibility === visibility && (last.provider ?? void 0) === (provider ?? void 0)) parts[parts.length - 1] = {
+		...last,
+		text: last.text + delta
+	};
+	else parts.push({
+		type: "reasoning",
+		text: delta,
+		visibility,
+		...provider !== void 0 ? { provider } : {}
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const upsertTranscriptSegment = (msg, segment) => {
+	const parts = msg.parts.slice();
+	const last = parts[parts.length - 1];
+	if (last?.type === "transcript" && last.state !== "complete") {
+		const segments = last.segments ? [...last.segments] : [];
+		const idx = segments.findIndex((item) => item.id === segment.id);
+		if (idx === -1) segments.push(segment);
+		else segments[idx] = segment;
+		parts[parts.length - 1] = {
+			...last,
+			segments
+		};
+	} else parts.push({
+		type: "transcript",
+		text: "",
+		segments: [segment]
+	});
+	return {
+		...msg,
+		parts
+	};
+};
+const markLatestPartComplete = (msg, partType) => {
+	const parts = msg.parts.slice();
+	for (let i = parts.length - 1; i >= 0; i -= 1) {
+		const part = parts[i];
+		if (!part || part.type !== partType) continue;
+		parts[i] = {
+			...part,
+			state: "complete"
+		};
+		return {
+			...msg,
+			parts
+		};
+	}
+	return msg;
+};
+const isApprovalLifecycleState = (state) => state === "approval-requested" || state === "approval-approved" || state === "approval-denied" || state === "approval-expired";
+const getApprovalPartState = (state) => state === "requested" ? "approval-requested" : state === "approved" ? "approval-approved" : state === "denied" ? "approval-denied" : "approval-expired";
+const getApprovalStatus = (state) => state === "denied" || state === "expired" ? "error" : "pending";
+const updateToolApprovalMeta = (msg, toolCallId, patch) => upsertToolPart(msg, "tool-call", toolCallId, {}, (part) => part.type === "tool-call" ? {
+	...part,
+	approval: {
+		...part.approval ?? {},
+		...patch.input !== void 0 ? { input: patch.input } : {},
+		...patch.meta !== void 0 ? { meta: patch.meta } : {},
+		...patch.note !== void 0 ? { note: patch.note } : {},
+		...patch.actorId !== void 0 ? { actorId: patch.actorId } : {}
+	}
+} : part);
+const isToolCallCompleted = (msg, toolCallId) => msg.parts.some((part) => part.type === "tool-call" && part.callId === toolCallId && (part.status === "success" || part.state === "completed" || part.state === "approval-denied" || part.state === "approval-expired"));
+const findToolCallPart = (msg, toolCallId) => msg.parts.find((part) => part.type === "tool-call" && part.callId === toolCallId);
+const upsertToolPart = (msg, kind, toolCallId, patch, updater) => {
+	const parts = msg.parts.slice();
+	const idx = parts.findIndex((p) => p.type === kind && "callId" in p && p.callId === toolCallId);
+	if (idx === -1) {
+		if (kind === "tool-call") parts.push({
+			type: "tool-call",
+			callId: toolCallId,
+			status: "pending",
+			...patch
+		});
+		else parts.push({
+			type: "tool-result",
+			callId: toolCallId,
+			status: "pending",
+			...patch
+		});
+		return {
+			...msg,
+			parts
+		};
+	}
+	const existing = parts[idx];
+	if (!existing) return {
+		...msg,
+		parts
+	};
+	if (kind === "tool-call" && existing.type === "tool-call") {
+		const merged = {
+			...existing,
+			...patch,
+			type: "tool-call"
+		};
+		parts[idx] = updater ? updater(merged) : merged;
+	} else if (kind === "tool-result" && existing.type === "tool-result") {
+		const merged = {
+			...existing,
+			...patch,
+			type: "tool-result"
+		};
+		parts[idx] = updater ? updater(merged) : merged;
+	}
+	return {
+		...msg,
+		parts
+	};
+};
+const updateAssistantMessage = (state, messageId, updater) => ensureAndUpdateMessage(state, messageId, "assistant", updater);
+const updateResolvedToolMessage = (state, parentMessageId, toolCallId, updater) => {
+	const targetMessageLocalId = resolveToolMessageLocalId(state, parentMessageId, toolCallId);
+	if (!targetMessageLocalId) return state;
+	return ensureAndUpdateMessage(state, targetMessageLocalId, "assistant", updater);
+};
+
+//#endregion
+//#region src/core/response.ts
+/** Builds a deterministic local id for messages synthesized from model output. */
+const makeResponseLocalId = (prefix, index) => `${prefix}_${index.toString(36)}`;
+/** Converts one model output item into a UI message. */
+const createMessageFromOutputItem = (item, index) => {
+	if (item.type === "message") {
+		const parts = typeof item.content === "string" ? [{
+			type: "text",
+			text: item.content,
+			state: "complete"
+		}] : item.content.map((part) => contentPartToUIPart(part)).filter((part) => part !== null);
+		if (parts.length === 0) return null;
+		return {
+			localId: makeResponseLocalId("response_message", index),
+			role: item.role,
+			parts
+		};
+	}
+	if (item.type === "tool-call") return {
+		localId: makeResponseLocalId("response_tool_call", index),
+		role: "assistant",
+		parts: [{
+			type: "tool-call",
+			callId: item.callId,
+			name: item.name,
+			args: item.arguments,
+			status: "pending",
+			state: "input-complete"
+		}]
+	};
+	if (item.type !== "provider-tool-result") return null;
+	const status = item.isError ? "error" : "success";
+	return {
+		localId: makeResponseLocalId("response_tool_result", index),
+		role: "assistant",
+		parts: [{
+			type: "tool-call",
+			callId: item.callId,
+			name: item.name,
+			status,
+			state: "completed"
+		}, {
+			type: "tool-result",
+			callId: item.callId,
+			result: item.result,
+			status
+		}]
+	};
+};
+/** Attaches a provider tool result to the latest matching assistant message. */
+const attachToolResultToMatchingMessage = (messages, item) => {
+	let messageIndex = -1;
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index];
+		if (!message || message.role !== "assistant") continue;
+		if (message.parts.some((part) => part.type === "tool-call" && part.callId === item.callId)) {
+			messageIndex = index;
+			break;
+		}
+	}
+	if (messageIndex < 0) return false;
+	const message = messages[messageIndex];
+	if (!message || message.role !== "assistant") return false;
+	const nextMessages = messages.slice();
+	const status = item.isError ? "error" : "success";
+	nextMessages[messageIndex] = {
+		...message,
+		parts: message.parts.flatMap((part) => part.type === "tool-call" && part.callId === item.callId ? [{
+			...part,
+			status,
+			state: "completed"
+		}, {
+			type: "tool-result",
+			callId: item.callId,
+			result: item.result,
+			status
+		}] : [part])
+	};
+	messages.splice(0, messages.length, ...nextMessages);
+	return true;
+};
+/**
+* Converts model response output into UI messages.
+*/
+const getMessagesFromResponse = (response) => {
+	const messages = [];
+	for (const [index, item] of (response?.output ?? []).entries()) {
+		if (item.type === "provider-tool-result" && attachToolResultToMatchingMessage(messages, item)) continue;
+		const message = createMessageFromOutputItem(item, index);
+		if (message) messages.push(message);
+	}
+	return messages;
+};
+
+//#endregion
+//#region src/core/controller.ts
+/**
+* Framework-agnostic controller for one agent conversation.
+*/
+var AgentChatController = class {
+	id;
+	state;
+	status = "ready";
+	error = void 0;
+	lastStreamId;
+	lastRunId;
+	lastResponse;
+	lastStructured;
+	lastAppliedSeq = -1;
+	lastAppliedSeqByStream = /* @__PURE__ */ new Map();
+	initialMessages;
+	listeners = /* @__PURE__ */ new Set();
+	destroyed = false;
+	initialized = false;
+	warnedHistoryCombo = false;
+	options;
+	activeAbortController = null;
+	constructor(client, options) {
+		this.client = client;
+		this.options = options;
+		this.id = options.id ?? makeLocalMessageId();
+		const normalized = this.normalizeMessages(options.initialMessages ?? []);
+		this.state = createMessageState(normalized);
+		this.initialMessages = normalized;
+		this.lastStreamId = this.getConfiguredInitialStreamId(options);
+	}
+	/** Returns the current messages. */
+	getMessages() {
+		return this.state.messages;
+	}
+	/** Returns the current status. */
+	getStatus() {
+		return this.status;
+	}
+	/** Returns the latest client error. */
+	getError() {
+		return this.error;
+	}
+	/** Returns the latest stream id. */
+	getStreamId() {
+		return this.lastStreamId;
+	}
+	/** Returns the latest run id. */
+	getRunId() {
+		return this.lastRunId;
+	}
+	/** True while a request is active. */
+	get isLoading() {
+		return this.status === "hydrating" || this.status === "submitted" || this.status === "streaming";
+	}
+	/** True while stream events are being consumed. */
+	get isStreaming() {
+		return this.status === "streaming";
+	}
+	/** Returns pending tool approvals. */
+	getPendingToolApprovals() {
+		const seen = /* @__PURE__ */ new Set();
+		const pending = [];
+		for (const message of this.state.messages) for (const part of message.parts) if (part.type === "tool-call" && part.state === "approval-requested" && !seen.has(part.callId)) {
+			pending.push({
+				toolCallId: part.callId,
+				toolName: part.name,
+				args: part.args,
+				toolTarget: part.toolTarget,
+				input: part.approval?.input,
+				meta: part.approval?.meta,
+				note: part.approval?.note,
+				actorId: part.approval?.actorId
+			});
+			seen.add(part.callId);
+		}
+		return pending;
+	}
+	/** Returns an immutable snapshot. */
+	getSnapshot() {
+		return {
+			id: this.id,
+			conversationId: this.options.conversationId,
+			messages: this.state.messages,
+			status: this.status,
+			error: this.error,
+			streamId: this.lastStreamId,
+			runId: this.lastRunId,
+			isLoading: this.isLoading,
+			isStreaming: this.isStreaming,
+			pendingToolApprovals: this.getPendingToolApprovals()
+		};
+	}
+	/** Stops the active run or stream. */
+	stop() {
+		if (this.destroyed) return;
+		this.cancelActiveWork();
+		this.setStatus("ready");
+	}
+	/** Replaces the transport client. */
+	updateClient(client) {
+		this.client = client;
+	}
+	/**
+	* Subscribes to state updates.
+	*/
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/** Calls each subscribed listener after controller state changes. */
+	notify() {
+		if (this.destroyed) return;
+		for (const listener of this.listeners) listener();
+	}
+	/** Stores run and stream ids from response headers. */
+	updateResponseIds(response) {
+		const runId = response.headers.get("x-run-id");
+		if (runId && runId !== this.lastRunId) this.lastRunId = runId;
+		const streamId = response.headers.get("x-stream-id");
+		if (streamId && streamId !== this.lastStreamId) this.lastStreamId = streamId;
+	}
+	/** Starts hydration or resume behavior. */
+	init() {
+		if (this.initialized) return;
+		this.initialized = true;
+		ensureBrowserTeardownTracking();
+		if (this.options.hydrateFromServer && this.options.conversationId) {
+			this.hydrateFromServer();
+			return;
+		}
+		this.initResume();
+	}
+	/** Starts resume behavior, even with messages when allowed. */
+	initResume(options) {
+		const resume = this.options.resume;
+		if (!resume) return;
+		const hasMessages = this.state.messages.length > 0;
+		const explicitStreamId = typeof resume === "object" && resume !== null && typeof resume.streamId === "string" ? resume.streamId : void 0;
+		const explicitAfterSeq = typeof resume === "object" && resume !== null ? resume.afterSeq : void 0;
+		const streamAfterSeq = explicitAfterSeq ?? (explicitStreamId ? this.lastAppliedSeqByStream.get(explicitStreamId) : void 0);
+		if (hasMessages && explicitStreamId === void 0 && explicitAfterSeq === void 0 && !options?.allowWithMessages) return;
+		if (explicitStreamId) {
+			this.resumeStream({
+				streamId: explicitStreamId,
+				...streamAfterSeq !== void 0 ? { afterSeq: streamAfterSeq } : {}
+			});
+			return;
+		}
+		if (!this.options.conversationId) {
+			console.warn("[better-agent] `resume` requires `conversationId` unless an explicit `streamId` is provided.");
+			return;
+		}
+		if (explicitAfterSeq !== void 0) {
+			this.resumeConversation({ afterSeq: explicitAfterSeq });
+			return;
+		}
+		this.resumeConversation();
+	}
+	/** Hydrates from server history before resuming. */
+	async hydrateFromServer() {
+		const conversationId = this.options.conversationId;
+		if (!conversationId) {
+			this.initResume();
+			return;
+		}
+		const loadConversation = this.client.loadConversation;
+		if (typeof loadConversation !== "function") {
+			this.initResume();
+			return;
+		}
+		const { signal, controller } = this.startOperation();
+		this.setStatus("hydrating");
+		let hydrationCompleted = false;
+		this.setError(void 0);
+		try {
+			const result = await loadConversation.call(this.client, this.options.agent, conversationId, { signal });
+			this.throwIfAborted(signal);
+			if (result) {
+				const uiMessages = fromConversationItems(result.items);
+				this.initialMessages = uiMessages;
+				this.state = createMessageState(uiMessages);
+				this.notify();
+			}
+			this.setStatus("ready");
+			hydrationCompleted = true;
+		} catch (e) {
+			if (this.isAbortError(e, signal)) return;
+			const err = this.toError(e, "Hydration failed");
+			this.options.onError?.(err);
+			this.setStatus("ready");
+			hydrationCompleted = true;
+		} finally {
+			this.finishOperation(controller);
+			if (hydrationCompleted) this.initResume({ allowWithMessages: true });
+		}
+	}
+	/** Sends one message. */
+	async sendMessage(input, options) {
+		return this.submitWithInternalOptions(input, options?.signal ? { signal: options.signal } : void 0);
+	}
+	/** Retries a user message by local id. */
+	async retryMessage(localId) {
+		const message = this.getMessageByLocalId(localId);
+		if (!message) throw new Error(`Message '${localId}' was not found.`);
+		if (message.role !== "user") throw new Error("Only user messages can be retried.");
+		const idx = this.state.byLocalId.get(localId);
+		if (idx === void 0) throw new Error(`Message '${localId}' was not found.`);
+		const retryMessages = this.state.messages.slice(0, idx + 1).map((candidate) => candidate.localId === localId ? this.createPendingUserMessage(candidate) ?? candidate : candidate);
+		return this.submitWithInternalOptions({
+			input: toModelMessages(retryMessages),
+			sendClientHistory: true
+		}, {
+			replaceLocalId: localId,
+			replaceMessage: this.createPendingUserMessage(message),
+			serializedHistoryInput: true
+		});
+	}
+	/** Resumes an existing stream. */
+	async resumeStream(options) {
+		const { streamId } = options;
+		const { signal, controller } = this.startOperation();
+		this.setStatus("submitted");
+		this.setError(void 0);
+		try {
+			const events = this.client.resumeStream(this.options.agent, {
+				streamId,
+				afterSeq: options.afterSeq ?? this.lastAppliedSeqByStream.get(streamId) ?? -1
+			}, {
+				signal,
+				onResponse: (response) => {
+					this.updateResponseIds(response);
+				}
+			});
+			const result = await this.consumeStreamUntilTerminal(events, {
+				signal,
+				replay: true,
+				disconnectMessage: "Resume stream disconnected."
+			});
+			if (!result.receivedEvent) {
+				this.setStatus("ready");
+				return;
+			}
+			if (!result.terminalState) throw this.toStreamDisconnectError(void 0, "Stream ended before terminal run event.");
+			if (result.terminalState === "error") throw result.terminalError ?? /* @__PURE__ */ new Error("Resume failed.");
+			this.setStatus("ready");
+			if (result.receivedEvent && result.terminalState) this.emitFinish({
+				streamId,
+				isAbort: result.terminalState === "aborted"
+			});
+		} catch (e) {
+			if (this.destroyed || this.isAbortError(e, signal) || this.isStreamDisconnectError(e) && this.isPageTeardownLike()) {
+				this.setStatus("ready");
+				return;
+			}
+			const err = toAgentClientError(e, "Resume failed.");
+			this.setError(err);
+			this.setStatus("error");
+			if (this.isStreamDisconnectError(e)) this.options.onDisconnect?.({
+				error: err,
+				runId: this.lastRunId,
+				streamId
+			});
+			this.options.onError?.(err);
+		} finally {
+			this.finishOperation(controller);
+		}
+	}
+	/** Resumes the active stream for the current conversation. */
+	async resumeConversation(options) {
+		const conversationId = this.options.conversationId;
+		if (!conversationId) {
+			console.warn("[better-agent] `resumeConversation()` requires `conversationId`.");
+			return;
+		}
+		const { signal, controller } = this.startOperation();
+		this.setStatus("submitted");
+		this.setError(void 0);
+		try {
+			const events = this.client.resumeConversation(this.options.agent, {
+				conversationId,
+				...options?.afterSeq !== void 0 ? { afterSeq: options.afterSeq } : {}
+			}, {
+				signal,
+				onResponse: (response) => {
+					this.updateResponseIds(response);
+				}
+			});
+			const result = await this.consumeStreamUntilTerminal(events, {
+				signal,
+				replay: true,
+				disconnectMessage: "Resume stream disconnected."
+			});
+			if (!result.receivedEvent) {
+				this.setStatus("ready");
+				return;
+			}
+			if (!result.terminalState) throw this.toStreamDisconnectError(void 0, "Stream ended before terminal run event.");
+			if (result.terminalState === "error") throw result.terminalError ?? /* @__PURE__ */ new Error("Resume failed.");
+			this.setStatus("ready");
+			if (result.receivedEvent && result.terminalState) this.emitFinish({
+				conversationId,
+				isAbort: result.terminalState === "aborted"
+			});
+		} catch (e) {
+			if (this.destroyed || this.isAbortError(e, signal) || this.isStreamDisconnectError(e) && this.isPageTeardownLike()) {
+				this.setStatus("ready");
+				return;
+			}
+			const err = toAgentClientError(e, "Resume failed.");
+			this.setError(err);
+			this.setStatus("error");
+			if (this.isStreamDisconnectError(e)) this.options.onDisconnect?.({
+				error: err,
+				runId: this.lastRunId,
+				streamId: this.lastStreamId
+			});
+			this.options.onError?.(err);
+		} finally {
+			this.finishOperation(controller);
+		}
+	}
+	/** Submits a tool approval decision. */
+	async approveToolCall(params) {
+		const runId = params.runId ?? this.lastRunId;
+		if (!runId) throw new Error("Cannot submit tool approval response without a runId.");
+		await this.client.submitToolApproval({
+			agent: this.options.agent,
+			runId,
+			toolCallId: params.toolCallId,
+			decision: params.decision,
+			...params.note !== void 0 ? { note: params.note } : {},
+			...params.actorId !== void 0 ? { actorId: params.actorId } : {}
+		});
+	}
+	/** Clears the current error. */
+	clearError() {
+		this.setError(void 0);
+		this.setStatus("ready");
+	}
+	/** Resets local state to the initial snapshot. */
+	reset() {
+		this.cancelActiveWork();
+		this.state = createMessageState(this.initialMessages);
+		this.lastResponse = void 0;
+		this.lastStructured = void 0;
+		this.lastRunId = void 0;
+		this.lastStreamId = this.getConfiguredInitialStreamId(this.options);
+		this.error = void 0;
+		this.status = "ready";
+		this.lastAppliedSeq = -1;
+		this.lastAppliedSeqByStream.clear();
+		this.notify();
+	}
+	/** Replaces local messages. */
+	setMessages(value) {
+		const current = this.state.messages;
+		const nextRaw = typeof value === "function" ? value(current) : value;
+		this.state = createMessageState(this.normalizeMessages(nextRaw));
+		this.notify();
+	}
+	/** Merges new options into the controller configuration. */
+	updateOptions(partial) {
+		const nextOptions = {
+			...this.options,
+			...partial,
+			...partial.resume !== void 0 && typeof partial.resume === "object" && partial.resume !== null ? { resume: {
+				...typeof this.options.resume === "object" && this.options.resume !== null ? this.options.resume : {},
+				...partial.resume
+			} } : {},
+			...partial.optimisticUserMessage && typeof partial.optimisticUserMessage === "object" && !Array.isArray(partial.optimisticUserMessage) ? { optimisticUserMessage: {
+				...typeof this.options.optimisticUserMessage === "object" && this.options.optimisticUserMessage !== null && !Array.isArray(this.options.optimisticUserMessage) ? this.options.optimisticUserMessage : {},
+				...partial.optimisticUserMessage
+			} } : {}
+		};
+		const shouldResetSession = this.hasSessionConfigurationChanged(this.options, nextOptions);
+		this.options = nextOptions;
+		if (shouldResetSession) this.resetForSessionChange();
+	}
+	/** Destroys the controller. */
+	destroy() {
+		this.cancelActiveWork();
+		this.destroyed = true;
+		this.listeners.clear();
+	}
+	/** Applies one streamed event to local state. */
+	applyEvent(ev, options) {
+		this.options.onEvent?.(ev);
+		const streamKey = typeof ev.streamId === "string" && ev.streamId.length > 0 ? ev.streamId : typeof ev.runId === "string" && ev.runId.length > 0 ? ev.runId : void 0;
+		if (typeof ev.seq === "number") if (streamKey) {
+			const prev = this.lastAppliedSeqByStream.get(streamKey) ?? -1;
+			if (ev.seq <= prev) return;
+			this.lastAppliedSeqByStream.set(streamKey, ev.seq);
+		} else {
+			if (ev.seq <= this.lastAppliedSeq) return;
+			this.lastAppliedSeq = ev.seq;
+		}
+		if (typeof ev.runId === "string" && ev.runId.length > 0 && ev.runId !== this.lastRunId) this.lastRunId = ev.runId;
+		if (ev.type === "RUN_FINISHED") {
+			const result = ev.result;
+			this.lastResponse = result?.response;
+			this.lastStructured = result?.structured;
+		}
+		if (ev.type === "DATA_PART") {
+			const payload = {
+				data: ev.data,
+				...ev.id ? { id: ev.id } : {}
+			};
+			this.options.onData?.(payload);
+		}
+		if (ev.streamId && ev.streamId !== this.lastStreamId) this.lastStreamId = ev.streamId;
+		if (options?.replay && ev.type === "RUN_STARTED") this.reconcileReplayUserMessage(ev.runInput, ev.runId);
+		this.state = applyEvent(this.state, ev, { synthesizeReplayUserMessage: Boolean(options?.replay) });
+		this.notify();
+	}
+	/** Reads streamed events until the stream finishes or a terminal event appears. */
+	async consumeStreamUntilTerminal(events, options) {
+		const result = { receivedEvent: false };
+		try {
+			for await (const event of events) {
+				this.throwIfAborted(options.signal);
+				result.receivedEvent = true;
+				if (this.status !== "streaming") this.setStatus("streaming");
+				const terminal = this.getTerminalStateFromEvent(event);
+				if (terminal) {
+					result.terminalState = terminal.state;
+					result.terminalError = terminal.error;
+				}
+				this.applyEvent(event, { replay: options.replay });
+			}
+		} catch (error) {
+			if (this.isAbortError(error, options.signal)) throw error;
+			throw this.toStreamDisconnectError(error, options.disconnectMessage);
+		}
+		this.throwIfAborted(options.signal);
+		return result;
+	}
+	/** Reads terminal state from one streamed event. */
+	getTerminalStateFromEvent(event) {
+		if (event.type === "RUN_FINISHED") return { state: "finished" };
+		if (event.type === "RUN_ABORTED") return { state: "aborted" };
+		if (event.type === "RUN_ERROR") return {
+			state: "error",
+			error: toAgentClientError(event.error, getEventErrorMessage(event.error))
+		};
+	}
+	/** Sends one request through final or stream delivery. */
+	async submitWithInternalOptions(runInput, internalOptions) {
+		const { signal, controller } = this.startOperation(internalOptions?.signal);
+		this.setStatus("submitted");
+		this.setError(void 0);
+		const context = this.createSubmissionContext(runInput, internalOptions, signal);
+		try {
+			this.warnIfClientHistoryReplacesConversation(context);
+			this.applyLocalSubmissionState(context);
+			const requestInput = this.buildRequestInput(context);
+			if (context.useFinalDelivery) return await this.runFinalDelivery(context, requestInput);
+			return await this.runStreamDelivery(context, requestInput);
+		} catch (e) {
+			return this.handleSubmissionFailure(e, context);
+		} finally {
+			this.finishOperation(controller);
+		}
+	}
+	/** Builds the mutable context for one submission. */
+	createSubmissionContext(runInput, internalOptions, signal) {
+		return {
+			signal,
+			conversationId: typeof runInput.conversationId === "string" ? runInput.conversationId : this.options.conversationId,
+			inputValue: runInput.input,
+			sendClientHistory: typeof runInput.sendClientHistory === "boolean" ? runInput.sendClientHistory : Boolean(this.options.sendClientHistory),
+			optimisticLocalId: internalOptions?.reuseOptimisticLocalId,
+			optimisticMessageMarkedSent: false,
+			optimisticConfig: normalizeOptimisticUserMessageConfig(this.options.optimisticUserMessage),
+			preSubmitState: this.state,
+			useFinalDelivery: Boolean(internalOptions?.forceRun) || !this.shouldUseStreamDelivery(),
+			runInput,
+			internalOptions
+		};
+	}
+	/** Warns when client history will replace stored server history. */
+	warnIfClientHistoryReplacesConversation(context) {
+		if (!context.sendClientHistory || !context.conversationId || context.internalOptions?.replaceLocalId || this.warnedHistoryCombo) return;
+		this.warnedHistoryCombo = true;
+		console.warn("[better-agent] Using sendClientHistory with conversationId. Client history will replace server-stored history on each request. For server-managed history, remove sendClientHistory.");
+	}
+	/** Applies retry replacement or optimistic user insertion. */
+	applyLocalSubmissionState(context) {
+		const replaceLocalId = context.internalOptions?.replaceLocalId;
+		if (replaceLocalId) {
+			this.replaceRetryMessage(replaceLocalId, context.internalOptions?.replaceMessage ?? context.inputValue);
+			context.optimisticLocalId = replaceLocalId;
+			return;
+		}
+		if (context.optimisticLocalId || !context.optimisticConfig.enabled) return;
+		if (!(!context.sendClientHistory && this.canOptimisticallyRenderUserTurn(context.inputValue) || context.sendClientHistory && this.canOmitSubmittedInputFromSerializedHistory(context.inputValue))) return;
+		const optimisticMessage = this.createPendingUserMessage(context.inputValue);
+		if (!optimisticMessage) return;
+		const optimisticLocalId = this.generateMessageId();
+		context.optimisticLocalId = optimisticLocalId;
+		this.state = createMessageState([...this.state.messages, {
+			...optimisticMessage,
+			localId: optimisticLocalId
+		}]);
+		this.notify();
+	}
+	/** Builds the request input for the next transport call. */
+	buildRequestInput(context) {
+		return this.prepareInputForRequest(context.inputValue, this.state.messages, {
+			sendClientHistory: context.sendClientHistory,
+			optimisticLocalId: context.optimisticLocalId,
+			serializedHistoryInput: Boolean(context.internalOptions?.serializedHistoryInput)
+		});
+	}
+	/** Runs one request through final delivery. */
+	async runFinalDelivery(context, requestInput) {
+		const result = await this.client.run(this.options.agent, this.createRunPayload(context.runInput, requestInput.inputToSend, requestInput.serializedClientHistory), {
+			onResponse: this.options.onResponse,
+			signal: context.signal
+		});
+		const normalized = this.normalizeFinalRunResult(result);
+		this.captureNormalizedRunResult(normalized);
+		this.markOptimisticMessageSent(context);
+		this.setStatus("ready");
+		this.emitFinish({
+			isAbort: false,
+			conversationId: context.conversationId
+		});
+		return {
+			runId: normalized.runId,
+			streamId: this.lastStreamId
+		};
+	}
+	/** Runs one request through streamed delivery. */
+	async runStreamDelivery(context, requestInput) {
+		const requestOptions = this.buildStreamRequestOptions(context.optimisticLocalId, () => {
+			context.optimisticMessageMarkedSent = true;
+		}, context.signal);
+		const stream = this.client.stream(this.options.agent, this.createRunPayload(context.runInput, requestInput.inputToSend, requestInput.serializedClientHistory), requestOptions);
+		const result = await this.consumeStreamUntilTerminal(stream, {
+			signal: context.signal,
+			disconnectMessage: "Stream disconnected."
+		});
+		if (!result.terminalState) throw this.toStreamDisconnectError(void 0, "Stream ended before terminal run event.");
+		if (result.terminalState === "error") throw result.terminalError ?? /* @__PURE__ */ new Error("Run failed.");
+		this.setStatus("ready");
+		this.emitFinish({
+			isAbort: result.terminalState === "aborted",
+			conversationId: context.conversationId
+		});
+		return { streamId: this.lastStreamId };
+	}
+	/** Handles aborts, fallback-to-run, and terminal submission errors. */
+	async handleSubmissionFailure(error, context) {
+		if (this.destroyed || this.isAbortError(error, context.signal) || this.isStreamDisconnectError(error) && this.isPageTeardownLike()) {
+			if (this.state !== context.preSubmitState && !context.optimisticMessageMarkedSent) {
+				this.state = context.preSubmitState;
+				this.notify();
+			}
+			if (!this.destroyed) this.setStatus("ready");
+			return { streamId: this.lastStreamId };
+		}
+		let err = toAgentClientError(error, "Run failed.");
+		if (!context.internalOptions?.forceRun && this.shouldFallbackToRun(err)) try {
+			return await this.submitWithInternalOptions(context.runInput, {
+				...context.internalOptions,
+				forceRun: true,
+				reuseOptimisticLocalId: context.optimisticLocalId
+			});
+		} catch (fallbackError) {
+			err = toAgentClientError(fallbackError, "Run failed.");
+		}
+		this.applyOptimisticFailure(context, err);
+		this.setError(err);
+		this.setStatus("error");
+		if (this.isStreamDisconnectError(error)) this.options.onDisconnect?.({
+			error: err,
+			...this.lastRunId ? { runId: this.lastRunId } : {},
+			...this.lastStreamId ? { streamId: this.lastStreamId } : {}
+		});
+		this.options.onError?.(err);
+		return this.lastStreamId ? { streamId: this.lastStreamId } : {};
+	}
+	/** Marks the optimistic user message as sent after a successful request. */
+	markOptimisticMessageSent(context) {
+		if (!context.optimisticLocalId || context.optimisticMessageMarkedSent) return;
+		this.updateMessageByLocalId(context.optimisticLocalId, (msg) => {
+			const { error: _error, ...rest } = msg;
+			return {
+				...rest,
+				status: "sent"
+			};
+		});
+		context.optimisticMessageMarkedSent = true;
+	}
+	/** Applies optimistic-message failure handling. */
+	applyOptimisticFailure(context, err) {
+		if (!context.optimisticLocalId) return;
+		if (context.optimisticConfig.onError === "remove") {
+			this.removeMessageByLocalId(context.optimisticLocalId);
+			return;
+		}
+		const failed = this.updateMessageByLocalId(context.optimisticLocalId, (msg) => ({
+			...msg,
+			status: "failed",
+			error: err.message
+		}));
+		if (failed) this.options.onOptimisticUserMessageError?.({
+			message: failed,
+			error: err
+		});
+	}
+	/** Stores the latest run result from final delivery. */
+	captureNormalizedRunResult(result) {
+		if (result.runId) this.lastRunId = result.runId;
+		if (result.response) {
+			this.lastResponse = result.response;
+			this.appendResponseMessages(result.response);
+		}
+		this.lastStructured = result.structured;
+	}
+	setStatus(status) {
+		if (this.status === status) return;
+		this.status = status;
+		this.notify();
+	}
+	/** Stores the latest controller error without notifying listeners. */
+	setError(error) {
+		this.error = error;
+	}
+	/** Normalizes unknown failures into an `Error` with a fallback message. */
+	toError(error, fallback) {
+		return error instanceof Error ? error : new Error(fallback);
+	}
+	/** Starts one controller operation. */
+	startOperation(externalSignal) {
+		this.throwIfDestroyed();
+		this.cancelActiveWork();
+		const controller = new AbortController();
+		this.activeAbortController = controller;
+		return {
+			controller,
+			signal: this.mergeSignals(controller.signal, externalSignal)
+		};
+	}
+	/** Clears the tracked active operation if it matches the provided controller. */
+	finishOperation(controller) {
+		if (this.activeAbortController === controller) this.activeAbortController = null;
+	}
+	/** Aborts and forgets any in-flight controller operation. */
+	cancelActiveWork() {
+		this.activeAbortController?.abort();
+		this.activeAbortController = null;
+	}
+	/** Merges the controller abort signal with an optional external signal. */
+	mergeSignals(primary, externalSignal) {
+		if (!externalSignal) return primary;
+		const controller = new AbortController();
+		const abortFrom = (source) => {
+			if (!controller.signal.aborted) controller.abort(source.reason);
+		};
+		if (primary.aborted) abortFrom(primary);
+		else primary.addEventListener("abort", () => abortFrom(primary), { once: true });
+		if (externalSignal.aborted) abortFrom(externalSignal);
+		else externalSignal.addEventListener("abort", () => abortFrom(externalSignal), { once: true });
+		return controller.signal;
+	}
+	/** Throws an abort-shaped error when the given signal has already aborted. */
+	throwIfAborted(signal) {
+		if (signal.aborted) throw this.toAbortError(signal.reason);
+	}
+	/** Rejects work after the controller has been destroyed. */
+	throwIfDestroyed() {
+		if (this.destroyed) throw new Error("AgentChatController has been destroyed.");
+	}
+	/** Returns `true` when a failure should be treated as an abort. */
+	isAbortError(error, signal) {
+		return (signal?.aborted ?? false) || error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
+	}
+	/** Returns true when a failure came from stream disconnection. */
+	isStreamDisconnectError(error) {
+		return error instanceof StreamDisconnectError;
+	}
+	/** Returns true when the page is being torn down during navigation or refresh. */
+	isPageTeardownLike() {
+		return isBrowserPageTearingDown() || typeof document !== "undefined" && document.visibilityState === "hidden";
+	}
+	/** Converts an abort reason into a standard `AbortError` instance. */
+	toAbortError(reason) {
+		if (reason instanceof Error) return reason;
+		try {
+			return new DOMException(typeof reason === "string" ? reason : "The operation was aborted.", "AbortError");
+		} catch {
+			const error = new Error(typeof reason === "string" ? reason : "The operation was aborted.");
+			error.name = "AbortError";
+			return error;
+		}
+	}
+	/** Wraps one failure as a stream disconnect. */
+	toStreamDisconnectError(error, fallback = "Stream disconnected.") {
+		return new StreamDisconnectError(this.toError(error, fallback).message, error);
+	}
+	/** Binds an already-visible current user turn to the replay run identity. */
+	reconcileReplayUserMessage(runInput, runId) {
+		const latestMessage = this.state.messages.at(-1);
+		if (!latestMessage || latestMessage.role !== "user") return;
+		const replayMessage = this.toReplayUserMessage(runInput, runId);
+		if (!replayMessage || this.state.byLocalId.has(replayMessage.localId)) return;
+		if (!this.isSameUserTurn(latestMessage, replayMessage)) return;
+		const nextMessages = this.state.messages.slice();
+		nextMessages[nextMessages.length - 1] = {
+			...latestMessage,
+			localId: replayMessage.localId,
+			...replayMessage.id !== void 0 ? { id: replayMessage.id } : {},
+			status: "sent"
+		};
+		this.state = createMessageState(nextMessages);
+	}
+	/** Reconstructs the replayed current user turn from one RUN_STARTED event. */
+	toReplayUserMessage(runInput, runId) {
+		const input = runInput.input;
+		if (typeof input === "string") return {
+			localId: `user_run:${runId}`,
+			id: `user_run:${runId}`,
+			role: "user",
+			parts: [{
+				type: "text",
+				text: input,
+				state: "complete"
+			}],
+			status: "sent"
+		};
+		const replayInput = Array.isArray(input) ? input : this.isSingleReplayMessageInput(input) ? [input] : void 0;
+		if (!replayInput) return;
+		let index = 0;
+		const latestUserMessage = [...fromModelMessages(replayInput, { generateId: () => `user_run:${runId}:${(index++).toString(36)}` })].reverse().find((message) => message.role === "user");
+		return latestUserMessage ? {
+			...latestUserMessage,
+			status: "sent"
+		} : void 0;
+	}
+	/** Detects one structured replay message item. */
+	isSingleReplayMessageInput(input) {
+		return typeof input === "object" && input !== null && input.type === "message" && (typeof input.content === "string" || Array.isArray(input.content));
+	}
+	/** Matches one already-visible user turn to its replayed equivalent. */
+	isSameUserTurn(current, replayed) {
+		return JSON.stringify(current.parts) === JSON.stringify(replayed.parts);
+	}
+	/** Generates a local message id using the configured factory when present. */
+	generateMessageId(message) {
+		return this.options.generateMessageId?.(message) ?? makeLocalMessageId();
+	}
+	/** Ensures every incoming UI message has a stable local id. */
+	normalizeMessages(list) {
+		return list.map((message) => ({
+			...message,
+			localId: message.localId ?? this.generateMessageId(message)
+		}));
+	}
+	/** Detects option changes that require resetting conversation session state. */
+	hasSessionConfigurationChanged(prev, next) {
+		return prev.agent !== next.agent || prev.conversationId !== next.conversationId || prev.hydrateFromServer !== next.hydrateFromServer || Boolean(prev.resume) !== Boolean(next.resume) || (typeof prev.resume === "object" ? prev.resume.streamId : void 0) !== (typeof next.resume === "object" ? next.resume.streamId : void 0) || (typeof prev.resume === "object" ? prev.resume.afterSeq : void 0) !== (typeof next.resume === "object" ? next.resume.afterSeq : void 0);
+	}
+	/** Resets controller state after a session-defining option changes. */
+	resetForSessionChange() {
+		this.cancelActiveWork();
+		const normalized = this.normalizeMessages(this.options.initialMessages ?? []);
+		this.state = createMessageState(normalized);
+		this.initialMessages = normalized;
+		this.lastResponse = void 0;
+		this.lastStructured = void 0;
+		this.lastRunId = void 0;
+		this.lastStreamId = this.getConfiguredInitialStreamId(this.options);
+		this.error = void 0;
+		this.status = "ready";
+		this.lastAppliedSeq = -1;
+		this.lastAppliedSeqByStream.clear();
+		this.warnedHistoryCombo = false;
+		this.initialized = false;
+		this.notify();
+		this.init();
+	}
+	/** Reads the initial resume stream id from controller options. */
+	getConfiguredInitialStreamId(options) {
+		return typeof options.resume === "object" && options.resume !== null ? options.resume.streamId : void 0;
+	}
+	/** Returns one message by local id from the current message state. */
+	getMessageByLocalId(localId) {
+		const idx = this.state.byLocalId.get(localId);
+		return idx === void 0 ? void 0 : this.state.messages[idx];
+	}
+	/** Updates one message by local id and notifies listeners when found. */
+	updateMessageByLocalId(localId, updater) {
+		const idx = this.state.byLocalId.get(localId);
+		if (idx === void 0) return void 0;
+		const current = this.state.messages[idx];
+		if (!current) return void 0;
+		const next = this.state.messages.slice();
+		next[idx] = updater(current);
+		this.state = createMessageState(next);
+		this.notify();
+		return next[idx];
+	}
+	/** Removes one local message from state and notifies listeners. */
+	removeMessageByLocalId(localId) {
+		if (this.state.byLocalId.get(localId) === void 0) return;
+		this.state = createMessageState(this.state.messages.filter((msg) => msg.localId !== localId));
+		this.notify();
+	}
+	/** Resolves the effective delivery mode for the next submission. */
+	shouldUseStreamDelivery() {
+		if (this.options.delivery === "stream") return true;
+		if (this.options.delivery === "final") return false;
+		return true;
+	}
+	/** Detects stream capability errors that should retry through `run()`. */
+	shouldFallbackToRun(error) {
+		if (this.options.delivery !== "auto") return false;
+		const message = error.message.toLowerCase();
+		return message.includes("does not support streaming generation") || message.includes("streaming generation is not supported") || message.includes("streaming is not supported");
+	}
+	/** Appends model response messages to local state after final delivery. */
+	appendResponseMessages(response) {
+		const responseMessages = getMessagesFromResponse(response).map((msg, i) => ({
+			...msg,
+			localId: this.generateMessageId(msg),
+			...msg.id ? {} : { id: `response_${i.toString(36)}` }
+		}));
+		if (responseMessages.length === 0) return;
+		this.state = createMessageState([...this.state.messages, ...responseMessages]);
+		this.notify();
+	}
+	/** Normalizes supported final-run response shapes into one controller shape. */
+	normalizeFinalRunResult(payload) {
+		if (typeof payload !== "object" || payload === null) return {};
+		const record = payload;
+		const next = {};
+		if (typeof record.runId === "string") next.runId = record.runId;
+		const maybeResponse = (typeof record.result === "object" && record.result !== null && typeof record.result.response === "object" && record.result.response !== null ? record.result.response : void 0) ?? (typeof record.response === "object" && record.response !== null ? record.response : "output" in record && Array.isArray(record.output) ? record : void 0);
+		if (maybeResponse) next.response = maybeResponse;
+		if ("structured" in record) next.structured = record.structured;
+		return next;
+	}
+	/** Builds the input payload, optionally serializing client history into it. */
+	prepareInputForRequest(inputValue, baseMessages, options) {
+		if (!options.sendClientHistory) return {
+			inputToSend: inputValue,
+			serializedClientHistory: false
+		};
+		if (options.serializedHistoryInput) return {
+			inputToSend: inputValue,
+			serializedClientHistory: true
+		};
+		const preparedMessages = this.options.prepareMessages?.({
+			messages: baseMessages,
+			input: inputValue
+		});
+		if (preparedMessages) return {
+			inputToSend: preparedMessages,
+			serializedClientHistory: true
+		};
+		const serializedMessages = toModelMessages(baseMessages);
+		const inputItems = this.normalizeInputItems(inputValue);
+		if (typeof inputValue === "string") return {
+			inputToSend: options.optimisticLocalId ? serializedMessages : [...serializedMessages, {
+				type: "message",
+				role: "user",
+				content: inputValue
+			}],
+			serializedClientHistory: true
+		};
+		if (inputItems) return {
+			inputToSend: options.optimisticLocalId && this.canOmitSubmittedInputFromSerializedHistory(inputValue) ? serializedMessages : [...serializedMessages, ...inputItems],
+			serializedClientHistory: true
+		};
+		return {
+			inputToSend: inputValue,
+			serializedClientHistory: false
+		};
+	}
+	/** Builds the run payload for one request. */
+	createRunPayload(runInput, inputToSend, serializedClientHistory) {
+		const conversationId = typeof runInput.conversationId === "string" ? runInput.conversationId : this.options.conversationId;
+		const modelOptions = mergeModelOptions(this.options.modelOptions, runInput.modelOptions);
+		const { modelOptions: _modelOptions, ...restRunInput } = runInput;
+		return {
+			...restRunInput,
+			input: inputToSend,
+			modelOptions: Object.keys(modelOptions).length > 0 ? modelOptions : void 0,
+			conversationId,
+			context: runInput.context !== void 0 || this.options.context !== void 0 ? runInput.context ?? this.options.context : void 0,
+			replaceHistory: serializedClientHistory && Boolean(conversationId) ? true : void 0
+		};
+	}
+	/** Builds stream request hooks for ids, callbacks, and optimistic updates. */
+	buildStreamRequestOptions(optimisticLocalId, onMarkedSent, signal) {
+		if (!(this.options.onResponse || this.options.onToolCall || this.options.toolHandlers) && !optimisticLocalId && !signal) return void 0;
+		return {
+			signal,
+			onResponse: (response) => {
+				this.updateResponseIds(response);
+				this.options.onResponse?.(response);
+				if (response.ok && optimisticLocalId) {
+					this.updateMessageByLocalId(optimisticLocalId, (msg) => {
+						const { error: _error, ...rest } = msg;
+						return {
+							...rest,
+							status: "sent"
+						};
+					});
+					onMarkedSent();
+				}
+			},
+			onToolCall: this.options.onToolCall,
+			toolHandlers: this.options.toolHandlers
+		};
+	}
+	/** Replaces one user message slot with a pending retry version. */
+	replaceRetryMessage(replaceLocalId, inputValue) {
+		const current = this.state.messages;
+		const idx = this.state.byLocalId.get(replaceLocalId);
+		const nextMessage = this.createPendingUserMessage(inputValue) ?? {
+			localId: replaceLocalId,
+			role: "user",
+			parts: [{
+				type: "text",
+				text: String(inputValue ?? "")
+			}],
+			status: "pending"
+		};
+		let nextMessages = current;
+		if (idx === void 0) nextMessages = [...current, nextMessage];
+		else {
+			const copy = current.slice(0, idx);
+			copy.push(nextMessage);
+			nextMessages = copy;
+		}
+		if (nextMessages !== current) {
+			this.state = createMessageState(nextMessages);
+			this.notify();
+		}
+	}
+	/** Derives a pending user message from retry input when possible. */
+	createPendingUserMessage(inputValue) {
+		if (typeof inputValue === "string") return {
+			localId: this.generateMessageId(),
+			role: "user",
+			parts: [{
+				type: "text",
+				text: inputValue
+			}],
+			status: "pending"
+		};
+		if (typeof inputValue === "object" && inputValue !== null && "localId" in inputValue) {
+			const message = inputValue;
+			if (message.role === "user" && Array.isArray(message.parts)) {
+				const { error: _error, ...rest } = message;
+				return {
+					...rest,
+					status: "pending"
+				};
+			}
+		}
+		const items = this.normalizeInputItems(inputValue);
+		if (!items) return;
+		const latestUser = [...fromModelMessages(items)].reverse().find((message) => message.role === "user");
+		if (!latestUser) return;
+		const { error: _error, ...rest } = latestUser;
+		return {
+			...rest,
+			status: "pending"
+		};
+	}
+	/** Normalizes supported input shapes into input items when possible. */
+	normalizeInputItems(inputValue) {
+		if (Array.isArray(inputValue)) return inputValue;
+		if (typeof inputValue === "object" && inputValue !== null && typeof inputValue.type === "string") return [inputValue];
+	}
+	/** Returns true when input is safely representable as one optimistic user turn. */
+	canOptimisticallyRenderUserTurn(inputValue) {
+		if (typeof inputValue === "string") return true;
+		if (typeof inputValue === "object" && inputValue !== null && "localId" in inputValue) {
+			const message = inputValue;
+			return message.role === "user" && Array.isArray(message.parts);
+		}
+		const items = this.normalizeInputItems(inputValue);
+		if (!items || items.length !== 1) return false;
+		const [item] = items;
+		return item?.type === "message" && (item.role === void 0 || item.role === "user");
+	}
+	/** Returns true when serialized history can reuse the optimistic user turn. */
+	canOmitSubmittedInputFromSerializedHistory(inputValue) {
+		if (typeof inputValue === "string") return true;
+		if (typeof inputValue === "object" && inputValue !== null && "localId" in inputValue) {
+			const message = inputValue;
+			return message.role === "user" && Array.isArray(message.parts);
+		}
+		const items = this.normalizeInputItems(inputValue);
+		if (!items || items.length !== 1) return false;
+		const [item] = items;
+		return item?.type === "message" && item.role === "user";
+	}
+	/** Calls `onFinish` with the latest completion data. */
+	emitFinish(overrides) {
+		const response = this.lastResponse;
+		const params = {
+			messages: this.state.messages,
+			isAbort: overrides.isAbort
+		};
+		if (this.lastRunId) params.runId = this.lastRunId;
+		const streamIdToUse = overrides.streamId ?? this.lastStreamId;
+		if (streamIdToUse) params.streamId = streamIdToUse;
+		const conversationId = overrides.conversationId ?? this.options.conversationId;
+		if (conversationId) params.conversationId = conversationId;
+		if (response) {
+			params.response = response;
+			params.finishReason = response.finishReason;
+			params.usage = response.usage;
+		}
+		if (this.lastStructured !== void 0) params.structured = this.lastStructured;
+		this.options.onFinish?.(params);
+	}
+};
+/**
+* Creates an `AgentChatController`.
+*/
+function createAgentChatController(client, options) {
+	return new AgentChatController(client, options);
+}
+
+//#endregion
+export { toModelMessages as a, fromModelMessages as i, createAgentChatController as n, getEventErrorMessage as o, fromConversationItems as r, toAgentClientError as s, AgentChatController as t };
+//# sourceMappingURL=controller-Cf_JhTdJ.mjs.map