@geteigen/cli 0.0.0-stage → 3.1.0

package/dist/shared/clarifyingQuestions.js

@@ -0,0 +1,207 @@
+const QUESTION_TOOL_RE = /^(askuserquestion|askfollowupquestion|askquestion|ask_user|ask_followup_question|ask_user_question|clarify|question|userinput|getinput)/i;
+/** Whether a tool name represents an agent asking the user clarifying questions. */
+export function isQuestionTool(name) {
+    return QUESTION_TOOL_RE.test(name.replace(/ToolCall$/i, ""));
+}
+/**
+ * Parse structured clarifying questions from tool input/arguments.
+ * Supports Claude Code's AskUserQuestion schema as well as general key/value formats.
+ */
+export function parseQuestionToolArgs(args) {
+    if (!args || typeof args !== "object")
+        return [];
+    const raw = args;
+    // Case 1: questions array (Claude Code / Agent SDK standard)
+    if (Array.isArray(raw.questions)) {
+        const list = [];
+        for (let i = 0; i < raw.questions.length; i++) {
+            const q = raw.questions[i];
+            if (typeof q === "string" && q.trim()) {
+                list.push({ id: `q-${i + 1}`, question: q.trim() });
+            }
+            else if (q && typeof q === "object") {
+                const item = q;
+                const questionText = String(item.question ?? item.prompt ?? item.text ?? item.title ?? "").trim();
+                if (!questionText)
+                    continue;
+                const header = typeof item.header === "string" ? item.header.trim() : undefined;
+                const multiSelect = Boolean(item.multiSelect);
+                let options;
+                if (Array.isArray(item.options)) {
+                    options = item.options
+                        .map((opt) => {
+                        if (typeof opt === "string" && opt.trim()) {
+                            return { label: opt.trim() };
+                        }
+                        if (opt && typeof opt === "object") {
+                            const o = opt;
+                            const label = String(o.label ?? o.text ?? o.title ?? "").trim();
+                            const description = typeof o.description === "string"
+                                ? o.description.trim()
+                                : undefined;
+                            if (label)
+                                return { label, description };
+                        }
+                        return null;
+                    })
+                        .filter((o) => o !== null);
+                }
+                list.push({
+                    id: String(item.id || `q-${i + 1}`),
+                    question: questionText,
+                    header,
+                    options: options && options.length ? options : undefined,
+                    multiSelect,
+                });
+            }
+        }
+        if (list.length)
+            return list;
+    }
+    // Case 2: single question object
+    const singleText = String(raw.question ?? raw.prompt ?? raw.query ?? raw.message ?? "").trim();
+    if (singleText) {
+        let options;
+        if (Array.isArray(raw.options)) {
+            options = raw.options
+                .map((opt) => {
+                if (typeof opt === "string" && opt.trim()) {
+                    return { label: opt.trim() };
+                }
+                if (opt && typeof opt === "object") {
+                    const o = opt;
+                    const label = String(o.label ?? o.text ?? o.title ?? "").trim();
+                    const description = typeof o.description === "string" ? o.description.trim() : undefined;
+                    if (label)
+                        return { label, description };
+                }
+                return null;
+            })
+                .filter((o) => o !== null);
+        }
+        return [
+            {
+                id: "q-1",
+                question: singleText,
+                header: typeof raw.header === "string" ? raw.header.trim() : undefined,
+                options: options && options.length ? options : undefined,
+                multiSelect: Boolean(raw.multiSelect),
+            },
+        ];
+    }
+    return [];
+}
+const CLARIFYING_PROSE_CUES = [
+    /\bclarifying questions?\b/i,
+    /\ba few questions before\b/i,
+    /\bquestions before I (?:proceed|start|continue|make|implement)\b/i,
+    /\bbefore (?:we|I) (?:proceed|start|continue)\b/i,
+    /\bcould you (?:please )?clarify\b/i,
+    /\bplease clarify\b/i,
+    /\bwhich (?:option|approach|alternative) would you prefer\b/i,
+    /\bdo you prefer\b/i,
+    /\bwhich do you prefer\b/i,
+    /\bto help me proceed\b/i,
+];
+/**
+ * Detects if an assistant response contains clarifying questions in prose/markdown.
+ * Returns structured questions with possible options, or null if not a clarifying message.
+ */
+export function detectClarifyingQuestions(content) {
+    if (!content || !content.trim())
+        return null;
+    const trimmed = content.trim();
+    const hasCue = CLARIFYING_PROSE_CUES.some((cue) => cue.test(trimmed));
+    const hasQuestionMark = trimmed.includes("?");
+    if (!hasCue && !hasQuestionMark)
+        return null;
+    // Split into lines to extract numbered or bulleted questions
+    const lines = trimmed.split("\n");
+    const questions = [];
+    let currentQuestion = null;
+    let inQuestionsSection = !hasCue; // if no specific cue word but looks like questions
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        // Check if line indicates start of questions section
+        if (CLARIFYING_PROSE_CUES.some((cue) => cue.test(line))) {
+            inQuestionsSection = true;
+            continue;
+        }
+        // Match numbered list: "1. Question text?" or "1) Question text?"
+        const numberedMatch = line.match(/^(\d+)[\.\)]\s+(.+)$/);
+        // Match bullet list: "- Question text?" or "* Question text?"
+        const bulletMatch = line.match(/^[-*•]\s+(.+)$/);
+        if (numberedMatch) {
+            const text = numberedMatch[2].trim();
+            if (text.includes("?") || inQuestionsSection) {
+                if (currentQuestion)
+                    questions.push(currentQuestion);
+                currentQuestion = {
+                    id: `q-${questions.length + 1}`,
+                    question: text.replace(/^\*\*|\*\*$/g, ""),
+                    options: [],
+                };
+                continue;
+            }
+        }
+        else if (bulletMatch) {
+            const text = bulletMatch[1].trim();
+            // If we are currently inside a question, check if this bullet is an option (e.g. "- Option A")
+            if (currentQuestion && !text.endsWith("?")) {
+                const optLabel = text.replace(/^\[[ x]\]\s*/i, "").replace(/^\*\*|\*\*$/g, "").trim();
+                if (optLabel && optLabel.length < 80) {
+                    if (!currentQuestion.options)
+                        currentQuestion.options = [];
+                    currentQuestion.options.push({ label: optLabel });
+                    continue;
+                }
+            }
+            if (text.includes("?") || inQuestionsSection) {
+                if (currentQuestion)
+                    questions.push(currentQuestion);
+                currentQuestion = {
+                    id: `q-${questions.length + 1}`,
+                    question: text.replace(/^\*\*|\*\*$/g, ""),
+                    options: [],
+                };
+                continue;
+            }
+        }
+        else if (line.endsWith("?") && inQuestionsSection && line.length < 200) {
+            if (currentQuestion)
+                questions.push(currentQuestion);
+            currentQuestion = {
+                id: `q-${questions.length + 1}`,
+                question: line.replace(/^\*\*|\*\*$/g, ""),
+                options: [],
+            };
+        }
+    }
+    if (currentQuestion) {
+        questions.push(currentQuestion);
+    }
+    // Clean up options
+    const cleanList = questions
+        .filter((q) => q.question.trim().length > 0)
+        .map((q) => ({
+        ...q,
+        options: q.options && q.options.length ? q.options : undefined,
+    }));
+    if (cleanList.length > 0 && hasCue) {
+        return cleanList;
+    }
+    // If cue was present but no list extracted, and trimmed ends with ?, use entire closing sentence
+    if (hasCue && cleanList.length === 0 && hasQuestionMark) {
+        const sentences = trimmed.split(/(?<=[.?!])\s+/);
+        const qSentences = sentences.filter((s) => s.trim().endsWith("?"));
+        if (qSentences.length > 0 && qSentences.length <= 3) {
+            return qSentences.map((q, idx) => ({
+                id: `q-${idx + 1}`,
+                question: q.trim(),
+            }));
+        }
+    }
+    return cleanList.length > 0 ? cleanList : null;
+}

