ompchamber 0.3.0 → 0.4.0

package/src/shared/lib/chat/timeline/omp-callbacks.test.ts

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The sidebar is signalled on the run's FIRST completed assistant turn (not on
+ * every assistant segment, not on user turns, and not on notice rows), and the
+ * guard re-arms at every run start / stream reattach. `omp:session-updated`
+ * rides a leading+trailing throttle, so an extra dispatch per assistant segment
+ * would keep resetting that window and delay the refresh it exists to trigger.
+ *
+ * One case is driven through `foldAgentEvent` with a real omp frame: the
+ * callbacks see the MAPPED chamber role (`assistant` → `ai`), which a
+ * hand-built message would hide.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import {
+  createOmpAgentCallbacks,
+  type OmpAgentCallbacksDeps,
+} from '@/shared/lib/chat/timeline/omp-callbacks';
+import { foldAgentEvent, type OmpAgentFoldDeps } from '@/shared/lib/chat/omp/agent-events';
+import type { ChatMessageData, OmpAgentCallbacks, OmpAgentState } from '@/shared/types';
+
+/** omp's own shape for a completed assistant turn, before the mapper runs. */
+const OMP_ASSISTANT_TURN = {
+  role: 'assistant',
+  content: [{ type: 'text', text: 'hi' }],
+  timestamp: 1757943900000,
+};
+
+const assistantTurn = (id: string): ChatMessageData => ({ id, role: 'ai', content: 'hi' });
+const userTurn = (id: string): ChatMessageData => ({ id, role: 'user', content: 'yo' });
+const noticeRow = (id: string): ChatMessageData => ({ id, role: 'ai', content: '', notice: 'job done' });
+
+describe('createOmpAgentCallbacks first-assistant sidebar signal', () => {
+  const signals: Array<{ name: string; sessionId?: string }> = [];
+
+  // `bun test` runs without a DOM: the dispatch site is window-guarded, so the
+  // suite installs a recording stub and removes it again.
+  const installWindowStub = () => {
+    Object.assign(globalThis, {
+      window: {
+        dispatchEvent: (event: Event) => {
+          const custom = event as CustomEvent<{ sessionId?: string }>;
+          signals.push({ name: custom.type, sessionId: custom.detail?.sessionId });
+          return true;
+        },
+      },
+    });
+  };
+
+  beforeEach(() => {
+    signals.length = 0;
+    installWindowStub();
+  });
+
+  afterEach(() => {
+    Reflect.deleteProperty(globalThis, 'window');
+  });
+
+  function makeCallbacks(): OmpAgentCallbacks {
+    const deps: OmpAgentCallbacksDeps = {
+      removeDeliveredFromQueue: () => {},
+      setGenerating: () => {},
+      setGeneratingVerb: () => {},
+      scrollToBottom: () => {},
+      adoptedSessionIdRef: { current: null },
+      sessionIdRef: { current: 'sess-1' },
+      metaRefreshedRef: { current: null },
+      firstAssistantRef: { current: false },
+      refreshSessionMeta: () => {},
+      setLocalMessages: () => {},
+      aiPlaceholderIdRef: { current: null },
+      optimisticUserIdRef: { current: null },
+      pendingUserDisplaysRef: { current: [] },
+      persistMessages: () => {},
+      abortControllerRef: { current: null },
+      appSettings: {},
+      enqueueExtensionDialog: () => {},
+      withdrawExtensionDialog: () => {},
+    };
+    return createOmpAgentCallbacks(deps);
+  }
+
+  function makeFoldDeps(callbacks: OmpAgentCallbacks): OmpAgentFoldDeps {
+    let state: OmpAgentState = { isGenerating: false, connected: true, error: null };
+    return {
+      sessionId: 'sess-1',
+      setState: (update) => {
+        state = typeof update === 'function' ? update(state) : update;
+      },
+      callbacksRef: { current: callbacks },
+      toolResultsRef: { current: new Map<string, { output: string }>() },
+      lastToolMessageRef: { current: null },
+      interruptPendingRef: { current: false },
+      activityRef: { current: '' },
+      currentThinkingLevelRef: { current: undefined },
+      fileMutatingCallsRef: { current: new Set<string>() },
+    };
+  }
+
+  test('signals on the first completed assistant turn of each run only', () => {
+    const callbacks = makeCallbacks();
+
+    callbacks.onAgentStart?.();
+    expect(signals.map(s => s.name)).toEqual(['omp:session-updated']);
+
+    callbacks.onMessageEnd?.(assistantTurn('a1'));
+    expect(signals).toHaveLength(2);
+    expect(signals[1]?.sessionId).toBe('sess-1');
+
+    // Later segments of the same run, and the steering user echo, stay silent.
+    callbacks.onMessageEnd?.(assistantTurn('a2'));
+    callbacks.onMessageEnd?.(userTurn('u2'));
+    expect(signals).toHaveLength(2);
+
+    // The next run re-arms the guard.
+    callbacks.onAgentStart?.();
+    callbacks.onMessageEnd?.(assistantTurn('a3'));
+    expect(signals).toHaveLength(4);
+  });
+
+  test('re-arms on a mid-run stream reattach', () => {
+    const callbacks = makeCallbacks();
+
+    callbacks.onResumeStream?.();
+    callbacks.onMessageEnd?.(assistantTurn('a1'));
+    callbacks.onMessageEnd?.(assistantTurn('a2'));
+
+    expect(signals).toHaveLength(2);
+  });
+
+  test('never signals from user turns or notice rows alone', () => {
+    const callbacks = makeCallbacks();
+
+    callbacks.onMessageEnd?.(userTurn('u1'));
+    callbacks.onMessageEnd?.(noticeRow('n1'));
+
+    expect(signals).toHaveLength(0);
+  });
+
+  test('a real omp assistant message_end frame reaches the signal once', () => {
+    const deps = makeFoldDeps(makeCallbacks());
+
+    foldAgentEvent({ type: 'agent_start' }, deps);
+    foldAgentEvent({ type: 'message_end', message: OMP_ASSISTANT_TURN }, deps);
+    foldAgentEvent({ type: 'message_end', message: { ...OMP_ASSISTANT_TURN, timestamp: 1757943901000 } }, deps);
+
+    expect(signals).toHaveLength(2);
+  });
+});

