mixdog 1.2.0 → 1.2.1

package/src/runtime/agent/orchestrator/session/conversation-import/claude.mjs

@@ -0,0 +1,184 @@
+/**
+ * Claude Code project transcript (`projects/<dir>/<session>.jsonl`) → raw
+ * import turns. The active branch is followed from the last main-chain entry
+ * back through `parentUuid` (and `logicalParentUuid` across a compaction), so
+ * replayed or abandoned branches never duplicate. Kept: text blocks and
+ * `tool_use` as `[ran tool: <name>]` notes; images become an omission marker;
+ * a compaction summary only when the history it replaced is no longer linked.
+ * Dropped: sidechains, meta entries, tool results, thinking, signatures and
+ * Claude Code's own command/notification envelopes.
+ */
+import { IMAGE_OMITTED_TEXT, IMPORT_WARNING_IMAGE_OMITTED, isWholeElement, textPart, toolNote } from './turns.mjs';
+
+const CLAUDE_ENVELOPE_TAGS = [
+  'local-command-stdout',
+  'local-command-stderr',
+  'local-command-caveat',
+  'task-notification',
+  'system-reminder',
+  'user-prompt-submit-hook',
+  'bash-input',
+  'bash-stdout',
+  'bash-stderr',
+];
+const SLASH_COMMAND_RE = /^(?:\s*<(command-name|command-message|command-args)>[\s\S]*?<\/\1>)+\s*$/;
+const INTERRUPTED_RE = /^\[Request interrupted by user[^\]\n]*\]$/;
+// Claude Code's text annotation that accompanies a pasted image block.
+const IMAGE_ANNOTATION_RE = /^\[Image\b[^\n]*\]$/;
+
+export function isClaudeEnvelopeText(text) {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return true;
+  return (
+    isWholeElement(trimmed, CLAUDE_ENVELOPE_TAGS) ||
+    SLASH_COMMAND_RE.test(trimmed) ||
+    INTERRUPTED_RE.test(trimmed) ||
+    IMAGE_ANNOTATION_RE.test(trimmed)
+  );
+}
+
+const isMessageEntry = (record) => record?.type === 'user' || record?.type === 'assistant';
+const stringOrNull = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+const uuidOrNull = (value) => (typeof value === 'string' ? value : null);
+const timestampOrNull = (value) => (typeof value === 'string' || typeof value === 'number' ? value : null);
+// Rough fixed cost of one retained entry object, so tiny entries still count.
+const ENTRY_OVERHEAD_BYTES = 64;
+const metadataLength = (entry) =>
+  (entry.uuid?.length || 0) +
+  (entry.parentUuid?.length || 0) +
+  (entry.logicalParentUuid?.length || 0) +
+  (typeof entry.at === 'string' ? entry.at.length : 0);
+
+/**
+ * The active branch, root first: walked back from the last main-chain entry.
+ * `crossedCompaction` tells whether a compaction boundary led back into the
+ * history it replaced (Claude Code often no longer keeps that history).
+ */
+function activeChain(entries) {
+  const main = entries.filter((entry) => entry.main);
+  const leaf = main[main.length - 1];
+  if (!leaf || leaf.uuid === null) return { chain: main, crossedCompaction: false };
+  const byUuid = new Map();
+  for (const entry of entries) {
+    if (entry.uuid !== null) byUuid.set(entry.uuid, entry);
+  }
+  const chain = [];
+  const seen = new Set();
+  let crossedCompaction = false;
+  let current = leaf;
+  while (current && !seen.has(current.uuid)) {
+    seen.add(current.uuid);
+    chain.push(current);
+    const parent = current.parentUuid !== null ? byUuid.get(current.parentUuid) : null;
+    const logical = !parent && current.logicalParentUuid !== null ? byUuid.get(current.logicalParentUuid) : null;
+    if (logical) crossedCompaction = true;
+    current = parent || logical;
+  }
+  return { chain: chain.reverse().filter((entry) => entry.main), crossedCompaction };
+}
+
+function entryParts(role, content, warnings) {
+  const blocks = typeof content === 'string' ? [{ type: 'text', text: content }] : content;
+  if (!Array.isArray(blocks)) return [];
+  const parts = [];
+  for (const block of blocks) {
+    if (!block || typeof block !== 'object') continue;
+    if (block.type === 'text' && typeof block.text === 'string') {
+      if (role === 'user' && isClaudeEnvelopeText(block.text)) continue;
+      parts.push(textPart(block.text));
+    } else if (block.type === 'image') {
+      warnings.add(IMPORT_WARNING_IMAGE_OMITTED);
+      parts.push(textPart(IMAGE_OMITTED_TEXT));
+    } else if (block.type === 'tool_use' && role === 'assistant') {
+      parts.push(toolNote(block.name));
+    }
+  }
+  return parts;
+}
+
+function skippedEntry(record) {
+  // Claude Code flags its compaction summary transcript-only as well.
+  if (record.isCompactSummary === true) return false;
+  return record.isMeta === true || record.isVisibleInTranscriptOnly === true || record.isApiErrorMessage === true;
+}
+
+/**
+ * Incremental reducer: `push(record)` keeps a compact chain entry (uuid links
+ * plus the plain-text parts of a main-chain message) and drops the record
+ * itself, so tool results, thinking and image data are never retained.
+ * `chars` is the kept text across every branch so far, `entries` the chain
+ * entries retained and `metadataBytes` their link/timestamp bookkeeping.
+ */
+export function createClaudeReducer() {
+  const entries = [];
+  let recognized = false;
+  let foreignSessionId = null;
+  let cwd = null;
+  let chars = 0;
+  let metadataBytes = 0;
+  return {
+    get chars() {
+      return chars;
+    },
+    get entries() {
+      return entries.length;
+    },
+    get metadataBytes() {
+      return metadataBytes;
+    },
+    push(record) {
+      const message = isMessageEntry(record);
+      if (message) recognized = true;
+      const main = message && record.isSidechain !== true;
+      if (main) {
+        foreignSessionId ||= stringOrNull(record.sessionId);
+        cwd ||= stringOrNull(record.cwd);
+      }
+      const uuid = uuidOrNull(record?.uuid);
+      if (!main && uuid === null) return;
+      const entry = {
+        uuid,
+        parentUuid: uuidOrNull(record.parentUuid),
+        logicalParentUuid: uuidOrNull(record.logicalParentUuid),
+        main,
+        role: null,
+        parts: null,
+        warnings: null,
+        at: timestampOrNull(record.timestamp),
+      };
+      metadataBytes += ENTRY_OVERHEAD_BYTES + metadataLength(entry);
+      if (main && !skippedEntry(record)) {
+        const body = record.message && typeof record.message === 'object' ? record.message : null;
+        entry.role = body?.role === 'user' || body?.role === 'assistant' ? body.role : record.type;
+        const warnings = new Set();
+        entry.parts = entryParts(entry.role, body ? body.content : null, warnings);
+        if (record.isCompactSummary === true) {
+          entry.summary = true;
+          entry.parts = entry.parts.map((part) => ({ ...part, summary: true }));
+        }
+        if (warnings.size) entry.warnings = warnings;
+        for (const part of entry.parts) chars += part.text.length;
+      }
+      entries.push(entry);
+    },
+    result() {
+      const warnings = new Set();
+      const rawTurns = [];
+      const { chain, crossedCompaction } = activeChain(entries);
+      for (const entry of chain) {
+        if (!entry.parts?.length) continue;
+        // The summary stands in for history only when that history is gone.
+        if (entry.summary && crossedCompaction) continue;
+        rawTurns.push({ role: entry.role, parts: entry.parts, at: entry.at });
+        for (const code of entry.warnings || []) warnings.add(code);
+      }
+      return { recognized, foreignSessionId, cwd, rawTurns, warnings };
+    },
+  };
+}
+
+export function convertClaudeRecords(records) {
+  const reducer = createClaudeReducer();
+  for (const record of records) reducer.push(record);
+  return reducer.result();
+}

