@antelopejs/dms-ai 0.1.6 → 0.2.0

package/frontend-vue/app/chat/composables/useConversation.ts

@@ -1,43 +1,36 @@
 import { type Ref, ref } from "vue";
-import {
-	MESSAGE_ROLES,
-	NOT_SENT_MESSAGE,
-	RETRY_NEEDS_FILES_MESSAGE,
-	STOP_NOT_DELIVERED_MESSAGE,
-	STORED_ERROR_ROLE,
-	STORED_TOOL_RESULT_ROLE,
-	STORED_TOOL_USE_ROLE,
-	TOOL_CUT_SHORT_RESULT,
-	TOOL_STATUS,
-} from "../constants/conversation";
-import {
-	CLIENT_MESSAGE_TYPES,
-	SERVER_EVENT_TYPES,
-} from "../constants/protocol";
+import { LOCAL_ERROR_KEYS, MESSAGE_ROLES } from "../constants/conversation";
+import { CLIENT_MESSAGE_TYPES } from "../constants/protocol";
 import type {
-	AssistantMessage,
 	ConversationMessage,
-	ErrorMessage,
 	MessageAttachment,
 	QueuedMessage,
 	RunProgress,
-	ToolCallMessage,
-	ToolStatus,
 	UserMessage,
 } from "../types/conversation";
-import type { PermissionRequestData } from "../types/permission";
-import type { QuestionData, QuestionRequestData } from "../types/question";
-import { type PendingAttachment, splitDataUrl } from "../utils/attachments";
+import type {
+	ChangeSetSummary,
+	ConversationModeState,
+	QuestionAnswerRecord,
+	WireAttachment,
+} from "../types/protocol";
+import type { PendingAttachment } from "../utils/attachments";
+import { splitDataUrl } from "../utils/attachments";
+import {
+	buildLocalError,
+	buildUserMessage,
+	settleOpenTools,
+} from "../utils/conversation-messages";
 import { newUuid } from "../utils/ids";
