mixdog 0.9.1 → 0.9.3

package/src/tui/engine/agent-envelope.mjs

@@ -0,0 +1,296 @@
+/**
+ * src/tui/engine/agent-envelope.mjs - parse agent/background-task/shell
+ * notification envelopes into synthetic tool-item shapes, and derive
+ * status/result text. Extracted from engine.mjs; parseBackgroundTaskEnvelope
+ * remains part of engine.mjs's public surface.
+ */
+import { isBackgroundErrorOnlyBody } from '../../runtime/shared/err-text.mjs';
+
+export function textBetweenTag(text, tag) {
+  const re = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`, 'i');
+  const match = re.exec(String(text ?? ''));
+  return match ? match[1].trim() : '';
+}
+
+export function stripSyntheticAgentTags(text) {
+  const value = String(text ?? '').trim();
+  const finalAnswer = textBetweenTag(value, 'final-answer');
+  if (finalAnswer) return finalAnswer;
+  const taskResult = textBetweenTag(value, 'result');
+  if (taskResult) return taskResult;
+  return value
+    .replace(/^agent result[^\n]*(?:\n|$)/i, '')
+    .replace(/<\/?(?:final-answer|task-notification|task-id|tool-use-id|output-file|result|status|summary|usage|total_tokens|tool_uses|duration_ms|worktree|worktreePath|worktreeBranch)[^>]*>/gi, '')
+    .trim();
+}
+
+export function splitBridgeEnvelope(text) {
+  const value = String(text ?? '').trim();
+  if (!value) return { head: '', body: '' };
+  const match = /\n\s*\n/.exec(value);
+  if (!match) return { head: value, body: '' };
+  return {
+    head: value.slice(0, match.index).trim(),
+    body: value.slice(match.index + match[0].length).trim(),
+  };
+}
+
+export function agentJobStatusText(parsed) {
+  if (!parsed) return '';
+  const parts = [];
+  if (parsed.status) parts.push(`status: ${parsed.status}`);
+  if (parsed.taskId) parts.push(`task_id: ${parsed.taskId}`);
+  return parts.join(' · ');
+}
+
+export function agentJobResultText(text, parsed = parseAgentJob(text)) {
+  const value = String(text ?? '').trim();
+  if (!value) return '';
+  if (parsed?.taskId) {
+    const { body } = splitBridgeEnvelope(value);
+    const cleanBody = stripSyntheticAgentTags(body);
+    if (cleanBody) return cleanBody;
+    return agentJobStatusText(parsed);
+  }
+  return stripSyntheticAgentTags(value) || value;
+}
+
+export function parseAgentResultEnvelope(text, fallback = {}) {
+  const value = String(text ?? '').trim();
+  if (!/^agent result\b/i.test(value)) return null;
+  const [head = '', ...restLines] = value.split('\n');
+  const body = stripSyntheticAgentTags(restLines.join('\n'));
+  const attrs = {};
+  const attrRe = /([a-zA-Z][\w-]*)=("[^"]*"|'[^']*'|\S+)/g;
+  let match;
+  while ((match = attrRe.exec(head))) {
+    attrs[match[1].toLowerCase()] = String(match[2] || '').replace(/^["']|["']$/g, '');
+  }
+  const providerModel = /\s([a-zA-Z0-9_.-]+)\/([^\s]+)\s*$/i.exec(head);
+  const agent = attrs.agent || fallback.agent || '';
+  return {
+    name: 'agent',
+    label: String(fallback.status || attrs.status || 'completed').toLowerCase(),
+    args: {
+      type: 'result',
+      status: fallback.status || attrs.status || 'completed',
+      task_id: fallback.taskId || attrs.task_id || attrs.taskid || undefined,
+      tag: fallback.tag || attrs.tag || undefined,
+      agent: agent || undefined,
+      provider: fallback.provider || attrs.provider || providerModel?.[1] || undefined,
+      model: fallback.model || attrs.model || providerModel?.[2] || undefined,
+      preset: fallback.preset || attrs.preset || undefined,
+      effort: fallback.effort || attrs.effort || undefined,
+      fast: fallback.fast ?? attrs.fast,
+    },
+    result: body || agentJobStatusText({ status: fallback.status || attrs.status || 'completed', taskId: fallback.taskId || attrs.task_id || attrs.taskid || '' }),
+    isError: /^(failed|error|timeout|cancelled|canceled|killed)$/i.test(fallback.status || attrs.status || ''),
+  };
+}
+
+export function parseBackgroundTaskEnvelope(text) {
+  const value = String(text ?? '').trim();
+  if (!/^background task\b/i.test(value)) return null;
+  const allLines = value.split('\n');
+  const rest = allLines.slice(1);
+  const blank = rest.findIndex((line) => !line.trim());
+  const headLines = blank >= 0 ? rest.slice(0, blank) : rest;
+  const body = blank >= 0 ? rest.slice(blank + 1).join('\n').trim() : '';
+  const fields = {};
+  for (const line of headLines) {
+    const match = /^([a-zA-Z][\w-]*):\s*(.*)$/.exec(line.trim());
+    if (match) fields[match[1].toLowerCase()] = match[2].trim();
+  }
+  const surface = String(fields.surface || fields.operation || 'task').toLowerCase();
+  const name = surface === 'explore' || surface === 'search' || surface === 'shell' || surface === 'agent' ? surface : 'task';
+  const status = String(fields.status || '').toLowerCase();
+  const taskId = fields.task_id || fields.taskid || '';
+  const errorText = fields.error || '';
+  const agentResult = parseAgentResultEnvelope(body, {
+    status,
+    taskId,
+    tag: fields.tag || fields.label || '',
+    agent: fields.agent || '',
+    provider: fields.provider || '',
+    model: fields.model || '',
+    preset: fields.preset || '',
+    effort: fields.effort || '',
+    fast: fields.fast,
+  });
+  if (agentResult) return { ...agentResult, rawResult: value };
+  const errorOnlyBody = isBackgroundErrorOnlyBody(body, errorText);
+  const resultBody = body && !errorOnlyBody ? body : '';
+  return {
+    name,
+    label: status || 'notification',
+    args: {
+      type: body ? 'result' : (fields.operation || 'status'),
+      status,
+      task_id: taskId || undefined,
+      surface,
+      operation: fields.operation || undefined,
+      label: fields.label || undefined,
+      tag: fields.tag || undefined,
+      agent: fields.agent || undefined,
+      provider: fields.provider || undefined,
+      model: fields.model || undefined,
+      preset: fields.preset || undefined,
+      effort: fields.effort || undefined,
+      fast: fields.fast || undefined,
+      error: errorText || undefined,
+      startedAt: fields.started || fields.startedat || undefined,
+      finishedAt: fields.finished || fields.finishedat || undefined,
+    },
+    result: resultBody || (!errorText ? [status ? `status: ${status}` : '', taskId ? `task_id: ${taskId}` : ''].filter(Boolean).join(' · ') : ''),
+    rawResult: value,
+    isError: /^(failed|error|timeout|cancelled|canceled|killed)$/i.test(status) || /^error:/i.test(body) || Boolean(errorText),
+  };
+}
+
+export function isStatusOnlyAgentCompletionNotification(text) {
+  const background = parseBackgroundTaskEnvelope(text);
+  if (background?.name === 'agent' && /^(completed|cancelled|canceled)$/i.test(background.label || '')) {
+    return !(hasAgentResponseResultText(background.result) || hasAgentResponseResultText(text));
+  }
+  const parsed = parseAgentJob(text);
+  const result = agentJobResultText(text, parsed);
+  if (!parsed?.taskId || !/^(completed|cancelled|canceled)$/i.test(parsed.status || '')) return false;
+  return !(hasAgentResponseResultText(result) || hasAgentResponseResultText(text));
+}
+
+export function hasAgentResponseResultText(text) {
+  const value = String(text || '').trim();
+  if (!value) return false;
+  if (/^status:\s*(?:running|pending|queued|completed|failed|cancelled|canceled)(?:\s*·\s*task_id:\s*\S+)?$/i.test(value)) return false;
+  if (/^(?:background task\b|agent task:|task_id:)/i.test(value) && !/\n\s*\n[\s\S]*\S/.test(value)) return false;
+  return true;
+}
+
+export function bracketField(text, name) {
+  const re = new RegExp(`^\\[${name}:\\s*([^\\]]*)\\]`, 'mi');
+  return re.exec(String(text ?? ''))?.[1]?.trim() || '';
+}
+
+export function toolResultStatus(text) {
+  const value = String(text ?? '');
+  const tagged = textBetweenTag(value, 'status');
+  if (tagged) return tagged.trim();
+  const bracketed = bracketField(value, 'status');
+  if (bracketed) return bracketed.trim();
+  const inline = /^(?:status|state):\s*([^\s·,;]+)/mi.exec(value);
+  return inline ? inline[1].trim() : '';
+}
+
+export function isErrorToolStatus(status) {
+  return /^(failed|error|timeout|cancelled|canceled|killed)$/i.test(String(status || '').trim());
+}
+
+export function parseSyntheticAgentMessage(text) {
+  const value = String(text ?? '').trim();
+  if (!value) return null;
+  const finalAnswer = textBetweenTag(value, 'final-answer');
+  if (finalAnswer) {
+    return {
+      name: 'agent',
+      label: 'final',
+      args: { type: 'read', description: 'agent result' },
+      result: finalAnswer,
+    };
+  }
+  const agentResult = parseAgentResultEnvelope(value);
+  if (agentResult) return agentResult;
+  const backgroundTask = parseBackgroundTaskEnvelope(value);
+  if (backgroundTask) return backgroundTask;
+  const shellTaskId = bracketField(value, 'task_id');
+  if (shellTaskId) {
+    const status = bracketField(value, 'status') || 'done';
+    const exit = bracketField(value, 'exit');
+    const command = bracketField(value, 'command');
+    return {
+      name: 'shell',
+      label: status,
+      args: { type: 'result', task_id: shellTaskId, command },
+      result: value,
+      isError: /^(failed|error|timeout|cancelled|killed)$/i.test(status) || (exit && exit !== '0' && exit !== 'n/a'),
+    };
+  }
+  const agentJob = parseAgentJob(value);
+  if (agentJob?.taskId) {
+    const label = agentJob.status || 'notification';
+    const result = agentJobResultText(value, agentJob);
+    return {
+      name: 'agent',
+      label,
+      args: agentArgsWithResultMetadata({ type: agentJob.type || 'notification', description: 'agent notification' }, agentJob),
+      result: result || agentJobStatusText(agentJob) || 'agent notification',
+      isError: /^(failed|error|timeout|cancelled|killed)$/i.test(label),
+    };
+  }
+  if (/<task-notification\b/i.test(value)) {
+    const status = textBetweenTag(value, 'status') || 'completed';
+    const summary = textBetweenTag(value, 'summary') || `Agent ${status}`;
+    const taskId = textBetweenTag(value, 'task-id');
+    const result = stripSyntheticAgentTags(value);
+    return {
+      name: 'agent',
+      label: status,
+      taskId,
+      summary,
+      result: result || summary,
+    };
+  }
+  return null;
+}
+
+export function parseAgentJob(text) {
+  const value = String(text || '');
+  const idMatch = /^agent task:\s*([^\s]+)/m.exec(value) || /^task_id:\s*([^\s]+)/m.exec(value);
+  if (!idMatch) return null;
+  const statusMatch = /^status:\s*([^\s(]+)/m.exec(value);
+  const typeMatch = /^type:\s*(.+)$/m.exec(value);
+  const targetMatch = /^target:\s*(.+)$/m.exec(value);
+  const agentMatch = /^agent:\s*(.+)$/m.exec(value);
+  const presetMatch = /^preset:\s*(.+)$/m.exec(value);
+  const modelMatch = /^model:\s*([^/\s]+)\/(.+)$/m.exec(value);
+  const effortMatch = /^effort:\s*(.+)$/m.exec(value);
+  const fastMatch = /^fast:\s*(on|off|true|false)$/m.exec(value);
+  return {
+    taskId: idMatch[1],
+    status: (statusMatch?.[1] || '').toLowerCase(),
+    type: (typeMatch?.[1] || '').trim(),
+    target: (targetMatch?.[1] || '').trim(),
+    agent: (agentMatch?.[1] || '').trim(),
+    preset: (presetMatch?.[1] || '').trim(),
+    provider: (modelMatch?.[1] || '').trim(),
+    model: (modelMatch?.[2] || '').trim(),
+    effort: (effortMatch?.[1] || '').trim(),
+    fast: fastMatch ? /^(on|true)$/i.test(fastMatch[1]) : undefined,
+  };
+}
+
+export function agentArgsWithResultMetadata(args, parsed) {
+  if (!parsed) return args;
+  const next = { ...(args && typeof args === 'object' ? args : {}) };
+  const requestedAction = String(next.type || next.action || next.mode || '').trim().toLowerCase();
+  if (parsed.type) {
+    // Job status envelopes report the original job type (usually "spawn").
+    // Preserve the user's current agent tool action ("status", "read", …) so
+    // manual checks render as "Reviewer status" instead of another
+    // "Spawning Reviewer" card. Keep the job type as metadata for detail.
+    if (!requestedAction || /^(notification|result|completion)$/i.test(requestedAction)) next.type = parsed.type;
+    else next.jobType = parsed.type;
+  }
+  if (parsed.status) next.status = parsed.status;
+  if (parsed.taskId) next.task_id = parsed.taskId;
+  if (parsed.agent) next.agent = parsed.agent;
+  if (parsed.preset) next.preset = parsed.preset;
+  if (parsed.provider) next.provider = parsed.provider;
+  if (parsed.model) next.model = parsed.model;
+  if (parsed.effort) next.effort = parsed.effort;
+  if (parsed.fast !== undefined) next.fast = parsed.fast;
+  if (!next.tag && parsed.target) {
+    const target = parsed.target.split(/\s+/)[0];
+    if (target && !target.startsWith('sess_')) next.tag = target;
+  }
+  return next;
+}

package/src/tui/engine/boot-profile.mjs

@@ -0,0 +1,21 @@
+/**
+ * src/tui/engine/boot-profile.mjs - opt-in boot timing trace.
+ *
+ * Extracted from engine.mjs. Emits `[mixdog-boot]` stderr lines when
+ * MIXDOG_BOOT_PROFILE is truthy; a no-op otherwise.
+ */
+import { performance } from 'node:perf_hooks';
+
+const BOOT_PROFILE_ENABLED = /^(1|true|yes|on)$/i.test(String(process.env.MIXDOG_BOOT_PROFILE || ''));
+const BOOT_PROFILE_START = globalThis.__mixdogBootProfileStart || (globalThis.__mixdogBootProfileStart = performance.now());
+
+export function bootProfile(event, fields = {}) {
+  if (!BOOT_PROFILE_ENABLED) return;
+  const elapsedMs = performance.now() - BOOT_PROFILE_START;
+  const parts = [`[mixdog-boot] +${elapsedMs.toFixed(1)}ms`, `tui:${event}`];
+  for (const [key, value] of Object.entries(fields || {})) {
+    if (value === undefined || value === null || value === '') continue;
+    parts.push(`${key}=${String(value).replace(/\s+/g, '_')}`);
+  }
+  try { process.stderr.write(`${parts.join(' ')}\n`); } catch {}
+}

package/src/tui/engine/labels.mjs

@@ -0,0 +1,67 @@
+/**
+ * src/tui/engine/labels.mjs - spinner verbs, elapsed formatting, and compact
+ * event label/detail helpers. Extracted from engine.mjs.
+ */
+import { SPINNER_VERBS } from '../spinner-verbs.mjs';
+
+export function pickVerb(turn) {
+  return SPINNER_VERBS[(turn * 7 + 3) % SPINNER_VERBS.length];
+}
+
+const TURN_DONE_VERBS = [
+  'Thought',
+  'Reasoned',
+  'Mapped',
+  'Checked',
+  'Solved',
+  'Composed',
+  'Synthesized',
+  'Wrapped',
+];
+
+export function pickDoneVerb(turn) {
+  return TURN_DONE_VERBS[(turn * 5 + 2) % TURN_DONE_VERBS.length];
+}
+
+export function formatElapsedSeconds(ms) {
+  const value = Math.max(0, Number(ms) || 0);
+  if (value <= 0) return '0s';
+  return `${Math.max(1, Math.ceil(value / 1000))}s`;
+}
+
+export function compactEventLabel(event = {}) {
+  const status = String(event.status || '').toLowerCase();
+  const reactive = String(event.trigger || '').toLowerCase() === 'reactive';
+  if (status === 'failed') return reactive ? 'Compact failed (overflow retry)' : 'Compact failed';
+  if (status === 'skipped') return 'Compact skipped';
+  if (status === 'no_change') return 'Compact checked';
+  return reactive ? 'Compact complete (overflow recovery)' : 'Compact complete';
+}
+
+export function compactEventDetail(event = {}) {
+  // Keep the elapsed time as the lead detail, but no longer discard the rest of
+  // the compact metadata. Surface type/trigger and the boundary/pressure so the
+  // statusdone marker reflects what actually fired.
+  const parts = [];
+  const elapsed = formatElapsedSeconds(Number(event.durationMs ?? event.elapsedMs ?? 0));
+  if (elapsed) parts.push(elapsed);
+  const type = String(event.compactType || event.type || '').trim();
+  if (type && type !== 'semantic') parts.push(type);
+  const trigger = String(event.trigger || '').toLowerCase();
+  if (trigger === 'reactive') parts.push('reactive');
+  else if (trigger === 'manual') parts.push('manual');
+  const before = Number(event.beforeTokens ?? event.pressureTokens ?? 0);
+  const after = Number(event.afterTokens ?? 0);
+  const fmtTok = (n) => {
+    const v = Number(n) || 0;
+    if (v >= 1000) return `${(v / 1000).toFixed(v >= 10_000 ? 0 : 1)}k`;
+    return `${Math.round(v)}`;
+  };
+  if (before > 0 && after > 0 && after !== before) parts.push(`${fmtTok(before)}→${fmtTok(after)}`);
+  return parts.join(' · ');
+}
+
+export function projectNameFromPath(value) {
+  const text = String(value || '').replace(/[\\/]+$/, '');
+  return text.split(/[\\/]/).pop() || text || '(current)';
+}

package/src/tui/engine/notice-text.mjs

@@ -0,0 +1,112 @@
+/**
+ * src/tui/engine/notice-text.mjs - polish user-facing failure/notice text.
+ * Extracted from engine.mjs.
+ */
+const FAILED_NOTICE_ACTIONS = new Map([
+  ['api key save', 'save API key'],
+  ['auth-forget', 'forget auth'],
+  ['auto-clear', 'update auto-clear'],
+  ['autoclear', 'update auto-clear'],
+  ['agent', 'run agent command'],
+  ['channels', 'load channels'],
+  ['channels update', 'update channels'],
+  ['clear', 'clear chat'],
+  ['compact', 'compact context'],
+  ['copy', 'copy'],
+  ['core memory', 'load core memory'],
+  ['cwd', 'update working directory'],
+  ['effort switch', 'switch effort'],
+  ['fast', 'update fast mode'],
+  ['hook rule update', 'update hook rule'],
+  ['hook toggle', 'toggle hook'],
+  ['hook update', 'update hook'],
+  ['hooks status', 'load hooks'],
+  ['local provider update', 'update local provider'],
+  ['mcp add', 'add MCP server'],
+  ['mcp reconnect', 'reconnect MCP server'],
+  ['mcp status', 'load MCP status'],
+  ['mcp toggle', 'toggle MCP server'],
+  ['memory', 'run memory command'],
+  ['memory status', 'load memory status'],
+  ['model save', 'save model'],
+  ['model switch', 'switch model'],
+  ['oauth code', 'finish OAuth login'],
+  ['oauth login', 'start OAuth login'],
+  ['output style switch', 'switch output style'],
+  ['OpenAI usage auth save', 'save OpenAI usage auth'],
+  ['OpenCode Go usage auth save', 'save OpenCode Go usage auth'],
+  ['plugin add', 'add plugin'],
+  ['plugin MCP enable', 'enable plugin MCP'],
+  ['plugin uninstall', 'uninstall plugin'],
+  ['plugin update', 'update plugin'],
+  ['plugins status', 'load plugins'],
+  ['providers', 'load providers'],
+  ['recall', 'run recall'],
+  ['resume', 'resume chat'],
+  ['schedule toggle', 'toggle schedule'],
+  ['setup save', 'save setup'],
+  ['settings update', 'update settings'],
+  ['skill add', 'add skill'],
+  ['skills status', 'load skills'],
+  ['tools status', 'load tool status'],
+  ['usage', 'load usage'],
+  ['webhook toggle', 'toggle webhook'],
+  ['workflow switch', 'switch workflow'],
+]);
+
+function polishNoticeAction(action) {
+  const value = String(action || '').trim();
+  if (!value) return 'finish';
+  const key = value.toLowerCase();
+  for (const [candidate, replacement] of FAILED_NOTICE_ACTIONS.entries()) {
+    if (candidate.toLowerCase() === key) return replacement;
+  }
+  const suffixes = [
+    [' save', 'save'],
+    [' switch', 'switch'],
+    [' update', 'update'],
+    [' toggle', 'toggle'],
+    [' reconnect', 'reconnect'],
+    [' enable', 'enable'],
+    [' uninstall', 'uninstall'],
+    [' add', 'add'],
+  ];
+  for (const [suffix, verb] of suffixes) {
+    if (!key.endsWith(suffix)) continue;
+    const subject = value.slice(0, -suffix.length).trim();
+    return subject ? `${verb} ${subject}` : verb;
+  }
+  return value;
+}
+
+function sentenceStart(text) {
+  const value = String(text || '').trim();
+  return value ? `${value[0].toUpperCase()}${value.slice(1)}` : value;
+}
+
+export function polishNoticeText(text) {
+  let value = String(text ?? '').trim().replace(/^✓\s*/, '');
+  if (!value) return '';
+  const error = /^error\s*:\s*(.+)$/i.exec(value);
+  if (error?.[1]) value = error[1].trim();
+  const couldNot = /^could not\s+(.+?)(?::\s*(.+))?$/i.exec(value);
+  if (couldNot) {
+    return couldNot[2]
+      ? `Couldn’t ${couldNot[1]}: ${couldNot[2]}`
+      : `Couldn’t ${couldNot[1]}.`;
+  }
+  const failed = /^(.+?)\s+failed(?::\s*(.+))?$/i.exec(value);
+  if (failed) {
+    const action = polishNoticeAction(failed[1]);
+    return failed[2] ? `Couldn’t ${action}: ${failed[2]}` : `Couldn’t ${action}.`;
+  }
+  const busy = /^(.+?)\s+already in progress\.?$/i.exec(value);
+  if (busy) return `${sentenceStart(polishNoticeAction(busy[1]))} is already running.`;
+  const required = /^(.+?)\s+is required(?:\s+for\s+(.+))?\.?$/i.exec(value);
+  if (required) {
+    const subject = required[1].trim();
+    const target = required[2]?.trim();
+    return `${subject}${target ? ` required for ${target}` : ' required'}.`;
+  }
+  return value;
+}

package/src/tui/engine/queue-helpers.mjs

@@ -0,0 +1,161 @@
+/**
+ * src/tui/engine/queue-helpers.mjs - pure helpers for the prompt/notification
+ * queue: priority ordering, entry visibility/editability, prompt content
+ * flattening, session activity timestamps, and batch merging. Extracted from
+ * engine.mjs.
+ */
+import {
+  agentJobResultText,
+  parseAgentJob,
+  parseSyntheticAgentMessage,
+} from './agent-envelope.mjs';
+
+const QUEUE_PRIORITY = { now: 0, next: 1, later: 2 };
+
+export function queuePriorityValue(value) {
+  return QUEUE_PRIORITY[String(value || 'next')] ?? QUEUE_PRIORITY.next;
+}
+
+export function defaultQueuePriority(mode) {
+  // Queue priority defaults:
+  // - user/bashed prompt input defaults to `next`, so it can be attached at the
+  //   next model-send boundary while a turn is active.
+  // - task notifications default to `later`, unless the caller explicitly marks
+  //   them urgent (e.g. interactive shell stall/completion).
+  return mode === 'task-notification' ? 'later' : 'next';
+}
+
+export function isQueuedEntryEditable(entry) {
+  const mode = entry?.mode || 'prompt';
+  return mode !== 'task-notification' && mode !== 'pending-resume';
+}
+
+export function isQueuedEntryVisible(entry) {
+  // state.queued drives the user-command wait list above the prompt. Background
+  // task completions stay in the internal pending queue, but should never look
+  // like commands typed by the user while they wait to be drained.
+  const mode = entry?.mode || 'prompt';
+  if (mode === 'pending-resume') return false;
+  return isQueuedEntryEditable(entry);
+}
+
+export function isSlashQueuedEntry(entry) {
+  if (entry?.skipSlashCommands) return false;
+  const text = promptContentText(entry?.content ?? entry?.text ?? '');
+  return text.trim().startsWith('/');
+}
+
+export function firstQueueLine(text) {
+  return String(text || '').split('\n').map((line) => line.trim()).find(Boolean) || '';
+}
+
+export function shortTextFingerprint(text) {
+  const value = String(text || '').trim();
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+export function notificationDisplayText(text) {
+  const parsed = parseAgentJob(text);
+  const result = agentJobResultText(text, parsed);
+  const synthetic = parseSyntheticAgentMessage(text);
+  return firstQueueLine(synthetic?.result || result || text) || 'agent notification';
+}
+
+export function promptContentText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => {
+      if (typeof part === 'string') return part;
+      if (part?.type === 'text') return part.text || '';
+      if (part?.type === 'image') return '[Image]';
+      return part?.text || '';
+    }).filter(Boolean).join('\n');
+  }
+  return String(content ?? '');
+}
+
+export function timestampMs(value) {
+  if (value == null || value === '') return 0;
+  const n = Number(value);
+  if (Number.isFinite(n) && n > 0) return n;
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export function hasModelVisibleConversation(session) {
+  const messages = Array.isArray(session?.messages) ? session.messages : [];
+  return messages.some((message) => {
+    const role = message?.role;
+    if (role !== 'user' && role !== 'assistant' && role !== 'tool') return false;
+    const text = promptContentText(message.content).trim();
+    if (role === 'user' && text.startsWith('<system-reminder>')) return false;
+    if (role === 'assistant' && text === '.' && !Array.isArray(message.toolCalls)) return false;
+    return !!text || role === 'assistant' || role === 'tool';
+  });
+}
+
+export function sessionActivityTimestamp(session, fallback = 0) {
+  if (!hasModelVisibleConversation(session)) return 0;
+  return timestampMs(session?.lastUsedAt)
+    || timestampMs(session?.updatedAt)
+    || timestampMs(fallback);
+}
+
+export function promptDisplayText(content, options = {}) {
+  if (typeof options.displayText === 'string') return options.displayText;
+  return promptContentText(content);
+}
+
+export function mergePromptContents(entries) {
+  const batch = Array.isArray(entries) ? entries : [];
+  if (batch.every((entry) => typeof entry?.content === 'string')) {
+    return batch.map((entry) => entry.content).filter((text) => String(text || '').trim()).join('\n');
+  }
+  const parts = [];
+  for (const entry of batch) {
+    const content = entry?.content;
+    if (typeof content === 'string') {
+      if (content.trim()) parts.push({ type: 'text', text: content });
+    } else if (Array.isArray(content)) {
+      parts.push(...content);
+    }
+    parts.push({ type: 'text', text: '\n' });
+  }
+  while (parts.length && parts[parts.length - 1]?.type === 'text' && parts[parts.length - 1]?.text === '\n') parts.pop();
+  return parts.length === 1 && parts[0]?.type === 'text' ? parts[0].text : parts;
+}
+
+export function mergePastedImages(entries) {
+  const out = {};
+  for (const entry of entries || []) {
+    const images = entry?.pastedImages;
+    if (!images || typeof images !== 'object') continue;
+    for (const [id, image] of Object.entries(images)) {
+      if (image) out[id] = image;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+export function mergePastedTexts(entries) {
+  const out = {};
+  for (const entry of entries || []) {
+    const texts = entry?.pastedTexts;
+    if (!texts || typeof texts !== 'object') continue;
+    for (const [id, text] of Object.entries(texts)) {
+      if (text) out[id] = text;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+export function callCommitCallbacks(entries) {
+  for (const entry of entries || []) {
+    try { entry?.onCommitted?.(); } catch {}
+  }
+}