praana 0.5.0

package/dist/ui/tui/sink.d.ts

@@ -0,0 +1,4 @@
+import type { Dispatch } from "react";
+import type { TurnUiSink } from "../../ui-events.js";
+import type { TranscriptAction } from "./reducer.js";
+export declare function createTuiTurnSink(dispatch: Dispatch<TranscriptAction>): TurnUiSink;

package/dist/ui/tui/sink.js

@@ -0,0 +1,89 @@
+const THROTTLE_MS = 50;
+/**
+ * Create a throttled text delta dispatcher.
+ *
+ * Rapid token-by-token streaming causes Ink to re-render the entire component
+ * tree on every dispatch, which triggers terminal redraws and a strobing effect.
+ * This buffer coalesces deltas within a time window so the terminal only updates
+ * at a controlled rate (~20 fps).
+ */
+function createThrottledDispatcher(dispatch) {
+    let buffer = "";
+    let timer = null;
+    const flushBuffer = () => {
+        if (buffer) {
+            dispatch({ type: "assistant_delta", delta: buffer });
+            buffer = "";
+        }
+        timer = null;
+    };
+    const onDelta = (delta) => {
+        buffer += delta;
+        if (!timer) {
+            timer = setTimeout(flushBuffer, THROTTLE_MS);
+        }
+    };
+    return { onDelta, flush: flushBuffer };
+}
+export function createTuiTurnSink(dispatch) {
+    const text = createThrottledDispatcher(dispatch);
+    let pendingStats = null;
+    return {
+        onTextDelta: (delta) => text.onDelta(delta),
+        onThinkingDelta: (delta) => {
+            dispatch({ type: "thinking_delta", delta });
+        },
+        onToolCallsStart: () => {
+            text.flush();
+            dispatch({ type: "thinking_close" });
+        },
+        onToolCall: (toolName, args) => {
+            text.flush();
+            dispatch({ type: "tool_call", toolName, args });
+        },
+        onToolResult: (toolName, resultText, isError) => {
+            text.flush();
+            dispatch({ type: "tool_result", toolName, resultText, isError });
+        },
+        flushText: () => text.flush(),
+        consumeTurnStats: () => {
+            const stats = pendingStats;
+            pendingStats = null;
+            return stats;
+        },
+        onDebug: (message) => {
+            dispatch({ type: "system_lines", lines: [`[debug] ${message}`] });
+        },
+        onDebugBlock: (stepIndex, toolCalls, toolResults) => {
+            const lines = [`[debug] step ${stepIndex} tools`];
+            for (const tc of toolCalls) {
+                lines.push(`  > ${tc.toolName}(${JSON.stringify(tc.args).slice(0, 120)})`);
+            }
+            for (const tr of toolResults) {
+                lines.push(`  < ${tr.toolName}`);
+            }
+            dispatch({ type: "system_lines", lines });
+        },
+        onMemoryBanner: (stats) => {
+            pendingStats = stats;
+        },
+        onSpinnerStart: () => {
+            /* busy state handled by turn wrapper */
+        },
+        onSpinnerStop: () => {
+            /* noop */
+        },
+        onNewline: () => {
+            dispatch({ type: "assistant_delta", delta: "\n" });
+        },
+        onFallback: (text) => {
+            dispatch({ type: "assistant_delta", delta: text + "\n" });
+        },
+        onError: (entry) => {
+            dispatch({
+                type: "system_lines",
+                lines: [`[${entry.level}] ${entry.domain}: ${entry.message}`],
+            });
+        },
+    };
+}

package/dist/ui/tui/status-bar-view.d.ts

@@ -0,0 +1,5 @@
+import React from "react";
+import type { StatusBarInput } from "../../status-bar.js";
+export declare function StatusBarView({ status, }: {
+    status: StatusBarInput;
+}): React.JSX.Element;

