@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/tui/model/task-lifecycle.js

@@ -0,0 +1,124 @@
+import { nextDisplayMessageKey } from "./display-history.js";
+import { mapTranscriptTools } from "./subagent-view.js";
+/**
+ * Occurrence for a restored terminal marker whose task_started marker is not
+ * in the retained log (the task was launched before a conversation_clear).
+ * It must never land on a later launch that happens to reuse the task id.
+ */
+export const UNMATCHED_LAUNCH = -1;
+function isLaunchRowFor(tool, taskId) {
+    return tool.metadata?.background === true && tool.metadata?.taskId === taskId;
+}
+function hasLanded(tool) {
+    return tool.metadata?.taskLifecycle !== undefined;
+}
+/** Launch rows for a task id in transcript order, one entry per tool call. */
+function launchRowsFor(messages, taskId) {
+    const seen = new Set();
+    const rows = [];
+    for (const message of messages) {
+        const tools = message.toolCalls
+            ?? message.parts?.flatMap((part) => (part.type === "tools" ? part.toolCalls : []))
+            ?? [];
+        for (const tool of tools) {
+            if (!isLaunchRowFor(tool, taskId) || seen.has(tool.id))
+                continue;
+            seen.add(tool.id);
+            rows.push(tool);
+        }
+    }
+    return rows;
+}
+/** The launch row a terminal state should land on, or undefined. */
+function targetLaunchRow(messages, taskId, occurrence) {
+    const rows = launchRowsFor(messages, taskId);
+    if (occurrence !== undefined)
+        return occurrence >= 0 ? rows[occurrence] : undefined;
+    for (let index = rows.length - 1; index >= 0; index -= 1) {
+        if (!hasLanded(rows[index]))
+            return rows[index];
+    }
+    return undefined;
+}
+function displayStatus(task) {
+    return task.status === "killed" ? "cancelled" : task.status === "failed" ? "failed" : "completed";
+}
+/** Returns a copy of `tool` carrying the task's terminal state. */
+export function applyTaskLifecycleToTool(tool, task, output) {
+    return {
+        ...tool,
+        status: displayStatus(task),
+        isError: task.status === "failed",
+        result: output?.trim() ? output : tool.result,
+        startedAt: task.startedAt ?? tool.startedAt,
+        metadata: {
+            ...tool.metadata,
+            kind: "shell",
+            background: true,
+            taskId: task.id,
+            taskLifecycle: task.status,
+            exitCode: task.exitCode ?? null,
+            endedAt: task.endedAt,
+            outputLines: task.outputLines,
+        },
+    };
+}
+/**
+ * Lands the terminal state on a launch row that is still in the streaming
+ * accumulator. Mutates in place because the accumulator's parts share the
+ * same tool objects. A row whose tool_end has not arrived yet is skipped:
+ * the reducer would overwrite the merge when the result lands.
+ */
+export function mergeTaskLifecycleIntoLiveTools(tools, task, output) {
+    const tool = [...tools].reverse().find((candidate) => isLaunchRowFor(candidate, task.id) && !hasLanded(candidate));
+    if (!tool || tool.status === "running")
+        return false;
+    Object.assign(tool, applyTaskLifecycleToTool(tool, task, output));
+    return true;
+}
+/**
+ * Lands the terminal state on exactly one committed launch row: the given
+ * launch occurrence, or (for live completions) the newest one still open.
+ */
+export function applyTaskLifecycleToMessages(messages, task, output, occurrence) {
+    const target = targetLaunchRow(messages, task.id, occurrence);
+    if (!target)
+        return { messages, merged: false };
+    const next = mapTranscriptTools(messages, (tool) => tool.id === target.id ? applyTaskLifecycleToTool(tool, task, output) : tool);
+    return { messages: next, merged: next !== messages };
+}
+/** Detached terminal row for a task whose launch row is not in the transcript. */
+export function taskLifecycleDisplayMessage(task, output) {
+    const tool = applyTaskLifecycleToTool({
+        id: `task-lifecycle:${task.id}:${task.endedAt ?? Date.now()}`,
+        name: "bash",
+        args: {
+            command: task.command,
+            ...(task.description ? { description: task.description } : {}),
+        },
+        startedAt: task.startedAt,
+    }, task, output);
+    return {
+        key: nextDisplayMessageKey("task"),
+        role: "assistant",
+        content: "",
+        toolCalls: [tool],
+        parts: [{ type: "tools", toolCalls: [tool] }],
+    };
+}
+/**
+ * Lands every terminal state on its launch row; tasks without one get a
+ * detached row appended in the given order.
+ */
+export function landTaskLifecycles(messages, terminals) {
+    let next = messages;
+    const detached = [];
+    for (const { task, output, occurrence } of terminals) {
+        const landed = applyTaskLifecycleToMessages(next, task, output, occurrence);
+        if (landed.merged)
+            next = landed.messages;
+        else
+            detached.push(taskLifecycleDisplayMessage(task, output));
+    }
+    return detached.length > 0 ? [...next, ...detached] : next;
+}

