@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/omp/session/parse-message-blocks.test.ts

@@ -0,0 +1,322 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Core behavior of the canonical omp message-content parser — the single
+ * source of truth shared by the live SSE path and the JSONL reload path. A
+ * regression here silently changes what every chat bubble and tool card
+ * renders, so these cases pin the parts that look "cleanable" but are load
+ * bearing:
+ *
+ * - `extractText` keeps only `type:'text'` blocks with a string body and joins
+ *   them with `\n`; every other shape yields `''`.
+ * - `inferToolType` is an ordered substring table, not a map: the first word
+ *   in the fixed order wins, so `todo_write` classifies as an edit and
+ *   `github_search` as a filesystem search. Input is lowercased first.
+ * - `parseMessageBlocks` argument extraction uses first-string-wins key lists
+ *   (an empty string stops the search), keeps raw args as `input` but drops
+ *   the empty object, falls back to the hashline patch header for `target`,
+ *   and pairs tool results either by toolCallId or with the most recent call.
+ * - `toToolCallData` derives status from output/streaming/isError precedence
+ *   and strips the synthetic `i` intent key from the stored input.
+ * - `isBlobImageRef` is a case-sensitive prefix test, not a digest validator.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { ToolType } from '@/shared/types/chat';
+import {
+  extractText,
+  inferToolType,
+  parseMessageBlocks,
+  type ParsedMessageBlocks,
+} from '@/shared/lib/omp/session/parse-message-blocks';
+
+const emptyParsed = (): ParsedMessageBlocks => ({
+  toolCalls: [],
+  inlineOutputs: new Map(),
+  inlineImages: new Map(),
+  textParts: [],
+});
+
+describe('extractText', () => {
+  test('returns a plain string content unchanged', () => {
+    expect(extractText('hello world')).toBe('hello world');
+    expect(extractText('')).toBe('');
+  });
+
+  test('returns empty string for anything that is not a string or array', () => {
+    expect(extractText(undefined)).toBe('');
+    expect(extractText(null)).toBe('');
+    expect(extractText(42)).toBe('');
+    expect(extractText({ type: 'text', text: 'ignored' })).toBe('');
+  });
+
+  test('joins text blocks with a newline and skips every other block', () => {
+    const content = [
+      { type: 'text', text: 'first' },
+      'not a block',
+      { type: 'text', text: 42 },
+      { type: 'image', data: 'x', mimeType: 'image/png' },
+      { type: 'thinking', thinking: 'inner' },
+      { type: 'text', text: 'second' },
+    ];
+    expect(extractText(content)).toBe('first\nsecond');
+  });
+
+  test('returns empty string for an empty or all-non-text array', () => {
+    expect(extractText([])).toBe('');
+    expect(extractText([{ type: 'toolCall', id: 'a' }])).toBe('');
+  });
+});
+
+describe('inferToolType', () => {
+  test('maps each documented name family to its tool type', () => {
+    const cases: Array<[string | undefined, ToolType]> = [
+      [undefined, 'custom'],
+      ['', 'custom'],
+      ['BASH', 'bash'],
+      ['run_command', 'bash'],
+      ['open_terminal', 'bash'],
+      ['shell_exec', 'bash'],
+      ['write_file', 'edit_file'],
+      ['apply_patch', 'edit_file'],
+      ['edit', 'edit_file'],
+      ['create_file', 'create_file'],
+      ['read_file', 'read_file'],
+      ['view', 'read_file'],
+      ['list_dir', 'read_file'],
+      ['grep', 'grep'],
+      ['glob', 'grep'],
+      ['search_files', 'search_fs'],
+      ['find', 'search_fs'],
+      // `search` is matched before `web`, so the canonical name itself lands
+      // on the filesystem search type — pinned rather than "corrected".
+      ['web_search', 'search_fs'],
+      ['web_fetch', 'web_search'],
+      ['fetch_url', 'web_search'],
+      ['http_request', 'web_search'],
+      ['todo', 'todo'],
+      ['task', 'task'],
+      ['lsp_hover', 'lsp'],
+      ['eval', 'eval'],
+      ['github', 'github'],
+      ['security_scan', 'security_scan'],
+      ['mcp__custom_thing', 'custom'],
+    ];
+    for (const [name, expected] of cases) {
+      expect(inferToolType(name), `name=${String(name)}`).toBe(expected);
+    }
+  });
+
+  test('the earlier rule in the fixed order wins, not the more specific word', () => {
+    // `write` (edit) is checked before `todo`.
+    expect(inferToolType('todo_write')).toBe('edit_file');
+    // `search` (fs) is checked before `github`.
+    expect(inferToolType('github_search')).toBe('search_fs');
+    // `run` (bash) is checked before `eval`.
+    expect(inferToolType('eval_run')).toBe('bash');
+  });
+
+  test('matching is case-insensitive', () => {
+    expect(inferToolType('Read_File')).toBe('read_file');
+    expect(inferToolType('Security_Scan')).toBe('security_scan');
+  });
+});
+
+describe('parseMessageBlocks', () => {
+  test('a string becomes a single text part', () => {
+    expect(parseMessageBlocks('hello')).toEqual({ ...emptyParsed(), textParts: ['hello'] });
+  });
+
+  test('non-string, non-array content yields the empty shape', () => {
+    expect(parseMessageBlocks(undefined)).toEqual(emptyParsed());
+    expect(parseMessageBlocks(null)).toEqual(emptyParsed());
+    expect(parseMessageBlocks(7)).toEqual(emptyParsed());
+    expect(parseMessageBlocks({ type: 'text', text: 'x' })).toEqual(emptyParsed());
+  });
+
+  test('text parts keep array order and ignore malformed blocks', () => {
+    const content = [
+      { type: 'text', text: 'first' },
+      'nope',
+      { type: 'text', text: 42 },
+      { type: 'text' },
+      { type: 'text', text: 'second' },
+    ];
+    expect(parseMessageBlocks(content).textParts).toEqual(['first', 'second']);
+  });
+
+  test('thinking prefers `thinking`, falls back to `text`, and last wins', () => {
+    expect(parseMessageBlocks([{ type: 'thinking', thinking: 'first thought' }]).thinking).toBe('first thought');
+    expect(parseMessageBlocks([{ type: 'thinking', text: 'fallback' }]).thinking).toBe('fallback');
+    expect(
+      parseMessageBlocks([{ type: 'thinking', thinking: 'old' }, { type: 'thinking', thinking: 'new' }]).thinking,
+    ).toBe('new');
+    // A non-string body sets nothing at all.
+    expect(parseMessageBlocks([{ type: 'thinking', thinking: 5 }]).thinking).toBeUndefined();
+  });
+
+  test('a tool call exposes id, name, command, input and a composed title', () => {
+    const parsed = parseMessageBlocks([
+      { type: 'toolCall', id: 'call-1', name: 'bash', arguments: { command: 'ls -la' } },
+    ]);
+    expect(parsed.toolCalls).toEqual([
+      {
+        id: 'call-1',
+        name: 'bash',
+        title: 'bash — ls -la',
+        intent: undefined,
+        target: undefined,
+        command: 'ls -la',
+        input: { command: 'ls -la' },
+      },
+    ]);
+    // A tool call is registered with an empty inline output slot.
+    expect(parsed.inlineOutputs.get('call-1')).toBe('');
+  });
+
+  test('a streaming tool call keeps one fallback id until its real one arrives', () => {
+    // A live `toolcall_delta` block: the arguments are partial JSON, so there is
+    // no readable input and no id yet. The card is keyed by the block's
+    // position for the whole stream — a random fallback remounted it per chunk.
+    const partial = parseMessageBlocks([{ type: 'toolCall', partialArgs: '{"path":' }]).toolCalls[0];
+    const later = parseMessageBlocks([{ type: 'toolCall', partialArgs: '{"path":"a.ts"}' }]).toolCalls[0];
+    expect(partial.id).toBe('tool-0');
+    expect(later.id).toBe('tool-0');
+    // `toolcall_end` hands the finished block over, real id and all.
+    const done = parseMessageBlocks([
+      { type: 'toolCall', id: 'call-1', name: 'write', arguments: { path: 'a.ts' } },
+    ]).toolCalls[0];
+    expect(done.id).toBe('call-1');
+  });
+
+  test('command extraction is first-string-wins across the documented keys', () => {
+    const [call] = parseMessageBlocks([
+      { type: 'toolCall', id: 'c', name: 'run', arguments: { command: 7, cmd: 'ls', CommandLine: 'echo' } },
+    ]).toolCalls;
+    expect(call.command).toBe('ls');
+    // An empty string is still a string: it stops the search and yields no command.
+    const [empty] = parseMessageBlocks([
+      { type: 'toolCall', id: 'c', name: 'run', arguments: { command: '', cmd: 'ls' } },
+    ]).toolCalls;
+    expect(empty.command).toBeUndefined();
+    expect(empty.title).toBe('run');
+  });
+
+  test('target extraction is first-string-wins and falls back to the hashline header', () => {
+    const [byKey] = parseMessageBlocks([
+      { type: 'toolCall', id: 'c', name: 'read', arguments: { TargetFile: 'a.ts', filePath: 'b.ts' } },
+    ]).toolCalls;
+    expect(byKey.target).toBe('a.ts');
+    expect(byKey.title).toBe('read — a.ts');
+
+    // An omp `edit` carries no path key; the patch header names the file.
+    const [byPatch] = parseMessageBlocks([
+      { type: 'toolCall', id: 'c', name: 'edit', arguments: { input: '[src/a.ts#A1B2]\nCUT 1.=1' } },
+    ]).toolCalls;
+    expect(byPatch.target).toBe('src/a.ts');
+    expect(byPatch.title).toBe('edit — src/a.ts');
+  });
+
+  test('`input` is used only when `arguments` is absent', () => {
+    const [fromInput] = parseMessageBlocks([
+      { type: 'toolCall', id: 'c', name: 'read', input: { path: 'p.ts' } },
+    ]).toolCalls;
+    expect(fromInput.target).toBe('p.ts');
+    // A non-record `arguments` short-circuits the `input` fallback.
+    const [shadowed] = parseMessageBlocks([
+      { type: 'toolCall', id: 'c', name: 'read', arguments: 'oops', input: { path: 'p.ts' } },
+    ]).toolCalls;
+    expect(shadowed.target).toBeUndefined();
+    expect(shadowed.input).toBeUndefined();
+  });
+
+  test('the first non-empty intent becomes the turn intent', () => {
+    const parsed = parseMessageBlocks([
+      { type: 'toolCall', id: 'a', name: 't', arguments: { i: 'first', command: 'x' } },
+      { type: 'toolCall', id: 'b', name: 't', arguments: { i: 'second' } },
+    ]);
+    expect(parsed.intent).toBe('first');
+    expect(parsed.toolCalls[0].intent).toBe('first');
+    expect(parsed.toolCalls[1].intent).toBe('second');
+  });
+
+  test('a tool call without id/name gets deterministic fallbacks', () => {
+    const [call] = parseMessageBlocks([{ type: 'toolCall', arguments: {} }]).toolCalls;
+    expect(call.name).toBe('tool');
+    expect(call.id.startsWith('tool-')).toBe(true);
+    expect(call.id.length).toBeGreaterThan('tool-'.length);
+    expect(call.title).toBe('tool');
+    // Raw args are kept only when non-empty.
+    expect(call.input).toBeUndefined();
+  });
+
+  test('a tool result pairs with its call by toolCallId', () => {
+    const parsed = parseMessageBlocks([
+      { type: 'toolCall', id: 'a', name: 'bash', arguments: { command: 'ls' } },
+      { type: 'toolCall', id: 'b', name: 'read', arguments: { path: 'p.ts' } },
+      { type: 'toolResult', toolCallId: 'a', text: 'out-a' },
+    ]);
+    expect(parsed.inlineOutputs.get('a')).toBe('out-a');
+    expect(parsed.inlineOutputs.get('b')).toBe('');
+  });
+
+  test('a result without a matching id attaches to the most recent call', () => {
+    const parsed = parseMessageBlocks([
+      { type: 'toolCall', id: 'a', name: 'bash', arguments: { command: 'ls' } },
+      { type: 'toolResult', toolCallId: 'unknown', text: 'fallback' },
+    ]);
+    expect(parsed.inlineOutputs.get('a')).toBe('fallback');
+    // No call at all: the result is dropped rather than inventing one.
+    expect(parseMessageBlocks([{ type: 'toolResult', toolCallId: 'x', text: 'orphan' }]).inlineOutputs.size).toBe(0);
+  });
+
+  test('inline tool-result images ride along, blob refs and base64 alike', () => {
+    const ref = `blob:sha256:${'a'.repeat(64)}`;
+    const parsed = parseMessageBlocks([
+      { type: 'toolCall', id: 'a', name: 'read', arguments: { path: 'p.png' } },
+      {
+        type: 'toolResult',
+        toolCallId: 'a',
+        text: 'Read image file',
+        content: [
+          { type: 'image', data: ref, mimeType: 'image/png' },
+          { type: 'image', data: 'QUJD', mimeType: 'image/jpeg' },
+        ],
+      },
+    ]);
+    expect(parsed.inlineImages.get('a')).toEqual([
+      { mimeType: 'image/png', blobRef: ref },
+      { mimeType: 'image/jpeg', dataBase64: 'QUJD' },
+    ]);
+  });
+
+  test('images ride the fallback pairing too, and an image-less result adds no entry', () => {
+    const ref = `blob:sha256:${'b'.repeat(64)}`;
+    const parsed = parseMessageBlocks([
+      { type: 'toolCall', id: 'a', name: 'read', arguments: { path: 'p.png' } },
+      { type: 'toolCall', id: 'b', name: 'read', arguments: { path: 'q.png' } },
+      { type: 'toolResult', toolCallId: 'stale', text: 'pic', content: [{ type: 'image', data: ref }] },
+      { type: 'toolResult', toolCallId: 'b', text: 'no pic' },
+    ]);
+    // Unknown id → the most recent call, which is `b`; the later text-only
+    // result for `b` overwrites the output but leaves the images in place.
+    expect(parsed.inlineImages.get('b')).toEqual([{ mimeType: 'image/png', blobRef: ref }]);
+    expect(parsed.inlineImages.has('a')).toBe(false);
+    expect(parsed.inlineOutputs.get('b')).toBe('no pic');
+  });
+
+  test('unknown block types and malformed entries contribute nothing', () => {
+    const parsed = parseMessageBlocks([
+      { type: 'image', data: 'QUJD', mimeType: 'image/png' },
+      { type: 'tool_result', toolCallId: 'x', text: 'snake case is not recognized' },
+      null,
+      [],
+      { text: 'no type' },
+      { type: 'text', text: 'kept' },
+    ]);
+    expect(parsed).toEqual({ ...emptyParsed(), textParts: ['kept'] });
+  });
+});