package/dist/shared/claudeModels.d.ts

@@ -0,0 +1,10 @@
+import type { ModelInfo } from "./events.js";
+/**
+ * Claude Code `--model` aliases. These always track the current generation —
+ * do not hardcode versioned ids here. The room page merges this list with
+ * Anthropic's live `/v1/models` catalog (and the local worker when available).
+ */
+export declare const CLAUDE_MODELS: ModelInfo[];
+/** Leave `--model` unset so Claude Code picks its current default. */
+export declare const DEFAULT_CLAUDE_MODEL = "auto";
+export declare function isClaudeModelId(id: string): boolean;

package/dist/shared/claudeModels.js

@@ -0,0 +1,52 @@
+/**
+ * Claude Code `--model` aliases. These always track the current generation —
+ * do not hardcode versioned ids here. The room page merges this list with
+ * Anthropic's live `/v1/models` catalog (and the local worker when available).
+ */
+export const CLAUDE_MODELS = [
+    {
+        id: "auto",
+        displayName: "Auto",
+        description: "Claude Code default — omit --model and use the CLI's latest recommended model",
+    },
+    {
+        id: "sonnet",
+        displayName: "Sonnet",
+        description: "Latest Sonnet alias — daily driver, tracks the current generation",
+    },
+    {
+        id: "opus",
+        displayName: "Opus",
+        description: "Latest Opus alias — strongest model for autonomous coding",
+    },
+    {
+        id: "haiku",
+        displayName: "Haiku",
+        description: "Latest Haiku alias — fastest / cheapest for small edits",
+    },
+    {
+        id: "fable",
+        displayName: "Fable",
+        description: "Latest Fable alias — long autonomous sessions",
+    },
+];
+/** Leave `--model` unset so Claude Code picks its current default. */
+export const DEFAULT_CLAUDE_MODEL = "auto";
+const CLAUDE_ALIASES = new Set([
+    "auto",
+    "sonnet",
+    "opus",
+    "haiku",
+    "fable",
+    "sonnet[1m]",
+    "opus[1m]",
+    "opusplan",
+    "best",
+]);
+export function isClaudeModelId(id) {
+    if (CLAUDE_ALIASES.has(id))
+        return true;
+    if (CLAUDE_MODELS.some((m) => m.id === id))
+        return true;
+    return id.startsWith("claude-");
+}

