ompchamber 0.3.0

package/src/shared/lib/omp/rpc/frame.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Bounded protocol-v2 framing for OMP's NDJSON RPC transport.
+ *
+ * Faithful port of omp-web/lib/omp/rpc-frame.ts. Logical RPC frames are
+ * carried as single JSONL lines when small; frames larger than the transport
+ * limit are split into `rpc_chunk` sequences (base64 payloads) and
+ * reassembled on the receiving side.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+
+export const MAX_RPC_FRAME_BYTES = 1024 * 1024;
+export const MAX_RPC_REASSEMBLED_BYTES = 64 * 1024 * 1024;
+const RPC_CHUNK_PAYLOAD_BYTES = 256 * 1024;
+
+export type RpcProtocolVersion = 1 | 2;
+export type RpcFrameRecord = { type: string; [key: string]: unknown };
+
+interface PendingChunks {
+  chunkId: string;
+  count: number;
+  byteLength: number;
+  nextIndex: number;
+  chunks: Uint8Array[];
+  receivedBytes: number;
+}
+
+function isSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value);
+}
+
+function utf8ByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function lineByteLength(value: string): number {
+  return utf8ByteLength(value) + 1;
+}
+
+/** Strict base64 decode (canonical padding + round-trip equality). */
+function decodeBase64(value: unknown): Uint8Array {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)
+  ) throw new Error('invalid RPC chunk data');
+  let bytes: Uint8Array;
+  try {
+    bytes = Uint8Array.fromBase64(value, { lastChunkHandling: 'strict' });
+  } catch {
+    throw new Error('invalid RPC chunk data');
+  }
+  if (bytes.toBase64() !== value) throw new Error('invalid RPC chunk data');
+  return bytes;
+}
+
+function concatChunks(chunks: Uint8Array[], byteLength: number): Uint8Array {
+  const merged = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return merged;
+}
+
+/** Decodes complete logical frames from parsed JSONL records. */
+export class RpcFrameDecoder {
+  private pending: PendingChunks | undefined;
+
+  push(value: unknown): RpcFrameRecord | undefined {
+    if (!isRecord(value) || value.type !== 'rpc_chunk') {
+      if (this.pending) throw new Error('RPC chunk sequence interrupted');
+      if (!isRecord(value) || typeof value.type !== 'string') throw new Error('RPC frame must be an object');
+      return value as RpcFrameRecord;
+    }
+    const { chunkId, index, count, byteLength } = value;
+    if (
+      typeof chunkId !== 'string' || chunkId.length === 0 || chunkId.length > 128 ||
+      !isSafeInteger(index) || !isSafeInteger(count) || !isSafeInteger(byteLength) ||
+      index < 0 || count < 2 || count > Math.ceil(MAX_RPC_REASSEMBLED_BYTES / RPC_CHUNK_PAYLOAD_BYTES) ||
+      index >= count || byteLength < MAX_RPC_FRAME_BYTES || byteLength > MAX_RPC_REASSEMBLED_BYTES
+    ) throw new Error('invalid RPC chunk metadata');
+
+    const bytes = decodeBase64(value.data);
+    if (bytes.byteLength > RPC_CHUNK_PAYLOAD_BYTES) throw new Error('RPC chunk payload exceeds the transport limit');
+    if (!this.pending) {
+      if (index !== 0) throw new Error('RPC chunk sequence must start at index 0');
+      this.pending = { chunkId, count, byteLength, nextIndex: 0, chunks: [], receivedBytes: 0 };
+    }
+    const pending = this.pending!;
+    if (pending.chunkId !== chunkId || pending.count !== count || pending.byteLength !== byteLength || pending.nextIndex !== index) {
+      throw new Error('RPC chunk sequence mismatch');
+    }
+    pending.chunks.push(bytes);
+    pending.receivedBytes += bytes.byteLength;
+    pending.nextIndex++;
+    if (pending.receivedBytes > pending.byteLength) throw new Error('RPC chunk sequence exceeds declared length');
+    if (pending.nextIndex < pending.count) return undefined;
+    if (pending.receivedBytes !== pending.byteLength) throw new Error('RPC chunk sequence length mismatch');
+
+    this.pending = undefined;
+    const json = new TextDecoder('utf-8', { fatal: true }).decode(concatChunks(pending.chunks, pending.byteLength));
+    const frame: unknown = JSON.parse(json);
+    if (!isRecord(frame) || typeof frame.type !== 'string') throw new Error('RPC frame must be an object');
+    return frame as RpcFrameRecord;
+  }
+}
+
+/** Physical JSONL records for a logical RPC frame at the selected protocol. */
+export function encodeRpcFrames(frame: RpcFrameRecord, protocolVersion: RpcProtocolVersion, chunkId: string): string[] {
+  const json = JSON.stringify(frame);
+  if (lineByteLength(json) <= MAX_RPC_FRAME_BYTES) return [`${json}\n`];
+  if (protocolVersion === 1) throw new Error('RPC frame exceeds the v1 transport limit');
+  const bytes = new TextEncoder().encode(json);
+  if (bytes.byteLength > MAX_RPC_REASSEMBLED_BYTES) throw new Error('RPC frame exceeds the v2 reassembly limit');
+  const count = Math.ceil(bytes.byteLength / RPC_CHUNK_PAYLOAD_BYTES);
+  const lines: string[] = [];
+  for (let index = 0; index < count; index++) {
+    const chunk = {
+      type: 'rpc_chunk', chunkId, index, count, byteLength: bytes.byteLength,
+      data: bytes.subarray(index * RPC_CHUNK_PAYLOAD_BYTES, (index + 1) * RPC_CHUNK_PAYLOAD_BYTES).toBase64(),
+    };
+    const line = JSON.stringify(chunk);
+    if (lineByteLength(line) > MAX_RPC_FRAME_BYTES) throw new Error('RPC chunk exceeds the transport limit');
+    lines.push(`${line}\n`);
+  }
+  return lines;
+}

