pikiloop 0.4.0

package/dist/agent/utils.js

@@ -0,0 +1,687 @@
+/**
+ * Pure utility functions shared across the agent layer.
+ * No filesystem or session state side effects.
+ */
+import fs from 'node:fs';
+import { writeScopedLog } from '../core/logging.js';
+export const Q = (a) => {
+    if (/[^a-zA-Z0-9_./:=@-]/.test(a)) {
+        return process.platform === 'win32'
+            ? `"${a.replace(/"/g, '""')}"`
+            : `'${a.replace(/'/g, "'\\''")}'`;
+    }
+    return a;
+};
+export function agentLog(msg, level = 'debug') {
+    writeScopedLog('agent', msg, { level });
+}
+export function agentWarn(msg) {
+    agentLog(msg, 'warn');
+}
+export function agentError(msg) {
+    agentLog(msg, 'error');
+}
+export function dedupeStrings(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const item = String(value || '').trim();
+        if (!item || seen.has(item))
+            continue;
+        seen.add(item);
+        deduped.push(item);
+    }
+    return deduped;
+}
+export function numberOrNull(...values) {
+    for (const value of values) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+    }
+    return null;
+}
+export function normalizeStreamPreviewPlan(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    const rawSteps = Array.isArray(record.steps)
+        ? record.steps
+        : Array.isArray(record.plan)
+            ? record.plan
+            : [];
+    const steps = rawSteps
+        .map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return null;
+        const step = typeof entry.step === 'string' ? entry.step.trim() : '';
+        if (!step)
+            return null;
+        const rawStatus = typeof entry.status === 'string' ? entry.status : 'pending';
+        const status = rawStatus === 'completed' || rawStatus === 'inProgress' || rawStatus === 'pending'
+            ? rawStatus
+            : 'pending';
+        return { step, status };
+    })
+        .filter((entry) => !!entry);
+    if (!steps.length)
+        return null;
+    return {
+        explanation: typeof record.explanation === 'string' && record.explanation.trim() ? record.explanation.trim() : null,
+        steps,
+    };
+}
+/** Parse a TodoWrite tool input into a StreamPreviewPlan. */
+export function parseTodoWriteAsPlan(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const rawTodos = Array.isArray(input.todos) ? input.todos : [];
+    if (!rawTodos.length)
+        return null;
+    const steps = [];
+    for (const todo of rawTodos) {
+        if (!todo || typeof todo !== 'object')
+            continue;
+        const content = typeof todo.content === 'string' ? todo.content.trim() : '';
+        if (!content)
+            continue;
+        const rawStatus = typeof todo.status === 'string' ? todo.status : 'pending';
+        const status = rawStatus === 'completed' ? 'completed'
+            : rawStatus === 'in_progress' ? 'inProgress'
+                : 'pending';
+        steps.push({ step: content, status });
+    }
+    if (!steps.length)
+        return null;
+    return { explanation: null, steps };
+}
+export function normalizeActivityLine(text) { return text.replace(/\s+/g, ' ').trim(); }
+// The activity feed is only ever rendered as a tail — downstream previews trim
+// it to ~900 chars (trimActivityForPreview) and the final reply to ~1600 — yet
+// every tool event rebuilds `s.activity = recentActivity.join('\n')`. A 500-line
+// cap made that rejoin effectively O(n²) over a tool-heavy turn for history no
+// view ever shows; 80 lines comfortably covers the largest consumer.
+export function pushRecentActivity(lines, line, maxLines = 80) {
+    const cleaned = normalizeActivityLine(line);
+    if (!cleaned)
+        return;
+    if (lines[lines.length - 1] === cleaned)
+        return;
+    lines.push(cleaned);
+    if (lines.length > maxLines)
+        lines.splice(0, lines.length - maxLines);
+}
+export function firstNonEmptyLine(text) {
+    for (const line of String(text || '').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return '';
+}
+// MCP tool results carry structured content blocks (e.g. screenshot returns
+// `[{type:'image',...}, {type:'text', text:'Saved as ...'}]`). Coerce that to
+// plain text by keeping only the `type:'text'` blocks; otherwise `String([{…}])`
+// silently becomes the literal "[object Object]" in activity summaries.
+export function coerceToolResultText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        return value
+            .filter((c) => c && c.type === 'text' && typeof c.text === 'string')
+            .map((c) => c.text)
+            .join('\n');
+    }
+    return '';
+}
+export function shortValue(value, max = 90) {
+    const text = typeof value === 'string' ? value.trim() : value == null ? '' : String(value).trim();
+    if (!text)
+        return '';
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, Math.max(0, max - 3)).trimEnd()}...`;
+}
+export function normalizeErrorMessage(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (value instanceof Error)
+        return value.message.trim();
+    if (Array.isArray(value)) {
+        return value.map(item => normalizeErrorMessage(item)).filter(Boolean).join('; ').trim();
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        const preferred = normalizeErrorMessage(record.message)
+            || normalizeErrorMessage(record.error)
+            || normalizeErrorMessage(record.detail)
+            || normalizeErrorMessage(record.type)
+            || normalizeErrorMessage(record.code)
+            || normalizeErrorMessage(record.status);
+        if (preferred)
+            return preferred;
+        try {
+            return JSON.stringify(value).trim();
+        }
+        catch { }
+    }
+    return value == null ? '' : String(value).trim();
+}
+export function joinErrorMessages(errors) {
+    if (!errors?.length)
+        return '';
+    return errors.map(error => normalizeErrorMessage(error)).filter(Boolean).join('; ').trim();
+}
+/**
+ * Detect Claude Code's synthetic "API Error: …" assistant message. When the
+ * upstream Anthropic API returns a transient error (529 Overloaded, 5xx, gateway
+ * timeouts, …), the Claude CLI swallows it and replaces the assistant turn with
+ * a single `text` block whose body is literally `API Error: <reason>`. The
+ * turn's stop_reason still claims `end_turn`, so the driver can't distinguish
+ * it from a normal short reply without inspecting the text.
+ *
+ * Heuristics — keep them tight so real prose mentioning "API Error" doesn't
+ * trip the detector:
+ *  - exact prefix "API Error: "
+ *  - total length ≤ 200 chars (the synthetic line is always short)
+ *  - no newlines (legit prose containing "API Error" virtually always wraps)
+ *
+ * Returns the trimmed reason (e.g. "Overloaded", "Internal server error") when
+ * matched, otherwise null. Callers decide whether the reason is retryable —
+ * `looksRetryable` answers that.
+ */
+export function detectClaudeApiError(text) {
+    if (!text)
+        return null;
+    const trimmed = text.trim();
+    if (trimmed.length > 200 || trimmed.includes('\n'))
+        return null;
+    const m = trimmed.match(/^API Error:\s*(.+)$/i);
+    return m ? m[1].trim() : null;
+}
+/**
+ * Retryable Claude Code API errors — transient upstream conditions that
+ * usually clear within seconds. Non-retryable conditions (auth, quota,
+ * context length) fall through and surface to the user immediately.
+ */
+export function isRetryableClaudeApiError(reason) {
+    const r = reason.toLowerCase();
+    if (/rate limit|rate limited|quota|usage limit|session limit/i.test(r))
+        return false;
+    return /overloaded|overload|timeout|timed out|500|502|503|504|529|temporar|gateway|connection|network|internal (server )?error/i.test(r);
+}
+/**
+ * Detect Claude Code's "selected model is unavailable" notice — emitted when
+ * the requested `--model` id is disabled / not provisioned for the account (a
+ * 404 model_not_found). Its delivery differs by mode:
+ *   - `-p`/stream-json: a `<synthetic>` assistant event carrying
+ *     `error:"model_not_found"` plus the banner text, and a `result` event with
+ *     `is_error` — both reach the parser.
+ *   - TUI: the banner is *only* painted to the PTY screen. It is never written
+ *     to the transcript JSONL and fires no Stop hook (verified 2026-06-13), so
+ *     the screen scrape is the sole signal and the turn would otherwise hang
+ *     until the stall watchdog (3–10 min).
+ *
+ * Matching is whitespace-insensitive on purpose: the TUI renders the banner
+ * character-by-character with cursor positioning, so after ANSI stripping the
+ * words lose their spaces and wrap arbitrarily ("issuewiththeselectedmodel").
+ * Collapsing whitespace on both sides makes the match survive that rendering.
+ * Callers compose the user-facing message via `claudeModelErrorMessage` with
+ * the concrete model id they hold.
+ */
+export function detectClaudeModelError(text) {
+    if (!text)
+        return false;
+    const collapsed = text.replace(/\s+/g, '').toLowerCase();
+    return collapsed.includes('issuewiththeselectedmodel')
+        || collapsed.includes('maynotexistoryoumaynothaveaccess');
+}
+/** User-facing message for an unavailable / no-access model (see {@link detectClaudeModelError}). */
+export function claudeModelErrorMessage(model) {
+    const id = (model || '').trim();
+    return `The selected model${id ? ` (${id})` : ''} is unavailable — it may not exist, or this account doesn't have access to it. Switch to a different model in pikiloop settings.`;
+}
+export function appendSystemPrompt(base, extra) {
+    const lhs = String(base || '').trim();
+    const rhs = String(extra || '').trim();
+    if (!lhs)
+        return rhs;
+    if (!rhs)
+        return lhs;
+    return `${lhs}\n\n${rhs}`;
+}
+export function mimeForExt(ext) {
+    switch (ext) {
+        case '.jpg':
+        case '.jpeg': return 'image/jpeg';
+        case '.png': return 'image/png';
+        case '.gif': return 'image/gif';
+        case '.webp': return 'image/webp';
+        default: return 'application/octet-stream';
+    }
+}
+export function computeContext(s) {
+    const fallbackTotal = (s.inputTokens ?? 0) + (s.cachedInputTokens ?? 0) + (s.cacheCreationInputTokens ?? 0);
+    const used = s.contextUsedTokens ?? (fallbackTotal > 0 ? fallbackTotal : null);
+    const pct = used != null && s.contextWindow
+        ? Math.min(99.9, Math.round(used / s.contextWindow * 1000) / 10)
+        : null;
+    return { contextUsedTokens: used, contextPercent: pct };
+}
+/** Max structured tool calls carried per preview emit (most recent win). */
+const PREVIEW_TOOL_CALLS_MAX = 40;
+export function buildStreamPreviewMeta(s) {
+    const ctx = computeContext(s);
+    const meta = {
+        inputTokens: s.inputTokens, outputTokens: s.outputTokens,
+        cachedInputTokens: s.cachedInputTokens,
+        contextUsedTokens: ctx.contextUsedTokens, contextPercent: ctx.contextPercent,
+    };
+    // Turn-cumulative output: finished calls' total + the in-flight call.
+    const turnOutput = (s.turnOutputTokensBase ?? 0) + (s.outputTokens ?? 0);
+    if (turnOutput > 0)
+        meta.turnOutputTokens = turnOutput;
+    if (s.byokProviderName)
+        meta.providerName = s.byokProviderName;
+    if (s.subAgents && s.subAgents.size > 0)
+        meta.subAgents = Array.from(s.subAgents.values());
+    if (s.generatingImages && s.generatingImages > 0)
+        meta.generatingImages = s.generatingImages;
+    if (s.claudeToolCallOrder?.length && s.claudeToolsById) {
+        const calls = [];
+        for (const id of s.claudeToolCallOrder.slice(-PREVIEW_TOOL_CALLS_MAX)) {
+            const tool = s.claudeToolsById.get(id);
+            if (!tool)
+                continue;
+            calls.push({
+                id,
+                name: tool.name,
+                summary: tool.summary,
+                input: tool.input ?? null,
+                result: tool.result ?? null,
+                status: tool.status ?? 'running',
+            });
+        }
+        if (calls.length)
+            meta.toolCalls = calls;
+    }
+    return meta;
+}
+/**
+ * Bounded, human-readable input detail for a live tool-call row. Bash shows
+ * the raw command (the summary already carries the description); everything
+ * else gets compact JSON. Returns null when there's nothing beyond the
+ * summary worth expanding.
+ */
+export function previewToolCallInput(name, input, max = 500) {
+    if (input == null)
+        return null;
+    if (String(name) === 'Bash') {
+        const cmd = typeof input.command === 'string' ? input.command.trim() : '';
+        return cmd ? clipText(cmd, max) : null;
+    }
+    try {
+        const json = JSON.stringify(input, null, 1);
+        if (!json || json === '{}' || json === 'null')
+            return null;
+        return clipText(json, max);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bounded text preview of a tool result. Accepts the JSONL tool_result
+ * `content` (string | block array) or a hook `tool_response` (string |
+ * object). Extracts text blocks where present, falls back to compact JSON.
+ */
+export function previewToolCallResult(content, max = 500) {
+    if (content == null)
+        return null;
+    if (typeof content === 'string')
+        return clipText(content.trim(), max) || null;
+    if (Array.isArray(content)) {
+        const text = content
+            .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+            .map((b) => b.text)
+            .join('\n')
+            .trim();
+        return text ? clipText(text, max) : null;
+    }
+    if (typeof content === 'object') {
+        // Hook tool_response commonly nests the payload under `content` / `result`.
+        if (content.content != null && content.content !== content) {
+            const nested = previewToolCallResult(content.content, max);
+            if (nested)
+                return nested;
+        }
+        if (typeof content.result === 'string')
+            return clipText(content.result.trim(), max) || null;
+        try {
+            const json = JSON.stringify(content, null, 1);
+            if (!json || json === '{}')
+                return null;
+            return clipText(json, max);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function clipText(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+// Claude tool use helpers (used by driver-claude.ts)
+export function summarizeClaudeToolUse(name, input) {
+    const tool = String(name || '').trim() || 'Tool';
+    const description = shortValue(input?.description, 120);
+    switch (tool) {
+        case 'Read': {
+            const t = shortValue(input?.file_path || input?.path, 140);
+            return t ? `Read ${t}` : 'Read file';
+        }
+        case 'Edit': {
+            const t = shortValue(input?.file_path || input?.path, 140);
+            return t ? `Edit ${t}` : 'Edit file';
+        }
+        case 'Write': {
+            const t = shortValue(input?.file_path || input?.path, 140);
+            return t ? `Write ${t}` : 'Write file';
+        }
+        case 'Glob': {
+            const p = shortValue(input?.pattern || input?.glob, 120);
+            return p ? `List files: ${p}` : 'List files';
+        }
+        case 'Grep': {
+            const p = shortValue(input?.pattern || input?.query, 120);
+            return p ? `Search text: ${p}` : 'Search text';
+        }
+        case 'WebFetch': {
+            const u = shortValue(input?.url, 120);
+            return u ? `Fetch ${u}` : 'Fetch web page';
+        }
+        case 'WebSearch': {
+            const q = shortValue(input?.query, 120);
+            return q ? `Search web: ${q}` : 'Search web';
+        }
+        case 'TodoWrite': return 'Update plan';
+        case 'AskUserQuestion': {
+            // Claude's built-in clarify tool. The CLI in `-p` mode self-resolves it
+            // with an error and degrades to a plain-text question in the same turn —
+            // we just surface the question text in the activity panel so users see
+            // what was asked.
+            const qs = Array.isArray(input?.questions) ? input.questions : [];
+            const first = qs[0];
+            const q = shortValue(first?.question || input?.question, 120);
+            return q ? `Ask user: ${q}` : 'Ask user';
+        }
+        case 'Task': {
+            const p = shortValue(input?.description || input?.prompt, 120);
+            return p ? `Run task: ${p}` : 'Run task';
+        }
+        case 'Bash': {
+            if (description)
+                return `Run shell: ${description}`;
+            const c = shortValue(input?.command, 120);
+            return c ? `Run shell: ${c}` : 'Run shell command';
+        }
+        default: {
+            // MCP tools come through as `mcp__<server>__<tool>` — unwrap common pikiloop tools
+            const mcpMatch = tool.match(/^mcp__[^_]+__(.+)$/);
+            const bare = mcpMatch ? mcpMatch[1] : tool;
+            if (bare === 'im_send_file') {
+                const p = shortValue(input?.path, 120);
+                return p ? `Send file: ${p}` : 'Send file';
+            }
+            if (bare === 'im_list_files')
+                return 'List workspace files';
+            if (bare === 'im_ask_user') {
+                const q = shortValue(input?.question, 120);
+                return q ? `Ask user: ${q}` : 'Ask user';
+            }
+            if (description)
+                return `${tool}: ${description}`;
+            const d = shortValue(input?.file_path || input?.path || input?.command || input?.query || input?.pattern || input?.url, 120);
+            return d ? `${tool}: ${d}` : tool;
+        }
+    }
+}
+export function summarizeClaudeToolResult(tool, block, toolUseResult) {
+    const summary = tool?.summary || shortValue(tool?.name || 'Tool', 120) || 'Tool';
+    const isError = !!block?.is_error;
+    const contentText = coerceToolResultText(block?.content);
+    if (isError) {
+        const detail = firstNonEmptyLine(toolUseResult?.stderr || toolUseResult?.stdout || contentText);
+        return detail ? `${summary} failed: ${shortValue(detail, 120)}` : `${summary} failed`;
+    }
+    const toolName = tool?.name || '';
+    if (toolName === 'Read' || toolName === 'Edit' || toolName === 'Write' || toolName === 'TodoWrite')
+        return `${summary} done`;
+    const detail = firstNonEmptyLine(toolUseResult?.stdout || contentText || toolUseResult?.stderr || '');
+    if (!detail)
+        return `${summary} done`;
+    return `${summary} -> ${shortValue(detail, 120)}`;
+}
+// Usage helpers (used by drivers)
+export function roundPercent(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return null;
+    return Math.max(0, Math.min(100, Math.round(n * 10) / 10));
+}
+export function toIsoFromEpochSeconds(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    return new Date(n * 1000).toISOString();
+}
+export function normalizeUsageStatus(value) {
+    const raw = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (!raw)
+        return null;
+    const normalized = raw.replace(/[\s-]+/g, '_');
+    if (normalized === 'limit_reached' || normalized === 'warning' || normalized === 'allowed')
+        return normalized;
+    if (normalized.includes('limit') || normalized.includes('exceeded') || normalized.includes('denied'))
+        return 'limit_reached';
+    if (normalized.includes('warning') || normalized.includes('warn'))
+        return 'warning';
+    if (normalized.includes('allowed') || normalized === 'ok' || normalized === 'healthy' || normalized === 'ready')
+        return 'allowed';
+    return normalized;
+}
+export function labelFromWindowMinutes(value, fallback) {
+    const minutes = Number(value);
+    if (!Number.isFinite(minutes) || minutes <= 0)
+        return fallback;
+    const roundedMinutes = Math.round(minutes);
+    if (Math.abs(roundedMinutes - 300) <= 2)
+        return '5h';
+    if (Math.abs(roundedMinutes - 10080) <= 5)
+        return '7d';
+    const roundedDays = Math.round(roundedMinutes / 1440);
+    if (roundedDays >= 1 && Math.abs(roundedMinutes - roundedDays * 1440) <= 5)
+        return `${roundedDays}d`;
+    const roundedHours = Math.round(roundedMinutes / 60);
+    if (roundedHours >= 1 && Math.abs(roundedMinutes - roundedHours * 60) <= 2)
+        return `${roundedHours}h`;
+    return `${roundedMinutes}m`;
+}
+export function usageWindowFromRateLimit(fallback, limit) {
+    if (!limit || typeof limit !== 'object')
+        return null;
+    const usedPercent = roundPercent(limit.used_percent);
+    const remainingPercent = usedPercent == null ? null : Math.max(0, Math.round((100 - usedPercent) * 10) / 10);
+    const resetAt = toIsoFromEpochSeconds(limit.reset_at ?? limit.resets_at);
+    let resetAfterSeconds = null;
+    const directResetAfter = Number(limit.reset_after_seconds);
+    if (Number.isFinite(directResetAfter) && directResetAfter >= 0)
+        resetAfterSeconds = Math.round(directResetAfter);
+    else if (resetAt) {
+        const resetAtMs = Date.parse(resetAt);
+        if (Number.isFinite(resetAtMs))
+            resetAfterSeconds = Math.max(0, Math.round((resetAtMs - Date.now()) / 1000));
+    }
+    return {
+        label: labelFromWindowMinutes(limit.window_minutes, fallback),
+        usedPercent, remainingPercent, resetAt, resetAfterSeconds,
+        status: normalizeUsageStatus(limit.status),
+    };
+}
+export function parseJsonTail(raw) {
+    const start = raw.indexOf('{');
+    if (start < 0)
+        return null;
+    try {
+        return JSON.parse(raw.slice(start));
+    }
+    catch {
+        return null;
+    }
+}
+export function modelFamily(model) {
+    const lower = model?.toLowerCase() || '';
+    if (!lower)
+        return null;
+    if (lower.includes('fable'))
+        return 'fable';
+    if (lower.includes('opus'))
+        return 'opus';
+    if (lower.includes('sonnet'))
+        return 'sonnet';
+    return null;
+}
+export function normalizeClaudeModelId(model) {
+    return typeof model === 'string' ? model.trim() : '';
+}
+export function emptyUsage(agent, error) {
+    return { ok: false, agent, source: null, capturedAt: null, status: null, windows: [], error };
+}
+export function readTailLines(filePath, maxBytes = 256 * 1024) {
+    try {
+        const stat = fs.statSync(filePath);
+        const readSize = Math.min(maxBytes, stat.size);
+        const fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(readSize);
+        fs.readSync(fd, buf, 0, readSize, stat.size - readSize);
+        fs.closeSync(fd);
+        return buf.toString('utf-8').split('\n').filter(l => l.trim());
+    }
+    catch {
+        return [];
+    }
+}
+export function stripInjectedPrompts(text) {
+    const markers = ['\n[Session Workspace]'];
+    for (const m of markers) {
+        const idx = text.indexOf(m);
+        if (idx >= 0)
+            text = text.slice(0, idx).trim();
+    }
+    // Strip Codex IDE context prefix ("# Context from my IDE setup: ...")
+    if (text.startsWith('# Context from')) {
+        const tag = '## My request for Codex:\n';
+        const idx = text.indexOf(tag);
+        if (idx >= 0)
+            return text.slice(idx + tag.length).trim();
+        return '';
+    }
+    return text;
+}
+export const SESSION_PREVIEW_IGNORED_USER_PATTERNS = [
+    /^\[Request interrupted by user(?: for tool use)?\]$/i,
+];
+export const SESSION_PREVIEW_IMAGE_PLACEHOLDER_RE = /\[Image:[^\]]+\]/gi;
+export const SESSION_PREVIEW_FILE_PLACEHOLDER_RE = /\[Attached file:[^\]]+\]/gi;
+/**
+ * Claude TUI mode prepends `@/abs/path/file.ext` mentions to the prompt as
+ * positional argv (see `src/agent/drivers/claude-tui.ts`) — that's how the TUI
+ * ingests local image files. The mentions end up baked into the JSONL user
+ * `content` string verbatim. This regex captures them so:
+ *   - the dashboard's user bubble (via `getClaudeSessionMessages`) can lift
+ *     them into structured `image` blocks for thumbnail rendering;
+ *   - session-list previews don't surface a long absolute path.
+ * Whitespace-free paths only — matches what `claude-tui.ts` emits.
+ */
+export const CLAUDE_AT_MENTION_IMAGE_RE = /(^|\s)@(\/[^\s@\n]+\.(?:png|jpe?g|gif|webp|svg))(?=\s|$)/gi;
+/** Pull the absolute paths out of every image-mention in `text`. */
+export function extractClaudeAtMentionImagePaths(text) {
+    if (!text)
+        return [];
+    const out = [];
+    for (const m of text.matchAll(CLAUDE_AT_MENTION_IMAGE_RE))
+        out.push(m[2]);
+    return out;
+}
+/** Remove image @-mentions from `text` while preserving the leading boundary
+ *  character (start-of-string or whitespace) so adjacent content stays joinable. */
+export function stripClaudeAtMentionImages(text) {
+    if (!text)
+        return text;
+    return text.replace(CLAUDE_AT_MENTION_IMAGE_RE, (_full, leading) => leading || '');
+}
+export function sanitizeSessionUserPreviewText(text) {
+    const cleaned = stripInjectedPrompts(text)
+        .replace(SESSION_PREVIEW_IMAGE_PLACEHOLDER_RE, ' ')
+        .replace(SESSION_PREVIEW_FILE_PLACEHOLDER_RE, ' ')
+        .replace(CLAUDE_AT_MENTION_IMAGE_RE, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!cleaned)
+        return '';
+    if (SESSION_PREVIEW_IGNORED_USER_PATTERNS.some(pattern => pattern.test(cleaned)))
+        return '';
+    return cleaned;
+}
+export function isPendingSessionId(sessionId) {
+    return typeof sessionId === 'string' && sessionId.startsWith('pending_');
+}
+/**
+ * Update a stream-state's session id and notify the caller in one step.
+ *
+ * Drivers used to assign `s.sessionId = ev.session_id ?? s.sessionId` at every
+ * place the CLI surfaced an id, then leave promotion until `finalizeStreamResult`
+ * at end-of-stream. That meant an early abort (before the result line) or a
+ * mid-stream rotation (Claude `--resume` rewriting the session id) was invisible
+ * to the bot runtime — leaving the runtime stuck on a pending id, or letting a
+ * later insertion land on a phantom session. Routing through this helper makes
+ * every observed id change propagate immediately to `opts.onSessionId`, which
+ * in bot.ts wires straight into `promoteSessionRuntime`.
+ */
+export function emitSessionIdUpdate(s, rawId) {
+    if (typeof rawId !== 'string')
+        return;
+    const trimmed = rawId.trim();
+    if (!trimmed || trimmed === s.sessionId)
+        return;
+    s.sessionId = trimmed;
+    try {
+        s._emitSessionId?.(trimmed);
+    }
+    catch { /* listeners must not break the stream loop */ }
+}
+/**
+ * Canonical session-list display title used by *every* surface (IM channels
+ * + dashboard). The order is intentional:
+ *
+ *   1. `title` — set ONCE from the original user prompt that started the
+ *      session. Stable; never overwritten by sub-agent or tool prompts.
+ *   2. `lastQuestion` — most recent user message. Fallback only, because for
+ *      Claude this can be a Task-tool sub-agent prompt and we don't want
+ *      sub-agent text leaking into the title.
+ *   3. `sessionId` — last-resort identifier.
+ *
+ * The dashboard frontend (`dashboard/src/utils.ts`) mirrors this order — keep
+ * the two in sync.
+ */
+export function sessionListDisplayTitle(session) {
+    const title = sanitizeSessionUserPreviewText(String(session.title || ''));
+    if (title)
+        return title;
+    const question = sanitizeSessionUserPreviewText(String(session.lastQuestion || ''));
+    if (question)
+        return question;
+    return session.sessionId || '';
+}