package/dist/shared/cloudBackends.d.ts

@@ -0,0 +1,21 @@
+import type { AgentBackendKind } from "./backends/types.js";
+import type { ModelInfo } from "./events.js";
+/** Agents that can run headless in the cloud (issues, swarms, automations). */
+export declare const CLOUD_BACKENDS: readonly AgentBackendKind[];
+export interface CloudBackendReadiness {
+    ready: boolean;
+    /** Why it can't run yet, phrased as what to do about it. */
+    reason?: string;
+    /** How it authenticates when ready. */
+    auth?: "api_key" | "subscription" | "free";
+}
+export interface CloudBackendOption extends CloudBackendReadiness {
+    backend: AgentBackendKind;
+    label: string;
+    models: ModelInfo[];
+    defaultModel: string;
+}
+export declare function cloudBackendName(backend: AgentBackendKind | null | undefined): string;
+/** Provider id for ModelProviderLogo. */
+export declare function cloudBackendLogo(backend: AgentBackendKind | null | undefined): "cursor" | "claude" | "codex" | "opencode";
+export declare function parseCloudBackend(value: unknown): AgentBackendKind | null;

package/dist/shared/cloudBackends.js

@@ -0,0 +1,29 @@
+/** Agents that can run headless in the cloud (issues, swarms, automations). */
+export const CLOUD_BACKENDS = ["cursor", "claude-code", "codex", "opencode"];
+export function cloudBackendName(backend) {
+    if (backend === "claude-code")
+        return "Claude Code";
+    if (backend === "codex")
+        return "Codex";
+    if (backend === "opencode")
+        return "OpenCode";
+    return "Cursor";
+}
+/** Provider id for ModelProviderLogo. */
+export function cloudBackendLogo(backend) {
+    if (backend === "claude-code")
+        return "claude";
+    if (backend === "codex")
+        return "codex";
+    if (backend === "opencode")
+        return "opencode";
+    return "cursor";
+}
+export function parseCloudBackend(value) {
+    return value === "cursor" ||
+        value === "claude-code" ||
+        value === "codex" ||
+        value === "opencode"
+        ? value
+        : null;
+}

package/dist/shared/codexModels.d.ts