package/dist/ui/tui/status-bar-view.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { formatTokenCount } from "../../status-bar.js";
+import { PALETTE } from "./palette.js";
+import { getTerminalWidth } from "./terminal-width.js";
+function formatStateLabel(stats) {
+    const parts = [];
+    if (stats.active > 0)
+        parts.push(`${stats.active} active`);
+    if (stats.soft > 0)
+        parts.push(`${stats.soft} soft`);
+    if (stats.hard > 0)
+        parts.push(`${stats.hard} hard`);
+    return parts.join(" · ");
+}
+function formatMemLabel(status) {
+    if (status.incognito)
+        return "incognito";
+    if (!status.memoryEnabled)
+        return "off (config)";
+    return "on";
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}
+export function StatusBarView({ status, }) {
+    const { memoryStats, currentTask, skills } = status;
+    const width = getTerminalWidth();
+    const pct = status.contextWindowTokens > 0
+        ? Math.min(100, Math.round((status.contextUsedTokens / status.contextWindowTokens) * 100))
+        : 0;
+    const modelShort = status.model.split("/").pop() ?? status.model;
+    const memStr = formatMemLabel(status);
+    const skillsCount = skills.length;
+    const stateStr = formatStateLabel(memoryStats);
+    const ctxStr = status.contextWindowTokens > 0
+        ? `${formatTokenCount(status.contextUsedTokens)}/${formatTokenCount(status.contextWindowTokens)} (${pct}%)`
+        : `${pct}%`;
+    const thinkStr = status.thinking ? "on" : "off";
+    const taskLabel = currentTask ? truncate(currentTask, Math.max(24, width - 20)) : null;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: PALETTE.assistant, children: `📦 ${modelShort}` }), _jsx(Text, { dimColor: true, children: "  |  " }), _jsx(Text, { color: pct > 90 ? PALETTE.error : pct > 70 ? PALETTE.tool : PALETTE.muted, children: `🧠 ctx ${ctxStr}` }), _jsx(Text, { dimColor: true, children: "  |  " }), _jsx(Text, { color: status.thinking ? PALETTE.tool : PALETTE.muted, children: `💭 think ${thinkStr}` }), _jsx(Text, { dimColor: true, children: "  |  " }), _jsx(Text, { color: memStr === "on" ? PALETTE.user : PALETTE.muted, children: `💾 mem ${memStr}` }), skillsCount > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "  |  " }), _jsx(Text, { color: PALETTE.tool, children: `🛠️  ${skillsCount} skills` })] })), stateStr && (_jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: "  |  " }), _jsx(Text, { color: PALETTE.muted, children: `◇ ${stateStr}` })] }))] }), taskLabel ? (_jsx(Box, { marginTop: 0, children: _jsx(Text, { color: PALETTE.muted, dimColor: true, children: `🎯 ${taskLabel}` }) })) : null] }));
+}

package/dist/ui/tui/terminal-height.d.ts

@@ -0,0 +1,12 @@
+/** Best-effort terminal row count for layout (TUI). */
+export declare function getTerminalRows(): number;
+export interface TranscriptBudgetOptions {
+    showLogo?: boolean;
+    showToast?: boolean;
+    showScrollHint?: boolean;
+}
+/**
+ * Lines available for transcript content after reserving chrome
+ * (prompt, status bar, padding, optional logo/toast).
+ */
+export declare function getTranscriptLineBudget(options?: TranscriptBudgetOptions): number;

package/dist/ui/tui/terminal-height.js

@@ -0,0 +1,20 @@
+/** Best-effort terminal row count for layout (TUI). */
+export function getTerminalRows() {
+    const rows = process.stdout.rows ?? process.stderr.rows ?? 24;
+    return Math.max(12, Math.min(rows, 200));
+}
+/**
+ * Lines available for transcript content after reserving chrome
+ * (prompt, status bar, padding, optional logo/toast).
+ */
+export function getTranscriptLineBudget(options = {}) {
+    const rows = getTerminalRows();
+    let overhead = 7; // outer padding, prompt row, status bar, gaps
+    if (options.showLogo)
+        overhead += 10;
+    if (options.showToast)
+        overhead += 1;
+    if (options.showScrollHint)
+        overhead += 2;
+    return Math.max(6, rows - overhead);
+}

package/dist/ui/tui/terminal-width.d.ts

@@ -0,0 +1,2 @@
+/** Best-effort terminal width for layout (TUI). */
+export declare function getTerminalWidth(): number;