package/src/shared/lib/omp/session/default-title.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { formatNewSessionTitle, isPendingSessionId, pendingSessionCreatedAt, pendingSessionTitle } from '@/shared/lib/omp/session/default-title';
+
+describe('pendingSessionCreatedAt', () => {
+  test('parses the epoch out of a pending session id', () => {
+    expect(pendingSessionCreatedAt('new-1737000000000')).toBe(1737000000000);
+  });
+
+  test('is NaN for a real omp UUID', () => {
+    expect(Number.isNaN(pendingSessionCreatedAt('01a08410-8135-772c-b1cc-9ceed604deec'))).toBe(true);
+  });
+
+  test('treats a bare prefix as epoch 0 because Number("") is 0', () => {
+    expect(pendingSessionCreatedAt('new-')).toBe(0);
+  });
+
+  test('is NaN for a non-numeric suffix', () => {
+    expect(Number.isNaN(pendingSessionCreatedAt('new-abc'))).toBe(true);
+  });
+
+  test('is NaN for null and undefined', () => {
+    expect(Number.isNaN(pendingSessionCreatedAt(null))).toBe(true);
+    expect(Number.isNaN(pendingSessionCreatedAt(undefined))).toBe(true);
+  });
+});
+
+describe('pendingSessionTitle', () => {
+  test('reflects the id epoch rather than the current clock', () => {
+    const title = pendingSessionTitle('new-1737000000000');
+    expect(title).toContain('New Session - ');
+    expect(title).toBe(formatNewSessionTitle(new Date(1737000000000)));
+  });
+
+  test('falls back to now for a non-numeric id without throwing', () => {
+    expect(pendingSessionTitle('new-not-a-number').startsWith('New Session')).toBe(true);
+  });
+});
+
+describe('isPendingSessionId', () => {
+  test('is true for a pending id and false for a settled one', () => {
+    expect(isPendingSessionId('new-1737000000000')).toBe(true);
+    expect(isPendingSessionId('ses_alpha')).toBe(false);
+  });
+});

