@bubblebrain-ai/bubble 0.0.6 → 0.0.8

package/dist/provider-transform.js

@@ -3,6 +3,13 @@ export { getAvailableThinkingLevels, getDefaultThinkingLevel, normalizeThinkingL
 const MOONSHOT_PROVIDER_IDS = new Set(["moonshot-cn", "moonshot-intl", "kimi-for-coding"]);
 const KIMI_K25_FAMILY = new Set(["kimi-k2.5", "k2.6-code-preview", "kimi-k2.6"]);
 const KIMI_THINKING_FAMILY = new Set(["kimi-k2-thinking", "kimi-k2-thinking-turbo"]);
+const KIMI_K26_DEFAULT_MAX_TOKENS = 32768;
+function isFireworksKimi(providerId, modelId) {
+    const model = modelId.toLowerCase();
+    return providerId === "fireworks" && (model.includes("kimi")
+        || model.includes("k2p6")
+        || model === "k2.6");
+}
 export function resolveProviderRequestConfig(providerId, modelId, requestedLevel) {
     const supportedLevels = getAvailableThinkingLevels(providerId, modelId);
     const effectiveThinkingLevel = normalizeThinkingLevel(requestedLevel, supportedLevels);
@@ -11,6 +18,14 @@ export function resolveProviderRequestConfig(providerId, modelId, requestedLevel
     if (providerId === "openai-codex") {
         return { effectiveThinkingLevel };
     }
+    if (isFireworksKimi(providerId, modelId)) {
+        return {
+            effectiveThinkingLevel,
+            reasoningContentEcho: "none",
+            parallelToolCalls: false,
+            maxTokens: KIMI_K26_DEFAULT_MAX_TOKENS,
+        };
+    }
     if (providerId === "deepseek" && (modelId === "deepseek-v4-flash" || modelId === "deepseek-v4-pro")) {
         return {
             effectiveThinkingLevel,

package/dist/provider.d.ts

@@ -4,10 +4,13 @@
  * Works with OpenRouter, OpenAI, DeepSeek, Google, Groq, Together, and local OpenAI-compatible endpoints.
  */
 import type { Provider, ProviderMessage, StreamChunk, ThinkingLevel } from "./types.js";
-type ReasoningContentEcho = "tool_calls" | "all";
+type ReasoningContentEcho = "tool_calls" | "all" | "none";
 export type ToolArgsMergeMode = "delta" | "snapshot";
 export interface TranslateOpenAIStreamOptions {
     toolArgsMergeMode?: ToolArgsMergeMode;
+    reasoningMergeMode?: ToolArgsMergeMode;
+    debugProviderId?: string;
+    debugModelId?: string;
 }
 export declare function toChatCompletionsMessage(message: ProviderMessage, options?: {
     reasoningContentEcho?: ReasoningContentEcho;

package/dist/provider.js

@@ -8,6 +8,7 @@ import { appendFileSync } from "node:fs";
 import { createOpenAICodexProvider, isOpenAICodexBaseUrl } from "./provider-openai-codex.js";
 import { createProviderProtocolArtifactFilter } from "./provider-artifacts.js";
 import { resolveProviderRequestConfig } from "./provider-transform.js";
+import { debugReasoningStream, summarizeDebugText } from "./reasoning-debug.js";
 // Diagnostic logger for tool-args byte-loss investigation. Activate with
 //   BUBBLE_DEBUG_TOOL_ARGS=/path/to/log.jsonl   (any writable path)
 // Each line is a JSON record describing a transition. When debugging is off,
@@ -101,6 +102,12 @@ export function createProviderInstance(options) {
         if (requestConfig.extraBody) {
             Object.assign(body, requestConfig.extraBody);
         }
+        if (tools && tools.length > 0 && requestConfig.parallelToolCalls !== undefined) {
+            body.parallel_tool_calls = requestConfig.parallelToolCalls;
+        }
+        if (requestConfig.maxTokens !== undefined) {
+            body.max_tokens = requestConfig.maxTokens;
+        }
         if (requestConfig.reasoningEffort && requestConfig.reasoningEffort !== "off") {
             body.reasoning = { enabled: true };
         }
@@ -109,6 +116,9 @@ export function createProviderInstance(options) {
         }));
         yield* translateOpenAIStream(stream, {
             toolArgsMergeMode: resolveToolArgsMergeMode(options.providerId || "", options.baseURL),
+            reasoningMergeMode: resolveReasoningMergeMode(options.providerId || "", options.baseURL),
+            debugProviderId: options.providerId || "",
+            debugModelId: chatOptions.model,
         });
         yield { type: "done" };
     }
@@ -126,6 +136,9 @@ export function createProviderInstance(options) {
         if (requestConfig.extraBody) {
             Object.assign(body, requestConfig.extraBody);
         }
+        if (requestConfig.maxTokens !== undefined) {
+            body.max_tokens = requestConfig.maxTokens;
+        }
         if (requestConfig.reasoningEffort && requestConfig.reasoningEffort !== "off") {
             body.reasoning = { enabled: true };
         }
@@ -188,6 +201,13 @@ function resolveToolArgsMergeMode(providerId, baseURL) {
         return "snapshot";
     return "delta";
 }
+function resolveReasoningMergeMode(providerId, baseURL) {
+    const id = providerId.toLowerCase();
+    const url = baseURL.toLowerCase();
+    if (id === "fireworks" || url.includes("fireworks.ai"))
+        return "snapshot";
+    return "delta";
+}
 function extractBalancedJson(s, start) {
     if (s[start] !== "{")
         return null;
@@ -232,6 +252,9 @@ export async function* translateOpenAIStream(stream, options = {}) {
     const toolCalls = new Map();
     const textFilter = createProviderProtocolArtifactFilter();
     const toolArgsMergeMode = options.toolArgsMergeMode ?? "delta";
+    const reasoningMergeMode = options.reasoningMergeMode ?? "delta";
+    let reasoningBuffer = "";
+    let rawChunkSeq = 0;
     // DeepSeek (and some inference re-hosts) sometimes deliver reasoning twice:
     // once via a dedicated `reasoning_content` / `thinking` field, and again
     // embedded as `<think>...</think>` inside `delta.content`. Track whether we
@@ -277,8 +300,21 @@ export async function* translateOpenAIStream(stream, options = {}) {
         }
     }
     for await (const chunk of stream) {
+        rawChunkSeq += 1;
         const delta = chunk.choices?.[0]?.delta;
         const usage = chunk.usage;
+        const finishReason = chunk.choices?.[0]?.finish_reason;
+        debugReasoningStream({
+            stage: "provider_raw",
+            providerId: options.debugProviderId,
+            modelId: options.debugModelId,
+            chunkSeq: rawChunkSeq,
+            finishReason,
+            content: summarizeDebugText(delta?.content),
+            reasoning: summarizeDebugText(delta?.reasoning),
+            thinking: summarizeDebugText(delta?.thinking),
+            reasoningContent: summarizeDebugText(delta?.reasoning_content),
+        });
         if (usage) {
             yield {
                 type: "usage",
@@ -294,16 +330,53 @@ export async function* translateOpenAIStream(stream, options = {}) {
                 },
             };
         }
-        const reasoning = delta?.reasoning ?? delta?.thinking ?? delta?.reasoning_content;
+        const reasoningField = delta?.reasoning !== undefined
+            ? "reasoning"
+            : delta?.thinking !== undefined
+                ? "thinking"
+                : delta?.reasoning_content !== undefined
+                    ? "reasoning_content"
+                    : undefined;
+        const reasoning = reasoningField ? delta[reasoningField] : undefined;
         if (reasoning) {
             hasDedicatedReasoningChannel = true;
-            yield { type: "reasoning_delta", content: reasoning };
+            const merged = mergeStreamingText(reasoningBuffer, reasoning, reasoningMergeMode);
+            reasoningBuffer = merged.args;
+            debugReasoningStream({
+                stage: "provider_emit",
+                providerId: options.debugProviderId,
+                modelId: options.debugModelId,
+                chunkSeq: rawChunkSeq,
+                source: reasoningField,
+                mergeMode: reasoningMergeMode,
+                suppressed: !merged.delta,
+                emitted: summarizeDebugText(merged.delta),
+                buffer: summarizeDebugText(reasoningBuffer),
+            });
+            if (merged.delta) {
+                yield { type: "reasoning_delta", content: merged.delta };
+            }
         }
         if (delta?.content) {
             const thinkMatch = delta.content.match(/<think>([\s\S]*?)<\/think>/);
             if (thinkMatch) {
                 if (thinkMatch[1] && !hasDedicatedReasoningChannel) {
-                    yield { type: "reasoning_delta", content: thinkMatch[1] };
+                    const merged = mergeStreamingText(reasoningBuffer, thinkMatch[1], reasoningMergeMode);
+                    reasoningBuffer = merged.args;
+                    debugReasoningStream({
+                        stage: "provider_emit",
+                        providerId: options.debugProviderId,
+                        modelId: options.debugModelId,
+                        chunkSeq: rawChunkSeq,
+                        source: "content_think",
+                        mergeMode: reasoningMergeMode,
+                        suppressed: !merged.delta,
+                        emitted: summarizeDebugText(merged.delta),
+                        buffer: summarizeDebugText(reasoningBuffer),
+                    });
+                    if (merged.delta) {
+                        yield { type: "reasoning_delta", content: merged.delta };
+                    }
                 }
                 const remaining = delta.content.replace(/<think>[\s\S]*?<\/think>/, "");
                 const cleaned = textFilter.push(remaining);
@@ -348,7 +421,6 @@ export async function* translateOpenAIStream(stream, options = {}) {
                 }
             }
         }
-        const finishReason = chunk.choices?.[0]?.finish_reason;
         if (finishReason === "tool_calls") {
             yield* flushToolCalls();
         }
@@ -386,3 +458,16 @@ function mergeToolArgumentDelta(current, incoming, mode) {
     debugToolArgs({ stage: "merge", branch: mode === "delta" ? "delta-append" : "snapshot-fallback-concat", current, incoming, args: current + incoming, delta: incoming });
     return { args: current + incoming, delta: incoming };
 }
+function mergeStreamingText(current, incoming, mode) {
+    if (!current)
+        return { args: incoming, delta: incoming };
+    if (!incoming)
+        return { args: current, delta: "" };
+    if (mode === "snapshot") {
+        if (incoming === current)
+            return { args: current, delta: "" };
+        if (incoming.startsWith(current))
+            return { args: incoming, delta: incoming.slice(current.length) };
+    }
+    return { args: current + incoming, delta: incoming };
+}

package/dist/reasoning-debug.d.ts

@@ -0,0 +1,7 @@
+export interface DebugTextSummary {
+    length: number;
+    hash: string;
+    preview?: string;
+}
+export declare function summarizeDebugText(value: unknown): DebugTextSummary | undefined;
+export declare function debugReasoningStream(event: Record<string, unknown>): void;

package/dist/reasoning-debug.js

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+const DEBUG_PATH = process.env.BUBBLE_DEBUG_REASONING_STREAM?.trim();
+const INCLUDE_PREVIEW = process.env.BUBBLE_DEBUG_REASONING_PREVIEW !== "0";
+const PREVIEW_CHARS = 180;
+let sequence = 0;
+export function summarizeDebugText(value) {
+    if (!DEBUG_PATH)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0)
+        return undefined;
+    const hash = createHash("sha256").update(value).digest("hex").slice(0, 16);
+    const summary = { length: value.length, hash };
+    if (INCLUDE_PREVIEW) {
+        summary.preview = value.replace(/\s+/g, " ").slice(0, PREVIEW_CHARS);
+    }
+    return summary;
+}
+export function debugReasoningStream(event) {
+    if (!DEBUG_PATH)
+        return;
+    try {
+        mkdirSync(dirname(DEBUG_PATH), { recursive: true });
+        appendFileSync(DEBUG_PATH, JSON.stringify({ t: Date.now(), seq: ++sequence, ...event }) + "\n", "utf-8");
+    }
+    catch {
+        // Debug logging must never affect an agent run.
+    }
+}

package/dist/session-log.js

@@ -72,6 +72,9 @@ export class SessionLog {
     getTodos() {
         for (let i = this.entries.length - 1; i >= 0; i--) {
             const entry = this.entries[i];
+            if (entry.type === "marker" && entry.kind === "conversation_clear") {
+                return [];
+            }
             if (entry.type === "todos_snapshot") {
                 return entry.todos.map((todo) => ({ ...todo }));
             }
@@ -92,20 +95,28 @@ export class SessionLog {
     toMessages() {
         const messages = [];
         let latestSummaryIndex = -1;
+        let latestClearIndex = -1;
         for (let index = this.entries.length - 1; index >= 0; index--) {
             if (this.entries[index].type === "summary") {
                 latestSummaryIndex = index;
                 break;
             }
         }
-        if (latestSummaryIndex >= 0) {
+        for (let index = this.entries.length - 1; index >= 0; index--) {
+            const entry = this.entries[index];
+            if (entry.type === "marker" && entry.kind === "conversation_clear") {
+                latestClearIndex = index;
+                break;
+            }
+        }
+        if (latestSummaryIndex > latestClearIndex) {
             const summary = this.entries[latestSummaryIndex];
             messages.push({
                 role: "system",
                 content: `Previous conversation summary: ${summary.summary}`,
             });
         }
-        const startIndex = latestSummaryIndex >= 0 ? latestSummaryIndex + 1 : 0;
+        const startIndex = Math.max(latestSummaryIndex > latestClearIndex ? latestSummaryIndex + 1 : 0, latestClearIndex + 1);
         for (let index = startIndex; index < this.entries.length; index++) {
             const entry = this.entries[index];
             switch (entry.type) {

package/dist/session-types.d.ts

@@ -5,7 +5,7 @@ export interface SessionMetadata {
     reasoningEffort?: ThinkingLevel;
     cwd?: string;
 }
-export type SessionMarkerKind = "model_switch" | "provider_switch" | "thinking_level_switch" | "skill_activated" | "mode_switch";
+export type SessionMarkerKind = "model_switch" | "provider_switch" | "thinking_level_switch" | "skill_activated" | "mode_switch" | "conversation_clear";
 interface BaseSessionLogEntry {
     id: string;
     timestamp: number;

package/dist/slash-commands/commands.js

@@ -1,4 +1,5 @@
 import { UserConfig, maskKey } from "../config.js";
+import { formatContextUsage } from "../context/usage.js";
 import { formatDiagnostics } from "../lsp/index.js";
 import { normalizeNameForMCP } from "../mcp/name.js";
 import { parseRule } from "../permissions/rule.js";
@@ -70,6 +71,29 @@ function syncSystemPrompt(ctx, model) {
         memoryPrompt: buildMemoryPrompt(ctx.cwd),
     }));
 }
+function formatMcpContextStatus(ctx) {
+    const states = ctx.mcpManager?.getStates() ?? [];
+    const lines = ["MCP"];
+    if (!ctx.mcpManager || states.length === 0) {
+        lines.push("- No MCP servers configured for this session.");
+        lines.push("- Context impact: none.");
+        return lines.join("\n");
+    }
+    for (const state of states) {
+        if (state.status.kind === "connected") {
+            lines.push(`- ${state.name} (${state.scope}): connected · ${state.status.tools.length} deferred tool${state.status.tools.length === 1 ? "" : "s"} · ${state.status.prompts.length} prompt${state.status.prompts.length === 1 ? "" : "s"}`);
+            continue;
+        }
+        if (state.status.kind === "failed") {
+            lines.push(`- ${state.name} (${state.scope}): failed · ${state.status.error}`);
+            continue;
+        }
+        lines.push(`- ${state.name} (${state.scope}): ${state.status.kind}`);
+    }
+    lines.push("- Context impact: MCP tool schemas are deferred. The prompt pays only a small deferred-tool reminder until tool_search unlocks a tool; unlocked MCP schemas then count under Tools.");
+    lines.push("- MCP prompts are slash commands; they do not enter context until invoked.");
+    return lines.join("\n");
+}
 function switchToProviderModel(providerId, modelId, ctx, thinkingLevel) {
     const provider = ctx.registry.getConfigured().find((item) => item.id === providerId);
     if (!provider?.apiKey) {
@@ -270,37 +294,30 @@ const builtinSlashCommandEntries = [
             return handleMemoryCommand(args, ctx);
         },
     },
+    {
+        name: "context",
+        description: "Show current context window usage and breakdown",
+        async handler(args, ctx) {
+            return `${formatContextUsage(ctx.agent.getContextUsageSnapshot())}\n\n${formatMcpContextStatus(ctx)}`;
+        },
+    },
     {
         name: "quit",
         description: "Exit the application",
         async handler(args, ctx) {
-            // Shut MCP stdio children down first; their stdout/stderr listeners
-            // otherwise hold the Node event loop open even after ink unmounts.
-            try {
-                await ctx.mcpManager?.shutdown();
-            }
-            catch {
-                // ignore — we're quitting anyway
-            }
-            try {
-                await ctx.flushMemory?.();
-            }
-            catch {
-                // memory shutdown hooks are best-effort during exit
-            }
             ctx.exit();
-            // Belt-and-braces: if anything else (raw-mode tty handle, pending
-            // timer, etc.) still holds the loop, force-exit shortly after.
-            setTimeout(() => process.exit(0), 100).unref();
         },
     },
     {
         name: "clear",
         description: "Clear the current conversation history",
         async handler(args, ctx) {
+            ctx.agent.messages = ctx.agent.messages.filter((m) => m.role === "system" || m.role === "meta");
+            ctx.sessionManager?.appendMarker("conversation_clear", "");
+            if (ctx.agent.getTodos().length > 0) {
+                ctx.agent.setTodos([]);
+            }
             ctx.clearMessages();
-            ctx.agent.messages = ctx.agent.messages.filter((m) => m.role === "system");
-            return "Conversation cleared.";
         },
     },
     {

package/dist/tools/edit.js

@@ -8,6 +8,7 @@ import { access, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { gateToolAction } from "../approval/tool-helper.js";
+import { countUnifiedDiffChanges } from "../diff-stats.js";
 import { formatDiagnosticBlocks } from "../lsp/index.js";
 import { applyEditsToContent, EditApplyError, formatEditMatchNotes } from "./edit-apply.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
@@ -70,6 +71,7 @@ export function createEditTool(cwd, approval, lsp, fileState) {
                     throw err;
                 }
                 const diff = createTwoFilesPatch(filePath, filePath, original, applied.content, "original", "modified", { context: 3 });
+                const diffStats = countUnifiedDiffChanges(diff);
                 // Gate on the approval controller BEFORE persisting the change.
                 const gate = await gateToolAction(approval, {
                     type: "edit",
@@ -111,6 +113,9 @@ export function createEditTool(cwd, approval, lsp, fileState) {
                     metadata: {
                         kind: "edit",
                         path: filePath,
+                        diff,
+                        addedLines: diffStats.added,
+                        removedLines: diffStats.removed,
                     },
                 };
             });

package/dist/tools/file-state.d.ts

@@ -13,10 +13,29 @@ export type FileFreshnessResult = {
     observed?: FileVersion;
     current?: FileVersion;
 };
+export interface ReadHistoryEntry {
+    argOffset: number | undefined;
+    argLimit: number | undefined;
+    effectiveOffset: number;
+    effectiveLimit: number;
+    returnedLines: number;
+    totalLines: number;
+    mtimeMs: number;
+    truncated: boolean;
+}
 export declare class FileStateTracker {
     private readonly cwd;
     private readonly observed;
+    private readonly readHistory;
     constructor(cwd: string);
+    getReadHistory(filePath: string): ReadHistoryEntry | undefined;
+    setReadHistory(filePath: string, entry: ReadHistoryEntry): void;
+    /**
+     * Drops all read-dedup state. Call this whenever conversation history is
+     * compacted or pruned, because the dedup stub points the model back at
+     * earlier tool_result content that may no longer be resident.
+     */
+    invalidateReadHistory(): void;
     observe(filePath: string, source: FileObservationSource, content?: string): Promise<FileVersion>;
     checkFresh(filePath: string): Promise<FileFreshnessResult>;
     private resolvePath;

package/dist/tools/file-state.js

@@ -4,9 +4,24 @@ import { isAbsolute, relative, resolve } from "node:path";
 export class FileStateTracker {
     cwd;
     observed = new Map();
+    readHistory = new Map();
     constructor(cwd) {
         this.cwd = cwd;
     }
+    getReadHistory(filePath) {
+        return this.readHistory.get(this.resolvePath(filePath));
+    }
+    setReadHistory(filePath, entry) {
+        this.readHistory.set(this.resolvePath(filePath), entry);
+    }
+    /**
+     * Drops all read-dedup state. Call this whenever conversation history is
+     * compacted or pruned, because the dedup stub points the model back at
+     * earlier tool_result content that may no longer be resident.
+     */
+    invalidateReadHistory() {
+        this.readHistory.clear();
+    }
     async observe(filePath, source, content) {
         const absolute = this.resolvePath(filePath);
         const version = await this.computeVersion(absolute, content);

package/dist/tools/read.d.ts

@@ -1,5 +1,5 @@
 /**
- * Read tool - read file contents with truncation.
+ * Read tool - read file contents with truncation, dedup, and auto-pagination.
  */
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";

package/dist/tools/read.js

@@ -1,18 +1,28 @@
 /**
- * Read tool - read file contents with truncation.
+ * Read tool - read file contents with truncation, dedup, and auto-pagination.
  */
 import { constants } from "node:fs";
-import { access, readFile } from "node:fs/promises";
+import { access, readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { isSensitivePath } from "./sensitive-paths.js";
-const MAX_LINES = 250;
-const MAX_BYTES = 100 * 1024;
+const MAX_LINES = 2500;
+const MAX_BYTES = 256 * 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) {
+    const localHistory = new Map();
+    const getHistory = (path) => fileState?.getReadHistory(path) ?? localHistory.get(path);
+    const setHistory = (path, entry) => {
+        if (fileState)
+            fileState.setReadHistory(path, entry);
+        else
+            localHistory.set(path, entry);
+    };
     return {
         name: "read",
         readOnly: true,
         effect: "read",
-        description: `Read the contents of a file. Output is truncated to ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files.`,
+        description: `Read the contents of a file. Output is truncated to ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB (whichever is hit first). For large files: either pass explicit offset/limit to target a range, or simply call read again — the tool auto-advances to the next page when the previous read was truncated and the file is unchanged.`,
         parameters: {
             type: "object",
             properties: {
@@ -51,11 +61,62 @@ export function createReadTool(cwd, approval, lsp, fileState) {
             catch {
                 return { content: `Error: Cannot read file: ${filePath}`, isError: true };
             }
-            let content = await readFile(filePath, "utf-8");
+            const argOffset = typeof args.offset === "number" ? args.offset : undefined;
+            const argLimit = typeof args.limit === "number" ? args.limit : undefined;
+            let currentMtimeMs;
+            try {
+                currentMtimeMs = (await stat(filePath)).mtimeMs;
+            }
+            catch {
+                currentMtimeMs = undefined;
+            }
+            const prior = getHistory(filePath);
+            const sameArgs = prior !== undefined
+                && prior.argOffset === argOffset
+                && prior.argLimit === argLimit;
+            const mtimeUnchanged = prior !== undefined
+                && currentMtimeMs !== undefined
+                && Math.floor(prior.mtimeMs) === Math.floor(currentMtimeMs);
+            let effectiveOffset = argOffset !== undefined ? Math.max(0, argOffset - 1) : 0;
+            let autoAdvanceNote;
+            if (prior && sameArgs && mtimeUnchanged) {
+                if (prior.truncated && argOffset === undefined) {
+                    const nextStart = prior.effectiveOffset + prior.returnedLines;
+                    if (nextStart >= prior.totalLines) {
+                        return {
+                            content: END_OF_FILE_STUB(prior.totalLines),
+                            status: "success",
+                            metadata: { kind: "read", path: filePath, dedup: "end_of_file" },
+                        };
+                    }
+                    effectiveOffset = nextStart;
+                    autoAdvanceNote =
+                        `[Auto-advanced from previous truncated read of ${filePath}. ` +
+                            `Showing lines ${effectiveOffset + 1}+ (file has ${prior.totalLines} lines). ` +
+                            `Pass an explicit offset/limit to override this auto-paging.]`;
+                }
+                else if (argOffset === undefined
+                    && prior.effectiveOffset > 0
+                    && !prior.truncated) {
+                    return {
+                        content: END_OF_FILE_STUB(prior.totalLines),
+                        status: "success",
+                        metadata: { kind: "read", path: filePath, dedup: "end_of_file" },
+                    };
+                }
+                else {
+                    return {
+                        content: FILE_UNCHANGED_STUB,
+                        status: "success",
+                        metadata: { kind: "read", path: filePath, dedup: "unchanged" },
+                    };
+                }
+            }
+            const content = await readFile(filePath, "utf-8");
             const lines = content.split("\n");
-            const offset = typeof args.offset === "number" ? Math.max(0, args.offset - 1) : 0;
-            const limit = typeof args.limit === "number" ? args.limit : lines.length;
-            let sliced = lines.slice(offset, offset + limit);
+            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);
@@ -67,10 +128,28 @@ export function createReadTool(cwd, approval, lsp, fileState) {
                 result = Buffer.from(result, "utf-8").subarray(0, MAX_BYTES).toString("utf-8");
                 truncated = true;
             }
+            if (autoAdvanceNote) {
+                result = `${autoAdvanceNote}\n${result}`;
+            }
             if (truncated) {
-                result += `\n[Output truncated: exceeded ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB limit]`;
+                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.]`;
+            }
+            if (currentMtimeMs !== undefined) {
+                setHistory(filePath, {
+                    argOffset,
+                    argLimit,
+                    effectiveOffset,
+                    effectiveLimit,
+                    returnedLines: sliced.length,
+                    totalLines,
+                    mtimeMs: currentMtimeMs,
+                    truncated,
+                });
             }
-            const isFullRead = offset === 0 && !truncated && offset + limit >= lines.length;
+            const isFullRead = effectiveOffset === 0
+                && !truncated
+                && effectiveOffset + effectiveLimit >= totalLines;
             if (isFullRead) {
                 await fileState?.observe(filePath, "read", content).catch(() => undefined);
             }
@@ -81,6 +160,8 @@ export function createReadTool(cwd, approval, lsp, fileState) {
                 metadata: {
                     kind: "read",
                     path: filePath,
+                    ...(autoAdvanceNote ? { autoAdvanced: true } : {}),
+                    ...(truncated ? { truncated: true } : {}),
                 },
             };
         },

package/dist/tui/escape-confirmation.d.ts

@@ -0,0 +1,15 @@
+export type EscapeConfirmationDecision = {
+    action: "arm";
+    expiresAt: number;
+} | {
+    action: "confirm";
+};
+export declare class EscapeConfirmationGate {
+    private readonly windowMs;
+    private armedRunId;
+    private deadline;
+    constructor(windowMs: number);
+    press(runId: number, now?: number): EscapeConfirmationDecision;
+    isArmed(runId: number, now?: number): boolean;
+    clear(): void;
+}