@tea-agent/loop-agent 0.13.0 → 0.14.0

package/dist/worker/observe/static/views/session-timeline.js

@@ -1,219 +1,771 @@
-/** Session event timeline helpers (Observe UI R5). */
-import { UI_TEXT } from "../constants.js";
-import { el } from "../dom.js";
-import { formatTs, truncateText } from "../format.js";
-import { fetchJson } from "../api.js";
-import {
-	uiState,
-	updateDagTimelineViewportState,
-	computeFollowLatest,
-} from "../state.js";
-
-export function extractAssistantSummary(event) {
-	if (!event || typeof event !== "object") return "—";
-	const record = event;
-	if (record.message && typeof record.message === "object") {
-		const content = record.message.content;
-		if (Array.isArray(content)) {
-			return (
-				content
-					.filter(
-						(part) => part?.type === "text" && typeof part.text === "string",
-					)
-					.map((part) => part.text)
-					.join(" ") || "—"
-			);
-		}
-		if (typeof record.message.content === "string") {
-			return record.message.content;
-		}
-	}
-	if (typeof record.text === "string") return record.text;
-	if (typeof record.outputPreview === "string") return record.outputPreview;
-	return "—";
-}
-
-export function formatSessionEventLabel(event) {
-	if (!event || typeof event !== "object") return "未知类型";
-	const type = typeof event.type === "string" ? event.type : "unknown";
-	const toolName = event.toolName ?? event.name ?? "—";
-	if (type === "agent_start") return "Agent 已启动";
-	if (type === "agent_end") return "Agent 已结束";
-	if (type === "agent_settled") return "Agent 已稳定";
-	if (type === "turn_start") return "开始新一轮处理";
-	if (type === "tool_execution_start" || type === "tool_start") {
-		return `调用工具 · ${toolName}`;
-	}
-	if (type === "tool_execution_end" || type === "tool_end") {
-		return `工具调用完成 · ${toolName}`;
-	}
-	if (
-		type === "turn_end" ||
-		type === "assistant" ||
-		type === "assistant_message"
-	) {
-		return `AI 回复摘要 · ${truncateText(extractAssistantSummary(event), 120)}`;
-	}
-	return type;
-}
-
-export function sessionEventTimestamp(event) {
-	if (!event || typeof event !== "object") return "";
-	const ts =
-		(typeof event.timestamp === "string" && event.timestamp) ||
-		(typeof event.at === "string" && event.at) ||
-		(typeof event.recordedAt === "string" && event.recordedAt);
-	return ts || "";
-}
-
-export function formatSessionEventTime(event) {
-	const ts = sessionEventTimestamp(event);
-	if (!ts) return "未记录时间";
-	return formatTs(ts).replace(/\s.*/, "") || formatTs(ts);
-}
-
-export function sessionEventKind(event) {
-	const type = typeof event?.type === "string" ? event.type : "unknown";
-	if (type === "tool_execution_start" || type === "tool_start")
-		return "tool-start";
-	if (type === "tool_execution_end" || type === "tool_end") return "tool-end";
-	if (
-		type === "turn_end" ||
-		type === "assistant" ||
-		type === "assistant_message"
-	) {
-		return "assistant";
-	}
-	if (type.startsWith("agent_") || type === "turn_start") return "lifecycle";
-	return "protocol";
-}
-
-export function buildSessionTimelineItems(events) {
-	const items = [];
-	for (let index = 0; index < events.length; index += 1) {
-		const event = events[index];
-		const type = typeof event?.type === "string" ? event.type : "unknown";
-		if (type === "message_start" || type === "message_end") {
-			let count = 1;
-			while (index + 1 < events.length) {
-				const nextType = events[index + 1]?.type;
-				if (nextType !== "message_start" && nextType !== "message_end") break;
-				count += 1;
-				index += 1;
-			}
-			items.push({ event, kind: "protocol", protocolCount: count });
-			continue;
-		}
-		items.push({ event, kind: sessionEventKind(event) });
-	}
-	return items;
-}
-
-export async function mergeSessionEvents(dagRunId, nodeId) {
-	if (!dagRunId || !nodeId) return;
-	// Capture the current identity token before awaiting. The token encodes the
-	// {dagRunId, nodeId} pair plus a per-switch sequence, and is bumped by
-	// selectDagNode / renderDagDetail whenever the selection changes. After the
-	// response resolves we re-check both the token and the live selection so a
-	// stale response for a previous node can never mutate the current node's
-	// event cache, even if the user switched nodes mid-flight.
-	const identity = uiState.sessionEventIdentity;
-	const page = await fetchJson(
-		`/api/dag-runs/${encodeURIComponent(dagRunId)}/nodes/${encodeURIComponent(nodeId)}/session-events?after=${uiState.sessionEventOffset}`,
-	);
-	if (
-		identity !== uiState.sessionEventIdentity ||
-		uiState.currentDagRunId !== dagRunId ||
-		uiState.selectedDagNodeId !== nodeId
-	) {
-		return;
-	}
-	if (!page) return;
-	if (Array.isArray(page.events) && page.events.length > 0) {
-		uiState.sessionEvents = uiState.sessionEvents.concat(page.events);
-	}
-	if (typeof page.nextOffset === "number") {
-		uiState.sessionEventOffset = page.nextOffset;
-	}
-}
-
-export function renderSessionTimeline(content, nodeId) {
-	content.dataset.dagRunId = uiState.currentDagRunId ?? "";
-	content.dataset.nodeId = nodeId ?? "";
-	content.classList.add("process-timeline-scroll");
-	if (!nodeId || uiState.sessionEvents.length === 0) {
-		content.appendChild(el("p", "empty", UI_TEXT.noSessionEvents));
-		return;
-	}
-
-	const timelineItems = buildSessionTimelineItems(uiState.sessionEvents);
-	const hasEventTimes = uiState.sessionEvents.some((event) =>
-		Boolean(sessionEventTimestamp(event)),
-	);
-	if (!hasEventTimes) {
-		content.appendChild(
-			el(
-				"p",
-				"process-timeline-note",
-				"事件未记录具体时间，以下按采集顺序展示。",
-			),
-		);
-	}
-	const ul = el("ul", "process-timeline");
-	for (let index = 0; index < timelineItems.length; index += 1) {
-		const item = timelineItems[index];
-		const li = el(
-			"li",
-			`process-timeline-item process-timeline-${item.kind}${hasEventTimes ? " has-time" : ""}`,
-		);
-		if (index === 0) li.classList.add("is-first");
-		if (index === timelineItems.length - 1) li.classList.add("is-last");
-		const rail = el("span", "process-timeline-rail");
-		rail.appendChild(el("span", "process-timeline-dot"));
-		li.appendChild(rail);
-		if (hasEventTimes) {
-			li.appendChild(
-				el("span", "process-timeline-time", formatSessionEventTime(item.event)),
-			);
-		}
-		const label =
-			item.protocolCount > 1
-				? `消息收发 · 已合并 ${item.protocolCount} 条协议事件`
-				: formatSessionEventLabel(item.event);
-		li.appendChild(el("span", "process-timeline-label", label));
-		ul.appendChild(li);
-	}
-	content.appendChild(ul);
-
-	const timelineState =
-		uiState.dagTimelineViewportState?.dagRunId === uiState.currentDagRunId &&
-		uiState.dagTimelineViewportState.nodeId === nodeId
-			? uiState.dagTimelineViewportState
-			: null;
-	content.addEventListener(
-		"scroll",
-		() => {
-			const followLatest = computeFollowLatest(
-				content.scrollTop,
-				content.scrollHeight,
-				content.clientHeight,
-			);
-			uiState.dagTimelineViewportState = updateDagTimelineViewportState(
-				uiState.dagTimelineViewportState,
-				uiState.currentDagRunId,
-				nodeId,
-				content.scrollLeft,
-				content.scrollTop,
-				followLatest,
-			);
-		},
-		{ passive: true },
-	);
-	if (timelineState?.followLatest ?? true) {
-		content.scrollLeft = timelineState?.scrollLeft ?? 0;
-		content.scrollTop = content.scrollHeight;
-	} else {
-		content.scrollLeft = timelineState.scrollLeft;
-		content.scrollTop = timelineState.scrollTop;
-	}
-}
+/** Session event timeline helpers (Observe UI R5 + rich process view). */
+import { UI_TEXT } from "../constants.js";
+import { el } from "../dom.js";
+import { formatTs, truncateText } from "../format.js";
+import { renderMarkdown } from "../markdown-render.js";
+import { fetchJson } from "../api.js";
+import {
+	uiState,
+	updateDagTimelineViewportState,
+	computeFollowLatest,
+} from "../state.js";
+
+/** Default visible lines for tool result preview before expand. */
+export const TOOL_RESULT_PREVIEW_LINES = 20;
+
+export function normalizeSessionEventFields(event) {
+	if (!event || typeof event !== "object") return {};
+	const args = event.args ?? event.input ?? event.toolInput;
+	const result = event.result ?? event.toolResult;
+	return {
+		...event,
+		...(args !== undefined ? { args, input: event.input ?? args } : {}),
+		...(result !== undefined ? { result } : {}),
+	};
+}
+
+export function sessionEventArgs(event) {
+	const normalized = normalizeSessionEventFields(event);
+	const args = normalized.args;
+	return args && typeof args === "object" && !Array.isArray(args) ? args : {};
+}
+
+export function sessionEventResult(event) {
+	return normalizeSessionEventFields(event).result;
+}
+
+export function extractAssistantSummary(event) {
+	if (!event || typeof event !== "object") return "—";
+	const record = event;
+	if (record.message && typeof record.message === "object") {
+		const content = record.message.content;
+		if (Array.isArray(content)) {
+			return (
+				content
+					.filter(
+						(part) => part?.type === "text" && typeof part.text === "string",
+					)
+					.map((part) => part.text)
+					.join(" ") || "—"
+			);
+		}
+		if (typeof record.message.content === "string") {
+			return record.message.content;
+		}
+	}
+	if (typeof record.text === "string") return record.text;
+	if (typeof record.outputPreview === "string") return record.outputPreview;
+	return "—";
+}
+
+export function extractThinkingBlocks(event) {
+	const content = event?.message?.content;
+	if (!Array.isArray(content)) return [];
+	return content
+		.filter(
+			(part) =>
+				part?.type === "thinking" && typeof part.thinking === "string",
+		)
+		.map((part) => part.thinking);
+}
+
+/** Tool calls declared on a turn_end / assistant message (name + args + id). */
+export function extractToolCallsFromTurn(event) {
+	const content = event?.message?.content;
+	if (!Array.isArray(content)) return [];
+	const calls = [];
+	for (const part of content) {
+		if (!part || typeof part !== "object") continue;
+		if (part.type !== "toolCall" && part.type !== "tool_use") continue;
+		const name = part.name ?? part.toolName ?? "tool";
+		const args =
+			(part.arguments && typeof part.arguments === "object"
+				? part.arguments
+				: null) ??
+			(part.args && typeof part.args === "object" ? part.args : null) ??
+			{};
+		calls.push({
+			id: typeof part.id === "string" ? part.id : "",
+			name: String(name),
+			args,
+			summary: formatToolSummary(String(name), args),
+		});
+	}
+	return calls;
+}
+
+export function formatToolSummary(toolName, args) {
+	const name = toolName || "tool";
+	const input = args && typeof args === "object" ? args : {};
+	if (name === "bash" || name === "bashExecution") {
+		const cmd = typeof input.command === "string" ? input.command : "";
+		return cmd ? `${name} · ${truncateText(cmd, 80)}` : name;
+	}
+	if (name === "read" || name === "write" || name === "edit") {
+		const path = typeof input.path === "string" ? input.path : "";
+		return path ? `${name} · ${truncateText(path, 80)}` : name;
+	}
+	if (name === "grep") {
+		const pattern = typeof input.pattern === "string" ? input.pattern : "";
+		const scope =
+			(typeof input.glob === "string" && input.glob) ||
+			(typeof input.path === "string" && input.path) ||
+			"";
+		if (pattern && scope) return `grep · ${truncateText(pattern, 48)} in ${truncateText(scope, 40)}`;
+		if (pattern) return `grep · ${truncateText(pattern, 80)}`;
+		return "grep";
+	}
+	if (name === "find" || name === "glob") {
+		const pattern = typeof input.pattern === "string" ? input.pattern : "";
+		return pattern ? `${name} · ${truncateText(pattern, 80)}` : name;
+	}
+	if (name === "ls") {
+		const path = typeof input.path === "string" ? input.path : "";
+		return path ? `ls · ${truncateText(path, 80)}` : "ls";
+	}
+	try {
+		const json = JSON.stringify(input);
+		if (json && json !== "{}") return `${name} · ${truncateText(json, 80)}`;
+	} catch {
+		/* ignore */
+	}
+	return name;
+}
+
+export function formatToolResultText(result) {
+	if (result == null) return "";
+	if (typeof result === "string") return result;
+	if (typeof result !== "object") return String(result);
+	if (Array.isArray(result.content)) {
+		return result.content
+			.map((part) => {
+				if (typeof part === "string") return part;
+				if (part?.type === "text" && typeof part.text === "string") return part.text;
+				return "";
+			})
+			.filter(Boolean)
+			.join("\n");
+	}
+	if (typeof result.content === "string") return result.content;
+	if (typeof result.text === "string") return result.text;
+	if (result.error != null) {
+		return typeof result.error === "string"
+			? result.error
+			: JSON.stringify(result.error, null, 2);
+	}
+	try {
+		return JSON.stringify(result, null, 2);
+	} catch {
+		return String(result);
+	}
+}
+
+export function splitPreviewLines(text, maxLines = TOOL_RESULT_PREVIEW_LINES) {
+	const normalized = String(text ?? "");
+	const lines = normalized.split("\n");
+	if (lines.length <= maxLines) {
+		return { preview: normalized, truncated: false, totalLines: lines.length };
+	}
+	return {
+		preview: lines.slice(0, maxLines).join("\n"),
+		truncated: true,
+		totalLines: lines.length,
+	};
+}
+
+export function formatSessionEventLabel(event) {
+	if (!event || typeof event !== "object") return "未知类型";
+	const type = typeof event.type === "string" ? event.type : "unknown";
+	const toolName = event.toolName ?? event.name ?? "—";
+	if (type === "agent_start") return "Agent 已启动";
+	if (type === "agent_end") return "Agent 已结束";
+	if (type === "agent_settled") return "Agent 已稳定";
+	if (type === "turn_start") return "开始新一轮处理";
+	if (type === "tool_execution_start" || type === "tool_start") {
+		return `调用工具 · ${formatToolSummary(toolName, sessionEventArgs(event))}`;
+	}
+	if (type === "tool_execution_end" || type === "tool_end") {
+		return `工具调用完成 · ${toolName}`;
+	}
+	if (
+		type === "turn_end" ||
+		type === "assistant" ||
+		type === "assistant_message"
+	) {
+		return `AI 回复摘要 · ${truncateText(extractAssistantSummary(event), 120)}`;
+	}
+	return type;
+}
+
+export function sessionEventTimestamp(event) {
+	if (!event || typeof event !== "object") return "";
+	const ts =
+		(typeof event.timestamp === "string" && event.timestamp) ||
+		(typeof event.at === "string" && event.at) ||
+		(typeof event.recordedAt === "string" && event.recordedAt);
+	return ts || "";
+}
+
+export function formatSessionEventTime(event) {
+	const ts = sessionEventTimestamp(event);
+	if (!ts) return "未记录时间";
+	return formatTs(ts).replace(/\s.*/, "") || formatTs(ts);
+}
+
+export function sessionEventKind(event) {
+	const type = typeof event?.type === "string" ? event.type : "unknown";
+	if (type === "tool_execution_start" || type === "tool_start")
+		return "tool-start";
+	if (type === "tool_execution_end" || type === "tool_end") return "tool-end";
+	if (
+		type === "turn_end" ||
+		type === "assistant" ||
+		type === "assistant_message"
+	) {
+		return "assistant";
+	}
+	if (type.startsWith("agent_") || type === "turn_start") return "lifecycle";
+	return "protocol";
+}
+
+/** Legacy flat item builder (kept for label-only consumers / tests). */
+export function buildSessionTimelineItems(events) {
+	const items = [];
+	for (let index = 0; index < events.length; index += 1) {
+		const event = events[index];
+		const type = typeof event?.type === "string" ? event.type : "unknown";
+		if (type === "message_start" || type === "message_end") {
+			let count = 1;
+			while (index + 1 < events.length) {
+				const nextType = events[index + 1]?.type;
+				if (nextType !== "message_start" && nextType !== "message_end") break;
+				count += 1;
+				index += 1;
+			}
+			items.push({ event, kind: "protocol", protocolCount: count });
+			continue;
+		}
+		items.push({ event, kind: sessionEventKind(event) });
+	}
+	return items;
+}
+
+/**
+ * Build rich timeline items: merge tool start/end by toolCallId, collapse
+ * protocol noise, surface turn thinking/text without dumping agent_end.messages.
+ */
+export function buildRichTimelineItems(events, options = {}) {
+	const showProtocol = Boolean(options.showProtocol);
+	const items = [];
+	const pendingTools = new Map();
+
+	const flushTool = (toolCallId) => {
+		const pending = pendingTools.get(toolCallId);
+		if (!pending) return;
+		pendingTools.delete(toolCallId);
+		items.push(pending);
+	};
+
+	const flushAllPending = () => {
+		for (const id of [...pendingTools.keys()]) flushTool(id);
+	};
+
+	for (let index = 0; index < events.length; index += 1) {
+		const event = normalizeSessionEventFields(events[index]);
+		const type = typeof event?.type === "string" ? event.type : "unknown";
+
+		if (type === "message_start" || type === "message_end") {
+			let count = 1;
+			const protocolEvents = [event];
+			while (index + 1 < events.length) {
+				const nextType = events[index + 1]?.type;
+				if (nextType !== "message_start" && nextType !== "message_end") break;
+				count += 1;
+				index += 1;
+				protocolEvents.push(normalizeSessionEventFields(events[index]));
+			}
+			if (showProtocol) {
+				items.push({
+					kind: "protocol",
+					event,
+					protocolCount: count,
+					protocolEvents,
+					detailKey: `protocol-${items.length}`,
+				});
+			} else {
+				items.push({
+					kind: "protocol",
+					event,
+					protocolCount: count,
+					collapsed: true,
+					detailKey: `protocol-${items.length}`,
+				});
+			}
+			continue;
+		}
+
+		if (type === "tool_execution_start" || type === "tool_start") {
+			const toolCallId =
+				typeof event.toolCallId === "string" && event.toolCallId
+					? event.toolCallId
+					: `anon-start-${index}`;
+			const toolName = event.toolName ?? event.name ?? "tool";
+			const args = sessionEventArgs(event);
+			pendingTools.set(toolCallId, {
+				kind: "tool",
+				toolCallId,
+				toolName,
+				args,
+				startEvent: event,
+				endEvent: null,
+				result: null,
+				isError: false,
+				pending: true,
+				detailKey: `tool-${toolCallId}`,
+				event,
+			});
+			continue;
+		}
+
+		// Streaming progress between start/end — do not flush pending tools.
+		if (
+			type === "tool_execution_update" ||
+			type === "tool_update" ||
+			type === "thinking_delta" ||
+			type === "message_update"
+		) {
+			continue;
+		}
+
+		if (type === "tool_execution_end" || type === "tool_end") {
+			const toolCallId =
+				typeof event.toolCallId === "string" && event.toolCallId
+					? event.toolCallId
+					: `anon-end-${index}`;
+			const toolName = event.toolName ?? event.name ?? "tool";
+			const result = sessionEventResult(event);
+			const isError = event.isError === true;
+			const existing = pendingTools.get(toolCallId);
+			if (existing) {
+				existing.endEvent = event;
+				existing.result = result;
+				existing.isError = isError;
+				existing.pending = false;
+				existing.toolName = existing.toolName || toolName;
+				existing.event = event;
+				flushTool(toolCallId);
+			} else {
+				items.push({
+					kind: "tool",
+					toolCallId,
+					toolName,
+					args: sessionEventArgs(event),
+					startEvent: null,
+					endEvent: event,
+					result,
+					isError,
+					pending: false,
+					detailKey: `tool-${toolCallId}`,
+					event,
+				});
+			}
+			continue;
+		}
+
+		if (
+			type === "turn_end" ||
+			type === "assistant" ||
+			type === "assistant_message"
+		) {
+			// Do not flush pending tools here: tool_execution_update / out-of-order
+			// ends may still arrive after turn_end in some streams.
+			items.push({
+				kind: "turn",
+				event,
+				thinking: extractThinkingBlocks(event),
+				text: extractAssistantSummary(event),
+				toolCalls: extractToolCallsFromTurn(event),
+				detailKey: `turn-${items.length}`,
+			});
+			continue;
+		}
+
+		if (type === "agent_end") {
+			const messages = Array.isArray(event.messages) ? event.messages : [];
+			items.push({
+				kind: "lifecycle",
+				event,
+				agentEnd: true,
+				messageCount: messages.length,
+				willRetry: event.willRetry === true,
+				detailKey: `agent-end-${items.length}`,
+			});
+			continue;
+		}
+
+		// Lifecycle / unknown noise must not flush in-flight tool starts.
+		if (
+			type === "agent_start" ||
+			type === "turn_start" ||
+			type === "agent_settled" ||
+			type === "auto_retry_start" ||
+			type === "auto_retry_end" ||
+			type.startsWith("agent_")
+		) {
+			items.push({
+				kind: sessionEventKind(event),
+				event,
+				detailKey: `evt-${items.length}-${type}`,
+			});
+			continue;
+		}
+
+		items.push({
+			kind: sessionEventKind(event),
+			event,
+			detailKey: `evt-${items.length}-${type}`,
+		});
+	}
+
+	// Only after the full event list: leftover starts with no end.
+	flushAllPending();
+	return items;
+}
+
+function ensureOpenDetailsSet() {
+	if (!(uiState.sessionTimelineOpenDetails instanceof Set)) {
+		uiState.sessionTimelineOpenDetails = new Set();
+	}
+	return uiState.sessionTimelineOpenDetails;
+}
+
+function bindDetailsToggle(details, detailKey) {
+	const openSet = ensureOpenDetailsSet();
+	if (openSet.has(detailKey)) details.open = true;
+	details.addEventListener("toggle", () => {
+		if (details.open) openSet.add(detailKey);
+		else openSet.delete(detailKey);
+	});
+}
+
+function appendPreBlock(parent, className, text) {
+	const pre = el("pre", className);
+	pre.textContent = text;
+	parent.appendChild(pre);
+	return pre;
+}
+
+function renderToolCard(item) {
+	const card = el(
+		"div",
+		`process-timeline-card process-timeline-tool-card${item.isError ? " is-error" : ""}${item.pending ? " is-pending" : ""}`,
+	);
+	const summary = formatToolSummary(item.toolName, item.args);
+	const status = item.pending ? "进行中" : item.isError ? "失败" : "完成";
+	const details = document.createElement("details");
+	details.className = "process-timeline-details";
+	details.dataset.detailKey = item.detailKey;
+	bindDetailsToggle(details, item.detailKey);
+
+	const summaryEl = document.createElement("summary");
+	summaryEl.className = "process-timeline-summary";
+	summaryEl.appendChild(
+		el("span", "process-timeline-summary-title", summary),
+	);
+	summaryEl.appendChild(
+		el(
+			"span",
+			`process-timeline-summary-status status-${item.pending ? "pending" : item.isError ? "failed" : "succeeded"}`,
+			status,
+		),
+	);
+	details.appendChild(summaryEl);
+
+	const body = el("div", "process-timeline-card-body");
+	const argsJson = (() => {
+		try {
+			return JSON.stringify(item.args ?? {}, null, 2);
+		} catch {
+			return String(item.args ?? {});
+		}
+	})();
+	body.appendChild(el("div", "process-timeline-section-label", "参数"));
+	appendPreBlock(body, "process-timeline-code", argsJson);
+
+	const resultText = formatToolResultText(item.result);
+	if (resultText) {
+		body.appendChild(el("div", "process-timeline-section-label", "结果"));
+		const { preview, truncated, totalLines } = splitPreviewLines(resultText);
+		appendPreBlock(body, "process-timeline-code", preview);
+		if (truncated) {
+			const more = document.createElement("details");
+			more.className = "process-timeline-more";
+			more.dataset.detailKey = `${item.detailKey}-full`;
+			bindDetailsToggle(more, `${item.detailKey}-full`);
+			const moreSummary = document.createElement("summary");
+			moreSummary.textContent = `展开全部结果（${totalLines} 行）`;
+			more.appendChild(moreSummary);
+			appendPreBlock(more, "process-timeline-code", resultText);
+			body.appendChild(more);
+		}
+	} else if (!item.pending) {
+		body.appendChild(el("p", "muted", "无结果正文"));
+	}
+	details.appendChild(body);
+	card.appendChild(details);
+	return card;
+}
+
+function renderTurnCard(item) {
+	const card = el("div", "process-timeline-card process-timeline-turn-card");
+	const toolCalls = Array.isArray(item.toolCalls) ? item.toolCalls : [];
+	const hasText = Boolean(item.text && item.text !== "—");
+	const title = hasText
+		? `AI 回复 · ${truncateText(item.text, 80)}`
+		: toolCalls.length > 0
+			? `本回合仅调用工具 · ${toolCalls.length} 个`
+			: item.thinking.length > 0
+				? "AI 回复 · 含思考过程"
+				: "AI 回复";
+
+	if (item.thinking.length > 0) {
+		for (const [i, thinking] of item.thinking.entries()) {
+			const details = document.createElement("details");
+			details.className = "process-timeline-details process-timeline-thinking";
+			details.dataset.detailKey = `${item.detailKey}-thinking-${i}`;
+			// Default open for first thinking block so anomalies are visible.
+			if (i === 0) details.open = true;
+			bindDetailsToggle(details, `${item.detailKey}-thinking-${i}`);
+			const summary = document.createElement("summary");
+			summary.className = "process-timeline-summary";
+			summary.textContent = "思考过程";
+			details.appendChild(summary);
+			appendPreBlock(details, "process-timeline-thinking-body", thinking);
+			card.appendChild(details);
+		}
+	}
+
+	const textBlock = el("div", "process-timeline-turn-text");
+	textBlock.appendChild(el("div", "process-timeline-section-label", title));
+	if (hasText) {
+		textBlock.appendChild(renderMarkdown(item.text));
+	} else if (toolCalls.length > 0) {
+		textBlock.appendChild(
+			el(
+				"p",
+				"muted process-timeline-tool-only-note",
+				"本回合没有文本回复，模型直接发起了下列工具调用（详情见上方工具卡）：",
+			),
+		);
+		const list = el("ul", "process-timeline-turn-tools");
+		for (const call of toolCalls) {
+			list.appendChild(el("li", null, call.summary || call.name));
+		}
+		textBlock.appendChild(list);
+	} else {
+		textBlock.appendChild(el("p", "muted", "无文本回复"));
+	}
+	card.appendChild(textBlock);
+	return card;
+}
+
+function renderLifecycleCard(item) {
+	if (item.agentEnd) {
+		const card = el("div", "process-timeline-card process-timeline-lifecycle-card");
+		const parts = ["Agent 已结束"];
+		if (item.messageCount > 0) parts.push(`${item.messageCount} 条消息`);
+		if (item.willRetry) parts.push("将重试");
+		card.appendChild(el("div", "process-timeline-label", parts.join(" · ")));
+		card.appendChild(
+			el(
+				"p",
+				"muted process-timeline-agent-end-note",
+				"完整会话 messages 体积可能很大，此处不展开；请查看上方工具与回合卡片。",
+			),
+		);
+		return card;
+	}
+	return el("span", "process-timeline-label", formatSessionEventLabel(item.event));
+}
+
+function renderProtocolCard(item) {
+	if (item.collapsed) {
+		return el(
+			"span",
+			"process-timeline-label",
+			`消息收发 · 已合并 ${item.protocolCount} 条协议事件`,
+		);
+	}
+	const details = document.createElement("details");
+	details.className = "process-timeline-details";
+	details.dataset.detailKey = item.detailKey;
+	bindDetailsToggle(details, item.detailKey);
+	const summary = document.createElement("summary");
+	summary.className = "process-timeline-summary";
+	summary.textContent = `消息收发 · ${item.protocolCount} 条协议事件`;
+	details.appendChild(summary);
+	const body = el("div", "process-timeline-card-body");
+	for (const event of item.protocolEvents ?? [item.event]) {
+		const role = event?.message?.role ?? event?.type ?? "event";
+		body.appendChild(el("div", "process-timeline-section-label", String(role)));
+		try {
+			appendPreBlock(
+				body,
+				"process-timeline-code",
+				JSON.stringify(event, null, 2),
+			);
+		} catch {
+			appendPreBlock(body, "process-timeline-code", String(event));
+		}
+	}
+	details.appendChild(body);
+	return details;
+}
+
+export async function mergeSessionEvents(dagRunId, nodeId) {
+	if (!dagRunId || !nodeId) return;
+	const identity = uiState.sessionEventIdentity;
+	const page = await fetchJson(
+		`/api/dag-runs/${encodeURIComponent(dagRunId)}/nodes/${encodeURIComponent(nodeId)}/session-events?after=${uiState.sessionEventOffset}`,
+	);
+	if (
+		identity !== uiState.sessionEventIdentity ||
+		uiState.currentDagRunId !== dagRunId ||
+		uiState.selectedDagNodeId !== nodeId
+	) {
+		return;
+	}
+	if (!page) return;
+	if (Array.isArray(page.events) && page.events.length > 0) {
+		uiState.sessionEvents = uiState.sessionEvents.concat(page.events);
+	}
+	if (typeof page.nextOffset === "number") {
+		uiState.sessionEventOffset = page.nextOffset;
+	}
+}
+
+export function renderSessionTimeline(content, nodeId) {
+	content.dataset.dagRunId = uiState.currentDagRunId ?? "";
+	content.dataset.nodeId = nodeId ?? "";
+	content.classList.add("process-timeline-scroll");
+	if (!nodeId || uiState.sessionEvents.length === 0) {
+		content.appendChild(el("p", "empty", UI_TEXT.noSessionEvents));
+		return;
+	}
+
+	const showProtocol = Boolean(uiState.sessionTimelineShowProtocol);
+	const toolbar = el("div", "process-timeline-toolbar");
+	const protocolToggle = document.createElement("button");
+	protocolToggle.type = "button";
+	protocolToggle.className = "process-timeline-toggle";
+	protocolToggle.setAttribute("aria-pressed", String(showProtocol));
+	protocolToggle.textContent = showProtocol
+		? "隐藏原始协议事件"
+		: "展开原始协议事件";
+	protocolToggle.addEventListener("click", () => {
+		uiState.sessionTimelineShowProtocol = !showProtocol;
+		const parent = content;
+		const scrollTop = parent.scrollTop;
+		const scrollLeft = parent.scrollLeft;
+		while (parent.firstChild) parent.removeChild(parent.firstChild);
+		renderSessionTimeline(parent, nodeId);
+		parent.scrollTop = scrollTop;
+		parent.scrollLeft = scrollLeft;
+	});
+	toolbar.appendChild(protocolToggle);
+	content.appendChild(toolbar);
+
+	const timelineItems = buildRichTimelineItems(uiState.sessionEvents, {
+		showProtocol,
+	});
+	const hasEventTimes = uiState.sessionEvents.some((event) =>
+		Boolean(sessionEventTimestamp(event)),
+	);
+	if (!hasEventTimes) {
+		content.appendChild(
+			el(
+				"p",
+				"process-timeline-note",
+				"事件未记录具体时间，以下按采集顺序展示。",
+			),
+		);
+	}
+
+	const ul = el("ul", "process-timeline process-timeline-rich");
+	for (let index = 0; index < timelineItems.length; index += 1) {
+		const item = timelineItems[index];
+		const kindClass =
+			item.kind === "tool"
+				? item.isError
+					? "tool-end is-error"
+					: item.pending
+						? "tool-start"
+						: "tool-end"
+				: item.kind === "turn"
+					? "assistant"
+					: item.kind;
+		const li = el(
+			"li",
+			`process-timeline-item process-timeline-${kindClass}${hasEventTimes ? " has-time" : ""}`,
+		);
+		if (index === 0) li.classList.add("is-first");
+		if (index === timelineItems.length - 1) li.classList.add("is-last");
+		const rail = el("span", "process-timeline-rail");
+		rail.appendChild(el("span", "process-timeline-dot"));
+		li.appendChild(rail);
+		if (hasEventTimes) {
+			li.appendChild(
+				el("span", "process-timeline-time", formatSessionEventTime(item.event)),
+			);
+		}
+		const body = el("div", "process-timeline-body");
+		if (item.kind === "tool") {
+			body.appendChild(renderToolCard(item));
+		} else if (item.kind === "turn") {
+			body.appendChild(renderTurnCard(item));
+		} else if (item.kind === "lifecycle" && item.agentEnd) {
+			body.appendChild(renderLifecycleCard(item));
+		} else if (item.kind === "protocol") {
+			body.appendChild(renderProtocolCard(item));
+		} else {
+			body.appendChild(
+				el("span", "process-timeline-label", formatSessionEventLabel(item.event)),
+			);
+		}
+		li.appendChild(body);
+		ul.appendChild(li);
+	}
+	content.appendChild(ul);
+
+	const timelineState =
+		uiState.dagTimelineViewportState?.dagRunId === uiState.currentDagRunId &&
+		uiState.dagTimelineViewportState.nodeId === nodeId
+			? uiState.dagTimelineViewportState
+			: null;
+	content.addEventListener(
+		"scroll",
+		() => {
+			const followLatest = computeFollowLatest(
+				content.scrollTop,
+				content.scrollHeight,
+				content.clientHeight,
+			);
+			uiState.dagTimelineViewportState = updateDagTimelineViewportState(
+				uiState.dagTimelineViewportState,
+				uiState.currentDagRunId,
+				nodeId,
+				content.scrollLeft,
+				content.scrollTop,
+				followLatest,
+			);
+		},
+		{ passive: true },
+	);
+	if (timelineState?.followLatest ?? true) {
+		content.scrollLeft = timelineState?.scrollLeft ?? 0;
+		content.scrollTop = content.scrollHeight;
+	} else {
+		content.scrollLeft = timelineState.scrollLeft;
+		content.scrollTop = timelineState.scrollTop;
+	}
+}