package/src/runtime/agent/orchestrator/session/conversation-import/codex.mjs

@@ -0,0 +1,136 @@
+/**
+ * Codex CLI rollout (`rollout-*.jsonl`) → raw import turns. Kept: the first
+ * `session_meta` (foreign id, cwd), user/assistant `message` items as text and
+ * tool calls as `[ran tool: <name>]` notes. Dropped: developer/system
+ * messages, Codex's own wrapper user messages, tool outputs, reasoning,
+ * event_msg, token counts and turn_context.
+ */
+import { IMAGE_OMITTED_TEXT, IMPORT_WARNING_IMAGE_OMITTED, isWholeElement, textPart, toolNote } from './turns.mjs';
+
+// User-role envelopes Codex injects itself (environment, instructions, abort
+// notices, plugin hints, shell-command echoes, image wrappers).
+const CODEX_ENVELOPE_TAGS = [
+  'environment_context',
+  'user_instructions',
+  'turn_aborted',
+  'recommended_plugins',
+  'user_shell_command',
+  'subagent_notification',
+  'skills_instructions',
+];
+const TOOL_CALL_TYPES = new Set(['function_call', 'custom_tool_call', 'local_shell_call']);
+
+export function isCodexEnvelopeText(text) {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return true;
+  if (/^# AGENTS\.md instructions\b/.test(trimmed) && trimmed.includes('<INSTRUCTIONS>')) return true;
+  if (isWholeElement(trimmed, CODEX_ENVELOPE_TAGS)) return true;
+  // The `<image name=…>` / `</image>` text parts that wrap an input_image.
+  return /^<image\b[^>]*>$/.test(trimmed) || trimmed === '</image>';
+}
+
+function messageParts(payload, warnings) {
+  const content = typeof payload.content === 'string' ? [{ type: 'text', text: payload.content }] : payload.content;
+  if (!Array.isArray(content)) return [];
+  const parts = [];
+  for (const item of content) {
+    if (!item || typeof item !== 'object') continue;
+    if (item.type === 'input_image' || item.type === 'image') {
+      warnings.add(IMPORT_WARNING_IMAGE_OMITTED);
+      parts.push(textPart(IMAGE_OMITTED_TEXT));
+      continue;
+    }
+    if (typeof item.text !== 'string') continue;
+    if (payload.role === 'user' && isCodexEnvelopeText(item.text)) continue;
+    parts.push(textPart(item.text));
+  }
+  return parts;
+}
+
+function toolName(payload) {
+  if (typeof payload.name === 'string' && payload.name.trim()) return payload.name;
+  return payload.type === 'local_shell_call' ? 'local_shell' : '';
+}
+
+const stringOrNull = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+// Rough fixed cost of one retained turn object, so tiny turns still count.
+const ENTRY_OVERHEAD_BYTES = 64;
+
+/**
+ * Incremental reducer: `push(record)` keeps only the plain-text parts of one
+ * record (the record itself is not retained), `chars` is the kept text so far,
+ * `entries` the raw turns kept and `metadataBytes` their timestamp bookkeeping.
+ */
+export function createCodexReducer() {
+  const warnings = new Set();
+  const rawTurns = [];
+  let recognized = false;
+  let foreignSessionId = null;
+  let cwd = null;
+  let metaSeen = false;
+  let chars = 0;
+  let metadataBytes = 0;
+  const keep = (role, parts, at) => {
+    for (const part of parts) chars += part.text.length;
+    const stamp = typeof at === 'string' || typeof at === 'number' ? at : null;
+    metadataBytes += ENTRY_OVERHEAD_BYTES + (typeof stamp === 'string' ? stamp.length : 0);
+    rawTurns.push({ role, parts, at: stamp });
+  };
+  return {
+    get chars() {
+      return chars;
+    },
+    get entries() {
+      return rawTurns.length;
+    },
+    get metadataBytes() {
+      return metadataBytes;
+    },
+    push(record) {
+      const payload = record?.payload && typeof record.payload === 'object' ? record.payload : null;
+      if (!payload) return;
+      if (record.type === 'session_meta') {
+        recognized = true;
+        if (!metaSeen) {
+          metaSeen = true;
+          foreignSessionId = stringOrNull(payload.id) || stringOrNull(payload.session_id);
+          cwd = stringOrNull(payload.cwd);
+        }
+        return;
+      }
+      if (record.type !== 'response_item') return;
+      recognized = true;
+      if (payload.type === 'message' && (payload.role === 'user' || payload.role === 'assistant')) {
+        const parts = messageParts(payload, warnings);
+        if (parts.length) keep(payload.role, parts, record.timestamp);
+      } else if (TOOL_CALL_TYPES.has(payload.type)) {
+        keep('assistant', [toolNote(toolName(payload))], record.timestamp);
+      }
+    },
+    result() {
+      return { recognized, foreignSessionId, cwd, rawTurns, warnings };
+    },
+  };
+}
+
+export function convertCodexRecords(records) {
+  const reducer = createCodexReducer();
+  for (const record of records) reducer.push(record);
+  return reducer.result();
+}
+
+/** id/cwd of a `session_meta` first line cut off by a bounded prefix read. */
+export function codexMetaFromTruncatedLine(line) {
+  const text = String(line || '');
+  if (!/"type"\s*:\s*"session_meta"/.test(text)) return null;
+  const field = (name) => {
+    const match = new RegExp(`"${name}"\\s*:\\s*("(?:[^"\\\\]|\\\\.)*")`).exec(text);
+    if (!match) return null;
+    try {
+      return stringOrNull(JSON.parse(match[1]));
+    } catch {
+      return null;
+    }
+  };
+  return { foreignSessionId: field('id') || field('session_id'), cwd: field('cwd') };
+}

package/src/runtime/agent/orchestrator/session/conversation-import/convert.mjs

@@ -0,0 +1,128 @@
+/**
+ * JSONL lines of a foreign conversation → normalized plain-text turns, one
+ * line at a time: each parsed record is reduced to its kept plain text and
+ * dropped. Tolerates a BOM, CRLF line ends and individual malformed lines
+ * (reported as the `malformed` warning). Pure, no IO.
+ */
+import { createClaudeReducer } from './claude.mjs';
+import { createCodexReducer } from './codex.mjs';
+import { IMPORT_WARNING_MALFORMED, conversationTitle, normalizeTurns } from './turns.mjs';
+
+export const IMPORT_SOURCES = Object.freeze(['codex', 'claude']);
+/** A line or converted transcript beyond the import limits fails the file. */
+export const IMPORT_ERROR_TOO_LARGE = 'tooLarge';
+export const IMPORT_MAX_LINE_BYTES = 32 * 1024 * 1024;
+/** Bytes read from one source file before it fails as `tooLarge`. */
+export const IMPORT_MAX_FILE_BYTES = 256 * 1024 * 1024;
+/** Normalized transcript text (the final turns, separators and stub included). */
+export const IMPORT_MAX_TRANSCRIPT_CHARS = 4 * 1024 * 1024;
+/** Entries a reducer may retain (Claude chain links, Codex turns). */
+export const IMPORT_MAX_RETAINED_ENTRIES = 200_000;
+/** Bookkeeping a reducer retains besides kept text (ids, links, timestamps). */
+export const IMPORT_MAX_METADATA_BYTES = 16 * 1024 * 1024;
+
+export function isImportSource(value) {
+  return IMPORT_SOURCES.includes(value);
+}
+
+const transcriptChars = (turns) => turns.reduce((total, turn) => total + turn.text.length, 0);
+
+/**
+ * Incremental converter. `pushLine(line)` returns false once the conversion
+ * is over a limit (`tooLarge`): kept text over `maxTranscriptChars`, retained
+ * entries over `maxRetainedEntries` or their bookkeeping over
+ * `maxMetadataBytes`; `markTooLarge()` records a limit enforced by the reader
+ * (an over-long line or file). `result()` may be called repeatedly and also
+ * holds the normalized turns to `maxTranscriptChars`.
+ * `errorCode` is null for an importable result, else one of `empty` |
+ * `malformed` | `unsupported` | `tooLarge` (whose turns are not returned).
+ */
+export function createConversationConverter(
+  source,
+  {
+    maxTranscriptChars = IMPORT_MAX_TRANSCRIPT_CHARS,
+    maxRetainedEntries = IMPORT_MAX_RETAINED_ENTRIES,
+    maxMetadataBytes = IMPORT_MAX_METADATA_BYTES,
+  } = {}
+) {
+  if (!isImportSource(source)) throw new TypeError('source must be codex or claude.');
+  const reducer = source === 'codex' ? createCodexReducer() : createClaudeReducer();
+  let lines = 0;
+  let records = 0;
+  let malformed = 0;
+  let tooLarge = false;
+  return {
+    markTooLarge() {
+      tooLarge = true;
+    },
+    pushLine(raw) {
+      if (tooLarge) return false;
+      let line = String(raw);
+      if (lines++ === 0 && line.charCodeAt(0) === 0xfeff) line = line.slice(1);
+      if (line.endsWith('\r')) line = line.slice(0, -1);
+      if (!line.trim()) return true;
+      let value;
+      try {
+        value = JSON.parse(line);
+      } catch {
+        malformed += 1;
+        return true;
+      }
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        malformed += 1;
+        return true;
+      }
+      records += 1;
+      reducer.push(value);
+      if (
+        reducer.chars > maxTranscriptChars ||
+        reducer.entries > maxRetainedEntries ||
+        reducer.metadataBytes > maxMetadataBytes
+      ) {
+        tooLarge = true;
+      }
+      return !tooLarge;
+    },
+    result() {
+      const parsed = reducer.result();
+      const turns = normalizeTurns(parsed.rawTurns);
+      // Joins and the user stub add text the reducer never counted.
+      if (transcriptChars(turns) > maxTranscriptChars) tooLarge = true;
+      const warnings = new Set(parsed.warnings);
+      if (malformed) warnings.add(IMPORT_WARNING_MALFORMED);
+      let errorCode = null;
+      if (tooLarge) errorCode = IMPORT_ERROR_TOO_LARGE;
+      else if (!records) errorCode = malformed ? 'malformed' : 'empty';
+      else if (!parsed.recognized) errorCode = 'unsupported';
+      else if (!turns.length) errorCode = 'empty';
+      return {
+        source,
+        errorCode,
+        foreignSessionId: parsed.foreignSessionId,
+        cwd: parsed.cwd,
+        turns: tooLarge ? [] : turns,
+        title: conversationTitle(turns),
+        messageCount: tooLarge ? 0 : turns.length,
+        warnings: [...warnings],
+      };
+    },
+  };
+}
+
+/** Convert an in-memory JSONL body; `complete:false` drops a trailing partial line. */
+export function convertConversationText(source, text, { complete = true, ...limits } = {}) {
+  const converter = createConversationConverter(source, limits);
+  let body = String(text ?? '');
+  if (!complete) {
+    const end = body.lastIndexOf('\n');
+    body = end < 0 ? '' : body.slice(0, end);
+  }
+  let start = 0;
+  while (start < body.length) {
+    const newline = body.indexOf('\n', start);
+    const end = newline < 0 ? body.length : newline;
+    if (!converter.pushLine(body.slice(start, end))) break;
+    start = end + 1;
+  }
+  return converter.result();
+}