package/dist/ui/tui/terminal-width.js

@@ -0,0 +1,5 @@
+/** Best-effort terminal width for layout (TUI). */
+export function getTerminalWidth() {
+    const cols = process.stdout.columns ?? process.stderr.columns ?? 80;
+    return Math.max(40, Math.min(cols, 200));
+}

package/dist/ui/tui/tool-display.d.ts

@@ -0,0 +1,23 @@
+import type { MemoryBannerStats } from "../../ui-events.js";
+export interface ToolDisplayInfo {
+    icon: string;
+    label: string;
+    pending: string;
+}
+/** Produce a compact one-line summary of a tool result for display. */
+export declare function summarizeResultForDisplay(text: string): string;
+export declare function formatToolDisplay(toolName: string, args: Record<string, unknown>): ToolDisplayInfo;
+/** Turn-specific stats for the footer (excludes state — tier counts live in the status bar). */
+export declare function formatTurnStatsSuffix(stats?: MemoryBannerStats): string;
+export declare function formatTurnFooter(model: string, durationMs: number, stats?: MemoryBannerStats): string;
+/** Compact boot summary for the TUI welcome panel. */
+export declare function formatTuiBootSummary(input: {
+    sessionId: string;
+    contextTokens?: number;
+    engineEnabled: boolean;
+    skillCount: number;
+    memoryEnabled: boolean;
+    incognito: boolean;
+}): string;
+/** Whether this entry should have extra top margin (visual break from prior block). */
+export declare function needsTopMargin(role: string, prevRole: string | undefined): boolean;

package/dist/ui/tui/tool-display.js