@@ -0,0 +1,10 @@
+import type { ModelInfo } from "./events.js";
+/**
+ * Codex CLI fallback `--model` choices.
+ * Do not hardcode versioned GPT ids — the room page fetches the live catalog
+ * from `codex debug models` and/or OpenAI `/v1/models`.
+ */
+export declare const CODEX_MODELS: ModelInfo[];
+/** Leave `--model` unset so Codex picks its current default. */
+export declare const DEFAULT_CODEX_MODEL = "auto";
+export declare function isCodexModelId(id: string): boolean;

package/dist/shared/codexModels.js

@@ -0,0 +1,28 @@
+/**
+ * Codex CLI fallback `--model` choices.
+ * Do not hardcode versioned GPT ids — the room page fetches the live catalog
+ * from `codex debug models` and/or OpenAI `/v1/models`.
+ */
+export const CODEX_MODELS = [
+    {
+        id: "auto",
+        displayName: "Auto",
+        description: "Codex CLI default — omit --model and use the latest recommended model",
+    },
+];
+/** Leave `--model` unset so Codex picks its current default. */
+export const DEFAULT_CODEX_MODEL = "auto";
+export function isCodexModelId(id) {
+    if (id === "auto")
+        return true;
+    if (CODEX_MODELS.some((m) => m.id === id))
+        return true;
+    return (id.startsWith("gpt-") ||
+        id.includes("codex") ||
+        id === "o1" ||
+        id === "o3" ||
+        id === "o4-mini" ||
+        id.startsWith("o1-") ||
+        id.startsWith("o3-") ||
+        id.startsWith("o4-"));
+}

package/dist/shared/contextWindows.d.ts

@@ -0,0 +1,2 @@
+import type { AgentBackendKind } from "./backends/types.js";
+export declare function contextWindowForModel(_backend: AgentBackendKind | string | null | undefined, modelId: string | null | undefined): number | null;

package/dist/shared/contextWindows.js

@@ -0,0 +1,30 @@
+const K = 1000;
+/**
+ * Context windows for models where the value is stable enough to show a
+ * percentage. Unknown models intentionally return null: the composer then
+ * shows the raw context token count instead of inventing a denominator.
+ */
+const RULES = [
+    { match: /gemini-.*pro/i, tokens: 1_000 * K },
+    { match: /gemini/i, tokens: 1_000 * K },
+    { match: /gpt-4\.1/i, tokens: 1_000 * K },
+    { match: /gpt-4o/i, tokens: 128 * K },
+    { match: /gpt-5/i, tokens: 400 * K },
+    { match: /o[134](-|$)/i, tokens: 200 * K },
+    { match: /claude/i, tokens: 200 * K },
+    { match: /deepseek/i, tokens: 128 * K },
+    { match: /qwen/i, tokens: 128 * K },
+    { match: /kimi|moonshot/i, tokens: 256 * K },
+    { match: /minimax/i, tokens: 200 * K },
+    { match: /grok/i, tokens: 256 * K },
+];
+export function contextWindowForModel(_backend, modelId) {
+    const id = (modelId || "").trim();
+    if (!id || /(^|[/:])auto$|^auto$/i.test(id))
+        return null;
+    for (const rule of RULES) {
+        if (rule.match.test(id))
+            return rule.tokens;
+    }
+    return null;
+}

package/dist/shared/cursorMcpConfig.d.ts