package/src/shared/lib/omp/session/parse-message-blocks.ts

@@ -0,0 +1,328 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Single source of truth for parsing omp message content blocks (text /
+ * thinking / toolCall / toolResult) into Kabmo's parsed-message shape.
+ *
+ * Both render paths share this core so their behavior can never drift:
+ * - live SSE events:  hooks/chat/omp/stream.ts → mapper.ts (streaming=true)
+ * - JSONL reload:     lib/omp/session/messages-parse.ts → messages-map.ts
+ *
+ * The two adapters only handle what is genuinely path-specific: the entry
+ * wrapper shape, the streaming status of tool calls, and output pairing
+ * (incremental in live, 2-pass on reload).
+ */
+
+import type { ToolCallData, ToolType } from '@/shared/types/chat';
+import { hashlineTargetPath } from '@/shared/lib/omp/session/hashline-patch';
+import { extractToolImages, type ToolImageRef } from '@/shared/lib/omp/session/tool-images';
+import { isRecord } from '@/shared/lib/util/guards';
+
+/** Extract plain text from omp content (string or [{type:'text',text},...]). */
+export function extractText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!isRecord(block)) continue;
+    if (block.type === 'text' && typeof block.text === 'string') parts.push(block.text);
+  }
+  return parts.join('\n');
+}
+
+export interface ParsedToolCall {
+  id: string;
+  name: string;
+  title: string;
+  intent?: string;
+  target?: string;
+  command?: string;
+  input?: string | Record<string, unknown>;
+}
+
+export interface ParsedMessageBlocks {
+  thinking?: string;
+  toolCalls: ParsedToolCall[];
+  /** toolCallId → text output carried by inline toolResult blocks. */
+  inlineOutputs: Map<string, string>;
+  /** toolCallId → pictures the inline toolResult blocks returned. */
+  inlineImages: Map<string, ToolImageRef[]>;
+  textParts: string[];
+  /** Short human intent (omp arguments.i) for the tool calls in this turn. */
+  intent?: string;
+}
+
+function inferToolType(name?: string): ToolType {
+  const lower = (name || '').toLowerCase();
+  if (lower.includes('bash') || lower.includes('terminal') || lower.includes('shell') || lower.includes('run')) {
+    return 'bash';
+  }
+  if (lower.includes('write') || lower.includes('edit') || lower.includes('patch') || lower.includes('apply')) {
+    return 'edit_file';
+  }
+  if (lower.includes('create')) return 'create_file';
+  if (lower.includes('read') || lower.includes('view') || lower.includes('list')) return 'read_file';
+  if (lower.includes('grep') || lower.includes('glob')) return 'grep';
+  if (lower.includes('search') || lower.includes('find')) return 'search_fs';
+  if (lower.includes('web') || lower.includes('fetch') || lower.includes('http')) return 'web_search';
+  if (lower.includes('todo')) return 'todo';
+  if (lower.includes('task')) return 'task';
+  if (lower.includes('lsp')) return 'lsp';
+  if (lower.includes('eval')) return 'eval';
+  if (lower.includes('github')) return 'github';
+  if (lower.includes('security')) return 'security_scan';
+  return 'custom';
+}
+
+export { inferToolType };
+
+function stringArg(rawInput: Record<string, unknown> | undefined, keys: string[]): string {
+  if (!rawInput) return '';
+  for (const key of keys) {
+    const value = rawInput[key];
+    if (typeof value === 'string') return value;
+  }
+  return '';
+}
+
+const COMMAND_KEYS = ['command', 'cmd', 'CommandLine', 'commandLine'];
+const TARGET_KEYS = ['path', 'TargetFile', 'targetFile', 'FilePath', 'filePath', 'AbsolutePath', 'file'];
+
+/** Parse omp message content (string or block array) into the canonical
+ *  parsed-message shape shared by the live and reload render paths. */
+export function parseMessageBlocks(content: unknown): ParsedMessageBlocks {
+  const result: ParsedMessageBlocks = { toolCalls: [], inlineOutputs: new Map(), inlineImages: new Map(), textParts: [] };
+  if (typeof content === 'string') {
+    result.textParts.push(content);
+    return result;
+  }
+  if (!Array.isArray(content)) return result;
+
+  for (const [blockIndex, raw] of content.entries()) {
+    if (!isRecord(raw)) continue;
+    const block = raw as {
+      type?: unknown;
+      text?: unknown;
+      thinking?: unknown;
+      narration?: unknown;
+      id?: unknown;
+      name?: unknown;
+      toolCallId?: unknown;
+      arguments?: unknown;
+      input?: unknown;
+    };
+    if (block.type === 'thinking') {
+      const body = typeof block.thinking === 'string'
+        ? block.thinking
+        : typeof block.text === 'string'
+          ? block.text
+          : undefined;
+      // omp 18.12.0 marks a thinking block whose text is prose addressed to the
+      // USER (`narration`), and its own surfaces present it as answer text
+      // (`presentNarrationAsAnswer`, used by the TUI, print mode and ACP).
+      // Folding it into `thinking` hid the reply inside a collapsed "Thinking"
+      // accordion; the two render paths share this parser, so the rule is
+      // stated once here.
+      if (body !== undefined && block.narration === true) result.textParts.push(body);
+      else if (body !== undefined) result.thinking = body;
+    } else if (block.type === 'toolCall') {
+      // The child streams FULL accumulated messages (`child-config.ts`), so the
+      // block carries omp's own `id` and `name` from the first delta. The
+      // fallbacks cover a frame that somehow omits them (a hand-built fixture, a
+      // build that ignores the filter): a random id would re-key the card on
+      // every frame and remount it per chunk, while the block's position is
+      // stable for the whole stream.
+      const id = typeof block.id === 'string' ? block.id : `tool-${blockIndex}`;
+      const name = typeof block.name === 'string' ? block.name : 'tool';
+      const rawInput = (block.arguments ?? block.input) as Record<string, unknown> | undefined;
+      const args = isRecord(rawInput) ? rawInput : undefined;
+      const command = stringArg(args, COMMAND_KEYS);
+      // An omp `edit` carries its target inside the patch header (`input:
+      // "[PATH#TAG]\nCUT …"`) — no `path` key — so the card would otherwise
+      // render without a file name until the result's `details.path` arrives.
+      const target = stringArg(args, TARGET_KEYS) || (args ? hashlineTargetPath(args) : undefined);
+      const intent = typeof args?.i === 'string' ? args.i : undefined;
+      const detail = command || target;
+      result.toolCalls.push({
+        id,
+        name,
+        title: detail ? `${name} — ${detail}` : name,
+        intent,
+        target: target || undefined,
+        command: command || undefined,
+        input: args && Object.keys(args).length > 0 ? args : undefined,
+      });
+      if (intent && !result.intent) result.intent = intent;
+      result.inlineOutputs.set(id, '');
+    } else if (block.type === 'toolResult') {
+      const targetId = typeof block.toolCallId === 'string' ? block.toolCallId : undefined;
+      const text = typeof block.text === 'string' ? block.text : '';
+      const images = extractToolImages(raw);
+      if (targetId && result.inlineOutputs.has(targetId)) {
+        result.inlineOutputs.set(targetId, text);
+        if (images.length > 0) result.inlineImages.set(targetId, images);
+      } else if (result.toolCalls.length > 0) {
+        const last = result.toolCalls[result.toolCalls.length - 1];
+        if (text) result.inlineOutputs.set(last.id, text);
+        if (images.length > 0) result.inlineImages.set(last.id, images);
+      }
+    } else if (block.type === 'text') {
+      if (typeof block.text === 'string') result.textParts.push(block.text);
+    }
+  }
+  return result;
+}
+
+/** Build a Kabmo ToolCallData from the parsed core shape. `streaming`
+ *  controls the initial status (live calls start 'running'); pairing an
+ *  output after the fact overrides it back to success/error. */
+export function toToolCallData(
+  parsed: ParsedToolCall,
+  options: { streaming: boolean; output?: string; isError?: boolean; images?: ToolImageRef[] },
+): ToolCallData {
+  const input = parsed.input;
+  const stripped = isRecord(input)
+    ? Object.fromEntries(Object.entries(input).filter(([key]) => key !== 'i'))
+    : input;
+  const status: ToolCallData['status'] = options.isError
+    ? 'error'
+    : options.output !== undefined
+      ? 'success'
+      : options.streaming ? 'running' : 'success';
+  return {
+    id: parsed.id,
+    type: inferToolType(parsed.name),
+    name: parsed.name,
+    title: parsed.title,
+    intent: parsed.intent,
+    target: parsed.target,
+    command: parsed.command,
+    input: stripped && Object.keys(stripped).length > 0 ? stripped : undefined,
+    output: options.output,
+    ...(options.images && options.images.length > 0 ? { images: options.images } : {}),
+    status,
+  };
+}
+
+/**
+ * A user-attachment entry extracted from an omp content block. `blobRef` is set
+ * when omp externalized the bytes instead of inlining them (see
+ * `@/server/lib/omp/session/blobs.server`); the server resolves it before the
+ * timeline sees the attachment, so `preview` here is only a placeholder.
+ */
+export interface ExtractedImageAttachment {
+  id: string;
+  name: string;
+  preview: string;
+  type: string;
+  /** `blob:sha256:<hash>` when the bytes were externalized, else undefined. */
+  blobRef?: string;
+}
+
+/** True for the `blob:sha256:<hash>` references omp writes in place of image data. */
+export function isBlobImageRef(data: string): boolean {
+  return data.startsWith('blob:sha256:');
+}
+
+/** Extract image blocks from an omp user content array ({type:'image',
+ *  data: base64 | blob:sha256:<hash>, mimeType}) into ChatMessageData attachment
+ *  entries so the timeline keeps showing them after a reload from the session
+ *  JSONL. A blob ref carries no preview: building one from the ref string
+ *  produced an undecodable `data:` URL, which is what the server-side resolver
+ *  now replaces with the real bytes. */
+export function extractUserImageAttachments(
+  content: unknown,
+): ExtractedImageAttachment[] {
+  if (!Array.isArray(content)) return [];
+  const attachments: ExtractedImageAttachment[] = [];
+  let index = 0;
+  for (const block of content) {
+    if (!isRecord(block) || block.type !== 'image') continue;
+    const data = typeof block.data === 'string' ? block.data : undefined;
+    const mimeType = typeof block.mimeType === 'string' ? block.mimeType : 'image/png';
+    if (!data) continue;
+    index += 1;
+    const ext = (mimeType.split('/')[1] || 'png').replace(/[^a-z0-9]/gi, '') || 'png';
+    const externalized = isBlobImageRef(data);
+    attachments.push({
+      id: `att-${index}`,
+      name: `attachment-${index}.${ext}`,
+      preview: externalized ? '' : `data:${mimeType};base64,${data}`,
+      type: mimeType,
+      ...(externalized ? { blobRef: data } : {}),
+    });
+  }
+  return attachments;
+}
+
+/** Strip the inlined "Attached file: ..." fenced blocks that the composer
+ *  appends to the prompt before sending (mirror omp-web). The JSONL stores
+ *  the composed prompt; the timeline should show the original text only —
+ *  the file itself renders as an attachment chip. Handles both a leading
+ *  block (attach-only prompt) and one appended after the user text. */
+export function stripInlinedTextAttachments(text: string): string {
+  const match = text.match(/(?:^|\n{2})\s*Attached file: /);
+  if (!match || match.index === undefined) return text;
+  const before = text.slice(0, match.index);
+  const rest = text.slice(match.index + match[0].length);
+  if (!/^[^\n]+\n```[a-z]*\n/.test(rest)) return text;
+  return before.trim();
+}
+
+/** One text file recovered from an inlined `Attached file:` block. */
+export interface InlinedTextAttachment {
+  name: string;
+  content: string;
+}
+
+/**
+ * Recover the text files the composer inlined into a delivered prompt.
+ *
+ * omp stores no attachment metadata for a text file: the composer appends each
+ * one to the prompt as `Attached file: <name>` plus a fenced block, and that
+ * composed prompt IS the session record. `stripInlinedTextAttachments` removes
+ * those blocks for display, which also throws the names away — so a reloaded
+ * session showed no chip for a dropped `.md`/`.py`/`.json` while its image
+ * siblings survived (images ride as their own content block).
+ *
+ * This walks the same format back out, so the timeline can render the chips and
+ * re-open the files. The fence length is whatever `fenceForContent` chose (at
+ * least 3 backticks, longer when the content itself contains a run), and a
+ * block's content may contain anything — including the literal string
+ * "Attached file:" — so the closing fence is matched by exact length rather
+ * than by looking for the next header.
+ */
+export function extractInlinedTextAttachments(text: string): InlinedTextAttachment[] {
+  const attachments: InlinedTextAttachment[] = [];
+  const header = /(?:^|\n{2})Attached file: ([^\n]+)\n(`{3,})[a-zA-Z0-9_-]*\n/g;
+  let match: RegExpExecArray | null;
+  while ((match = header.exec(text)) !== null) {
+    const name = match[1].trim();
+    const fence = match[2];
+    const contentStart = match.index + match[0].length;
+    // The closing fence sits on its own line and repeats the opening run
+    // exactly; a longer run is content, not the close.
+    const closer = `\n${fence}`;
+    let cursor = contentStart;
+    let end = -1;
+    while (cursor <= text.length) {
+      const at = text.indexOf(closer, cursor);
+      if (at === -1) break;
+      const after = text.slice(at + closer.length);
+      // Accept the close only at a block boundary: end of string, or a blank
+      // line followed by the next header / nothing.
+      if (after === '' || after.startsWith('\n') || /^\n{2}Attached file: /.test(after)) {
+        end = at;
+        break;
+      }
+      cursor = at + closer.length;
+    }
+    if (end === -1) continue;
+    attachments.push({ name, content: text.slice(contentStart, end) });
+    header.lastIndex = end + closer.length;
+  }
+  return attachments;
+}