@@ -0,0 +1,217 @@
+import { summarizeArgs } from "../../tool-summary.js";
+function fmtToken(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 1_000_000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return `${(n / 1_000_000).toFixed(1)}M`;
+}
+function shellShortLabel(command) {
+    const trimmed = command.trim();
+    if (trimmed.length <= 64)
+        return trimmed;
+    const segments = trimmed.split("&&").map((s) => s.trim());
+    const last = segments[segments.length - 1] ?? trimmed;
+    const short = last.split(/\s+/).slice(0, 4).join(" ");
+    return short.length > 56 ? `${short.slice(0, 55)}…` : short;
+}
+/** Produce a compact one-line summary of a tool result for display. */
+export function summarizeResultForDisplay(text) {
+    if (!text)
+        return "(empty)";
+    const artifactMatch = text.match(/\[artifact:\s*(art_[a-f0-9]+)/i);
+    if (artifactMatch) {
+        const tokenMatch = text.match(/([\d,]+)\s*tokens?\b/i);
+        const id = artifactMatch[1];
+        return tokenMatch
+            ? `artifact ${id.slice(0, 12)}… · ${tokenMatch[1].replace(/,/g, "")} tokens`
+            : `artifact ${id.slice(0, 16)}…`;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed.ok === false) {
+            return `error: ${String(parsed.error ?? "failed").slice(0, 72)}`;
+        }
+        if (typeof parsed.stdout === "string") {
+            const stdout = parsed.stdout.trim();
+            const lineCount = stdout ? stdout.split("\n").filter(Boolean).length : 0;
+            const preview = stdout.split("\n")[0]?.slice(0, 56) ?? "";
+            const suffix = preview ? ` — ${preview}${stdout.length > 56 ? "…" : ""}` : "";
+            return `exit ${parsed.exitCode ?? 0} · ${lineCount} line(s)${suffix}`;
+        }
+        if (typeof parsed.content === "string") {
+            const content = parsed.content;
+            const lineCount = content.split("\n").length;
+            const preview = content.split("\n")[0]?.slice(0, 56) ?? "";
+            return `${lineCount} line(s) · ${preview}${content.length > 56 ? "…" : ""}`;
+        }
+        if (parsed.id) {
+            return `ok · ${String(parsed.id).slice(0, 28)}`;
+        }
+    }
+    catch {
+        /* plain text */
+    }
+    const lines = text.split("\n").length;
+    const chars = text.length;
+    const preview = text.slice(0, 200).split("\n")[0];
+    const previewText = preview.length > 72 ? `${preview.slice(0, 71)}…` : preview;
+    const size = lines > 1 ? `${lines} lines, ${chars} chars` : `${chars} chars`;
+    return `${size} — ${previewText}`;
+}
+function formatPath(path) {
+    const value = String(path ?? "");
+    if (!value)
+        return "";
+    return value.length > 60 ? "…" + value.slice(-57) : value;
+}
+export function formatToolDisplay(toolName, args) {
+    switch (toolName) {
+        case "shell": {
+            const command = String(args.command ?? "");
+            return {
+                icon: "$",
+                label: command ? shellShortLabel(command) : "shell",
+                pending: "Running command…",
+            };
+        }
+        case "retrieve_artifact": {
+            const id = String(args.id ?? args.artifact_id ?? "").slice(0, 16);
+            return {
+                icon: "◆",
+                label: id ? `Artifact ${id}` : "Retrieve artifact",
+                pending: "Retrieving artifact…",
+            };
+        }
+        case "read_file": {
+            const path = formatPath(args.path);
+            return { icon: "→", label: `Read ${path}`, pending: "Reading file…" };
+        }
+        case "write_file": {
+            const path = formatPath(args.path);
+            return { icon: "←", label: `Write ${path}`, pending: "Writing file…" };
+        }
+        case "edit_file": {
+            const path = formatPath(args.path);
+            return { icon: "✎", label: `Edit ${path}`, pending: "Editing file…" };
+        }
+        case "search_code": {
+            const pattern = String(args.pattern ?? "");
+            const path = args.path ? ` in ${formatPath(args.path)}` : "";
+            return {
+                icon: "✱",
+                label: `Grep "${pattern}"${path}`,
+                pending: "Searching…",
+            };
+        }
+        case "recall": {
+            const query = String(args.query ?? "").slice(0, 80);
+            return { icon: "◈", label: `Recall "${query}"`, pending: "Recalling…" };
+        }
+        case "search_session_log": {
+            const query = String(args.query ?? "").slice(0, 80);
+            return { icon: "◈", label: `Search log "${query}"`, pending: "Searching log…" };
+        }
+        case "create_task": {
+            const title = String(args.title ?? "").slice(0, 80);
+            return { icon: "◇", label: `Task ${title}`, pending: "Creating task…" };
+        }
+        case "complete_task":
+        case "hydrate":
+        case "soft_unload":
+        case "hard_unload": {
+            const id = String(args.id ?? "").slice(0, 26);
+            return { icon: "◇", label: `${toolName} ${id}`, pending: "Updating state…" };
+        }
+        case "remember": {
+            const content = String(args.content ?? "").slice(0, 60);
+            return { icon: "◈", label: `Remember ${content}`, pending: "Storing memory…" };
+        }
+        default: {
+            const summary = summarizeArgs(toolName, args);
+            return {
+                icon: "⚙",
+                label: summary ? `${toolName} ${summary}` : toolName,
+                pending: "Running…",
+            };
+        }
+    }
+}
+/** Turn-specific stats for the footer (excludes state — tier counts live in the status bar). */
+export function formatTurnStatsSuffix(stats) {
+    if (!stats)
+        return "";
+    const parts = [];
+    if (stats.promptTokens > 0)
+        parts.push(`prompt ~${fmtToken(stats.promptTokens)}`);
+    if (stats.outputTokens > 0)
+        parts.push(`out ~${fmtToken(stats.outputTokens)}`);
+    if (stats.digestLen > 0)
+        parts.push(`digest ${stats.digestLen}c`);
+    if (stats.recallCalls > 0) {
+        parts.push(`recall ${stats.recallHits}/${stats.recallCalls}`);
+    }
+    if (stats.autoHydrated > 0)
+        parts.push(`auto+${stats.autoHydrated}`);
+    return parts.join(" · ");
+}
+export function formatTurnFooter(model, durationMs, stats) {
+    const modelShort = model.split("/").pop() ?? model;
+    const duration = durationMs < 1000
+        ? `${Math.max(0, Math.round(durationMs))}ms`
+        : `${(durationMs / 1000).toFixed(1)}s`;
+    const parts = [`▣ PRAANA`, modelShort, duration];
+    const suffix = formatTurnStatsSuffix(stats);
+    if (suffix)
+        parts.push(suffix);
+    return parts.join(" · ");
+}
+/** Compact boot summary for the TUI welcome panel. */
+export function formatTuiBootSummary(input) {
+    const parts = [`session ${input.sessionId}`];
+    if (input.contextTokens && input.contextTokens > 0) {
+        parts.push(`ctx ~${input.contextTokens} tok`);
+    }
+    if (input.engineEnabled)
+        parts.push("engine on");
+    if (input.skillCount > 0) {
+        parts.push(`${input.skillCount} skill${input.skillCount === 1 ? "" : "s"}`);
+    }
+    if (input.incognito)
+        parts.push("incognito");
+    else if (!input.memoryEnabled) {
+        parts.push("mem off (enable memory.enabled in config)");
+    }
+    return parts.join(" · ");
+}
+const BLOCK_ROLES = new Set([
+    "user",
+    "assistant",
+    "tool",
+    "tool_result",
+    "thinking",
+    "turn_footer",
+    "system",
+]);
+/** Whether this entry should have extra top margin (visual break from prior block). */
+export function needsTopMargin(role, prevRole) {
+    if (role === "user")
+        return true;
+    if (!prevRole)
+        return false;
+    if (role === prevRole)
+        return false;
+    if (role === "turn_footer")
+        return true;
+    if (role === "thinking" && prevRole !== "thinking")
+        return true;
+    if (role === "tool" &&
+        prevRole !== "tool" &&
+        prevRole !== "tool_result") {
+        return true;
+    }
+    if (role === "assistant" && BLOCK_ROLES.has(prevRole)) {
+        return true;
+    }
+    return false;
+}