@@ -0,0 +1,14 @@
+/** HTTP MCP server Steer attaches to a local Cursor CLI run. */
+export interface SteerMcpHttpServer {
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Merge Steer MCP servers into a Cursor `.cursor/mcp.json` document.
+ * Header values are stored as `${env:...}` references so the file on disk
+ * does not contain bearer tokens.
+ */
+export declare function cursorMcpEnvConfig(existingRaw: string | null | undefined, servers: Record<string, SteerMcpHttpServer>): {
+    json: string;
+    env: Record<string, string>;
+};

package/dist/shared/cursorMcpConfig.js

@@ -0,0 +1,43 @@
+/**
+ * Merge Steer MCP servers into a Cursor `.cursor/mcp.json` document.
+ * Header values are stored as `${env:...}` references so the file on disk
+ * does not contain bearer tokens.
+ */
+export function cursorMcpEnvConfig(existingRaw, servers) {
+    let base = {};
+    if (existingRaw?.trim()) {
+        try {
+            const parsed = JSON.parse(existingRaw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                base = parsed;
+            }
+        }
+        catch {
+            base = {};
+        }
+    }
+    const current = base.mcpServers &&
+        typeof base.mcpServers === "object" &&
+        !Array.isArray(base.mcpServers)
+        ? { ...base.mcpServers }
+        : {};
+    const env = {};
+    let n = 0;
+    for (const [name, server] of Object.entries(servers)) {
+        const headers = {};
+        for (const [key, value] of Object.entries(server.headers || {})) {
+            const envName = `STEER_MCP_${n}_${key.replace(/[^A-Za-z0-9]/g, "_").toUpperCase()}`.slice(0, 64);
+            env[envName] = value;
+            headers[key] = `\${env:${envName}}`;
+            n += 1;
+        }
+        current[name] = {
+            url: server.url,
+            ...(Object.keys(headers).length ? { headers } : {}),
+        };
+    }
+    return {
+        json: `${JSON.stringify({ ...base, mcpServers: current }, null, 2)}\n`,
+        env,
+    };
+}

package/dist/shared/cursorProjectMcp.d.ts

@@ -0,0 +1,10 @@
+import { type SteerMcpHttpServer } from "./cursorMcpConfig.js";
+/**
+ * Write Steer servers into `<repo>/.cursor/mcp.json` for one Cursor CLI run.
+ * Cursor has no per-invocation MCP flag; it reads this file. The previous
+ * file is restored when `restore` runs. Tokens stay in `env`, not on disk.
+ */
+export declare function mountCursorProjectMcp(repoPath: string, servers: Record<string, SteerMcpHttpServer> | undefined): Promise<{
+    env: Record<string, string>;
+    restore: () => Promise<void>;
+}>;

package/dist/shared/cursorProjectMcp.js

@@ -0,0 +1,42 @@
+import { mkdir, readFile, unlink, writeFile } from "fs/promises";
+import { join } from "path";
+import { cursorMcpEnvConfig, } from "./cursorMcpConfig.js";
+/**
+ * Write Steer servers into `<repo>/.cursor/mcp.json` for one Cursor CLI run.
+ * Cursor has no per-invocation MCP flag; it reads this file. The previous
+ * file is restored when `restore` runs. Tokens stay in `env`, not on disk.
+ */
+export async function mountCursorProjectMcp(repoPath, servers) {
+    if (!servers || Object.keys(servers).length === 0) {
+        return { env: {}, restore: async () => { } };
+    }
+    const dir = join(repoPath, ".cursor");
+    const file = join(dir, "mcp.json");
+    let previous = null;
+    let existed = false;
+    try {
+        previous = await readFile(file, "utf8");
+        existed = true;
+    }
+    catch {
+        previous = null;
+    }
+    const { json, env } = cursorMcpEnvConfig(previous, servers);
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, json);
+    return {
+        env,
+        restore: async () => {
+            if (existed && previous != null) {
+                await writeFile(file, previous);
+                return;
+            }
+            try {
+                await unlink(file);
+            }
+            catch {
+                // already gone
+            }
+        },
+    };
+}

