@bubblebrain-ai/bubble 0.0.51 → 0.0.53

package/dist/tools/bash.d.ts

@@ -15,7 +15,9 @@ export interface BashToolOptions {
      */
     processManager?: ProcessManager;
     allowBackgroundTasks?: boolean;
-    /** Ctrl+G send-to-background requests, keyed by toolCall id (design §2.5). */
+    /** Ctrl+B send-to-background requests, keyed by toolCall id (design §2.5). */
     promotionChannel?: PromotionChannel;
+    /** Move a still-running foreground command into Tasks after this budget. */
+    autoBackgroundAfterMs?: number | false;
 }
 export declare function createBashTool(cwd: string, approval?: ApprovalController, _fileState?: FileStateTracker, options?: BashToolOptions): ToolRegistryEntry;

package/dist/tools/bash.js

@@ -126,6 +126,7 @@ export function createBashTool(cwd, approval, _fileState, options = {}) {
                 let terminalError;
                 let resolved = false;
                 let timeoutHandle;
+                let autoBackgroundHandle;
                 let forceKillHandle;
                 let settleHandle;
                 let postExitHandle;
@@ -174,6 +175,8 @@ export function createBashTool(cwd, approval, _fileState, options = {}) {
                 const cleanup = () => {
                     if (timeoutHandle)
                         clearTimeout(timeoutHandle);
+                    if (autoBackgroundHandle)
+                        clearTimeout(autoBackgroundHandle);
                     if (forceKillHandle)
                         clearTimeout(forceKillHandle);
                     if (settleHandle)
@@ -208,7 +211,7 @@ export function createBashTool(cwd, approval, _fileState, options = {}) {
                     resolved = true;
                     cleanup();
                     if (terminal === "promoted") {
-                        // Ctrl+G promotion (design §2.5): the process lives on under the
+                        // Ctrl+B/automatic promotion (design §2.5): the process lives on under the
                         // task manager — skip the group kill AND the stream destruction
                         // (the manager attached its own data listeners in adoptTask).
                         resolve({
@@ -347,7 +350,7 @@ export function createBashTool(cwd, approval, _fileState, options = {}) {
                         terminal = "exit";
                     finish();
                 };
-                // Ctrl+G promotion (design §2.5): flag-flip into the task manager.
+                // Ctrl+B/automatic promotion (design §2.5): flag-flip into the task manager.
                 // Registered only for background-capable hosts; a no-op once any
                 // terminal state is set (benign race with exit/timeout/cancel).
                 const promoteToBackground = () => {
@@ -381,6 +384,14 @@ export function createBashTool(cwd, approval, _fileState, options = {}) {
                 if (backgroundEnabled && options.promotionChannel && ctx.toolCall?.id) {
                     unregisterPromotion = options.promotionChannel.register(ctx.toolCall.id, promoteToBackground);
                 }
+                if (backgroundEnabled
+                    && options.autoBackgroundAfterMs !== false
+                    && typeof options.autoBackgroundAfterMs === "number"
+                    && options.autoBackgroundAfterMs > 0
+                    && options.autoBackgroundAfterMs < timeoutSec * 1000) {
+                    autoBackgroundHandle = setTimeout(promoteToBackground, options.autoBackgroundAfterMs);
+                    autoBackgroundHandle.unref?.();
+                }
                 timeoutHandle = setTimeout(timeoutChild, timeoutSec * 1000);
                 if (ctx.abortSignal?.aborted)
                     abortChild();

package/dist/tools/grep.d.ts

@@ -1,5 +1,9 @@
 /**
- * Grep tool - search file contents using ripgrep.
+ * Grep tool - bounded, streaming search using ripgrep.
+ *
+ * The limits in this file are model-context safety boundaries, not UI-only
+ * truncation. We stop rg as soon as a global budget is filled so a repository
+ * search can never materialize a multi-megabyte tool result in memory/history.
  */
 import type { ToolRegistryEntry } from "../types.js";
 export declare function createGrepTool(cwd: string): ToolRegistryEntry;

package/dist/tools/grep.js

@@ -1,30 +1,55 @@
 /**
- * Grep tool - search file contents using ripgrep.
+ * Grep tool - bounded, streaming search using ripgrep.
+ *
+ * The limits in this file are model-context safety boundaries, not UI-only
+ * truncation. We stop rg as soon as a global budget is filled so a repository
+ * search can never materialize a multi-megabyte tool result in memory/history.
  */
-import { execFile } from "node:child_process";
+import { spawn } from "node:child_process";
 import { resolve as resolvePath } from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import { isSensitivePath } from "./sensitive-paths.js";
 import { analyzeToolIntent } from "../agent/tool-intent.js";
 import { resolveToolPath } from "./path-utils.js";
-const MAX_MATCHES = 100;
+const DEFAULT_MATCH_LIMIT = 100;
+const MAX_MATCH_LIMIT = 1_000;
+const MAX_RENDERED_LINE_CODE_POINTS = 1_000;
+const MAX_RESULT_BYTES = 40 * 1024;
+const MAX_RAW_STDOUT_BYTES = 5 * 1024 * 1024;
+const MAX_STDERR_BYTES = 64 * 1024;
+const MAX_FILE_SIZE = "5M";
+const MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024;
+const GREP_TIMEOUT_MS = 30_000;
+const KILL_GRACE_MS = 250;
+const RESULT_NOTICE_RESERVE_BYTES = 1_024;
 export function createGrepTool(cwd) {
     return {
         name: "grep",
         readOnly: true,
         effect: "read",
-        description: `Search file contents using regex (via ripgrep). Use this instead of running grep, rg, or ripgrep through bash. Returns up to ${MAX_MATCHES} matches.`,
+        description: [
+            "Search file contents using regex (via ripgrep).",
+            `Returns at most ${DEFAULT_MATCH_LIMIT} matches by default (explicit limit is capped at ${MAX_MATCH_LIMIT}),`,
+            `${MAX_RESULT_BYTES / 1024}KiB total, and ${MAX_RENDERED_LINE_CODE_POINTS} Unicode characters per rendered match.`,
+            `Files larger than ${MAX_FILE_SIZE} are skipped. Narrow path/glob/pattern when a result is marked truncated.`,
+        ].join(" "),
         parameters: {
             type: "object",
             properties: {
                 pattern: { type: "string", description: "Regex pattern to search for" },
                 path: { type: "string", description: "Directory or file to search in (optional, default: cwd)" },
                 glob: { type: "string", description: "Glob pattern to filter files (optional, e.g. '*.ts')" },
+                limit: {
+                    type: "number",
+                    description: `Maximum matches to return (default ${DEFAULT_MATCH_LIMIT}, hard maximum ${MAX_MATCH_LIMIT})`,
+                },
             },
             required: ["pattern"],
         },
-        async execute(args) {
+        async execute(args, ctx) {
             const searchPath = args.path ? resolveToolPath(cwd, args.path) : cwd;
             const pattern = String(args.pattern);
+            const matchLimit = normalizeMatchLimit(args.limit);
             const intent = analyzeToolIntent({
                 name: "grep",
                 parsedArgs: {
@@ -48,72 +73,296 @@ export function createGrepTool(cwd) {
                     },
                 };
             }
-            const rgArgs = ["--json", "-n", "--max-count", String(MAX_MATCHES), pattern];
-            if (args.glob) {
+            const rgArgs = [
+                "--json",
+                "--line-number",
+                "--color=never",
+                "--max-columns",
+                String(MAX_RENDERED_LINE_CODE_POINTS),
+                "--max-columns-preview",
+                "--max-filesize",
+                MAX_FILE_SIZE,
+            ];
+            if (args.glob)
                 rgArgs.push("--glob", String(args.glob));
-            }
-            rgArgs.push(searchPath);
-            return new Promise((resolve) => {
-                execFile("rg", rgArgs, { cwd, maxBuffer: 10 * 1024 * 1024 }, (_error, stdout, _stderr) => {
-                    // rg returns exit code 1 when no matches found, which is not an error for us
-                    const lines = stdout.split("\n").filter((l) => l.trim() !== "");
-                    const matches = [];
-                    const matchedPaths = new Set();
-                    for (const line of lines) {
-                        try {
-                            const obj = JSON.parse(line);
-                            if (obj.type === "match") {
-                                const path = obj.data.path.text;
-                                const lineNum = obj.data.line_number;
-                                const text = obj.data.lines.text?.trim() ?? "";
-                                if (typeof path === "string" && path.trim()) {
-                                    matchedPaths.add(resolvePath(cwd, path));
-                                }
-                                matches.push(`${path}:${lineNum}: ${text}`);
-                            }
-                        }
-                        catch {
-                            // ignore parse errors
-                        }
-                    }
-                    if (matches.length === 0) {
-                        resolve({
-                            content: "No matches found.",
-                            status: "no_match",
-                            metadata: {
-                                kind: "search",
-                                path: searchPath,
-                                pattern,
-                                matches: 0,
-                                truncated: false,
-                                searchSignature: intent.search?.signature,
-                                searchFamily: intent.search?.familyKey,
-                                paths: [],
-                            },
-                        });
-                        return;
-                    }
-                    let output = matches.join("\n");
-                    const truncated = matches.length >= MAX_MATCHES;
-                    if (matches.length >= MAX_MATCHES) {
-                        output += `\n[More than ${MAX_MATCHES} matches, output truncated]`;
-                    }
-                    resolve({
-                        content: output,
-                        status: truncated ? "partial" : "success",
-                        metadata: {
-                            kind: "search",
-                            path: searchPath,
-                            pattern,
-                            matches: matches.length,
-                            truncated,
-                            searchSignature: intent.search?.signature,
-                            searchFamily: intent.search?.familyKey,
-                            paths: [...matchedPaths],
-                        },
-                    });
-                });
+            rgArgs.push("--", pattern, searchPath);
+            return executeBoundedGrep({
+                cwd,
+                searchPath,
+                pattern,
+                rgArgs,
+                matchLimit,
+                abortSignal: ctx.abortSignal,
+                baseMetadata: {
+                    kind: "search",
+                    path: searchPath,
+                    pattern,
+                    searchSignature: intent.search?.signature,
+                    searchFamily: intent.search?.familyKey,
+                    maxFileSizeBytes: MAX_FILE_SIZE_BYTES,
+                },
             });
         },
     };
 }
+function executeBoundedGrep(options) {
+    return new Promise((resolve) => {
+        const child = spawn("rg", options.rgArgs, {
+            cwd: options.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const decoder = new StringDecoder("utf8");
+        const matches = [];
+        let stdoutBuffer = "";
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let stderr = "";
+        let stopReason;
+        let spawnError;
+        let settled = false;
+        let killTimer;
+        const requestStop = (reason) => {
+            if (stopReason)
+                return;
+            stopReason = reason;
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGTERM");
+                killTimer = setTimeout(() => {
+                    if (child.exitCode === null && child.signalCode === null)
+                        child.kill("SIGKILL");
+                }, KILL_GRACE_MS);
+                killTimer.unref?.();
+            }
+        };
+        const processJsonLine = (line) => {
+            if (!line.trim() || stopReason)
+                return;
+            try {
+                const event = JSON.parse(line);
+                if (event.type !== "match")
+                    return;
+                const rawPath = decodeRgField(event.data?.path);
+                const lineNumber = event.data?.line_number;
+                const rawText = decodeRgField(event.data?.lines, "[non-UTF-8 match bytes omitted]") ?? "";
+                const displayPath = rawPath || "<non-UTF-8 path>";
+                const normalizedText = rawText.replace(/\r\n/g, "\n").replace(/\r/g, "").replace(/\n$/, "");
+                const rendered = truncateCodePoints(`${displayPath}:${typeof lineNumber === "number" ? lineNumber : "?"}: ${normalizedText}`, MAX_RENDERED_LINE_CODE_POINTS);
+                matches.push({
+                    rendered,
+                    ...(rawPath ? { absolutePath: resolvePath(options.cwd, rawPath) } : {}),
+                });
+                // We stop at N rather than pretending we proved there are N+1 matches.
+                // The notice says "limit reached / may be incomplete", which is honest
+                // even for the exact-fit case and avoids continuing a huge tree walk.
+                if (matches.length >= options.matchLimit)
+                    requestStop("match_limit");
+            }
+            catch {
+                // A truncated/invalid JSON event is not useful to the model. Raw byte
+                // accounting remains authoritative and will stop pathological lines.
+            }
+        };
+        const processDecodedText = (text) => {
+            stdoutBuffer += text;
+            while (!stopReason) {
+                const newline = stdoutBuffer.indexOf("\n");
+                if (newline < 0)
+                    break;
+                const line = stdoutBuffer.slice(0, newline);
+                stdoutBuffer = stdoutBuffer.slice(newline + 1);
+                processJsonLine(line);
+            }
+        };
+        child.stdout.on("data", (value) => {
+            if (stopReason)
+                return;
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            const remaining = Math.max(0, MAX_RAW_STDOUT_BYTES - stdoutBytes);
+            const accepted = chunk.subarray(0, remaining);
+            stdoutBytes += accepted.length;
+            if (accepted.length > 0)
+                processDecodedText(decoder.write(accepted));
+            if (accepted.length < chunk.length || stdoutBytes >= MAX_RAW_STDOUT_BYTES) {
+                requestStop("stdout_limit");
+            }
+        });
+        child.stdout.on("end", () => {
+            if (stopReason)
+                return;
+            processDecodedText(decoder.end());
+            if (stdoutBuffer) {
+                processJsonLine(stdoutBuffer);
+                stdoutBuffer = "";
+            }
+        });
+        child.stderr.on("data", (value) => {
+            if (stopReason)
+                return;
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            const remaining = Math.max(0, MAX_STDERR_BYTES - stderrBytes);
+            const accepted = chunk.subarray(0, remaining);
+            stderrBytes += accepted.length;
+            if (accepted.length > 0)
+                stderr += accepted.toString("utf8");
+            if (accepted.length < chunk.length || stderrBytes >= MAX_STDERR_BYTES) {
+                requestStop("stderr_limit");
+            }
+        });
+        const timeout = setTimeout(() => requestStop("timeout"), GREP_TIMEOUT_MS);
+        timeout.unref?.();
+        const onAbort = () => requestStop("aborted");
+        options.abortSignal?.addEventListener("abort", onAbort, { once: true });
+        if (options.abortSignal?.aborted)
+            onAbort();
+        child.on("error", (error) => {
+            spawnError = error;
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (killTimer)
+                clearTimeout(killTimer);
+            options.abortSignal?.removeEventListener("abort", onAbort);
+            if (stopReason === "aborted") {
+                resolve({
+                    content: "Search cancelled.",
+                    isError: true,
+                    status: "cancelled",
+                    metadata: { ...options.baseMetadata, matches: 0, truncated: false, paths: [] },
+                });
+                return;
+            }
+            if (spawnError) {
+                resolve({
+                    content: `Error calling grep: ${spawnError.message}`,
+                    isError: true,
+                    status: "command_error",
+                    metadata: { ...options.baseMetadata, matches: 0, truncated: false, paths: [] },
+                });
+                return;
+            }
+            const naturalCommandError = !stopReason && code !== 0 && code !== 1;
+            const stoppedWithoutMatches = !!stopReason && matches.length === 0;
+            if (matches.length === 0 && !stoppedWithoutMatches && !naturalCommandError) {
+                resolve({
+                    content: "No matches found.",
+                    status: "no_match",
+                    metadata: { ...options.baseMetadata, matches: 0, truncated: false, paths: [] },
+                });
+                return;
+            }
+            if (naturalCommandError && matches.length === 0) {
+                resolve({
+                    content: `Error calling grep: ${stderr.trim() || `ripgrep exited with code ${code}`}`,
+                    isError: true,
+                    status: "command_error",
+                    metadata: { ...options.baseMetadata, matches: 0, truncated: false, paths: [] },
+                });
+                return;
+            }
+            const formatted = formatMatches(matches, options.matchLimit, stopReason, naturalCommandError ? stderr.trim() : "");
+            const truncated = !!stopReason || formatted.byteTruncated || naturalCommandError;
+            const paths = [...new Set(formatted.emittedMatches.flatMap((match) => match.absolutePath ? [match.absolutePath] : []))];
+            resolve({
+                content: formatted.content,
+                ...(naturalCommandError && matches.length === 0 ? { isError: true } : {}),
+                status: stopReason === "timeout" && matches.length === 0
+                    ? "timeout"
+                    : truncated
+                        ? "partial"
+                        : "success",
+                metadata: {
+                    ...options.baseMetadata,
+                    matches: formatted.emittedMatches.length,
+                    collectedMatches: matches.length,
+                    truncated,
+                    truncationReason: stopReason ?? (formatted.byteTruncated ? "result_bytes" : naturalCommandError ? "command_error" : undefined),
+                    rawStdoutBytes: stdoutBytes,
+                    paths,
+                },
+            });
+        });
+    });
+}
+function formatMatches(matches, matchLimit, stopReason, commandWarning) {
+    const emitted = [];
+    let bodyBytes = 0;
+    const bodyBudget = MAX_RESULT_BYTES - RESULT_NOTICE_RESERVE_BYTES;
+    for (const match of matches) {
+        const lineBytes = Buffer.byteLength(match.rendered, "utf8") + (emitted.length > 0 ? 1 : 0);
+        if (bodyBytes + lineBytes > bodyBudget)
+            break;
+        emitted.push(match);
+        bodyBytes += lineBytes;
+    }
+    const byteTruncated = emitted.length < matches.length;
+    const notices = [];
+    if (stopReason === "match_limit") {
+        notices.push(`Search stopped after reaching the global limit of ${matchLimit} matches; results may be incomplete. Narrow path/glob/pattern to continue.`);
+    }
+    else if (stopReason === "stdout_limit") {
+        notices.push(`Raw ripgrep output reached ${formatBytes(MAX_RAW_STDOUT_BYTES)}; results are incomplete. Narrow the search.`);
+    }
+    else if (stopReason === "stderr_limit") {
+        notices.push(`ripgrep diagnostics reached ${formatBytes(MAX_STDERR_BYTES)}; results are incomplete.`);
+    }
+    else if (stopReason === "timeout") {
+        notices.push(`Search timed out after ${GREP_TIMEOUT_MS / 1000}s; results are incomplete. Narrow the search.`);
+    }
+    if (byteTruncated) {
+        notices.push(`Showing ${emitted.length} of ${matches.length} collected matches because tool output is capped at ${formatBytes(MAX_RESULT_BYTES)}.`);
+    }
+    if (commandWarning)
+        notices.push(`ripgrep also reported: ${truncateCodePoints(commandWarning, 300)}`);
+    let content = emitted.map((match) => match.rendered).join("\n");
+    if (notices.length > 0)
+        content += `${content ? "\n" : ""}[${notices.join(" ")}]`;
+    // The reserve above normally guarantees this. Keep an exact byte backstop so
+    // future notice copy cannot accidentally violate the model-facing contract.
+    if (Buffer.byteLength(content, "utf8") > MAX_RESULT_BYTES) {
+        content = truncateUtf8Prefix(content, MAX_RESULT_BYTES);
+    }
+    return { content, emittedMatches: emitted, byteTruncated };
+}
+function normalizeMatchLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return DEFAULT_MATCH_LIMIT;
+    return Math.min(MAX_MATCH_LIMIT, Math.max(1, Math.floor(value)));
+}
+function decodeRgField(value, invalidBytesFallback) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    if (typeof record.text === "string")
+        return record.text;
+    if (typeof record.bytes === "string") {
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(record.bytes, "base64"));
+        }
+        catch {
+            return invalidBytesFallback;
+        }
+    }
+    return undefined;
+}
+function truncateCodePoints(value, maxCodePoints) {
+    const points = Array.from(value);
+    if (points.length <= maxCodePoints)
+        return value;
+    const marker = "... [truncated]";
+    return `${points.slice(0, Math.max(0, maxCodePoints - Array.from(marker).length)).join("")}${marker}`;
+}
+function truncateUtf8Prefix(value, maxBytes) {
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.length <= maxBytes)
+        return value;
+    let end = maxBytes;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return bytes.subarray(0, end).toString("utf8");
+}
+function formatBytes(bytes) {
+    return bytes % 1024 === 0 ? `${bytes / 1024}KiB` : `${bytes} bytes`;
+}

package/dist/tools/index.d.ts

@@ -55,7 +55,9 @@ export interface CreateAllToolsOptions {
      */
     processManager?: ProcessManager;
     allowBackgroundTasks?: boolean;
-    /** Ctrl+G send-to-background requests from the TUI (design §2.5). */
+    /** Ctrl+B send-to-background requests from the TUI (design §2.5). */
     promotionChannel?: PromotionChannel;
+    /** Grok-style foreground wait budget before a Bash Execute is demoted. */
+    autoBackgroundAfterMs?: number | false;
 }
 export declare function createAllTools(cwd: string, skillRegistry?: SkillRegistry, options?: CreateAllToolsOptions): ToolRegistryEntry[];

package/dist/tools/index.js

@@ -51,6 +51,7 @@ export function createAllTools(cwd, skillRegistry, options = {}) {
             processManager: options.processManager,
             allowBackgroundTasks: backgroundTasks,
             promotionChannel: backgroundTasks ? options.promotionChannel : undefined,
+            autoBackgroundAfterMs: backgroundTasks ? options.autoBackgroundAfterMs : false,
         }),
         ...(backgroundTasks ? createBackgroundTaskTools(options.processManager) : []),
         ...createManagedServerTools(cwd, approval),

package/dist/tools/question.js

@@ -1,4 +1,5 @@
 import { QuestionRejectedError } from "../question/index.js";
+import { normalizeQuestionInlineText } from "../question/normalize.js";
 export function createQuestionTool(controller) {
     return {
         name: "question",
@@ -127,8 +128,8 @@ function normalizeQuestions(input) {
             return { error: `Error: question at index ${index} must be an object.` };
         }
         const q = raw;
-        const header = typeof q.header === "string" ? q.header.trim() : "";
-        const question = typeof q.question === "string" ? q.question.trim() : "";
+        const header = typeof q.header === "string" ? normalizeQuestionInlineText(q.header) : "";
+        const question = typeof q.question === "string" ? normalizeQuestionInlineText(q.question) : "";
         const options = q.options;
         if (!header)
             return { error: `Error: question at index ${index} has an empty header.` };
@@ -147,8 +148,8 @@ function normalizeQuestions(input) {
                 return { error: `Error: option ${optIndex + 1} for "${header}" must be an object.` };
             }
             const value = opt;
-            const label = typeof value.label === "string" ? value.label.trim() : "";
-            const description = typeof value.description === "string" ? value.description.trim() : "";
+            const label = typeof value.label === "string" ? normalizeQuestionInlineText(value.label) : "";
+            const description = typeof value.description === "string" ? normalizeQuestionInlineText(value.description) : "";
             if (!label)
                 return { error: `Error: option ${optIndex + 1} for "${header}" has empty label.` };
             if (!description)

package/dist/tools/read.js

@@ -7,8 +7,9 @@ import { basename, dirname, extname, join, relative } from "node:path";
 import { isSensitivePath } from "./sensitive-paths.js";
 import { FileStateTracker } from "./file-state.js";
 import { resolveToolPath } from "./path-utils.js";
+import { utf8Prefix } from "../context/tool-output-truncate.js";
 const MAX_LINES = 2500;
-const MAX_BYTES = 256 * 1024;
+const MAX_BYTES = 64 * 1024;
 const FILE_UNCHANGED_STUB = "File unchanged since last read. The earlier read tool_result in this conversation is still current — refer to that instead of re-reading. If you need a different range, call read again with explicit offset/limit; if the file has actually changed, edit or write will refresh this cache automatically.";
 const END_OF_FILE_STUB = (totalLines) => `End of file reached. All ${totalLines} lines of this file have already been returned by previous read tool_results in this conversation. Refer to those results, or pass an explicit offset to re-read a specific range.`;
 export function createReadTool(cwd, approval, lsp, fileState) {
@@ -126,32 +127,46 @@ export function createReadTool(cwd, approval, lsp, fileState) {
             const lines = content.split("\n");
             const totalLines = lines.length;
             const effectiveLimit = argLimit !== undefined ? argLimit : totalLines;
-            let sliced = lines.slice(effectiveOffset, effectiveOffset + effectiveLimit);
-            let truncated = false;
-            if (sliced.length > MAX_LINES) {
-                sliced = sliced.slice(0, MAX_LINES);
-                truncated = true;
-            }
-            let result = sliced.join("\n");
-            const byteLength = Buffer.byteLength(result, "utf-8");
-            if (byteLength > MAX_BYTES) {
-                result = Buffer.from(result, "utf-8").subarray(0, MAX_BYTES).toString("utf-8");
-                truncated = true;
-            }
-            if (autoAdvanceNote) {
-                result = `${autoAdvanceNote}\n${result}`;
-            }
+            const requestedLines = lines.slice(effectiveOffset, effectiveOffset + effectiveLimit);
+            const lineLimited = requestedLines.length > MAX_LINES;
+            const candidates = requestedLines.slice(0, MAX_LINES);
+            const prefix = autoAdvanceNote ? `${autoAdvanceNote}\n` : "";
+            let returnedLines = candidates.length;
+            let partialFirstLine = false;
+            let body = candidates.join("\n");
+            let truncated = lineLimited || Buffer.byteLength(`${prefix}${body}`, "utf8") > MAX_BYTES;
             if (truncated) {
-                const lastLine = effectiveOffset + sliced.length;
-                result += `\n[Output truncated at line ${lastLine} of ${totalLines}. Call read again on the same path to auto-advance to the next page, or pass explicit offset/limit.]`;
+                const accepted = [];
+                for (const line of candidates) {
+                    const next = accepted.length === 0 ? line : `${accepted.join("\n")}\n${line}`;
+                    const nextReturnedLines = accepted.length + 1;
+                    const marker = readTruncationMarker(effectiveOffset + nextReturnedLines, totalLines);
+                    if (Buffer.byteLength(`${prefix}${next}${marker}`, "utf8") > MAX_BYTES)
+                        break;
+                    accepted.push(line);
+                }
+                returnedLines = accepted.length;
+                body = accepted.join("\n");
+                // A pathological single line can exceed the whole page. Preserve a
+                // UTF-8-safe prefix and advance by exactly that represented line so
+                // auto-pagination never loops forever or skips multiple unseen lines.
+                if (returnedLines === 0 && candidates.length > 0) {
+                    returnedLines = 1;
+                    partialFirstLine = true;
+                    const marker = readTruncationMarker(effectiveOffset + returnedLines, totalLines);
+                    const available = Math.max(0, MAX_BYTES - Buffer.byteLength(`${prefix}${marker}`, "utf8"));
+                    body = utf8Prefix(candidates[0], available);
+                }
+                body += readTruncationMarker(effectiveOffset + returnedLines, totalLines);
             }
+            const result = `${prefix}${body}`;
             if (currentMtimeMs !== undefined) {
                 setHistory(filePath, {
                     argOffset,
                     argLimit,
                     effectiveOffset,
                     effectiveLimit,
-                    returnedLines: sliced.length,
+                    returnedLines,
                     totalLines,
                     mtimeMs: currentMtimeMs,
                     truncated,
@@ -159,7 +174,7 @@ export function createReadTool(cwd, approval, lsp, fileState) {
             }
             const isFullRead = effectiveOffset === 0
                 && !truncated
-                && effectiveOffset + effectiveLimit >= totalLines;
+                && effectiveOffset + returnedLines >= totalLines;
             if (isFullRead) {
                 await fileState?.observe(filePath, "read", content).catch(() => undefined);
             }
@@ -171,15 +186,19 @@ export function createReadTool(cwd, approval, lsp, fileState) {
                     kind: "read",
                     path: filePath,
                     offset: effectiveOffset + 1,
-                    lines: sliced.length,
+                    lines: returnedLines,
                     total: totalLines,
                     ...(autoAdvanceNote ? { autoAdvanced: true } : {}),
                     ...(truncated ? { truncated: true } : {}),
+                    ...(partialFirstLine ? { partialFirstLine: true } : {}),
                 },
             };
         },
     };
 }
+function readTruncationMarker(lastLine, totalLines) {
+    return `\n[Output truncated at line ${lastLine} of ${totalLines}. Call read again on the same path to auto-advance to the next page, or pass explicit offset/limit.]`;
+}
 async function readFileNotFoundMessage(filePath, cwd, error) {
     const message = [`Error: Cannot read file: ${filePath}`];
     const code = typeof error?.code === "string" ? error.code : undefined;

package/dist/tui/animation-clock.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One clock owns all decorative TUI animation. Components expose pure frame
+ * advancement; they never create timers or request renders independently.
+ */
+export declare class TuiAnimationClock {
+    private readonly onTick;
+    private readonly intervalMs;
+    private timer;
+    constructor(onTick: (elapsedMs: number) => void, intervalMs?: number);
+    setActive(active: boolean): void;
+    isActive(): boolean;
+    dispose(): void;
+    private stop;
+}