package/dist/ui/tui/transcript-line.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+import type { TranscriptEntry } from "./reducer.js";
+export interface TranscriptLineProps {
+    entry: TranscriptEntry;
+    prevRole?: TranscriptEntry["role"];
+    live?: boolean;
+    showThinking?: boolean;
+    markdownRendering?: boolean;
+    syntaxHighlighting?: boolean;
+    syntaxTheme?: string;
+}
+export declare const TranscriptLine: React.NamedExoticComponent<TranscriptLineProps>;

package/dist/ui/tui/transcript-line.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { Box, Text } from "ink";
+import stripAnsi from "strip-ansi";
+import { PALETTE } from "./palette.js";
+import { MarkdownRender } from "./markdown-render.js";
+import { needsTopMargin } from "./tool-display.js";
+import { UserBlock } from "./components/user-block.js";
+import { ThinkingBlock } from "./components/thinking-block.js";
+import { InlineToolRow } from "./components/inline-tool-row.js";
+import { ToolResultLine } from "./components/tool-result-line.js";
+import { TurnFooter } from "./components/turn-footer.js";
+import { SystemLine } from "./components/system-line.js";
+export const TranscriptLine = React.memo(function TranscriptLine({ entry, prevRole, live = false, showThinking = false, markdownRendering = true, syntaxHighlighting = true, syntaxTheme = "solarized-dark", }) {
+    const plain = stripAnsi(entry.text);
+    const marginTop = needsTopMargin(entry.role, prevRole);
+    if (entry.role === "user") {
+        return (_jsx(UserBlock, { text: plain, marginTop: marginTop, showTurnBreak: prevRole === "turn_footer" }));
+    }
+    if (entry.role === "thinking") {
+        return (_jsx(ThinkingBlock, { text: plain, live: live, showBody: showThinking, durationMs: entry.durationMs, markdownRendering: markdownRendering, syntaxHighlighting: syntaxHighlighting, syntaxTheme: syntaxTheme }));
+    }
+    if (entry.role === "tool") {
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(InlineToolRow, { icon: entry.toolIcon ?? "⚙", label: entry.toolLabel ?? plain, pending: entry.toolPending, complete: entry.resultSummary !== undefined, isError: entry.isError, marginTop: marginTop }), entry.resultSummary ? (_jsx(ToolResultLine, { summary: entry.resultSummary, isError: entry.isError })) : null] }));
+    }
+    if (entry.role === "tool_result") {
+        const summary = entry.resultSummary ?? plain;
+        return (_jsx(Box, { flexDirection: "column", marginTop: marginTop ? 1 : 0, paddingLeft: 1, children: _jsx(ToolResultLine, { summary: summary, isError: entry.isError }) }));
+    }
+    if (entry.role === "turn_footer") {
+        return _jsx(TurnFooter, { text: plain, marginTop: true });
+    }
+    if (entry.role === "system") {
+        return _jsx(SystemLine, { text: plain, marginTop: marginTop });
+    }
+    if (entry.role === "assistant") {
+        if (!plain.trim())
+            return null;
+        const useMarkdown = markdownRendering;
+        return (_jsx(Box, { flexDirection: "column", marginTop: marginTop ? 1 : 0, paddingLeft: 1, children: useMarkdown ? (_jsx(MarkdownRender, { text: plain, syntaxHighlighting: syntaxHighlighting, syntaxTheme: syntaxTheme })) : (_jsx(Text, { wrap: "wrap", color: PALETTE.text, children: plain || " " })) }));
+    }
+    return (_jsx(Box, { marginTop: marginTop ? 1 : 0, paddingLeft: 1, children: _jsx(Text, { wrap: "wrap", children: plain || " " }) }));
+});