package/src/shared/lib/omp/session/default-title.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Default display titles for sessions that have no user/auto name yet.
+ *
+ * A brand-new session must still be distinguishable in the sidebar and navbar
+ * before omp derives a real title (first prompt / JSONL title slot), so the
+ * default carries the creation timestamp:
+ *
+ *   New Session - yyyy-mm-ddThh:mm:ss
+ *
+ * The timestamp is local time and is stable per session: pending sessions take
+ * it from their `new-<epochMs>` id, persisted sessions from the JSONL header
+ * timestamp — two nameless sessions can never render the same title.
+ */
+
+const PENDING_SESSION_PREFIX = 'new-';
+
+function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+/** `New Session - yyyy-mm-ddThh:mm:ss` (local time); plain "New Session" when
+ *  the date is invalid. */
+export function formatNewSessionTitle(date: Date = new Date()): string {
+  if (Number.isNaN(date.getTime())) return 'New Session';
+  return `New Session - ${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}T${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
+}
+
+/** True for client-side pending session ids (`new-<epochMs>`, pre-spawn). */
+export function isPendingSessionId(sessionId: string | null | undefined): boolean {
+  return Boolean(sessionId?.startsWith(PENDING_SESSION_PREFIX));
+}
+
+/** Creation epoch (ms) encoded in a pending session id (`new-<epochMs>`);
+ *  NaN for any other id, including real omp UUIDs. */
+export function pendingSessionCreatedAt(sessionId: string | null | undefined): number {
+  return sessionId?.startsWith(PENDING_SESSION_PREFIX)
+    ? Number(sessionId.slice(PENDING_SESSION_PREFIX.length))
+    : Number.NaN;
+}
+
+/** Default title of a client-side pending session; the id carries its
+ *  creation epoch (`new-<epochMs>`). */
+export function pendingSessionTitle(sessionId: string | null | undefined): string {
+  const epochMs = pendingSessionCreatedAt(sessionId);
+  return formatNewSessionTitle(Number.isFinite(epochMs) ? new Date(epochMs) : new Date());
+}

package/src/shared/lib/omp/session/hashline-patch.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'bun:test';
+import { hashlinePatchFromArgs, hashlineTargetPath, parseHashlinePatch } from '@/shared/lib/omp/session/hashline-patch';
+
+/** Real args a model sent for `edit`: `{i, input}` with no delimiter wrapper. */
+const REAL_INPUT = '[app/components/workspace/chat-timeline/UndoConfirmModal.tsx#A328]\nCUT 18.=18';
+
+describe('parseHashlinePatch', () => {
+  test('reads the header and a bodyless op from a wrapper-less patch', () => {
+    const [section] = parseHashlinePatch(REAL_INPUT);
+    expect(section.path).toBe('app/components/workspace/chat-timeline/UndoConfirmModal.tsx');
+    expect(section.tag).toBe('A328');
+    expect(section.removed).toBe(false);
+    expect(section.ops).toEqual([{ verb: 'CUT', spec: '18.=18', body: [] }]);
+  });
+
+  test('keeps body rows verbatim — indent, blank and escaped markers', () => {
+    const [section] = parseHashlinePatch(
+      [
+        '*** Begin Patch',
+        '[app/x.ts#0a1b]',
+        'PUT 3.=3:',
+        '+  if (dry) return;',
+        '+',
+        '+- literal minus',
+        '++ literal plus',
+        '*** End Patch',
+      ].join('\n'),
+    );
+    expect(section.ops).toHaveLength(1);
+    expect(section.ops[0].verb).toBe('PUT');
+    expect(section.ops[0].spec).toBe('3.=3');
+    expect(section.ops[0].body).toEqual(['+  if (dry) return;', '+', '+- literal minus', '++ literal plus']);
+  });
+
+  test('treats REM and MV as section-level file ops', () => {
+    const [section] = parseHashlinePatch('[app/old.ts#beef]\nREM');
+    expect(section.removed).toBe(true);
+    expect(section.ops).toEqual([]);
+
+    const [moved] = parseHashlinePatch('[app/old.ts#beef]\nMV app/new.ts');
+    expect(moved.moveTo).toBe('app/new.ts');
+  });
+
+  test('parses gap, block and register ops, and splits sections', () => {
+    const sections = parseHashlinePatch(
+      [
+        '[app/a.ts#1111]',
+        'PUT <4:',
+        '+before',
+        'PUT >$ @tail',
+        '[app/b.ts#2222]',
+        'PUT 7*:',
+        '+replaced block',
+      ].join('\n'),
+    );
+    expect(sections.map((s) => s.path)).toEqual(['app/a.ts', 'app/b.ts']);
+    expect(sections[0].ops.map((op) => op.spec)).toEqual(['<4', '>$ @tail']);
+    expect(sections[1].ops[0].spec).toBe('7*');
+  });
+
+  test('accepts a missing closing bracket and a quoted path', () => {
+    expect(parseHashlinePatch('[app/x.ts#0000').at(0)?.path).toBe('app/x.ts');
+    expect(parseHashlinePatch('["app/with space.ts"#0000]\nCUT 1.=1').at(0)?.path).toBe('app/with space.ts');
+    expect(parseHashlinePatch('["app/with space.ts"]\nCUT 1.=1').at(0)?.path).toBe('app/with space.ts');
+    // omp strips the tag before the quotes, so a tag *inside* the quotes stays
+    // part of the path — mirrored here rather than silently "corrected".
+    expect(parseHashlinePatch('["app/x.ts#0000"]\nCUT 1.=1').at(0)?.path).toBe('app/x.ts#0000');
+    // Only a 4-hex suffix is a snapshot tag; anything else stays in the path.
+    expect(parseHashlinePatch('[app/x.ts#HEAD]\nCUT 1.=1').at(0)?.path).toBe('app/x.ts#HEAD');
+  });
+
+  test('returns nothing for non-patch text', () => {
+    expect(parseHashlinePatch('app/components/Foo.tsx')).toEqual([]);
+    expect(parseHashlinePatch('')).toEqual([]);
+  });
+});
+
+describe('hashline patch in tool args', () => {
+  test('finds the patch under `input` and derives the target path', () => {
+    const args = { i: 'Hapus deklarasi handler duplikat modal', input: REAL_INPUT };
+    expect(hashlinePatchFromArgs(args)?.text).toBe(REAL_INPUT);
+    expect(hashlineTargetPath(args)).toBe('app/components/workspace/chat-timeline/UndoConfirmModal.tsx');
+  });
+
+  test('ignores args that carry no hashline patch', () => {
+    expect(hashlineTargetPath({ i: 'x', path: 'app/y.ts', old_string: 'a' })).toBeUndefined();
+    expect(hashlineTargetPath(undefined)).toBeUndefined();
+  });
+});

package/src/shared/lib/omp/session/hashline-patch.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * omp's hashline patch grammar — the `edit` tool's `input` argument. The
+ * chamber never applies a patch; it reads the text to name the target file
+ * while the call is still streaming (omp only ships the applied diff in the
+ * toolResult `details`, i.e. long after the card first paints) and to show
+ * which lines the patch touches before that diff lands.
+ *
+ * Grammar, per the omp edit tool description:
+ *
+ *   [PATH#TAG]
+ *   PUT 3.=3:
+ *   +replacement
+ *
+ * `TAG` is the 4-hex read snapshot the model edited against. Ops:
+ * `PUT N.=M:` / `PUT N*:` replace, `PUT <N:` / `PUT >N:` / `PUT >$:` insert,
+ * `CUT N.=M` / `CUT N*` delete (optionally capturing into `@name`), `PUT … @name`
+ * pastes a captured register, `REM` removes the file, `MV DEST` renames it.
+ * Body rows start with `+` and are verbatim — indentation included — with
+ * `+-`/`++` escaping a literal leading `-`/`+`. The `*** Begin Patch` /
+ * `*** End Patch` wrapper is optional, so neither delimiter is required here.
+ */
+
+/** A line op inside a section. File-level `REM`/`MV` are section fields. */
+export type HashlineVerb = 'PUT' | 'CUT';
+
+export interface HashlineOp {
+  verb: HashlineVerb;
+  /** Op target, trailing body `:` stripped: `18.=18 @name`, `<12`, `>$`, `7*`. */
+  spec: string;
+  /** Verbatim body rows (leading `+` marker included) following the op. */
+  body: string[];
+}
+
+export interface HashlineSection {
+  /** Path from the `[PATH#TAG]` header, surrounding quotes stripped. */
+  path: string;
+  /** 4-hex read snapshot from the header. */
+  tag?: string;
+  /** `MV <dest>` — where the file is moved/renamed to. */
+  moveTo?: string;
+  /** `REM` — the patch deletes this file outright. */
+  removed: boolean;
+  ops: HashlineOp[];
+}
+
+/** Argument keys an omp hashline patch can arrive under. */
+const PATCH_KEYS = ['input', '_input', 'patch'];
+
+/** Header snapshot tag, mirroring omp's `#[0-9A-Fa-f]{4}$`. */
+const HEADER_TAG_RE = /#([0-9a-fA-F]{4})$/;
+/** Line ops carry `PUT`/`CUT` as a whole word. */
+const OP_RE = /^(PUT|CUT)\b/;
+
+function stripQuotes(value: string): string {
+  const first = value[0];
+  return value.length >= 2 && (first === '"' || first === "'") && first === value[value.length - 1]
+    ? value.slice(1, -1)
+    : value;
+}
+
+/** `[PATH#TAG]` header line → path + snapshot tag. The closing bracket is
+ *  optional in omp's parser, and the tag is only stripped when it is 4 hex. */
+function parseHeader(line: string): { path: string; tag?: string } | undefined {
+  const trimmed = line.trimEnd();
+  if (!trimmed.startsWith('[')) return undefined;
+  const inner = (trimmed.endsWith(']') ? trimmed.slice(1, -1) : trimmed.slice(1)).trim();
+  const tag = HEADER_TAG_RE.exec(inner);
+  const path = stripQuotes((tag ? inner.slice(0, tag.index) : inner).trim());
+  return path ? { path, tag: tag?.[1] } : undefined;
+}
+
+/** Parse a hashline patch (with or without the `*** … Patch` delimiters). */
+export function parseHashlinePatch(text: string): HashlineSection[] {
+  const sections: HashlineSection[] = [];
+  let section: HashlineSection | undefined;
+
+  for (const raw of text.replace(/^\uFEFF/, '').split('\n')) {
+    const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+    const header = parseHeader(line);
+    if (header) {
+      section = { path: header.path, tag: header.tag, removed: false, ops: [] };
+      sections.push(section);
+      continue;
+    }
+    if (!section) continue;
+
+    const op = line.trim();
+    if (op === 'REM') {
+      section.removed = true;
+      continue;
+    }
+    if (op.startsWith('MV ')) {
+      section.moveTo = stripQuotes(op.slice(3).trim()) || undefined;
+      continue;
+    }
+    if (OP_RE.test(op)) {
+      section.ops.push({
+        verb: op.slice(0, 3) as HashlineVerb,
+        spec: op.slice(3).trim().replace(/:$/, ''),
+        body: [],
+      });
+      continue;
+    }
+
+    const last = section.ops[section.ops.length - 1];
+    if (last && line.startsWith('+')) last.body.push(line);
+  }
+
+  return sections;
+}
+
+/** Hashline patch carried by tool arguments, with its raw text for copying. */
+export function hashlinePatchFromArgs(
+  args: Record<string, unknown> | undefined,
+): { text: string; sections: HashlineSection[] } | undefined {
+  if (!args) return undefined;
+  for (const key of PATCH_KEYS) {
+    const value = args[key];
+    if (typeof value !== 'string') continue;
+    const sections = parseHashlinePatch(value);
+    if (sections.length > 0) return { text: value, sections };
+  }
+  return undefined;
+}
+
+/** Target file of a hashline patch in tool args — the card's subtitle source. */
+export function hashlineTargetPath(args: Record<string, unknown> | undefined): string | undefined {
+  return hashlinePatchFromArgs(args)?.sections[0].path;
+}

package/src/shared/lib/omp/session/jsonl.ts

@@ -0,0 +1,197 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Low-level JSONL + header parsing for oh-my-pi session files.
+ *
+ * Trimmed from omp-web/lib/omp/session-files.ts (itself a port of oh-my-pi
+ * session-listing.ts). These helpers derive a session header from a small
+ * prefix window of a `.jsonl` file, tolerating truncated lines via lenient
+ * parsing and raw-text string scans. Nothing here touches the filesystem.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+
+/** JSON.stringify never emits raw newlines, so line splitting is a faithful
+ *  lenient JSONL parse: malformed/truncated lines are skipped, not fatal. */
+export function parseJsonlLenient<T>(body: string): T[] {
+  const out: T[] = [];
+  for (const rawLine of body.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    try {
+      out.push(JSON.parse(line) as T);
+    } catch {
+      // Skip malformed line (torn write, prefix-window truncation).
+    }
+  }
+  return out;
+}
+
+export function extractTextFromContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  const text: string[] = [];
+  for (const block of content) {
+    if (isRecord(block) && block.type === 'text' && typeof block.text === 'string') text.push(block.text);
+  }
+  return text.join(' ');
+}
+
+// ============================================================================
+// Raw-text string scans (tolerate a header line straddling the prefix window)
+// ============================================================================
+
+function decodeJsonStringFragment(value: string): string {
+  const safeValue = value.endsWith('\\') ? value.slice(0, -1) : value;
+  try {
+    return JSON.parse(`"${safeValue}"`) as string;
+  } catch {
+    return safeValue
+      .replace(/\\n/g, '\n')
+      .replace(/\\r/g, '\r')
+      .replace(/\\t/g, '\t')
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, '\\');
+  }
+}
+
+/** Raw-text string-property scan used on the possibly-truncated prefix window. */
+export function extractStringProperty(source: string, name: string, startIndex = 0): string | undefined {
+  const propertyIndex = source.indexOf(`"${name}"`, startIndex);
+  if (propertyIndex === -1) return undefined;
+  const colonIndex = source.indexOf(':', propertyIndex + name.length + 2);
+  if (colonIndex === -1) return undefined;
+
+  let valueIndex = colonIndex + 1;
+  while (valueIndex < source.length) {
+    const char = source.charCodeAt(valueIndex);
+    if (char !== 32 && char !== 9 && char !== 10 && char !== 13) break;
+    valueIndex++;
+  }
+  if (source.charCodeAt(valueIndex) !== 34) return undefined;
+
+  const valueStart = valueIndex + 1;
+  let escaped = false;
+  for (let i = valueStart; i < source.length; i++) {
+    const char = source.charCodeAt(i);
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === 92) {
+      escaped = true;
+      continue;
+    }
+    if (char === 34) {
+      return decodeJsonStringFragment(source.slice(valueStart, i));
+    }
+  }
+  return decodeJsonStringFragment(source.slice(valueStart));
+}
+
+export function countMessageMarkers(content: string): number {
+  let count = 0;
+  let index = 0;
+  while (index < content.length) {
+    const typeIndex = content.indexOf('"type"', index);
+    if (typeIndex === -1) break;
+    const colonIndex = content.indexOf(':', typeIndex + 6);
+    if (colonIndex === -1) break;
+    if (extractStringProperty(content, 'type', typeIndex) === 'message') count++;
+    index = colonIndex + 1;
+  }
+  return count;
+}
+
+export function extractFirstDisplayMessageFromPrefix(content: string): string | undefined {
+  let fallback: string | undefined;
+  let index = content.indexOf('"role"');
+  while (index !== -1) {
+    const role = extractStringProperty(content, 'role', index);
+    const text = extractStringProperty(content, 'content', index) ?? extractStringProperty(content, 'text', index);
+    if (text) {
+      if (role === 'user') return text;
+      if (!fallback && (role === 'developer' || role === 'assistant')) fallback = text;
+    }
+    index = content.indexOf('"role"', index + 6);
+  }
+  return fallback;
+}
+
+// ============================================================================
+// Header parsing
+// ============================================================================
+
+export interface SessionListHeader {
+  id: string;
+  cwd?: string;
+  title?: string;
+  parentSession?: string;
+  timestamp?: string;
+}
+
+function normalizeTitleOverride(title: string | undefined): string | null | undefined {
+  if (title === undefined) return undefined;
+  return title.trim() ? title : null;
+}
+
+function sessionListHeaderFromRecord(
+  record: Record<string, unknown> | undefined,
+  titleOverride?: string | null,
+): SessionListHeader | undefined {
+  if (record?.type !== 'session' || typeof record.id !== 'string') return undefined;
+  return {
+    id: record.id,
+    cwd: typeof record.cwd === 'string' ? record.cwd : undefined,
+    title:
+      titleOverride === null
+        ? undefined
+        : (titleOverride ?? (typeof record.title === 'string' ? record.title : undefined)),
+    parentSession: typeof record.parentSession === 'string' ? record.parentSession : undefined,
+    timestamp: typeof record.timestamp === 'string' ? record.timestamp : undefined,
+  };
+}
+
+function parseSessionListHeaderLine(line: string, titleOverride?: string | null): SessionListHeader | undefined {
+  if (extractStringProperty(line, 'type') !== 'session') return undefined;
+  const id = extractStringProperty(line, 'id');
+  if (!id) return undefined;
+  return {
+    id,
+    cwd: extractStringProperty(line, 'cwd'),
+    title: titleOverride === null ? undefined : (titleOverride ?? extractStringProperty(line, 'title')),
+    parentSession: extractStringProperty(line, 'parentSession'),
+    timestamp: extractStringProperty(line, 'timestamp'),
+  };
+}
+
+/** Parse the header from the prefix window; slot titles override header titles.
+ *  Falls back to a raw-text scan when the header line straddles the window. */
+export function parseSessionListHeader(
+  content: string,
+  entries: Array<Record<string, unknown>>,
+): SessionListHeader | undefined {
+  const firstEntry = entries[0];
+  const parsedSlotTitle = normalizeTitleOverride(
+    firstEntry?.type === 'title' && typeof firstEntry.title === 'string' ? firstEntry.title : undefined,
+  );
+  const parsedHeader = sessionListHeaderFromRecord(entries[firstEntry?.type === 'title' ? 1 : 0], parsedSlotTitle);
+  if (parsedHeader) return parsedHeader;
+
+  let slotTitle: string | null | undefined;
+  let firstNonEmpty = true;
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (firstNonEmpty && extractStringProperty(line, 'type') === 'title') {
+      slotTitle = normalizeTitleOverride(extractStringProperty(line, 'title'));
+      firstNonEmpty = false;
+      continue;
+    }
+    return parseSessionListHeaderLine(line, slotTitle);
+  }
+  return undefined;
+}