package/src/shared/lib/chat/timeline/omp-callbacks.ts

@@ -14,8 +14,8 @@
 
 import type { Dispatch, SetStateAction } from 'preact/compat';
 import type { ChatMessageData, ExtensionUiDialogRequest, IncomingExtensionUiRequest, OmpAgentCallbacks } from '@/shared/types';
-import { normalizeNoticePositions } from '@/shared/lib/chat/order';
 import { triggerChatCompletionSound } from '@/client/hooks/ui/notification-sound';
+import { isNoticeRow } from '@/shared/lib/chat/notice-row';
 import { createRafBatch } from '@/shared/lib/chat/timeline/stream-raf';
 import { PHASE_VERBS } from '@/shared/lib/chat/timeline/tool-phrases';
 
@@ -54,6 +54,9 @@ export interface OmpAgentCallbacksDeps {
   adoptedSessionIdRef: { current: string | null };
   sessionIdRef: { current: string | null };
   metaRefreshedRef: { current: string | null };
+  /** Per-run guard: the sidebar is signalled once, on the run's first completed
+   *  assistant turn. Reset at every run start (and on stream reattach). */
+  firstAssistantRef: { current: boolean };
   refreshSessionMeta: (sid: string) => void;
   setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>;
   aiPlaceholderIdRef: { current: string | null };
@@ -77,6 +80,7 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
     adoptedSessionIdRef,
     sessionIdRef,
     metaRefreshedRef,
+    firstAssistantRef,
     refreshSessionMeta,
     setLocalMessages,
     aiPlaceholderIdRef,
@@ -103,6 +107,8 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
       setGenerating(true);
       setGeneratingVerb(PHASE_VERBS.thinking);
       setTimeout(() => scrollToBottom('smooth'), 50);
+      // A fresh run re-arms the first-assistant signal.
+      firstAssistantRef.current = false;
       const sid = adoptedSessionIdRef.current ?? sessionIdRef.current;
       if (sid) {
         // Sidebar signal on EVERY run start — the metaRefreshedRef guard below
@@ -123,6 +129,9 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
       setGenerating(true);
       setGeneratingVerb(PHASE_VERBS.thinking);
       setTimeout(() => scrollToBottom('smooth'), 50);
+      // Reattach re-arms the signal too: the reattached run's first assistant
+      // turn has not been signalled by THIS mount.
+      firstAssistantRef.current = false;
       const sid = adoptedSessionIdRef.current ?? sessionIdRef.current;
       // Reattach mid-run: the sidebar needs the `stream` status row.
       if (sid) window.dispatchEvent(new CustomEvent('omp:session-updated', { detail: { sessionId: sid } }));
@@ -139,21 +148,22 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
     onMessageUpdate: (msg) => {
       // React may invoke state updaters more than once (eager-state bailout),
       // so this ref mutation must stay OUTSIDE the updater to keep it pure.
-      if (msg.role !== 'user' && !msg.notice) optimisticUserIdRef.current = null;
+      if (msg.role !== 'user' && !isNoticeRow(msg)) optimisticUserIdRef.current = null;
       // Queue for the next frame, collapsing same-message bursts to the newest
       // full-content frame; scroll runs once per rendered frame.
       messageBatch.queue(prev => {
         const placeholderId = aiPlaceholderIdRef.current;
-        // Notice rows (e.g. background job done, system alerts) belong chronologically
-        // right before the next AI response, NEVER backwards before the initiating user message.
-        if (msg.notice) {
+        // Notice rows (e.g. background job done, system alerts) are appended in
+        // arrival order — the timeline renders state as-is, so omp's own write
+        // order is what the user sees.
+        if (isNoticeRow(msg)) {
           if (prev.some(m => m.id === msg.id)) return prev;
           // If an active AI placeholder is generating at the tail, insert notice immediately before it
           if (placeholderId && prev.some(m => m.id === placeholderId)) {
             const pIdx = prev.findIndex(m => m.id === placeholderId);
-            return normalizeNoticePositions([...prev.slice(0, pIdx), msg, ...prev.slice(pIdx)]);
+            return [...prev.slice(0, pIdx), msg, ...prev.slice(pIdx)];
           }
-          return normalizeNoticePositions([...prev, msg]);
+          return [...prev, msg];
         }
         // User turns from the stream (steering abort_and_prompt, queue
         // follow-up deliveries) carry no optimistic bubble — append them
@@ -205,6 +215,25 @@ export function createOmpAgentCallbacks(deps: OmpAgentCallbacksDeps): OmpAgentCa
       }, msg.id);
     },
     onMessageEnd: (msg) => {
+      // The run's first COMPLETED assistant turn. omp has durably written the
+      // turn by now — and, for a session it just titled, the auto title slot —
+      // so signal the sidebar here instead of waiting for agent_end (the whole
+      // run, tools included) or the 8s stream poll. A token-level
+      // (`onMessageUpdate`) signal would fire before the JSONL write and
+      // re-fetch the same scan; the completed turn is the first point where the
+      // refresh can actually return the new title/updated_at.
+      //
+      // Role is 'ai' here: toChatMessage collapses every non-user omp role to
+      // 'ai'. Notice rows (developer/system/custom) also carry 'ai', so they are
+      // excluded — a system-reminder row is not an answer.
+      if (msg.role === 'ai' && !isNoticeRow(msg) && !firstAssistantRef.current) {
+        firstAssistantRef.current = true;
+        const sid = adoptedSessionIdRef.current ?? sessionIdRef.current;
+        // Guarded: the fold also runs headless under `bun test` (no window).
+        if (sid && typeof window !== 'undefined') {
+          window.dispatchEvent(new CustomEvent('omp:session-updated', { detail: { sessionId: sid } }));
+        }
+      }
       // Apply any coalesced update before the terminal frame so the last chunk
       // is never dropped and the end always runs after it.
       messageBatch.flush();

package/src/shared/lib/chat/timeline/run-footer.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A run footer closes the AI response run, so it renders at the run's own
+ * boundary: after every row the run owns — including notice rows omp wrote at
+ * its tail — which keeps it immediately before the next user message. A run
+ * that is still generating, or a notice-only stretch, gets none.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { previousNonNoticeIndex, resolveRunFooters, streamingRowIndex } from '@/shared/lib/chat/timeline/run-footer';
+import type { ChatMessageData } from '@/shared/types';
+
+const user = (id: string, startedAt?: number): ChatMessageData => ({ id, role: 'user', content: 'yo', startedAt });
+const ai = (id: string, completedAt?: number): ChatMessageData => ({ id, role: 'ai', content: 'hi', completedAt });
+const notice = (id: string): ChatMessageData => ({ id, role: 'ai', content: '', notice: 'job done' });
+
+/** Slot message ids, one per timeline index — `null` where no footer renders. */
+const owners = (messages: ChatMessageData[], isGenerating = false) =>
+  resolveRunFooters(messages, isGenerating).map(slot => slot?.msg.id ?? null);
+
+describe('resolveRunFooters', () => {
+  test('renders the run footer after the run, before the next user message', () => {
+    expect(owners([user('u1'), ai('a1'), user('u2')])).toEqual([null, 'a1', null]);
+  });
+
+  test('renders after a trailing notice row, not before it', () => {
+    const messages = [user('u1'), ai('a1'), notice('n1'), user('u2')];
+    expect(owners(messages)).toEqual([null, null, 'a1', null]);
+  });
+
+  test('renders once per run at the run boundary', () => {
+    const messages = [user('u1'), ai('a1'), ai('a2'), notice('n1'), user('u2'), ai('a3')];
+    expect(owners(messages)).toEqual([null, null, null, 'a2', null, 'a3']);
+  });
+
+  test('measures the run span, falling back to the turn duration', () => {
+    const measured = resolveRunFooters([user('u1', 1_000), ai('a1', 61_000)], false);
+    expect(measured[1]?.durationMs).toBe(60_000);
+
+    const fallback = resolveRunFooters([user('u1'), { ...ai('a1'), durationMs: 2_500 }], false);
+    expect(fallback[1]?.durationMs).toBe(2_500);
+  });
+
+  test('holds the footer back while the run is still generating', () => {
+    expect(owners([user('u1'), ai('a1')], true)).toEqual([null, null]);
+    // A notice row at the tail ends the run but must not settle the footer.
+    expect(owners([user('u1'), ai('a1'), notice('n1')], true)).toEqual([null, null, null]);
+  });
+
+  test('settles the footer once the run completes', () => {
+    expect(owners([user('u1'), ai('a1'), notice('n1')], false)).toEqual([null, null, 'a1']);
+  });
+
+  test('gives a notice-only stretch no footer', () => {
+    expect(owners([user('u1'), notice('n1'), user('u2')])).toEqual([null, null, null]);
+  });
+
+  test('a notice carrying the answer is an ordinary AI row and owns the run', () => {
+    const diverted = { ...notice('n1'), model: 'deepseek-v4', usage: { totalTokens: 150_640 } };
+    const messages = [user('u1'), ai('a1'), diverted, user('u2')];
+
+    expect(owners(messages)).toEqual([null, null, 'n1', null]);
+    // While the run is still generating, the diverted answer streams — not the row before it.
+    expect(streamingRowIndex([user('u1'), ai('a1'), diverted])).toBe(2);
+  });
+});
+
+describe('streamingRowIndex', () => {
+  test('skips trailing notice rows so the answer is the streaming row', () => {
+    expect(streamingRowIndex([user('u1'), ai('a1'), notice('n1')])).toBe(1);
+    expect(streamingRowIndex([user('u1'), notice('n1')])).toBe(0);
+  });
+});
+
+describe('previousNonNoticeIndex', () => {
+  test('skips notice rows when pointing at the previous row', () => {
+    expect(previousNonNoticeIndex([user('u1'), ai('a1'), notice('n1'), ai('a2')])).toEqual([-1, 0, 1, 1]);
+  });
+});

package/src/shared/lib/chat/timeline/run-footer.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Run-footer placement for the chat timeline. The model/duration/token footer
+ * closes an AI response run, so it is emitted at the run's boundary — after
+ * every row the run owns, including notice rows omp wrote at its tail, and
+ * therefore immediately before the next user message. Nothing here reorders
+ * rows: the timeline renders file order and the footer is an extra row placed
+ * after the run's last one.
+ *
+ * "Notice row" means a real notice card: a row whose `notice` carries the
+ * answer instead is an ordinary AI row and owns its run (chat/notice-row.ts).
+ */
+
+import { responseRunDurationMs } from '@/shared/lib/chat/duration';
+import { isNoticeRow } from '@/shared/lib/chat/notice-row';
+import type { ChatMessageData } from '@/shared/types';
+
+export interface RunFooterSlot {
+  /** The run's last real AI message — the row carrying model/usage/duration. */
+  msg: ChatMessageData;
+  /** Index of that message, i.e. the row that streams during generation. */
+  ownerIndex: number;
+  /** Measured run span, falling back to the turn's own recorded duration. */
+  durationMs: number | null;
+}
+
+/**
+ * The row that streams while generating: the last non-notice row. Notice rows
+ * sit after the turn, so a plain "last item" check would mark a notice as the
+ * streaming row and settle the footer early.
+ */
+export function streamingRowIndex(messages: ChatMessageData[]): number {
+  let index = messages.length - 1;
+  while (index >= 0 && isNoticeRow(messages[index])) index--;
+  return index;
+}
+
+/**
+ * `previousNonNoticeIndex[idx]`: nearest non-notice row index strictly BEFORE
+ * idx, or -1 when none. Rows use it to tell an assistant continuation from a
+ * fresh turn without re-scanning the timeline per row.
+ */
+export function previousNonNoticeIndex(messages: ChatMessageData[]): number[] {
+  const indexes: number[] = new Array(messages.length);
+  let prevIdx = -1;
+  for (let i = 0; i < messages.length; i++) {
+    indexes[i] = prevIdx;
+    if (!isNoticeRow(messages[i])) prevIdx = i;
+  }
+  return indexes;
+}
+
+/**
+ * One entry per timeline index: non-null when a run footer renders AFTER that
+ * row. A run is a maximal stretch of non-user rows; its footer lands on the
+ * run's last row, so trailing notice rows no longer separate the footer from
+ * the following user message. A notice-only run gets none (no AI message to
+ * describe), and a run that is still generating is skipped until it settles.
+ */
+export function resolveRunFooters(
+  messages: ChatMessageData[],
+  isGenerating: boolean,
+): (RunFooterSlot | null)[] {
+  const count = messages.length;
+  const footers: (RunFooterSlot | null)[] = new Array(count).fill(null);
+  const streamingIdx = streamingRowIndex(messages);
+  let ownerIndex = -1;
+
+  for (let i = 0; i < count; i++) {
+    const msg = messages[i];
+    if (msg.role === 'user') {
+      ownerIndex = -1;
+      continue;
+    }
+    if (!isNoticeRow(msg)) ownerIndex = i;
+
+    const endsRun = i === count - 1 || messages[i + 1]?.role === 'user';
+    if (!endsRun || ownerIndex < 0) continue;
+
+    const owner = messages[ownerIndex];
+    // The answer is still streaming — no footer until the run settles.
+    if (isGenerating && ownerIndex === streamingIdx && owner.role === 'ai') continue;
+
+    footers[i] = {
+      msg: owner,
+      ownerIndex,
+      durationMs: responseRunDurationMs(messages, ownerIndex) ?? owner.durationMs ?? null,
+    };
+  }
+
+  return footers;
+}

package/src/shared/lib/chat/tool-output.test.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Tool output is rendered as markdown, with one override: an XML wrapper that
+ * opens the output is transport, not content, so it is peeled before parsing.
+ * What makes the parser hard is telling that wrapper apart from markup that IS
+ * the content — a tag in the middle of prose, a mismatched pair, a second
+ * element after the first — and from content markdown would reflow (a log, a
+ * JSON body) once the wrapper is gone.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { outputMarkdown, readToolOutput } from '@/shared/lib/chat/tool-output';
+
+describe('readToolOutput XML envelope', () => {
+  test('peels a wrapper that opens the output and keeps the trailing line', () => {
+    const output = readToolOutput(
+      '<system-reminder reason="rule_violation" rule="ts-no-inline-cast-access">\n' +
+        'MUST comply with the following instruction.\n' +
+        '</system-reminder>\n' +
+        'Successfully wrote 3604 bytes to src/a.ts',
+    );
+
+    expect(output.envelope?.tag).toBe('system-reminder');
+    expect(output.envelope?.attributes).toEqual({
+      reason: 'rule_violation',
+      rule: 'ts-no-inline-cast-access',
+    });
+    expect(output.content).toBe(
+      'MUST comply with the following instruction.\n\nSuccessfully wrote 3604 bytes to src/a.ts',
+    );
+  });
+
+  test('reads single-quoted and valueless attributes', () => {
+    expect(readToolOutput("<a rule='ts-x' flag>\nbody\n</a>").envelope?.attributes).toEqual({
+      rule: 'ts-x',
+      flag: '',
+    });
+  });
+
+  test('dedents the wrapper body so markdown reads it as prose, not a code block', () => {
+    const output = readToolOutput('<result>\n  # Judul\n  teks biasa\n</result>');
+
+    expect(output.content).toBe('# Judul\nteks biasa');
+    expect(output.format).toBe('markdown');
+    expect(outputMarkdown(output.content, output.format)).toBe('# Judul\nteks biasa');
+  });
+
+  test('handles a `>` inside an attribute value and nested elements', () => {
+    expect(readToolOutput('<a title="x > y">\n<b>1</b>\n</a>').content).toBe('<b>1</b>');
+  });
+
+  test('leaves markup that does not open the output alone', () => {
+    const raw = 'Set <name> to the file, then run <cmd />';
+    const output = readToolOutput(raw);
+
+    expect(output.envelope?.tag).toBeUndefined();
+    expect(output.content).toBe(raw);
+  });
+
+  test('leaves mismatched and self-closing roots alone', () => {
+    expect(readToolOutput('<a>\n<b>x</a>').envelope?.tag).toBeUndefined();
+    expect(readToolOutput('<hr />').envelope?.tag).toBeUndefined();
+    expect(readToolOutput('<!-- note -->\nbody').envelope?.tag).toBeUndefined();
+  });
+
+  test('does not peel when a second element follows the wrapper', () => {
+    expect(readToolOutput('<a>1</a><b>2</b>').envelope?.tag).toBeUndefined();
+  });
+});
+
+describe('outputMarkdown', () => {
+  test('fences JSON so the parser cannot reflow it', () => {
+    const output = readToolOutput('{\n  "a": 1\n}');
+
+    expect(output.format).toBe('json');
+    expect(outputMarkdown(output.content, output.format)).toBe('```json\n{\n  "a": 1\n}\n```');
+  });
+
+  test('fences a plain log without a language', () => {
+    expect(outputMarkdown('error: boom\n  at foo', 'text')).toBe('```\nerror: boom\n  at foo\n```');
+  });
+
+  test('outgrows a fence already present in the content', () => {
+    expect(outputMarkdown('a ``` b', 'json')).toBe('````json\na ``` b\n````');
+  });
+});

package/src/shared/lib/chat/tool-output.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The one rule every tool-output surface follows: **output is rendered as
+ * markdown**.
+ *
+ * Two things happen before the parser sees it:
+ *
+ * 1. An XML envelope wrapping the whole output is peeled
+ *    (`<system-reminder …>…</system-reminder>`, `<result>…</result>`). Those
+ *    tags are transport — left in place, markdown escapes them and the user
+ *    reads markup instead of the message it carries.
+ * 2. Content markdown would reflow gets fenced. A log, a JSON body, an HTML
+ *    dump have no blank lines and no markers: parsed as prose they collapse
+ *    into a single paragraph and their `#`/`-` lines turn into headings and
+ *    bullets. A fence is still markdown, and it is the only shape that keeps
+ *    such a blob verbatim.
+ */
+
+import { detectOutputFormat, type OutputFormat } from '@/shared/lib/chat/detect-format';
+import { unwrapXmlEnvelope, type XmlEnvelope } from '@/shared/lib/chat/xml-envelope';
+
+export interface ToolOutputText {
+  /** What the user reads: the XML envelope peeled off, if there was one. */
+  content: string;
+  /** Format of `content`, deciding how `outputMarkdown` renders it. */
+  format: OutputFormat;
+  /** Wrapper that was peeled — rendered as the output's header. */
+  envelope?: XmlEnvelope;
+}
+
+/** Read raw tool output into the text the timeline renders. */
+export function readToolOutput(text: string): ToolOutputText {
+  const envelope = unwrapXmlEnvelope(text);
+  const content = envelope ? [envelope.inner, envelope.rest].filter(Boolean).join('\n\n') : text;
+  return {
+    content,
+    format: detectOutputFormat(content),
+    ...(envelope ? { envelope } : {}),
+  };
+}
+
+/** Markdown for output content — verbatim formats are fenced so the parser
+ *  cannot reflow them; markdown itself passes through untouched. */
+export function outputMarkdown(content: string, format: OutputFormat): string {
+  if (!content || format === 'markdown') return content;
+  let longest = 0;
+  for (const run of content.match(/`+/g) ?? []) longest = Math.max(longest, run.length);
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}${format === 'text' ? '' : format}\n${content}\n${fence}`;
+}