package/dist/ui/tui/transcript-replay.d.ts

@@ -0,0 +1,12 @@
+import type { Event } from "../../types.js";
+import type { TranscriptEntry } from "./reducer.js";
+/** Rebuild TUI transcript entries from session event log (resume). */
+export declare function buildTranscriptFromEvents(events: Event[]): TranscriptEntry[];
+/** Rough line budget for scroll windowing (terminals are line-limited). */
+export declare function estimateEntryLines(entry: TranscriptEntry, terminalWidth?: number): number;
+export declare function sliceEntriesByLineBudget(entries: TranscriptEntry[], lineBudget: number, scrollOffsetLines: number, terminalWidth?: number): {
+    entries: TranscriptEntry[];
+    startIndex: number;
+    totalLines: number;
+    maxScrollLines: number;
+};

package/dist/ui/tui/transcript-replay.js

@@ -0,0 +1,117 @@
+import { formatToolDisplay, summarizeResultForDisplay, } from "./tool-display.js";
+import { formatToolResultRawText } from "../../tool-summary.js";
+/** Rebuild TUI transcript entries from session event log (resume). */
+export function buildTranscriptFromEvents(events) {
+    const entries = [];
+    let nextId = 1;
+    let groupCounter = 0;
+    const push = (entry) => {
+        entries.push({ ...entry, id: `replay-${nextId++}`, group: groupCounter });
+    };
+    for (const ev of events) {
+        switch (ev.kind) {
+            case "user_message": {
+                groupCounter++;
+                const text = String(ev.payload.text ?? "").trim();
+                if (text)
+                    push({ role: "user", text });
+                break;
+            }
+            case "tool_call": {
+                const toolName = String(ev.payload.tool ?? "tool");
+                const args = (ev.payload.args ?? {});
+                const display = formatToolDisplay(toolName, args);
+                push({
+                    role: "tool",
+                    toolName,
+                    text: toolName,
+                    toolIcon: display.icon,
+                    toolLabel: display.label,
+                    toolPending: display.pending,
+                });
+                break;
+            }
+            case "tool_result": {
+                const toolName = String(ev.payload.tool ?? "tool");
+                const raw = formatToolResultRawText(ev.payload.result);
+                const summary = summarizeResultForDisplay(raw);
+                const isError = typeof ev.payload.result === "object" &&
+                    ev.payload.result !== null &&
+                    ev.payload.result.ok === false;
+                for (let i = entries.length - 1; i >= 0; i--) {
+                    const entry = entries[i];
+                    if (entry?.role === "tool" &&
+                        entry.toolName === toolName &&
+                        entry.resultSummary === undefined) {
+                        entries[i] = {
+                            ...entry,
+                            resultSummary: summary,
+                            resultText: raw,
+                            isError: isError ?? false,
+                        };
+                        break;
+                    }
+                }
+                break;
+            }
+            case "agent_message": {
+                const text = String(ev.payload.text ?? "").trim();
+                if (text)
+                    push({ role: "assistant", text });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return entries;
+}
+/** Rough line budget for scroll windowing (terminals are line-limited). */
+export function estimateEntryLines(entry, terminalWidth = 80) {
+    const lines = entry.text.split("\n").length;
+    const wrapCols = Math.max(40, terminalWidth - 4);
+    switch (entry.role) {
+        case "user":
+            return Math.max(4, lines + 3);
+        case "assistant":
+            return Math.max(2, lines + Math.ceil(entry.text.length / wrapCols));
+        case "tool":
+            return entry.resultSummary ? 4 : 2;
+        case "thinking":
+            return 3;
+        case "turn_footer":
+            return 3;
+        case "system":
+            return Math.max(1, lines);
+        default:
+            return Math.max(1, lines);
+    }
+}
+export function sliceEntriesByLineBudget(entries, lineBudget, scrollOffsetLines, terminalWidth = 80) {
+    const weights = entries.map((entry) => estimateEntryLines(entry, terminalWidth));
+    const totalLines = weights.reduce((a, b) => a + b, 0);
+    const maxScrollLines = Math.max(0, totalLines - lineBudget);
+    const offset = Math.min(Math.max(0, scrollOffsetLines), maxScrollLines);
+    if (totalLines <= lineBudget) {
+        return { entries, startIndex: 0, totalLines, maxScrollLines: 0 };
+    }
+    const topLine = Math.max(0, totalLines - lineBudget - offset);
+    let start = 0;
+    let lineAcc = 0;
+    while (start < entries.length && lineAcc + (weights[start] ?? 1) <= topLine) {
+        lineAcc += weights[start] ?? 1;
+        start++;
+    }
+    let end = start;
+    let windowLines = 0;
+    while (end < entries.length && windowLines < lineBudget) {
+        windowLines += weights[end] ?? 1;
+        end++;
+    }
+    return {
+        entries: entries.slice(start, end),
+        startIndex: start,
+        totalLines,
+        maxScrollLines,
+    };
+}

package/dist/ui-events.d.ts

@@ -0,0 +1,39 @@
+import type { LogEntry } from "./logger.js";
+import type { computeMemoryStats } from "./turn.js";
+export type MemoryBannerStats = ReturnType<typeof computeMemoryStats>;
+/** UI sink for turn execution — replaces direct stdout/stderr writes when provided. */
+export interface TurnUiSink {
+    onTextDelta?(delta: string): void;
+    onThinkingDelta?(delta: string): void;
+    onToolCallsStart?(): void;
+    onToolCall?(toolName: string, args: Record<string, unknown>): void;
+    /** Notify UI of the raw tool result text for rendering as a distinct block. */
+    onToolResult?(toolName: string, resultText: string, isError?: boolean): void;
+    onDebug?(message: string): void;
+    onDebugBlock?(stepIndex: number, toolCalls: Array<{
+        toolName: string;
+        args: Record<string, unknown>;
+    }>, toolResults: Array<{
+        toolName: string;
+        result: unknown;
+    }>): void;
+    onMemoryBanner?(stats: MemoryBannerStats): void;
+    onSpinnerStart?(text: string): void;
+    onSpinnerStop?(): void;
+    onNewline?(): void;
+    onFallback?(text: string): void;
+    /** Structured error for UI display (LLM failures, etc.). */
+    onError?(entry: LogEntry): void;
+    /** Flush any buffered text before dispatching terminal actions (e.g. assistant_complete).
+     *  Used by throttled sinks to ensure no text is lost. */
+    flushText?(): void;
+    /** Take buffered turn stats for the combined turn footer line. */
+    consumeTurnStats?(): MemoryBannerStats | null;
+}
+/** Default sink: streaming callbacks + legacy terminal helpers. */
+export declare function createDefaultTurnSink(options?: {
+    onTextDelta?: (delta: string) => void;
+    onThinkingDelta?: (delta: string) => void;
+    onToolCallsStart?: () => void;
+}): TurnUiSink;
+export declare function hasTurnUiSink(sink?: TurnUiSink): sink is TurnUiSink;