package/src/runtime/agent/orchestrator/session/conversation-import/imported-session.mjs

@@ -0,0 +1,127 @@
+/**
+ * Materialize an imported conversation as an ordinary Lead session: the normal
+ * createSession initialization (route, tools, context limits, cache config,
+ * system messages, BP3 fields) followed by the converted plain-text turns,
+ * with `importOrigin` provenance. Persisted durably before returning, then
+ * dropped from the same-process live cache.
+ */
+import { createSession } from '../manager/session-lifecycle.mjs';
+import { deleteSession, evictLiveSession, saveSessionAsync } from '../store.mjs';
+import { newTranscriptMessageId } from '../../../../shared/transcript-metadata.mjs';
+import { writeStderrBestEffort } from '../../../../shared/best-effort-stderr.mjs';
+import { IMPORTED_MESSAGE_SOURCE } from '../imported-message.mjs';
+import { ingestSessionTurn } from '../../../../session-search/session-search-ingest.mjs';
+
+export const IMPORT_ORIGIN_VERSION = 1;
+
+/** Dedupe identity: the foreign session id, else the canonical source path. */
+export function importOriginKey(source, foreignSessionId, canonicalPath) {
+  return foreignSessionId ? `${source}:${foreignSessionId}` : `${source}:path:${canonicalPath}`;
+}
+
+export function buildImportOrigin({ source, sourcePath, foreignSessionId = null, sourceCwd = null, importedAt }) {
+  return {
+    version: IMPORT_ORIGIN_VERSION,
+    source,
+    sourcePath,
+    foreignSessionId: foreignSessionId || null,
+    sourceCwd: sourceCwd || null,
+    importedAt,
+    key: importOriginKey(source, foreignSessionId, sourcePath),
+  };
+}
+
+// Lead identity every imported session carries (what a normal Lead session has).
+const LEAD_FIELDS = Object.freeze({ owner: 'cli', agent: 'lead', lane: 'cli', sourceType: 'lead', sourceName: 'main' });
+// Ownership, live binding and placement the importing runtime must not lend.
+const NOT_INHERITED = [
+  'id',
+  'parentSessionId',
+  'ownerSessionId',
+  'visibility',
+  'agentTag',
+  'taskType',
+  'permission',
+  'permissionMode',
+  'clientHostPid',
+  'mcpScopeId',
+  'approvalMode',
+  'scopeKey',
+  'cwd',
+  'desktopSession',
+];
+
+/** Lead createSession options → options of a fresh, unbound imported session. */
+export function importedSessionOptions(leadOptions, { cwd = null, desktopSession }) {
+  const options = { ...leadOptions };
+  for (const key of NOT_INHERITED) delete options[key];
+  Object.assign(options, LEAD_FIELDS);
+  if (cwd) options.cwd = cwd;
+  options.desktopSession = desktopSession;
+  return options;
+}
+
+/** Normalized turns → plain user/assistant transcript messages. `meta.source`
+ *  marks them imported prose: restore and the model wire never read their text
+ *  as runtime control content (reminders, task envelopes, summaries). */
+export function importedTranscriptMessages(turns, importedAt) {
+  return turns.map((turn) => ({
+    role: turn.role,
+    content: turn.text,
+    meta: {
+      source: IMPORTED_MESSAGE_SOURCE,
+      transcript: { messageId: newTranscriptMessageId(), at: turn.at || importedAt },
+    },
+  }));
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// createSession's own debounced save keeps the id pinned until it settles.
+async function evictWhenSettled(id, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (!evictLiveSession(id)) {
+    if (Date.now() >= deadline) return false;
+    await sleep(25);
+  }
+  return true;
+}
+
+/**
+ * Create, fill and persist one imported session. Save failures reject (the
+ * half-made record is removed); once saved it is handed to content-search
+ * ingestion (the same fire-and-forget ingest a finished turn gets) so it is
+ * searchable right away. The live-cache eviction afterwards is bookkeeping only.
+ */
+export async function createImportedSession({
+  leadOptions,
+  conversation,
+  origin,
+  cwd = null,
+  desktopSession,
+  createSessionFn = createSession,
+  ingestFn = ingestSessionTurn,
+  evictTimeoutMs = 5_000,
+}) {
+  const session = createSessionFn(importedSessionOptions(leadOptions, { cwd, desktopSession }));
+  try {
+    // Append after the system layer createSession seeded; never replace it.
+    session.messages.push(...importedTranscriptMessages(conversation.turns, origin.importedAt));
+    session.importOrigin = origin;
+    if (conversation.title) session.title = conversation.title;
+    session.updatedAt = Date.now();
+    await saveSessionAsync(session);
+  } catch (error) {
+    try {
+      deleteSession(session.id);
+    } catch (cleanupError) {
+      writeStderrBestEffort(
+        `[conversation-import] cleanup of ${session.id} failed: ${cleanupError?.message || cleanupError}\n`
+      );
+    }
+    throw error;
+  }
+  ingestFn(session);
+  await evictWhenSettled(session.id, evictTimeoutMs);
+  return session;
+}

package/src/runtime/agent/orchestrator/session/conversation-import/turns.mjs

@@ -0,0 +1,101 @@
+/**
+ * Shared shape of an imported conversation: plain-text user/assistant turns,
+ * the markers that stand in for dropped content, and the title rule. Codex and
+ * Claude Code parsers both emit raw turns `{ role, parts: [{ text, note }], at }`
+ * and normalize them here. Pure, leaf, no IO.
+ */
+
+/** Language-neutral warning codes attached to an imported conversation. */
+export const IMPORT_WARNING_IMAGE_OMITTED = 'imageOmitted';
+export const IMPORT_WARNING_MALFORMED = 'malformed';
+export const IMPORT_WARNING_CWD_MISSING = 'cwdMissing';
+
+/** Stands in for an image the importer does not carry over. */
+export const IMAGE_OMITTED_TEXT = '[image omitted]';
+/** Leads a conversation whose first kept turn is the assistant's. */
+export const IMPORTED_USER_STUB_TEXT = '[Imported conversation continues from an earlier assistant reply.]';
+
+const TITLE_MAX_CHARS = 100;
+
+/** Plain-text note for a tool call: its name only, never its arguments. */
+export function toolNote(name) {
+  const clean = String(name || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return { text: `[ran tool: ${clean || 'unknown'}]`, note: true };
+}
+
+export function textPart(text) {
+  return { text: String(text), note: false };
+}
+
+/** Whole-text match of one XML-style envelope element (`<tag>…</tag>`). */
+export function isWholeElement(text, tags) {
+  const trimmed = String(text || '').trim();
+  return tags.some(
+    (tag) => (trimmed.startsWith(`<${tag}>`) || trimmed.startsWith(`<${tag} `)) && trimmed.endsWith(`</${tag}>`)
+  );
+}
+
+export function timestampMs(value) {
+  const ms = typeof value === 'number' ? value : Date.parse(String(value || ''));
+  return Number.isFinite(ms) && ms > 0 ? ms : null;
+}
+
+// Consecutive tool notes stay one per line; every other boundary is a blank line.
+function joinParts(parts) {
+  let text = '';
+  let previous = null;
+  for (const part of parts) {
+    const piece = String(part.text || '').trim();
+    if (!piece) continue;
+    if (previous) text += previous.note && part.note ? '\n' : '\n\n';
+    text += piece;
+    previous = part;
+  }
+  return { text, last: previous };
+}
+
+/**
+ * Raw turns → normalized turns `{ role, text, at, stub? }`: empty turns dropped,
+ * consecutive same-role turns merged, and a short user stub inserted when the
+ * conversation would otherwise begin with the assistant.
+ */
+export function normalizeTurns(rawTurns) {
+  const merged = [];
+  for (const raw of rawTurns) {
+    if (raw?.role !== 'user' && raw?.role !== 'assistant') continue;
+    const parts = (Array.isArray(raw.parts) ? raw.parts : []).filter((part) => String(part?.text || '').trim());
+    if (!parts.length) continue;
+    const previous = merged[merged.length - 1];
+    if (previous && previous.role === raw.role) previous.parts.push(...parts);
+    else merged.push({ role: raw.role, parts: [...parts], at: timestampMs(raw.at) });
+  }
+  const turns = merged.map(({ role, parts, at }) => {
+    const turn = { role, text: joinParts(parts).text, at };
+    // A carried-over compaction summary never names the conversation.
+    if (parts.some((part) => part.summary)) turn.titleText = joinParts(parts.filter((part) => !part.summary)).text;
+    return turn;
+  });
+  if (turns[0]?.role === 'assistant') {
+    turns.unshift({ role: 'user', text: IMPORTED_USER_STUB_TEXT, at: turns[0].at, stub: true });
+  }
+  return turns;
+}
+
+const titleLines = (turn) =>
+  (turn.titleText ?? turn.text)
+    .split('\n')
+    .map((value) => value.replace(/\s+/g, ' ').trim())
+    .filter(Boolean);
+
+/** First line of the first genuine user turn, whitespace-normalized, ≤100 chars
+ *  (an image marker only when the turn has no text line). */
+export function conversationTitle(turns) {
+  const first = turns.find((turn) => turn.role === 'user' && !turn.stub && titleLines(turn).length);
+  if (!first) return null;
+  const lines = titleLines(first);
+  const line = lines.find((value) => value !== IMAGE_OMITTED_TEXT) || lines[0];
+  if (!line) return null;
+  return Array.from(line).slice(0, TITLE_MAX_CHARS).join('').trim() || null;
+}