package/dist/tui/model/terminal-env.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether we're running inside a terminal multiplexer (tmux or GNU screen).
+ *
+ * Ink commits settled transcript rows to native scrollback via <Static> and
+ * repaints only the short live region in place. When that live region SHRINKS
+ * (a turn settles, a steer commits, a run is interrupted), Ink erases the prior
+ * frame with a cursor-up + clear. Under a multiplexer that erase cannot reach
+ * rows that have already scrolled out of the pane, leaving a blank gap — so
+ * those transitions fall back to a full screen+scrollback reprint to stay clean.
+ *
+ * On a normal terminal that reprint is unnecessary (Ink's in-place erase works)
+ * and visible as a one-frame full-screen flash, so we skip it. This predicate is
+ * the gate. Pure + injectable for tests.
+ */
+export declare function isMultiplexedTerminal(env?: NodeJS.ProcessEnv): boolean;

package/dist/tui/model/terminal-env.js

@@ -0,0 +1,22 @@
+/**
+ * Whether we're running inside a terminal multiplexer (tmux or GNU screen).
+ *
+ * Ink commits settled transcript rows to native scrollback via <Static> and
+ * repaints only the short live region in place. When that live region SHRINKS
+ * (a turn settles, a steer commits, a run is interrupted), Ink erases the prior
+ * frame with a cursor-up + clear. Under a multiplexer that erase cannot reach
+ * rows that have already scrolled out of the pane, leaving a blank gap — so
+ * those transitions fall back to a full screen+scrollback reprint to stay clean.
+ *
+ * On a normal terminal that reprint is unnecessary (Ink's in-place erase works)
+ * and visible as a one-frame full-screen flash, so we skip it. This predicate is
+ * the gate. Pure + injectable for tests.
+ */
+export function isMultiplexedTerminal(env = process.env) {
+    if (env.TMUX)
+        return true; // inside tmux
+    if (env.STY)
+        return true; // inside GNU screen
+    const term = env.TERM ?? "";
+    return /^(screen|tmux)(-|\.|$)/.test(term); // e.g. screen-256color, tmux-256color
+}

package/dist/tui/model/terminal-mouse.d.ts

@@ -0,0 +1,28 @@
+export declare const ALTERNATE_SCROLL_ENABLE = "\u001B[?1007h";
+export declare const ALTERNATE_SCROLL_DISABLE = "\u001B[?1007l";
+export declare const MOUSE_REPORTING_ENABLE = "\u001B[?1000h\u001B[?1006h";
+export declare const MOUSE_REPORTING_DISABLE = "\u001B[?1003l\u001B[?1002l\u001B[?1000l\u001B[?1005l\u001B[?1006l\u001B[?1015l";
+interface TerminalMouseEnv {
+    BUBBLE_ENABLE_MOUSE?: string;
+    BUBBLE_TUI_MOUSE?: string;
+}
+/**
+ * Terminal mouse reporting captures drag events before the host terminal can
+ * create a native text selection. Keep it opt-in until Bubble owns a full
+ * renderer-level selection/copy pipeline.
+ */
+export declare function isTerminalMouseReportingEnabled(env?: TerminalMouseEnv): boolean;
+export type MouseWheelDirection = "up" | "down";
+export interface TerminalMouseInput {
+    strippedInput: string;
+    wheelDirections: MouseWheelDirection[];
+    hasMouse: boolean;
+}
+export declare function sanitizeTerminalMouseInput(input: string): TerminalMouseInput;
+export declare function transcriptScrollLinesFromMouseInput(mouseInput: TerminalMouseInput, options: {
+    overlayActive: boolean;
+}): number[];
+export declare function stripTerminalMouseSequences(input: string): string;
+export declare function hasTerminalMouseSequence(input: string): boolean;
+export declare function parseTerminalMouseWheel(input: string): MouseWheelDirection[];
+export {};

package/dist/tui/model/terminal-mouse.js

@@ -0,0 +1,82 @@
+// DECSET 1007 makes terminals translate wheel gestures into Up/Down arrows
+// while the alternate screen is active. Keep it disabled in Ink; otherwise
+// terminals without kitty event metadata make wheel and keyboard arrows
+// indistinguishable.
+export const ALTERNATE_SCROLL_ENABLE = "\x1b[?1007h";
+export const ALTERNATE_SCROLL_DISABLE = "\x1b[?1007l";
+// Use normal mouse tracking + SGR encoding so wheel events reach the app as
+// mouse reports instead of being translated into keyboard arrows.
+export const MOUSE_REPORTING_ENABLE = "\x1b[?1000h\x1b[?1006h";
+// Disable every common tracking mode defensively in case a crash or another
+// renderer left the terminal in a reporting state.
+export const MOUSE_REPORTING_DISABLE = "\x1b[?1003l\x1b[?1002l\x1b[?1000l\x1b[?1005l\x1b[?1006l\x1b[?1015l";
+function envValueEnabled(value) {
+    if (!value)
+        return false;
+    return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+/**
+ * Terminal mouse reporting captures drag events before the host terminal can
+ * create a native text selection. Keep it opt-in until Bubble owns a full
+ * renderer-level selection/copy pipeline.
+ */
+export function isTerminalMouseReportingEnabled(env = process.env) {
+    return envValueEnabled(env.BUBBLE_ENABLE_MOUSE) || envValueEnabled(env.BUBBLE_TUI_MOUSE);
+}
+const ESCAPED_MOUSE_SEQUENCE_RE = /\x1b(?:\[<(\d+);\d+;\d+([mM])|\[M([\s\S])[\s\S]{2})/g;
+const RAW_SGR_MOUSE_SEQUENCE_RE = /\[?<(\d+);\d+;\d+([mM])/g;
+const RAW_SGR_MOUSE_INPUT_RE = /^(?:\[?<\d+;\d+;\d+[mM])+$/;
+function wheelDirectionFromButtonCode(code) {
+    if ((code & 64) !== 64)
+        return undefined;
+    const wheelButton = code & 0b11;
+    if (wheelButton === 0)
+        return "up";
+    if (wheelButton === 1)
+        return "down";
+    return undefined;
+}
+function collectWheelDirection(directions, code, final) {
+    if (final !== undefined && final !== "M")
+        return;
+    const direction = wheelDirectionFromButtonCode(code);
+    if (direction)
+        directions.push(direction);
+}
+export function sanitizeTerminalMouseInput(input) {
+    const wheelDirections = [];
+    let hasMouse = false;
+    ESCAPED_MOUSE_SEQUENCE_RE.lastIndex = 0;
+    let strippedInput = input.replace(ESCAPED_MOUSE_SEQUENCE_RE, (_sequence, sgrCode, sgrFinal, x10Button) => {
+        hasMouse = true;
+        const code = sgrCode !== undefined
+            ? Number(sgrCode)
+            : (x10Button?.charCodeAt(0) ?? 32) - 32;
+        collectWheelDirection(wheelDirections, code, sgrFinal);
+        return "";
+    });
+    if (RAW_SGR_MOUSE_INPUT_RE.test(strippedInput)) {
+        hasMouse = true;
+        RAW_SGR_MOUSE_SEQUENCE_RE.lastIndex = 0;
+        strippedInput = strippedInput.replace(RAW_SGR_MOUSE_SEQUENCE_RE, (_sequence, sgrCode, sgrFinal) => {
+            collectWheelDirection(wheelDirections, Number(sgrCode), sgrFinal);
+            return "";
+        });
+    }
+    return { strippedInput, wheelDirections, hasMouse };
+}
+export function transcriptScrollLinesFromMouseInput(mouseInput, options) {
+    if (options.overlayActive)
+        return [];
+    return mouseInput.wheelDirections.map((direction) => direction === "up" ? -1 : 1);
+}
+export function stripTerminalMouseSequences(input) {
+    return sanitizeTerminalMouseInput(input).strippedInput;
+}
+export function hasTerminalMouseSequence(input) {
+    ESCAPED_MOUSE_SEQUENCE_RE.lastIndex = 0;
+    return ESCAPED_MOUSE_SEQUENCE_RE.test(input) || RAW_SGR_MOUSE_INPUT_RE.test(input);
+}
+export function parseTerminalMouseWheel(input) {
+    return sanitizeTerminalMouseInput(input).wheelDirections;
+}

package/dist/tui/model/theme-style.d.ts

@@ -0,0 +1,10 @@
+/** Apply a configured foreground without letting a malformed override crash rendering. */
+export declare function themeForeground(color: string | undefined, text: string): string;
+/** Apply a configured background without letting a malformed override crash rendering. */
+export declare function themeBackground(color: string | undefined, text: string): string;
+export declare function themeDim(color: string | undefined, text: string): string;
+/** ANSI pair used by the alternate-screen renderer to paint every cell. */
+export declare function themeBackgroundCodes(color: string | undefined): {
+    open: string;
+    close: string;
+} | undefined;

package/dist/tui/model/theme-style.js

@@ -0,0 +1,79 @@
+import chalk from "chalk";
+const NAMED_COLORS = new Set([
+    "black",
+    "red",
+    "green",
+    "yellow",
+    "blue",
+    "magenta",
+    "cyan",
+    "white",
+    "gray",
+    "grey",
+]);
+function isHexColor(value) {
+    return /^#[0-9a-f]{6}$/i.test(value) || /^#[0-9a-f]{3}$/i.test(value);
+}
+/** Apply a configured foreground without letting a malformed override crash rendering. */
+export function themeForeground(color, text) {
+    if (!color)
+        return text;
+    if (isHexColor(color))
+        return chalk.hex(color)(text);
+    const normalized = color.toLowerCase();
+    if (NAMED_COLORS.has(normalized))
+        return chalk[normalized](text);
+    return text;
+}
+/** Apply a configured background without letting a malformed override crash rendering. */
+export function themeBackground(color, text) {
+    if (!color)
+        return text;
+    if (isHexColor(color))
+        return chalk.bgHex(color)(text);
+    const normalized = color.toLowerCase();
+    if (!NAMED_COLORS.has(normalized))
+        return text;
+    switch (normalized) {
+        case "black": return chalk.bgBlack(text);
+        case "red": return chalk.bgRed(text);
+        case "green": return chalk.bgGreen(text);
+        case "yellow": return chalk.bgYellow(text);
+        case "blue": return chalk.bgBlue(text);
+        case "magenta": return chalk.bgMagenta(text);
+        case "cyan": return chalk.bgCyan(text);
+        case "white": return chalk.bgWhite(text);
+        case "gray":
+        case "grey": return chalk.bgGray(text);
+    }
+}
+export function themeDim(color, text) {
+    return chalk.dim(themeForeground(color, text));
+}
+/** ANSI pair used by the alternate-screen renderer to paint every cell. */
+export function themeBackgroundCodes(color) {
+    if (!color)
+        return undefined;
+    if (isHexColor(color)) {
+        const expanded = color.length === 4
+            ? color.slice(1).split("").map((part) => part + part).join("")
+            : color.slice(1);
+        const channels = expanded.match(/../g)?.map((part) => Number.parseInt(part, 16));
+        if (!channels || channels.length !== 3)
+            return undefined;
+        return { open: `\x1b[48;2;${channels.join(";")}m`, close: "\x1b[49m" };
+    }
+    const normalized = color.toLowerCase();
+    if (!NAMED_COLORS.has(normalized))
+        return undefined;
+    const code = normalized === "black" ? 40
+        : normalized === "red" ? 41
+            : normalized === "green" ? 42
+                : normalized === "yellow" ? 43
+                    : normalized === "blue" ? 44
+                        : normalized === "magenta" ? 45
+                            : normalized === "cyan" ? 46
+                                : normalized === "white" ? 47
+                                    : 100;
+    return { open: `\x1b[${code}m`, close: "\x1b[49m" };
+}

package/dist/tui/model/theme.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Renderer-neutral theme tokens shared by the terminal UI surfaces.
+ */
+export type ResolvedTheme = "light" | "dark";
+export type ThemeMode = "auto" | ResolvedTheme;
+export interface Theme {
+    user: string;
+    agent: string;
+    error: string;
+    warning: string;
+    success: string;
+    /**
+     * Painted canvas color. `undefined` means "do not paint" — the terminal's
+     * own background shows through, so the app never fights the user's terminal
+     * palette (e.g. forcing pure black inside a soft-dark terminal). Users can
+     * still force a painted canvas via `theme.overrides.background` in config.
+     */
+    background: string | undefined;
+    accent: string;
+    /** Welcome banner border. */
+    bannerBorder: string;
+    /** Welcome banner logo/title gradient endpoints (top→bottom, left→right). */
+    bannerGradientFrom: string;
+    bannerGradientTo: string;
+    border: string;
+    borderActive: string;
+    backgroundPanel: string;
+    backgroundElement: string;
+    inputBorder: string;
+    inputBorderDisabled: string;
+    inputBg: string;
+    inputBgDisabled: string;
+    inputText: string;
+    inputPlaceholder: string;
+    muted: string;
+    dim: string;
+    thinking: string;
+    thinkingDim: string;
+    toolName: string;
+    toolResult: string;
+    toolError: string;
+    toolPending: string;
+    /** Markdown inline `code` spans. */
+    inlineCode: string;
+    traceAction: string;
+    traceCount: string;
+    traceDetail: string;
+    traceCommand: string;
+    tracePending: string;
+    /** Neutral painted surfaces for pointer-hovered / selected tool traces. */
+    traceHoverBg: string;
+    traceSelectedBg: string;
+    userMessageBorder: string;
+    userMessageBg: string;
+    userMessageText: string;
+    /** Painted band backgrounds for diff lines inside user-message cards. */
+    diffAdd: string;
+    diffRemove: string;
+    /** Foregrounds for +/- diff lines rendered without a painted background. */
+    diffAddFg: string;
+    diffRemoveFg: string;
+}
+export declare const darkTheme: Theme;
+export declare const lightTheme: Theme;
+export declare function canvasBackgroundFor(mode: ThemeMode, resolved: ResolvedTheme, terminalTheme: ResolvedTheme): string | undefined;
+/** Build a palette from one of the shipped themes plus user overrides. */
+export declare function paletteFor(resolved: ResolvedTheme, overrides?: Record<string, string>): Theme;
+/** Resolve the complete live palette used by an interactive TUI instance. */
+export declare function resolveThemePalette(mode: ThemeMode, terminalTheme: ResolvedTheme, overrides?: Record<string, string>): {
+    resolved: ResolvedTheme;
+    palette: Theme;
+};

package/dist/tui/model/theme.js

@@ -0,0 +1,121 @@
+export const darkTheme = {
+    user: "green",
+    agent: "blue",
+    error: "red",
+    warning: "yellow",
+    success: "green",
+    background: undefined,
+    accent: "cyan",
+    bannerBorder: "#38bdf8",
+    bannerGradientFrom: "#67e8f9",
+    bannerGradientTo: "#a78bfa",
+    border: "gray",
+    borderActive: "cyan",
+    backgroundPanel: "#141414",
+    backgroundElement: "#1c1c24",
+    inputBorder: "#8A7FC6",
+    inputBorderDisabled: "#4a4754",
+    inputBg: "#1c1c24",
+    inputBgDisabled: "#161620",
+    inputText: "#f3f3f7",
+    inputPlaceholder: "#6c6a78",
+    muted: "gray",
+    dim: "gray",
+    thinking: "magenta",
+    thinkingDim: "gray",
+    toolName: "cyan",
+    toolResult: "gray",
+    toolError: "red",
+    toolPending: "yellow",
+    inlineCode: "#a78bfa",
+    traceAction: "#E89A6B",
+    traceCount: "#c9c1bd",
+    traceDetail: "gray",
+    traceCommand: "#59BCE8",
+    tracePending: "yellow",
+    traceHoverBg: "#232323",
+    traceSelectedBg: "#2B2B2B",
+    userMessageBorder: "#8A7FC6",
+    userMessageBg: "#2A2A2A",
+    userMessageText: "#f3f3f7",
+    diffAdd: "#1a3d1a",
+    diffRemove: "#3d1a1a",
+    diffAddFg: "green",
+    diffRemoveFg: "red",
+};
+export const lightTheme = {
+    user: "#356FD2",
+    agent: "#171717",
+    error: "#B62633",
+    warning: "#8B4A00",
+    success: "#2F7D4A",
+    background: undefined,
+    accent: "#8B4A00",
+    bannerBorder: "#356FD2",
+    bannerGradientFrom: "#0E7490",
+    bannerGradientTo: "#6D28D9",
+    border: "#B9BDB8",
+    borderActive: "#356FD2",
+    backgroundPanel: "#F6F6F3",
+    backgroundElement: "#ECEDEA",
+    inputBorder: "#356FD2",
+    inputBorderDisabled: "#D7DAD4",
+    inputBg: "#F1F3F0",
+    inputBgDisabled: "#F6F6F3",
+    inputText: "#171717",
+    inputPlaceholder: "#6F7377",
+    muted: "#6F7377",
+    dim: "#8B9094",
+    thinking: "#5F666D",
+    thinkingDim: "#8B9094",
+    toolName: "#495057",
+    toolResult: "#171717",
+    toolError: "#B62633",
+    toolPending: "#8B4A00",
+    inlineCode: "#6D28D9",
+    traceAction: "#8B4A00",
+    traceCount: "#6F7377",
+    traceDetail: "#8B9094",
+    traceCommand: "#257E8A",
+    tracePending: "#8B4A00",
+    traceHoverBg: "#E8E8E5",
+    traceSelectedBg: "#DDDFDB",
+    userMessageBorder: "#356FD2",
+    userMessageBg: "#F1F3F0",
+    userMessageText: "#234B93",
+    diffAdd: "#D7E8D8",
+    diffRemove: "#F7DADC",
+    diffAddFg: "#2F7D4A",
+    diffRemoveFg: "#B62633",
+};
+const paintedCanvas = {
+    dark: "#0A0A0A",
+    light: "#FCFCFA",
+};
+export function canvasBackgroundFor(mode, resolved, terminalTheme) {
+    if (mode === "auto" || resolved === terminalTheme)
+        return undefined;
+    return paintedCanvas[resolved];
+}
+/** Build a palette from one of the shipped themes plus user overrides. */
+export function paletteFor(resolved, overrides) {
+    const base = resolved === "light" ? lightTheme : darkTheme;
+    if (!overrides)
+        return { ...base };
+    const palette = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (typeof value !== "string" || !(key in base))
+            continue;
+        palette[key] = value;
+    }
+    return palette;
+}
+/** Resolve the complete live palette used by an interactive TUI instance. */
+export function resolveThemePalette(mode, terminalTheme, overrides) {
+    const resolved = mode === "auto" ? terminalTheme : mode;
+    const palette = paletteFor(resolved, overrides);
+    if (palette.background === undefined) {
+        palette.background = canvasBackgroundFor(mode, resolved, terminalTheme);
+    }
+    return { resolved, palette };
+}

package/dist/tui/model/trace-groups.d.ts

@@ -0,0 +1,45 @@
+import type { DisplayToolCall } from "./display-history.js";
+export type TraceGroupKind = "list" | "read" | "search" | "execute" | "edit" | "write" | "subagent" | "other";
+export interface TraceGroup {
+    kind: TraceGroupKind;
+    title: string;
+    raw: DisplayToolCall[];
+    count?: number;
+    noun?: string;
+    command?: string;
+    /** Model-provided one-line summary of what the command does (bash `description` arg). */
+    description?: string;
+    /** Original command split into lines, line breaks preserved (execute groups only). */
+    commandLines?: string[];
+    items: string[];
+    previewLines: string[];
+    errorLines: string[];
+    omitted: number;
+    pending: boolean;
+    hasError: boolean;
+    errorCount: number;
+    startedAt?: number;
+    /** Final lifecycle label for traces whose tool call launches background work. */
+    statusLabel?: string;
+}
+export interface TraceGroupOptions {
+    maxItems?: number;
+    maxPreviewLines?: number;
+    homeDir?: string;
+}
+export declare function buildTraceGroups(toolCalls: DisplayToolCall[], options?: TraceGroupOptions): TraceGroup[];
+export declare function formatTracePath(value: unknown, homeDir?: string): string;
+export declare function formatElapsed(startedAt: number | undefined, now?: number): string | null;
+export declare function traceGroupLabel(group: TraceGroup): string;
+/**
+ * An execute command is shown inline in the header only when nothing is lost:
+ * no description competing for the slot, a single logical line, and it fits
+ * the width budget. Otherwise the full command renders as a wrapped block
+ * below the header — commands are never clipped mid-line.
+ */
+export declare function shouldInlineExecuteCommand(group: TraceGroup, widthBudget: number): boolean;
+/** Visible command-block lines for compact rendering, capped at `maxLines`. */
+export declare function executeCommandBlock(group: TraceGroup, maxLines: number): {
+    lines: string[];
+    omitted: number;
+};