-import { toActivityKind } from "../utils/run-status";
+import { dispatchConversationEvent } from "./conversation-events";
 
 export interface UseConversationOptions {
 	activeId: Ref<string>;
 	/** Returns false when the message could not leave the chat. */
 	send: (msg: object) => boolean;
 	onMessage: (handler: (msg: unknown) => void) => () => void;
-	onPermissionRequest?: (req: PermissionRequestData) => void;
-	onQuestionRequest?: (req: QuestionRequestData) => void;
+	/** The page the dashboard shows, stamped on the messages sent from it. */
+	getPagePath?: () => string | undefined;
 }
 
 export interface UseConversationResult {
@@ -50,432 +43,29 @@ export interface UseConversationResult {
 	isTurnInFlight: Ref<boolean>;
 	/** Local time of the last event the sidecar sent about this conversation. */
 	lastEventAtMs: Ref<number>;
-	sendUserMessage: (content: string, attachments?: PendingAttachment[]) => void;
-	/** Sends the last user message again, with its files when still at hand. */
+	/** The change sets of this conversation, by id. */
+	changeSets: Ref<Record<string, ChangeSetSummary>>;
+	/** The chat's own approval mode and scope; null until the sidecar says. */
+	mode: Ref<ConversationModeState | null>;
+	/** Tokens this chat has used so far; null until the sidecar says. */
+	totalTokens: Ref<number | null>;
+	sendUserMessage: (
+		content: string,
+		attachments?: PendingAttachment[],
+		extra?: Record<string, unknown>,
+	) => void;
+	/**
+	 * Runs the last turn again: the sidecar re-runs a stored message, the chat
+	 * resends one that never left.
+	 */
 	retry: () => void;
-	cancelQueued: (id: string) => void;
 	interrupt: () => void;
+	recordAnswers: (answers: QuestionAnswerRecord[]) => void;
 	reset: () => void;
 }
 
-interface SnapshotMessage {
-	role: string;
-	content: string;
-	toolName?: string;
-	callId?: string;
-	status?: string;
-	attachments?: MessageAttachment[];
-	isRetryable?: boolean;
-	timestampMs: number;
-}
-
-interface ChunkEvent {
-	type: typeof SERVER_EVENT_TYPES.ASSISTANT_MESSAGE_CHUNK;
-	conversationId: string;
-	text: string;
-}
-
-interface ToolStartEvent {
-	type: typeof SERVER_EVENT_TYPES.TOOL_CALL_START;
-	conversationId: string;
-	callId: string;
-	toolName: string;
-	args: unknown;
-}
-
-interface ToolEndEvent {
-	type: typeof SERVER_EVENT_TYPES.TOOL_CALL_END;
-	conversationId: string;
-	callId: string;
-	status: "success" | "error";
-	result: unknown;
-}
-
-interface RunDoneEvent {
-	type: typeof SERVER_EVENT_TYPES.RUN_DONE;
-	conversationId: string;
-}
-
-interface RunResumedEvent {
-	type: typeof SERVER_EVENT_TYPES.RUN_RESUMED;
-	conversationId: string;
-}
-
-interface RunErrorEvent {
-	type: typeof SERVER_EVENT_TYPES.RUN_ERROR;
-	conversationId: string;
-	error: string;
-	isRetryable?: boolean;
-}
-
-interface RunProgressEvent {
-	type: typeof SERVER_EVENT_TYPES.RUN_PROGRESS;
-	conversationId: string;
-	activity: string;
-	detail?: string;
-	elapsedMs: number;
-	idleMs: number;
-}
-
-interface SnapshotEvent {
-	type: typeof SERVER_EVENT_TYPES.CONVERSATION_SNAPSHOT;
-	conversationId: string;
-	messages: SnapshotMessage[];
-}
-
-interface PermissionRequestEvent {
-	type: typeof SERVER_EVENT_TYPES.PERMISSION_REQUEST;
-	conversationId: string;
-	requestId: string;
-	toolName: string;
-	args: unknown;
-	summary: string;
-}
-
-interface AskQuestionEvent {
-	type: typeof SERVER_EVENT_TYPES.ASK_QUESTION;
-	conversationId: string;
-	requestId: string;
-	questions: QuestionData[];
-}
-
-interface WireAttachment {
-	name: string;
-	mimeType: string;
-	size: number;
-	data: string;
-}
-
-interface AttachmentMeta {
-	name: string;
-	mimeType: string;
-	size: number;
-}
-
-interface QueuedItemWire {
-	id: string;
-	content: string;
-	attachments?: WireAttachment[];
-}
-
-interface QueueStateEvent {
-	type: typeof SERVER_EVENT_TYPES.QUEUE_STATE;
-	conversationId: string;
-	items: QueuedItemWire[];
-}
-
-interface UserMessageEchoEvent {
-	type: typeof SERVER_EVENT_TYPES.USER_MESSAGE_ECHO;
-	conversationId: string;
-	content: string;
-	attachments?: AttachmentMeta[];
-	timestampMs: number;
-}
-
-function newId(): string {
-	return newUuid();
-}
-
-function buildUserMessage(
-	content: string,
-	attachments?: MessageAttachment[],
-): UserMessage {
-	return {
-		id: newId(),
-		role: MESSAGE_ROLES.USER,
-		content,
-		attachments,
-		timestampMs: Date.now(),
-	};
-}
-
-function markUnsent(message: UserMessage, isSent: boolean): UserMessage {
-	return isSent ? message : { ...message, isUnsent: true };
-}
-
-function buildAssistantMessage(text: string): AssistantMessage {
-	return {
-		id: newId(),
-		role: MESSAGE_ROLES.ASSISTANT,
-		content: text,
-		timestampMs: Date.now(),
-	};
-}
-
-function buildToolCallMessage(event: ToolStartEvent): ToolCallMessage {
-	return {
-		id: newId(),
-		role: MESSAGE_ROLES.TOOL,
-		callId: event.callId,
-		toolName: event.toolName,
-		args: event.args,
-		status: TOOL_STATUS.PENDING,
-		timestampMs: Date.now(),
-	};
-}
-
-function appendChunk(
-	list: ConversationMessage[],
-	text: string,
-): ConversationMessage[] {
-	const last = list.at(-1);
-	if (last !== undefined && last.role === MESSAGE_ROLES.ASSISTANT) {
-		const updated: AssistantMessage = { ...last, content: last.content + text };
-		return [...list.slice(0, -1), updated];
-	}
-	return [...list, buildAssistantMessage(text)];
-}
-
-function upsertToolCall(
-	list: ConversationMessage[],
-	event: ToolStartEvent,
-): ConversationMessage[] {
-	const exists = list.some(
-		(msg) => msg.role === MESSAGE_ROLES.TOOL && msg.callId === event.callId,
-	);
-	if (!exists) return [...list, buildToolCallMessage(event)];
-	return list.map((msg) => {
-		if (msg.role !== MESSAGE_ROLES.TOOL || msg.callId !== event.callId) {
-			return msg;
-		}
-		return {
-			...msg,
-			toolName: event.toolName,
-			args: event.args,
-			status: TOOL_STATUS.PENDING,
-		};
-	});
-}
-
-function applyToolEnd(
-	list: ConversationMessage[],
-	event: ToolEndEvent,
-): ConversationMessage[] {
-	return list.map((msg) => {
-		if (msg.role !== MESSAGE_ROLES.TOOL) return msg;
-		if (msg.callId !== event.callId) return msg;
-		return { ...msg, status: event.status, result: event.result };
-	});
-}
-
-function normalizeToolStatus(raw: string | undefined): ToolStatus {
-	if (raw === TOOL_STATUS.SUCCESS) return TOOL_STATUS.SUCCESS;
-	if (raw === TOOL_STATUS.ERROR) return TOOL_STATUS.ERROR;
-	return TOOL_STATUS.PENDING;
-}
-
-function safeParse(raw: string): unknown {
-	try {
-		return JSON.parse(raw);
-	} catch {
-		return raw;
-	}
-}
-
-function buildUserSnapshot(snap: SnapshotMessage): UserMessage {
-	return {
-		id: newId(),
-		role: MESSAGE_ROLES.USER,
-		content: snap.content,
-		attachments: snap.attachments,
-		timestampMs: snap.timestampMs,
-	};
-}
-
-function buildAssistantSnapshot(snap: SnapshotMessage): AssistantMessage {
-	return {
-		id: newId(),
-		role: MESSAGE_ROLES.ASSISTANT,
-		content: snap.content,
-		timestampMs: snap.timestampMs,
-	};
-}
-
-function buildToolUseSnapshot(snap: SnapshotMessage): ToolCallMessage | null {
-	if (snap.callId === undefined || snap.toolName === undefined) return null;
-	return {
-		id: newId(),
-		role: MESSAGE_ROLES.TOOL,
-		callId: snap.callId,
-		toolName: snap.toolName,
-		args: safeParse(snap.content),
-		status: TOOL_STATUS.PENDING,
-		timestampMs: snap.timestampMs,
-	};
-}
-
-function applyToolResultSnapshot(
-	out: ConversationMessage[],
-	toolByCallId: Map<string, ToolCallMessage>,
-	snap: SnapshotMessage,
-): void {
-	if (snap.callId === undefined) return;
-	const result = safeParse(snap.content);
-	const status = normalizeToolStatus(snap.status);
-	const existing = toolByCallId.get(snap.callId);
-	if (existing !== undefined) {
-		existing.result = result;
-		existing.status = status;
-		return;
-	}
-	out.push({
-		id: newId(),
-		role: MESSAGE_ROLES.TOOL,
-		callId: snap.callId,
-		toolName: "",
-		args: undefined,
-		result,
-		status,
-		timestampMs: snap.timestampMs,
-	});
-}
-
-function appendSnapshotItem(
-	out: ConversationMessage[],
-	toolByCallId: Map<string, ToolCallMessage>,
-	item: SnapshotMessage,
-): void {
-	if (item.role === MESSAGE_ROLES.USER) {
-		out.push(buildUserSnapshot(item));
-		return;
-	}
-	if (item.role === STORED_ERROR_ROLE) {
-		out.push(
-			buildErrorMessage(
-				item.content,
-				item.isRetryable ?? true,
-				item.timestampMs,
-			),
-		);
-		return;
-	}
-	if (item.role === MESSAGE_ROLES.ASSISTANT) {
-		out.push(buildAssistantSnapshot(item));
-		return;
-	}
-	if (item.role === STORED_TOOL_USE_ROLE) {
-		const message = buildToolUseSnapshot(item);
-		if (message === null) return;
-		out.push(message);
-		toolByCallId.set(message.callId, message);
-		return;
-	}
-	if (item.role === STORED_TOOL_RESULT_ROLE) {
-		applyToolResultSnapshot(out, toolByCallId, item);
-	}
-}
-
-function snapshotToMessages(snap: SnapshotMessage[]): ConversationMessage[] {
-	const out: ConversationMessage[] = [];
-	const toolByCallId = new Map<string, ToolCallMessage>();
-	for (const item of snap) {
-		appendSnapshotItem(out, toolByCallId, item);
-	}
-	return settlePendingTools(out);
-}
-
-function buildErrorMessage(
-	error: string,
-	isRetryable: boolean,
-	timestampMs: number = Date.now(),
-): ErrorMessage {
-	return {
-		id: newId(),
-		role: MESSAGE_ROLES.ERROR,
-		content: error,
-		isRetryable,
-		timestampMs,
-	};
-}
-
-function isPendingTool(msg: ConversationMessage): msg is ToolCallMessage {
-	return msg.role === MESSAGE_ROLES.TOOL && msg.status === TOOL_STATUS.PENDING;
-}
-
-function settlePendingTools(
-	list: ConversationMessage[],
-): ConversationMessage[] {
-	if (!list.some(isPendingTool)) return list;
-	return list.map((msg) => {
-		if (!isPendingTool(msg)) return msg;
-		return { ...msg, status: TOOL_STATUS.ERROR, result: TOOL_CUT_SHORT_RESULT };
-	});
-}
-
-function toRunProgress(event: RunProgressEvent): RunProgress {
-	return {
-		activity: toActivityKind(event.activity),
-		detail: event.detail,
-		elapsedMs: event.elapsedMs,
-		idleMs: event.idleMs,
-		receivedAtMs: Date.now(),
-	};
-}
-
-function isUserMessage(msg: ConversationMessage): msg is UserMessage {
-	return msg.role === MESSAGE_ROLES.USER;
-}
-
-function lastUserMessage(list: ConversationMessage[]): UserMessage | undefined {
-	for (let index = list.length - 1; index >= 0; index -= 1) {
-		const message = list[index];
-		if (isUserMessage(message)) return message;
-	}
-	return undefined;
-}
-
-function toResendableAttachments(
-	attachments: MessageAttachment[] | undefined,
-): PendingAttachment[] | null {
-	const list = attachments ?? [];
-	if (list.some((att) => !att.dataUrl)) return null;
-	return list.map((att) => ({
-		id: newId(),
-		name: att.name,
-		mimeType: att.mimeType,
-		size: att.size,
-		data: splitDataUrl(att.dataUrl ?? ""),
-		dataUrl: att.dataUrl ?? "",
-	}));
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object";
-}
-
-function getEventType(msg: unknown): string | null {
-	if (!isObject(msg)) return null;
-	const t = msg.type;
-	return typeof t === "string" ? t : null;
-}
-
-function getConversationId(msg: unknown): string | null {
-	if (!isObject(msg)) return null;
-	const id = msg.conversationId;
-	return typeof id === "string" ? id : null;
-}
-
-function toPermissionRequestData(
-	event: PermissionRequestEvent,
-): PermissionRequestData {
-	return {
-		requestId: event.requestId,
-		conversationId: event.conversationId,
-		toolName: event.toolName,
-		args: event.args,
-		summary: event.summary,
-	};
-}
-
-function toQuestionRequestData(event: AskQuestionEvent): QuestionRequestData {
-	return {
-		requestId: event.requestId,
-		conversationId: event.conversationId,
-		questions: event.questions,
-	};
-}
-
-interface ConversationState {
+/** Every piece of a conversation the event handlers write. */
+export interface ConversationState {
 	options: UseConversationOptions;
 	messages: Ref<ConversationMessage[]>;
 	isRunning: Ref<boolean>;
@@ -483,40 +73,23 @@ interface ConversationState {
 	progress: Ref<RunProgress | null>;
 	isTurnInFlight: Ref<boolean>;
 	lastEventAtMs: Ref<number>;
+	changeSets: Ref<Record<string, ChangeSetSummary>>;
+	mode: Ref<ConversationModeState | null>;
+	totalTokens: Ref<number | null>;
+	/**
+	 * When the calls of the stored transcript started and ended. A re-attach
+	 * replays the running turn's events, and the replayed calls take their
+	 * times from here rather than from the moment of the replay.
+	 */
+	callTimes: Map<string, CallTimes>;
 }
 
-type ConversationEvent =
-	| ChunkEvent
-	| ToolStartEvent
-	| ToolEndEvent
-	| RunDoneEvent
-	| RunResumedEvent
-	| RunErrorEvent
-	| RunProgressEvent
-	| SnapshotEvent
-	| PermissionRequestEvent
-	| AskQuestionEvent
-	| QueueStateEvent
-	| UserMessageEchoEvent;
-
-type ConversationEventType = ConversationEvent["type"];
-
-interface EventTypeTag<K extends ConversationEventType> {
-	type: K;
+/** When a call started and, once it did, ended, in sidecar time. */
+interface CallTimes {
+	startedAtMs: number;
+	endedAtMs?: number;
 }
 
-type EventOfType<K extends ConversationEventType> = Extract<
-	ConversationEvent,
-	EventTypeTag<K>
->;
-
-type EventHandlers = {
-	[K in ConversationEventType]: (
-		state: ConversationState,
-		event: EventOfType<K>,
-	) => void;
-};
-
 function appendMessage(
 	state: ConversationState,
 	message: ConversationMessage,
@@ -524,12 +97,12 @@ function appendMessage(
 	state.messages.value = [...state.messages.value, message];
 }
 
-function appendError(
+function appendLocalError(
 	state: ConversationState,
-	error: string,
+	key: string,
 	isRetryable = true,
 ): void {
-	appendMessage(state, buildErrorMessage(error, isRetryable));
+	appendMessage(state, buildLocalError(key, isRetryable));
 }
 
 function expectTurn(state: ConversationState): void {
@@ -538,149 +111,11 @@ function expectTurn(state: ConversationState): void {
 }
 
 function endTurn(state: ConversationState): void {
-	state.messages.value = settlePendingTools(state.messages.value);
-	state.progress.value = null;
-	state.isTurnInFlight.value = false;
-}
-
-function settleOrKeepRunning(state: ConversationState): void {
-	state.isRunning.value = state.queued.value.length > 0;
-}
-
-function applySnapshot(state: ConversationState, event: SnapshotEvent): void {
-	state.messages.value = snapshotToMessages(event.messages);
-	state.isRunning.value = false;
+	state.messages.value = settleOpenTools(state.messages.value);
 	state.progress.value = null;
 	state.isTurnInFlight.value = false;
 }
 
-function toPendingAttachment(wire: WireAttachment): PendingAttachment {
-	return {
-		id: newId(),
-		name: wire.name,
-		mimeType: wire.mimeType,
-		size: wire.size,
-		data: wire.data,
-		dataUrl: `data:${wire.mimeType};base64,${wire.data}`,
-	};
-}
-
-function applyQueueState(
-	state: ConversationState,
-	event: QueueStateEvent,
-): void {
-	state.queued.value = event.items.map((item) => ({
-		id: item.id,
-		content: item.content,
-		attachments: (item.attachments ?? []).map(toPendingAttachment),
-	}));
-}
-
-function withAttachments(
-	attachments: MessageAttachment[],
-): MessageAttachment[] | undefined {
-	return attachments.length > 0 ? attachments : undefined;
-}
-
-function applyUserEcho(
-	state: ConversationState,
-	event: UserMessageEchoEvent,
-): void {
-	const attachments = (event.attachments ?? []).map((a) => ({
-		...a,
-		dataUrl: "",
-	}));
-	appendMessage(
-		state,
-		buildUserMessage(event.content, withAttachments(attachments)),
-	);
-}
-
-function forwardPermissionRequest(
-	state: ConversationState,
-	event: PermissionRequestEvent,
-): void {
-	state.options.onPermissionRequest?.(toPermissionRequestData(event));
-}
-
-function forwardQuestion(
-	state: ConversationState,
-	event: AskQuestionEvent,
-): void {
-	state.options.onQuestionRequest?.(toQuestionRequestData(event));
-}
-
-function applyProgress(
-	state: ConversationState,
-	event: RunProgressEvent,
-): void {
-	state.progress.value = toRunProgress(event);
-	state.isRunning.value = true;
-	state.isTurnInFlight.value = true;
-}
-
-const EVENT_HANDLERS: EventHandlers = {
-	[SERVER_EVENT_TYPES.ASSISTANT_MESSAGE_CHUNK]: (state, event) => {
-		state.messages.value = appendChunk(state.messages.value, event.text);
-	},
-	[SERVER_EVENT_TYPES.TOOL_CALL_START]: (state, event) => {
-		state.messages.value = upsertToolCall(state.messages.value, event);
-	},
-	[SERVER_EVENT_TYPES.TOOL_CALL_END]: (state, event) => {
-		state.messages.value = applyToolEnd(state.messages.value, event);
-	},
-	[SERVER_EVENT_TYPES.RUN_DONE]: (state) => {
-		endTurn(state);
-		settleOrKeepRunning(state);
-	},
-	[SERVER_EVENT_TYPES.RUN_RESUMED]: (state) => {
-		state.isRunning.value = true;
-		expectTurn(state);
-	},
-	[SERVER_EVENT_TYPES.RUN_ERROR]: (state, event) => {
-		endTurn(state);
-		appendError(state, event.error, event.isRetryable ?? true);
-		settleOrKeepRunning(state);
-	},
-	[SERVER_EVENT_TYPES.RUN_PROGRESS]: applyProgress,
-	[SERVER_EVENT_TYPES.CONVERSATION_SNAPSHOT]: applySnapshot,
-	[SERVER_EVENT_TYPES.PERMISSION_REQUEST]: forwardPermissionRequest,
-	[SERVER_EVENT_TYPES.ASK_QUESTION]: forwardQuestion,
-	[SERVER_EVENT_TYPES.QUEUE_STATE]: applyQueueState,
-	[SERVER_EVENT_TYPES.USER_MESSAGE_ECHO]: applyUserEcho,
-};
-
-function isForActiveConversation(
-	state: ConversationState,
-	msg: unknown,
-): boolean {
-	const eventId = getConversationId(msg);
-	return eventId === null || eventId === state.options.activeId.value;
-}
-
-function isHandledEventType(
-	type: string | null,
-): type is ConversationEventType {
-	return type !== null && Object.hasOwn(EVENT_HANDLERS, type);
-}
-
-function runHandler<K extends ConversationEventType>(
-	state: ConversationState,
-	type: K,
-	event: EventOfType<K>,
-): void {
-	const handler: EventHandlers[K] = EVENT_HANDLERS[type];
-	handler(state, event);
-}
-
-function dispatch(state: ConversationState, msg: unknown): void {
-	const type = getEventType(msg);
-	if (!isHandledEventType(type)) return;
-	if (!isForActiveConversation(state, msg)) return;
-	state.lastEventAtMs.value = Date.now();
-	runHandler(state, type, msg as EventOfType<typeof type>);
-}
-
 function toWireAttachments(attachments: PendingAttachment[]): WireAttachment[] {
 	return attachments.map((a) => ({
 		name: a.name,
@@ -692,7 +127,8 @@ function toWireAttachments(attachments: PendingAttachment[]): WireAttachment[] {
 
 function toLocalAttachments(
 	attachments: PendingAttachment[],
-): MessageAttachment[] {
+): MessageAttachment[] | undefined {
+	if (attachments.length === 0) return undefined;
 	return attachments.map((a) => ({
 		name: a.name,
 		mimeType: a.mimeType,
@@ -701,43 +137,46 @@ function toLocalAttachments(
 	}));
 }
 
+function withWire(attachments: PendingAttachment[]): Record<string, unknown> {
+	const wire = toWireAttachments(attachments);
+	return wire.length > 0 ? { attachments: wire } : {};
+}
+
 function queueFollowUp(
 	state: ConversationState,
 	content: string,
 	attachments: PendingAttachment[],
 ): void {
-	const wire = toWireAttachments(attachments);
 	const isQueued = state.options.send({
 		type: CLIENT_MESSAGE_TYPES.QUEUE_ENQUEUE,
 		conversationId: state.options.activeId.value,
-		item: {
-			id: newId(),
-			content,
-			...(wire.length > 0 ? { attachments: wire } : {}),
-		},
+		item: { id: newUuid(), content, ...withWire(attachments) },
 	});
-	if (!isQueued) appendError(state, NOT_SENT_MESSAGE);
+	if (!isQueued) appendLocalError(state, LOCAL_ERROR_KEYS.NOT_SENT);
 }
 
 function startTurn(
 	state: ConversationState,
 	content: string,
 	attachments: PendingAttachment[],
+	extra: Record<string, unknown>,
 ): void {
-	const wire = toWireAttachments(attachments);
 	const isSent = state.options.send({
 		type: CLIENT_MESSAGE_TYPES.USER_MESSAGE,
 		conversationId: state.options.activeId.value,
 		content,
-		...(wire.length > 0 ? { attachments: wire } : {}),
+		...withWire(attachments),
+		...extra,
 	});
+	state.messages.value = settleOpenTools(state.messages.value);
 	const message = buildUserMessage(
 		content,
-		withAttachments(toLocalAttachments(attachments)),
+		toLocalAttachments(attachments),
+		state.options.getPagePath?.(),
 	);
-	appendMessage(state, markUnsent(message, isSent));
+	appendMessage(state, isSent ? message : { ...message, isUnsent: true });
 	if (!isSent) {
-		appendError(state, NOT_SENT_MESSAGE);
+		appendLocalError(state, LOCAL_ERROR_KEYS.NOT_SENT);
 		return;
 	}
 	state.isRunning.value = true;
@@ -748,6 +187,7 @@ function sendUserMessage(
 	state: ConversationState,
 	content: string,
 	attachments: PendingAttachment[],
+	extra: Record<string, unknown>,
 ): void {
 	const trimmed = content.trim();
 	if (trimmed.length === 0 && attachments.length === 0) return;
@@ -755,31 +195,60 @@ function sendUserMessage(
 		queueFollowUp(state, trimmed, attachments);
 		return;
 	}
-	startTurn(state, trimmed, attachments);
+	startTurn(state, trimmed, attachments, extra);
 }
 
-function retry(state: ConversationState): void {
-	const last = lastUserMessage(state.messages.value);
-	if (last === undefined) return;
+function lastUserMessage(list: ConversationMessage[]): UserMessage | undefined {
+	const users = list.filter(
+		(msg): msg is UserMessage => msg.role === MESSAGE_ROLES.USER,
+	);
+	return users.at(-1);
+}
+
+function toResendableAttachments(
+	attachments: MessageAttachment[] | undefined,
+): PendingAttachment[] | null {
+	const list = attachments ?? [];
+	if (list.some((att) => !att.dataUrl)) return null;
+	return list.map((att) => ({
+		id: newUuid(),
+		name: att.name,
+		mimeType: att.mimeType,
+		size: att.size,
+		data: splitDataUrl(att.dataUrl ?? ""),
+		dataUrl: att.dataUrl ?? "",
+	}));
+}
+
+function resendLocally(state: ConversationState, last: UserMessage): void {
 	const attachments = toResendableAttachments(last.attachments);
 	if (attachments === null) {
-		appendError(state, RETRY_NEEDS_FILES_MESSAGE, false);
+		appendLocalError(state, LOCAL_ERROR_KEYS.RETRY_NEEDS_FILES, false);
 		return;
 	}
-	if (last.isUnsent === true) {
-		state.messages.value = state.messages.value.filter(
-			(msg) => msg.id !== last.id,
-		);
-	}
-	sendUserMessage(state, last.content, attachments);
+	state.messages.value = state.messages.value.filter(
+		(msg) => msg.id !== last.id,
+	);
+	sendUserMessage(state, last.content, attachments, {});
 }
 
-function cancelQueued(state: ConversationState, id: string): void {
-	state.options.send({
-		type: CLIENT_MESSAGE_TYPES.QUEUE_CANCEL,
+function retry(state: ConversationState): void {
+	const last = lastUserMessage(state.messages.value);
+	if (last === undefined || state.isRunning.value) return;
+	if (last.isUnsent === true) {
+		resendLocally(state, last);
+		return;
+	}
+	const isSent = state.options.send({
+		type: CLIENT_MESSAGE_TYPES.RETRY_TURN,
 		conversationId: state.options.activeId.value,
-		id,
 	});
+	if (!isSent) {
+		appendLocalError(state, LOCAL_ERROR_KEYS.NOT_SENT);
+		return;
+	}
+	state.isRunning.value = true;
+	expectTurn(state);
 }
 
 function interrupt(state: ConversationState): void {
@@ -791,7 +260,20 @@ function interrupt(state: ConversationState): void {
 	if (isSent) return;
 	endTurn(state);
 	state.isRunning.value = false;
-	appendError(state, STOP_NOT_DELIVERED_MESSAGE);
+	appendLocalError(state, LOCAL_ERROR_KEYS.STOP_NOT_DELIVERED);
+}
+
+function recordAnswers(
+	state: ConversationState,
+	answers: QuestionAnswerRecord[],
+): void {
+	if (answers.length === 0) return;
+	appendMessage(state, {
+		id: newUuid(),
+		role: MESSAGE_ROLES.QUESTION_ANSWER,
+		answers,
+		timestampMs: Date.now(),
+	});
 }
 
 function reset(state: ConversationState): void {
@@ -800,6 +282,10 @@ function reset(state: ConversationState): void {
 	state.queued.value = [];
 	state.progress.value = null;
 	state.isTurnInFlight.value = false;
+	state.changeSets.value = {};
+	state.mode.value = null;
+	state.totalTokens.value = null;
+	state.callTimes.clear();
 }
 
 function createConversationState(
@@ -813,14 +299,23 @@ function createConversationState(
 		progress: ref<RunProgress | null>(null),
 		isTurnInFlight: ref(false),
 		lastEventAtMs: ref(Date.now()),
+		changeSets: ref<Record<string, ChangeSetSummary>>({}),
+		mode: ref<ConversationModeState | null>(null),
+		totalTokens: ref<number | null>(null),
+		callTimes: new Map(),
 	};
 }
 
+/**
+ * One conversation as the chat shows it: its transcript, its running turn,
+ * its queue, change sets, mode and token count, all folded from the
+ * sidecar's events for the active conversation.
+ */
 export function useConversation(
 	options: UseConversationOptions,
 ): UseConversationResult {
 	const state = createConversationState(options);
-	options.onMessage((msg) => dispatch(state, msg));
+	options.onMessage((msg) => dispatchConversationEvent(state, msg));
 	return {
 		messages: state.messages,
 		isRunning: state.isRunning,
@@ -828,11 +323,14 @@ export function useConversation(
 		progress: state.progress,
 		isTurnInFlight: state.isTurnInFlight,
 		lastEventAtMs: state.lastEventAtMs,
-		sendUserMessage: (content, attachments = []) =>
-			sendUserMessage(state, content, attachments),
+		changeSets: state.changeSets,
+		mode: state.mode,
+		totalTokens: state.totalTokens,
+		sendUserMessage: (content, attachments = [], extra = {}) =>
+			sendUserMessage(state, content, attachments, extra),
 		retry: () => retry(state),
-		cancelQueued: (id) => cancelQueued(state, id),
 		interrupt: () => interrupt(state),
+		recordAnswers: (answers) => recordAnswers(state, answers),
 		reset: () => reset(state),
 	};
 }