package/dist/shared/docs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Docs: lasting, shareable Markdown documents an agent writes for a room
+ * (reports, lead lists, comparisons, plans). Unlike uploaded files they render
+ * in Eigen, keep a version history, and are updated in place by agents.
+ */
+/** Who can open a doc: members of its room (default) or its whole workspace. */
+export type DocVisibility = "room" | "workspace";
+/** Snapshot carried on the chat message that shows the doc card. */
+export interface DocCardInfo {
+    id: string;
+    title: string;
+    summary: string;
+    /** Opening Markdown for the card preview. */
+    excerpt: string;
+    version: number;
+    /** "created" for the first card, "updated" when an agent revised it. */
+    change: "created" | "updated";
+    updatedAt: number;
+}
+export interface DocSummaryInfo {
+    id: string;
+    roomId: string;
+    title: string;
+    summary: string;
+    version: number;
+    visibility: DocVisibility;
+    authorLabel: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface DocInfo extends DocSummaryInfo {
+    content: string;
+    roomName: string | null;
+    /** Set when this is an automation's tracking doc. */
+    automationId?: string | null;
+    automationName?: string | null;
+    /** Viewer may change who can open it (room owner/editor). */
+    canManage: boolean;
+}
+export type DocUpdateMode = "replace" | "append" | "replace_section";
+export declare const DOC_TITLE_MAX = 200;
+export declare const DOC_SUMMARY_MAX = 600;
+export declare const DOC_CONTENT_MAX = 200000;
+/** Opening part of the doc for the chat card, cut at a line break. */
+export declare function docExcerpt(content: string): string;
+/**
+ * Replace the section under the heading `section` (any level) up to the next
+ * heading of the same or higher level. `replacement` may include its own
+ * heading; if it doesn't, the original heading is kept.
+ */
+export declare function replaceDocSection(content: string, section: string, replacement: string): string;
+/** New doc content after an agent's update. */
+export declare function applyDocUpdate(current: string, update: {
+    mode: DocUpdateMode;
+    content: string;
+    section?: string;
+}): string;
+/** `messages.docs_json` → doc cards on that message. */
+export declare function parseDocCardsJson(raw: unknown): DocCardInfo[] | undefined;

package/dist/shared/docs.js

@@ -0,0 +1,87 @@
+/**
+ * Docs: lasting, shareable Markdown documents an agent writes for a room
+ * (reports, lead lists, comparisons, plans). Unlike uploaded files they render
+ * in Eigen, keep a version history, and are updated in place by agents.
+ */
+export const DOC_TITLE_MAX = 200;
+export const DOC_SUMMARY_MAX = 600;
+export const DOC_CONTENT_MAX = 200_000;
+const EXCERPT_CHARS = 1_400;
+/** Opening part of the doc for the chat card, cut at a line break. */
+export function docExcerpt(content) {
+    const text = content.trim();
+    if (text.length <= EXCERPT_CHARS)
+        return text;
+    const cut = text.lastIndexOf("\n", EXCERPT_CHARS);
+    return text.slice(0, cut > EXCERPT_CHARS / 2 ? cut : EXCERPT_CHARS).trimEnd();
+}
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+function normalizeHeading(text) {
+    return text.replace(/^#+\s*/, "").trim().toLowerCase();
+}
+/**
+ * Replace the section under the heading `section` (any level) up to the next
+ * heading of the same or higher level. `replacement` may include its own
+ * heading; if it doesn't, the original heading is kept.
+ */
+export function replaceDocSection(content, section, replacement) {
+    const lines = content.split("\n");
+    const wanted = normalizeHeading(section);
+    let inFence = false;
+    let start = -1;
+    let level = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (/^\s*(```|~~~)/.test(lines[i]))
+            inFence = !inFence;
+        if (inFence)
+            continue;
+        const match = lines[i].match(HEADING_RE);
+        if (match && normalizeHeading(match[2]) === wanted) {
+            start = i;
+            level = match[1].length;
+            break;
+        }
+    }
+    if (start < 0)
+        throw new Error(`No section titled "${section}" in this doc`);
+    let end = lines.length;
+    inFence = false;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (/^\s*(```|~~~)/.test(lines[i]))
+            inFence = !inFence;
+        if (inFence)
+            continue;
+        const match = lines[i].match(HEADING_RE);
+        if (match && match[1].length <= level) {
+            end = i;
+            break;
+        }
+    }
+    const body = replacement.trim();
+    const hasHeading = HEADING_RE.test(body.split("\n")[0] ?? "");
+    const next = hasHeading ? body : `${lines[start]}\n\n${body}`;
+    return [...lines.slice(0, start), next, "", ...lines.slice(end)].join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** New doc content after an agent's update. */
+export function applyDocUpdate(current, update) {
+    if (update.mode === "append")
+        return `${current.trimEnd()}\n\n${update.content.trim()}`.trim();
+    if (update.mode === "replace_section") {
+        if (!update.section?.trim())
+            throw new Error("section is required for replace_section");
+        return replaceDocSection(current, update.section, update.content);
+    }
+    return update.content.trim();
+}
+/** `messages.docs_json` → doc cards on that message. */
+export function parseDocCardsJson(raw) {
+    if (typeof raw !== "string" || !raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) && parsed.length ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}