cli-jaw 2.0.4 → 2.0.5

package/public/js/features/help-dialog.ts

@@ -16,7 +16,11 @@ export function initHelpDialog(): void {
     document.addEventListener('keydown', handleKeydownCapture, true);
 }
 
-export function openHelpDialog(topicId: HelpTopicId, opener: HTMLElement | null = null): void {
+export function openHelpDialog(
+    topicId: HelpTopicId,
+    opener: HTMLElement | null = null,
+    topicIds: readonly HelpTopicId[] = [topicId],
+): void {
     const topic = HELP_TOPICS[topicId];
     if (!topic) {
         console.warn('[help-dialog] unknown topic:', topicId);
@@ -24,7 +28,7 @@ export function openHelpDialog(topicId: HelpTopicId, opener: HTMLElement | null
     }
     ensureDialog();
     lastOpener = opener;
-    renderTopic(topic);
+    renderTopic(topicId, normalizeTopicIds(topicIds, topicId));
     overlay?.classList.add('open');
     overlay?.setAttribute('aria-hidden', 'false');
     openState = true;
@@ -54,7 +58,7 @@ function handleDocumentClick(event: MouseEvent): void {
         return;
     }
     event.preventDefault();
-    openHelpDialog(topicId, trigger);
+    openHelpDialog(topicId, trigger, parseTopicList(trigger.getAttribute('data-help-topics'), topicId));
 }
 
 function handleKeydownCapture(event: KeyboardEvent): void {
@@ -115,33 +119,90 @@ function ensureDialog(): void {
     document.body.append(overlay);
 }
 
-function renderTopic(topic: HelpTopic): void {
+function renderTopic(topicId: HelpTopicId, topicIds: readonly HelpTopicId[] = [topicId]): void {
     if (!titleEl || !bodyEl || !closeBtn) return;
+    const topic = HELP_TOPICS[topicId];
     titleEl.textContent = t(topic.titleKey);
     closeBtn.setAttribute('aria-label', t('help.close'));
     bodyEl.replaceChildren();
 
-    appendTextSection(t('help.section.what'), t(topic.introKey));
-    appendTextSection(t('help.section.effect'), t(topic.effectKey), 'help-effect-text');
-    appendListSection(t('help.section.useWhen'), topic.useWhenKeys);
-    appendListSection(t('help.section.howTo'), topic.howToKeys);
-    appendListSection(t('help.section.example'), topic.exampleKeys, false, 'help-example-list');
-    if (topic.avoidWhenKeys?.length) appendListSection(t('help.section.avoidWhen'), topic.avoidWhenKeys);
-    if (topic.relatedKeys?.length) appendListSection(t('help.section.related'), topic.relatedKeys, true);
+    const content = document.createElement('div');
+    content.className = 'help-dialog-content';
+    appendTopicSections(content, topic);
+
+    if (topicIds.length <= 1) {
+        bodyEl.append(content);
+        return;
+    }
+
+    const layout = document.createElement('div');
+    layout.className = 'help-dialog-layout';
+    layout.append(createTopicNav(topicIds, topicId), content);
+    bodyEl.append(layout);
+}
+
+function appendTopicSections(parent: HTMLElement, topic: HelpTopic): void {
+    appendTextSection(parent, t('help.section.what'), t(topic.introKey));
+    appendTextSection(parent, t('help.section.effect'), t(topic.effectKey), 'help-effect-text');
+    appendListSection(parent, t('help.section.useWhen'), topic.useWhenKeys);
+    appendListSection(parent, t('help.section.howTo'), topic.howToKeys);
+    appendListSection(parent, t('help.section.example'), topic.exampleKeys, false, 'help-example-list');
+    if (topic.avoidWhenKeys?.length) appendListSection(parent, t('help.section.avoidWhen'), topic.avoidWhenKeys);
+    if (topic.relatedKeys?.length) appendListSection(parent, t('help.section.related'), topic.relatedKeys, true);
+}
+
+function createTopicNav(topicIds: readonly HelpTopicId[], activeTopicId: HelpTopicId): HTMLElement {
+    const nav = document.createElement('nav');
+    nav.className = 'help-dialog-nav';
+    nav.setAttribute('aria-label', t('help.section.related'));
+
+    for (const id of topicIds) {
+        const topic = HELP_TOPICS[id];
+        const item = document.createElement('button');
+        item.type = 'button';
+        item.className = 'help-dialog-nav-item';
+        item.textContent = t(topic.titleKey);
+        if (id === activeTopicId) {
+            item.classList.add('active');
+            item.setAttribute('aria-current', 'page');
+        }
+        item.addEventListener('click', () => renderTopic(id, topicIds));
+        nav.append(item);
+    }
+
+    return nav;
+}
+
+function parseTopicList(raw: string | null, fallback: HelpTopicId): HelpTopicId[] {
+    const values = raw?.split(/[\s,]+/).filter(Boolean) ?? [];
+    return normalizeTopicIds(values, fallback);
+}
+
+function normalizeTopicIds(values: readonly string[], fallback: HelpTopicId): HelpTopicId[] {
+    const ids: HelpTopicId[] = [];
+    for (const value of values) {
+        if (isHelpTopicId(value) && !ids.includes(value)) ids.push(value);
+    }
+    if (!ids.includes(fallback)) ids.unshift(fallback);
+    return ids;
 }
 
-function appendTextSection(heading: string, text: string, className?: string): void {
-    if (!bodyEl) return;
+function appendTextSection(parent: HTMLElement, heading: string, text: string, className?: string): void {
     const section = createSection(heading);
     const p = document.createElement('p');
     if (className) p.className = className;
     p.textContent = text;
     section.append(p);
-    bodyEl.append(section);
+    parent.append(section);
 }
 
-function appendListSection(heading: string, keys: string[], related = false, className?: string): void {
-    if (!bodyEl) return;
+function appendListSection(
+    parent: HTMLElement,
+    heading: string,
+    keys: string[],
+    related = false,
+    className?: string,
+): void {
     const section = createSection(heading);
     const list = document.createElement('ul');
     list.className = className ?? (related ? 'help-related-list' : 'help-dialog-list');
@@ -151,7 +212,7 @@ function appendListSection(heading: string, keys: string[], related = false, cla
         list.append(item);
     }
     section.append(list);
-    bodyEl.append(section);
+    parent.append(section);
 }
 
 function createSection(heading: string): HTMLElement {

package/public/js/features/message-actions.ts

@@ -0,0 +1,157 @@
+import { api } from '../api.js';
+import { escapeHtml } from '../render.js';
+import { ICONS } from '../icons.js';
+import { bindToolItemInteractions } from './tool-ui.js';
+import { bindProcessBlockInteractions } from './process-block.js';
+
+type MessageActionSource = {
+    role: string;
+    messageId: string;
+    turnIndex: number | null;
+};
+
+type MessageActionsOptions = {
+    onStatus?: (message: string) => void;
+};
+
+type ReminderFromMessageResponse = {
+    ok?: boolean;
+    item?: { id?: string; title?: string };
+    error?: string;
+};
+
+function currentPort(): number | null {
+    const port = Number(window.location.port);
+    if (Number.isFinite(port) && port > 0) return port;
+    const match = window.location.pathname.match(/^\/i\/(\d+)/);
+    return match ? Number(match[1]) : null;
+}
+
+function compactReminderTitle(text: string): string {
+    const firstLine = text.split(/\r?\n/).map(line => line.trim()).find(Boolean);
+    if (!firstLine) return 'Pinned reminder';
+    return firstLine.length > 96 ? `${firstLine.slice(0, 93)}...` : firstLine;
+}
+
+function messageText(msg: Element): string {
+    const content = msg.querySelector('.msg-content') as HTMLElement | null;
+    return content?.getAttribute('data-raw') || content?.innerText || content?.textContent || '';
+}
+
+function parseTurnIndex(value: string | undefined): number | null {
+    if (!value) return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+function sourcePayload(msg: HTMLElement, text: string): Record<string, unknown> {
+    const port = currentPort();
+    const messageId = msg.dataset['messageId'] || '';
+    return {
+        title: compactReminderTitle(text),
+        notes: text,
+        priority: 'normal',
+        instanceId: msg.dataset['instanceId'] || (port ? `port:${port}` : 'browser'),
+        messageId,
+        turnIndex: parseTurnIndex(msg.dataset['turnIndex']),
+        port,
+        threadKey: window.location.pathname,
+        sourceText: text,
+    };
+}
+
+function setCopied(btn: HTMLElement): void {
+    btn.classList.add('copied');
+    btn.innerHTML = ICONS.checkSimple;
+    setTimeout(() => {
+        btn.classList.remove('copied');
+        btn.textContent = '';
+    }, 600);
+}
+
+async function copyMessage(btn: HTMLElement): Promise<void> {
+    const msg = btn.closest('.msg');
+    if (!msg) return;
+    await navigator.clipboard.writeText(messageText(msg));
+    setCopied(btn);
+}
+
+async function pinMessage(btn: HTMLElement, options: MessageActionsOptions): Promise<void> {
+    const msg = btn.closest('.msg') as HTMLElement | null;
+    if (!msg) return;
+    const text = messageText(msg).trim();
+    if (!text) {
+        options.onStatus?.('Cannot pin an empty message as a reminder.');
+        return;
+    }
+    btn.setAttribute('aria-busy', 'true');
+    btn.classList.add('is-pinning');
+    try {
+        const result = await api<ReminderFromMessageResponse>('/api/dashboard/reminders/from-message', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(sourcePayload(msg, text)),
+        });
+        if (!result?.ok) throw new Error(result?.error || 'Reminder pin failed');
+        btn.classList.add('is-pinned');
+        options.onStatus?.(`Pinned reminder: ${result.item?.title || compactReminderTitle(text)}`);
+    } catch (error) {
+        options.onStatus?.(`Reminder pin failed: ${(error as Error).message}`);
+    } finally {
+        btn.classList.remove('is-pinning');
+        btn.removeAttribute('aria-busy');
+    }
+}
+
+function toggleToolGroup(target: HTMLElement): boolean {
+    const summary = target.closest('.tool-group-summary') as HTMLElement | null;
+    if (!summary) return false;
+    const group = summary.closest('.tool-group');
+    const details = summary.nextElementSibling as HTMLElement;
+    if (group && details) {
+        const isExpanding = !group.classList.contains('expanded');
+        group.classList.toggle('expanded');
+        details.classList.toggle('collapsed');
+        summary.setAttribute('aria-expanded', isExpanding ? 'true' : 'false');
+    }
+    return true;
+}
+
+export function messageSourceAttributes(source: MessageActionSource): string {
+    const attrs = [
+        `data-message-role="${escapeHtml(source.role)}"`,
+        `data-message-id="${escapeHtml(source.messageId)}"`,
+    ];
+    if (source.turnIndex !== null) attrs.push(`data-turn-index="${source.turnIndex}"`);
+    if (typeof window !== 'undefined') {
+        const port = currentPort();
+        if (port) attrs.push(`data-instance-id="port:${port}"`);
+    }
+    return attrs.join(' ');
+}
+
+export function renderMessageActionsHtml(): string {
+    return '<div class="msg-actions"><button class="msg-pin-reminder" type="button" title="Pin as reminder" aria-label="Pin as reminder"></button><button class="msg-copy" type="button" title="Copy" aria-label="Copy message"></button></div>';
+}
+
+export function initMessageActions(options: MessageActionsOptions = {}): void {
+    const chatMessages = document.getElementById('chatMessages');
+    if (!chatMessages) return;
+    bindProcessBlockInteractions(chatMessages);
+    bindToolItemInteractions(chatMessages);
+    chatMessages.addEventListener('click', (e) => {
+        const target = e.target as HTMLElement;
+        if (toggleToolGroup(target)) return;
+
+        const copyBtn = target.closest('.msg-copy') as HTMLElement | null;
+        if (copyBtn) {
+            copyMessage(copyBtn).catch((error) => {
+                options.onStatus?.(`Copy failed: ${(error as Error).message}`);
+            });
+            return;
+        }
+
+        const pinBtn = target.closest('.msg-pin-reminder') as HTMLElement | null;
+        if (pinBtn) void pinMessage(pinBtn, options);
+    });
+}

package/public/js/features/message-history.ts

@@ -0,0 +1,138 @@
+import { api } from '../api.js';
+import { renderMarkdown, linkifyFilePaths } from '../render.js';
+import { renderMermaidBlocks } from '../render.js';
+import { getVirtualScroll, VS_THRESHOLD, type VirtualItem } from '../virtual-scroll.js';
+import { bootstrapVirtualHistory, type VirtualHistoryBootstrapDeps } from '../virtual-scroll-bootstrap.js';
+import { activateWidgets } from '../diagram/iframe-renderer.js';
+import { ICONS } from '../icons.js';
+import { t } from './i18n.js';
+import { cacheMessages, getScopedMessages, setMessageScope } from './idb-cache.js';
+import { addMessage, addSystemMsg, showEmptyState } from './chat-messages.js';
+import { buildLazyVirtualMessageItem } from './message-item-html.js';
+import { addStep, buildProcessBlockHtml, collapseBlock, createProcessBlock } from './process-block.js';
+import { hasAgentToolBlock, normalizeAgentToolBlocks } from './process-block-dom.js';
+import { normalizeMessageToolLog, parseToolLog, toProcessSteps, type MessageItem } from './process-log-adapter.js';
+import { canFollowAfterRestore, ensureScrollTracking, markFollowingBottom, settleChatBottomAfterInitialLoad } from './chat-scroll.js';
+import { updateStatMsgs } from './ui-status.js';
+
+export function buildVirtualHistoryItems(msgs: MessageItem[]): VirtualItem[] {
+    return msgs.map((m, index) => buildLazyVirtualMessageItem(normalizeMessageToolLog(m), index));
+}
+
+export function registerVirtualScrollCallbacks(vs: ReturnType<typeof getVirtualScroll>): void {
+    vs.onLazyRender = (targets: HTMLElement[]) => {
+        for (const el of targets) {
+            if (!el.classList.contains('lazy-pending')) continue;
+            const raw = el.getAttribute('data-raw') || '';
+            const msgEl = el.closest('.msg-agent') as HTMLElement | null;
+            const body = msgEl?.querySelector('.agent-body') as HTMLElement | null;
+            const rawToolLog = body?.dataset['toolLog'] || '';
+            if (msgEl && body && rawToolLog && !hasAgentToolBlock(msgEl)) {
+                const tools = parseToolLog(rawToolLog);
+                if (tools.length > 0) {
+                    el.insertAdjacentHTML('beforebegin', buildProcessBlockHtml(toProcessSteps(tools), true));
+                }
+                delete body.dataset['toolLog'];
+                normalizeAgentToolBlocks(msgEl);
+            }
+            el.innerHTML = raw ? renderMarkdown(raw) : '';
+            el.classList.remove('lazy-pending');
+            activateWidgets(el);
+            void renderMermaidBlocks(el, { immediate: true });
+        }
+    };
+    vs.onPostRender = (viewport: HTMLElement) => {
+        activateWidgets(viewport);
+        linkifyFilePaths(viewport);
+        void renderMermaidBlocks(viewport, { immediate: true });
+    };
+}
+
+export function makeBootstrapDeps(
+    vs: ReturnType<typeof getVirtualScroll>,
+    options: { forceInitialBottom?: boolean; restoreIndex?: number | null } = {},
+): VirtualHistoryBootstrapDeps {
+    const shouldFollowBottom = options.forceInitialBottom ? () => true : canFollowAfterRestore;
+    return {
+        registerCallbacks: () => registerVirtualScrollCallbacks(vs),
+        setItems: (items, opts) => vs.setItems(items, opts),
+        activateIfNeeded: (toBottom) => vs.activateIfNeeded(toBottom),
+        scrollToBottom: () => vs.scrollToBottom(),
+        scrollToIndex: (index) => vs.scrollToIndex(index),
+        shouldFollowBottom,
+        restoreIndex: options.restoreIndex ?? null,
+        onBeforeVirtualHistoryBootstrap: () => { ensureScrollTracking(); },
+        onAfterVirtualHistoryBottomed: () => {
+            markFollowingBottom();
+            settleChatBottomAfterInitialLoad();
+        },
+    };
+}
+
+function hydrateSmallHistory(messages: MessageItem[]): void {
+    messages.forEach(m => {
+        const div = addMessage(m.role === 'assistant' ? 'agent' : m.role, m.content, m.cli);
+        if (m.role === 'assistant' && m.tool_log) {
+            const tools = parseToolLog(m.tool_log);
+            if (tools.length > 0) {
+                const body = div.querySelector('.agent-body') as HTMLElement;
+                if (body) {
+                    const pb = createProcessBlock(body);
+                    for (const tool of toProcessSteps(tools)) addStep(pb, tool);
+                    collapseBlock(pb);
+                }
+            }
+        }
+    });
+}
+
+export async function loadMessages(): Promise<void> {
+    const vs = getVirtualScroll();
+    const chatEl = document.getElementById('chatMessages');
+    try {
+        const settings = await api<{ workingDir?: string }>('/api/settings');
+        if (settings?.workingDir) setMessageScope(settings.workingDir);
+    } catch { /* localStorage fallback already initialized currentScope */ }
+    const msgs = await api<MessageItem[]>('/api/messages');
+    if (msgs !== null) {
+        const safeMsgs = msgs.map(normalizeMessageToolLog);
+        const hadRenderedHistory = Boolean(chatEl?.querySelector('.msg')) || vs.active;
+        const savedIndex = vs.active ? vs.firstVisibleIndex() : null;
+        vs.clear();
+        if (chatEl) chatEl.innerHTML = '';
+        if (safeMsgs.length >= VS_THRESHOLD) {
+            bootstrapVirtualHistory(buildVirtualHistoryItems(safeMsgs), makeBootstrapDeps(vs, {
+                forceInitialBottom: !hadRenderedHistory,
+                restoreIndex: hadRenderedHistory ? savedIndex : null,
+            }));
+        } else {
+            hydrateSmallHistory(safeMsgs);
+            if (!hadRenderedHistory) settleChatBottomAfterInitialLoad();
+        }
+        cacheMessages(safeMsgs.map(m => ({
+            role: m.role, content: m.content, cli: m.cli ?? null, tool_log: m.tool_log ?? null, timestamp: Date.now(),
+        }))).catch(() => {});
+        updateStatMsgs(safeMsgs.length);
+        showEmptyState();
+        return;
+    }
+    if (chatEl && chatEl.children.length > 0) {
+        showEmptyState();
+        return;
+    }
+    const cached = await getScopedMessages();
+    if (cached.length > 0) {
+        const safeCached = (cached as MessageItem[]).map(normalizeMessageToolLog);
+        if (safeCached.length >= VS_THRESHOLD) {
+            bootstrapVirtualHistory(buildVirtualHistoryItems(safeCached), makeBootstrapDeps(vs, {
+                forceInitialBottom: true,
+            }));
+        } else {
+            hydrateSmallHistory(safeCached);
+            settleChatBottomAfterInitialLoad();
+        }
+        addSystemMsg(`${ICONS.warning} ${t('ui.offline.banner')}`);
+        updateStatMsgs(safeCached.length);
+    }
+    showEmptyState();
+}

package/public/js/features/message-item-html.ts

@@ -0,0 +1,34 @@
+import { escapeHtml, stripOrchestration } from '../render.js';
+import { generateId } from '../uuid.js';
+import { getAppName } from './appname.js';
+import { getAgentAvatarMarkup, getUserAvatarMarkup } from './avatar.js';
+import { t } from './i18n.js';
+import { messageSourceAttributes, renderMessageActionsHtml } from './message-actions.js';
+import { formatUserPrompt } from './chat-messages.js';
+import { sanitizedToolLogJson, type MessageItem } from './process-log-adapter.js';
+import type { VirtualItem } from '../virtual-scroll.js';
+
+function getAgentIcon(_cli?: string | null): string {
+    return getAgentAvatarMarkup();
+}
+
+export function buildLazyVirtualMessageItem(m: MessageItem, index: number): VirtualItem {
+    const role = m.role === 'assistant' ? 'agent' : m.role;
+    const messageId = generateId();
+    const sourceAttrs = messageSourceAttributes({ role, messageId, turnIndex: index });
+    const rawContent = stripOrchestration(
+        role === 'user' ? formatUserPrompt(m.content) : m.content,
+    );
+    const label = escapeHtml(role === 'user' ? t('msg.you') : getAppName());
+    const sanitizedToolLog = m.role === 'assistant' && m.tool_log
+        ? sanitizedToolLogJson(m.tool_log)
+        : null;
+    const rawToolLog = sanitizedToolLog ? escapeHtml(sanitizedToolLog) : '';
+    const toolAttr = rawToolLog ? ` data-tool-log="${rawToolLog}"` : '';
+    const contentHtml = `<div class="msg-content lazy-pending" data-raw="${escapeHtml(rawContent)}"></div>`;
+    const actions = renderMessageActionsHtml();
+    const html = role === 'agent'
+        ? `<div class="msg msg-agent" ${sourceAttrs}><div class="agent-icon" aria-hidden="true">${getAgentIcon(m.cli)}</div><div class="agent-body"${toolAttr}>${contentHtml}${actions}</div></div>`
+        : `<div class="msg msg-${role}" ${sourceAttrs}><div class="user-body"><div class="msg-label">${label}</div>${contentHtml}${actions}</div><div class="user-icon" aria-hidden="true">${getUserAvatarMarkup()}</div></div>`;
+    return { id: generateId(), html, height: 80, rehydratesProcessDetails: Boolean(rawToolLog) };
+}

package/public/js/features/preview-shortcut-bridge.ts

@@ -0,0 +1,29 @@
+// Forward Alt-modified keyboard shortcuts from iframe to parent manager window.
+// Only active when the page is embedded as an iframe (preview mode).
+
+const FORWARD_KEYS = new Set(['j', 'k', 'i', 'n', 'p']);
+
+export function initPreviewShortcutBridge(): void {
+    if (window.parent === window) return;
+
+    document.addEventListener('keydown', (e) => {
+        if (!e.altKey) return;
+        if (e.ctrlKey || e.metaKey) return;
+        let key = e.key.toLowerCase();
+        // macOS Option+letter produces special chars (e.g. ∆ for Alt+J).
+        if (key.length !== 1 || !FORWARD_KEYS.has(key)) {
+            if (e.code?.startsWith('Key')) key = e.code.slice(3).toLowerCase();
+        }
+        if (!FORWARD_KEYS.has(key)) return;
+
+        e.preventDefault();
+        try {
+            window.parent.postMessage({
+                type: 'jaw-preview-shortcut',
+                key,
+                altKey: true,
+                shiftKey: e.shiftKey,
+            }, '*');
+        } catch { /* cross-origin guard */ }
+    });
+}

package/public/js/features/process-block-dom.ts

@@ -0,0 +1,175 @@
+import { ICONS } from '../icons.js';
+import {
+    getStoredProcessStepDetail,
+    processStepMetaFromStore,
+    releaseProcessBlockDetails,
+    type ProcessBlockState,
+    type ProcessStep,
+} from './process-block.js';
+import type { ToolLogEntry } from './tool-ui.js';
+
+const TOOL_BLOCK_SELECTOR =
+    ':scope > .process-block, :scope > .tool-group, ' +
+    ':scope > .msg-content > .process-block, :scope > .msg-content > .tool-group';
+
+function agentBody(agentMsg: HTMLElement): HTMLElement | null {
+    return agentMsg.querySelector('.agent-body') as HTMLElement | null;
+}
+
+function agentToolBlocks(agentMsg: HTMLElement): HTMLElement[] {
+    const body = agentBody(agentMsg);
+    return body ? Array.from(body.querySelectorAll<HTMLElement>(TOOL_BLOCK_SELECTOR)) : [];
+}
+
+function preferredAgentToolBlock(body: HTMLElement): HTMLElement | null {
+    const content = body.querySelector(':scope > .msg-content') as HTMLElement | null;
+    return body.querySelector(':scope > .process-block')
+        ?? body.querySelector(':scope > .tool-group')
+        ?? content?.querySelector(':scope > .process-block')
+        ?? content?.querySelector(':scope > .tool-group')
+        ?? null;
+}
+
+export function normalizeAgentToolBlocks(agentMsg: HTMLElement): void {
+    const body = agentBody(agentMsg);
+    if (!body) return;
+    const content = body.querySelector('.msg-content') as HTMLElement | null;
+    const blocks = agentToolBlocks(agentMsg);
+    if (blocks.length === 0) return;
+    const keep = preferredAgentToolBlock(body) ?? blocks[0];
+    if (content && keep.parentElement !== body) body.insertBefore(keep, content);
+    for (const block of blocks) {
+        if (block !== keep) {
+            releaseProcessBlockDetails(block);
+            block.remove();
+        }
+    }
+}
+
+export function hasAgentToolBlock(agentMsg: HTMLElement): boolean {
+    return agentToolBlocks(agentMsg).length > 0;
+}
+
+function processStepTypeFromDom(type?: string): ProcessStep['type'] {
+    return type === 'thinking' || type === 'search' || type === 'subagent' ? type : 'tool';
+}
+
+function processStepStatusFromDom(status?: string): ProcessStep['status'] {
+    return status === 'done' || status === 'error' ? status : 'running';
+}
+
+function processStepFromDom(row: HTMLElement): ProcessStep | null {
+    const id = row.dataset['stepId'] || '';
+    if (!id) return null;
+    const storedMeta = processStepMetaFromStore(id);
+    const label = row.querySelector('.process-step-label')?.textContent?.trim() || '';
+    const pre = row.querySelector('.process-step-full') as HTMLElement | null;
+    const detail = pre?.dataset['detailLazy'] === 'true'
+        ? getStoredProcessStepDetail(id) || storedMeta?.preview || ''
+        : pre?.textContent || getStoredProcessStepDetail(id) || storedMeta?.preview || '';
+    const iconEl = row.querySelector('.process-step-icon') as HTMLElement | null;
+    const icon = iconEl?.innerHTML || ICONS.tool;
+    const startTime = Number(row.dataset['startTime'] || '');
+    return {
+        id,
+        type: storedMeta?.type || processStepTypeFromDom(row.dataset['type']),
+        icon: storedMeta?.icon || icon,
+        rawIcon: storedMeta?.rawIcon,
+        label: storedMeta?.label || label,
+        isEmployee: storedMeta?.isEmployee === true || row.dataset['isEmployee'] === 'true',
+        detail,
+        detailPreview: storedMeta?.preview,
+        detailLength: storedMeta?.detailLength,
+        detailTruncated: storedMeta?.detailTruncated,
+        stepRef: storedMeta?.stepRef || row.dataset['stepRef'] || '',
+        traceRunId: storedMeta?.traceRunId || row.dataset['traceRunId'] || '',
+        traceSeq: storedMeta?.traceSeq || Number(row.dataset['traceSeq'] || 0) || undefined,
+        detailAvailable: storedMeta?.detailAvailable,
+        detailBytes: storedMeta?.detailBytes,
+        rawRetentionStatus: storedMeta?.rawRetentionStatus,
+        status: storedMeta?.status || processStepStatusFromDom(row.dataset['status']),
+        startTime: Number.isFinite(startTime) && startTime > 0 ? startTime : Date.now(),
+    };
+}
+
+export function currentProcessBlockFromDom(agentMsg: HTMLElement): ProcessBlockState | null {
+    const block = agentBody(agentMsg)?.querySelector(':scope > .process-block') as HTMLElement | null;
+    if (!block) return null;
+    const steps = Array.from(block.querySelectorAll<HTMLElement>('.process-step'))
+        .map(processStepFromDom)
+        .filter((step): step is ProcessStep => Boolean(step));
+    return { element: block, steps, collapsed: block.classList.contains('collapsed') };
+}
+
+function processStepToToolLog(step: ProcessStep, finalize = false): ToolLogEntry {
+    const detail = getStoredProcessStepDetail(step.id) || step.detail || step.detailPreview || '';
+    const status = finalize && step.status === 'running' ? 'done' : step.status;
+    return {
+        icon: step.rawIcon || step.icon || ICONS.tool,
+        rawIcon: step.rawIcon || step.icon || '',
+        label: step.label || 'tool',
+        isEmployee: step.isEmployee === true,
+        detail,
+        toolType: step.type,
+        stepRef: step.stepRef || '',
+        status,
+        traceRunId: step.traceRunId || '',
+        traceSeq: step.traceSeq,
+        detailAvailable: step.detailAvailable,
+        detailBytes: step.detailBytes,
+        rawRetentionStatus: step.rawRetentionStatus,
+    };
+}
+
+function processStepFromMeta(stepId: string, finalize = false): ToolLogEntry | null {
+    const meta = processStepMetaFromStore(stepId);
+    if (!meta) return null;
+    const status = finalize && meta.status === 'running' ? 'done' : meta.status;
+    return {
+        icon: meta.rawIcon || meta.icon || ICONS.tool,
+        rawIcon: meta.rawIcon || meta.icon || '',
+        label: meta.label || 'tool',
+        isEmployee: meta.isEmployee === true,
+        detail: getStoredProcessStepDetail(stepId) || meta.preview || '',
+        toolType: meta.type,
+        stepRef: meta.stepRef || '',
+        status,
+        traceRunId: meta.traceRunId || '',
+        traceSeq: meta.traceSeq,
+        detailAvailable: meta.detailAvailable,
+        detailBytes: meta.detailBytes,
+        rawRetentionStatus: meta.rawRetentionStatus,
+    };
+}
+
+export function serializeProcessStepsForToolLog(source: ProcessBlockState | HTMLElement | null, finalize = false): ToolLogEntry[] {
+    if (!source) return [];
+    if ('steps' in source) return source.steps.map(step => processStepToToolLog(step, finalize));
+    const ids = new Set<string>();
+    source.querySelectorAll<HTMLElement>('.process-block[data-process-step-ids]').forEach(block => {
+        (block.dataset['processStepIds'] || '').split(/\s+/).filter(Boolean).forEach(id => ids.add(id));
+    });
+    source.querySelectorAll<HTMLElement>('.process-step[data-step-id]').forEach(row => {
+        const id = row.dataset['stepId'];
+        if (id) ids.add(id);
+    });
+    const entries: ToolLogEntry[] = [];
+    ids.forEach(id => {
+        const fromMeta = processStepFromMeta(id, finalize);
+        if (fromMeta) {
+            entries.push(fromMeta);
+            return;
+        }
+        const row = source.querySelector<HTMLElement>(`.process-step[data-step-id="${CSS.escape(id)}"]`);
+        const step = row ? processStepFromDom(row) : null;
+        if (step) entries.push(processStepToToolLog(step, finalize));
+    });
+    return entries;
+}
+
+export function removeAgentToolBlocks(agentMsg: HTMLElement): void {
+    for (const block of agentToolBlocks(agentMsg)) {
+        releaseProcessBlockDetails(block);
+        block.remove();
+    }
+}