@bubblebrain-ai/bubble 0.0.20 → 0.0.21

package/dist/agent.d.ts

@@ -12,6 +12,7 @@ import { type AgentProfile, type SubagentRunResult } from "./agent/profiles.js";
 import { type SubagentThreadSnapshot } from "./agent/subagent-control.js";
 import type { SkillSummary } from "./skills/types.js";
 import type { FileStateTracker } from "./tools/file-state.js";
+export declare const INTERRUPTED_ASSISTANT_CONTENT = "Interrupted by user. The prior request was stopped and should not be resumed unless the user asks.";
 export declare class AgentAbortError extends Error {
     constructor(message?: string);
 }

package/dist/agent.js

@@ -40,7 +40,11 @@ const EMPTY_ASSISTANT_RECOVERY_REMINDER = "The previous model response contained
     "Respond now with a concise, user-visible answer, or call an available tool if more work is required. " +
     "Do not put the final answer only in hidden reasoning.";
 const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";
-const INTERRUPTED_ASSISTANT_CONTENT = "Interrupted by user. The prior request was stopped and should not be resumed unless the user asks.";
+// Model-facing interruption boundary. Persisted into the transcript so the
+// next turn sees an explicit stop instead of a dangling request — but it must
+// never render in the UI as if the assistant said it (the TUIs strip it and
+// show their own interrupt indicator instead).
+export const INTERRUPTED_ASSISTANT_CONTENT = "Interrupted by user. The prior request was stopped and should not be resumed unless the user asks.";
 function agentEventFromHookProgress(event) {
     const source = `${event.source.scope}:${event.source.index}`;
     if (event.type === "hook_start") {

package/dist/checkpoints.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Checkpoint store - pre-mutation file snapshots, keyed by conversation turn.
+ *
+ * Before the edit/write tools persist a change, they record the file's prior
+ * content here so /rewind can restore the workspace to the state it had just
+ * before a given user message. Changes made by bash commands are NOT tracked;
+ * checkpoints complement git, they do not replace it.
+ *
+ * On-disk layout (sibling of the session JSONL):
+ *   <session>.checkpoints/
+ *     blobs/<sha256>     full file content, content-addressed (deduplicated)
+ *     manifest.jsonl     one {turn, path, blob, timestamp} line per first
+ *                        capture of a file within a turn
+ *
+ * blob === null means the file did not exist before that turn, so rewinding
+ * deletes it.
+ */
+export interface CheckpointManifestEntry {
+    turn: string;
+    path: string;
+    blob: string | null;
+    timestamp: number;
+}
+export interface CheckpointRestoreResult {
+    /** Files whose pre-turn content was written back. */
+    restored: string[];
+    /** Files deleted because they were created during the rewound turns. */
+    deleted: string[];
+    /** Files that could not be restored (I/O errors). */
+    failed: string[];
+}
+export declare class CheckpointStore {
+    private readonly dir;
+    private readonly currentTurn;
+    private seen?;
+    constructor(dir: string, currentTurn: () => string);
+    /**
+     * Record a file's content before it is mutated. `priorContent` is the
+     * current on-disk content, or null when the file does not exist yet.
+     * Capturing must never break the mutation itself, so all errors are
+     * swallowed.
+     */
+    captureBefore(filePath: string, priorContent: string | null): Promise<void>;
+    listEntries(): CheckpointManifestEntry[];
+    /** Unique files first captured at or after the given turn. */
+    filesTouchedSince(turn: string): string[];
+    /** Unique files captured during exactly the given turn. */
+    filesTouchedAt(turn: string): string[];
+    /**
+     * Restore every tracked file to its content from just before `turn`.
+     * For each file the earliest capture at-or-after the cutoff wins (it holds
+     * the oldest pre-mutation content). Consumed manifest entries are pruned so
+     * a later rewind over reused turn ids cannot resurrect stale state.
+     */
+    restoreTo(turn: string): Promise<CheckpointRestoreResult>;
+    private loadSeen;
+}

package/dist/feishu/agent-host/run-driver.js

@@ -78,6 +78,7 @@ export class RunDriver {
             approvalController,
             lspService,
             fileStateTracker,
+            checkpoints: () => session.manager.getCheckpoints(),
             // questionController intentionally omitted — Feishu v1 doesn't surface
             // the question tool to the agent.
         });

package/dist/main.js

@@ -30,6 +30,10 @@ import { basename } from "node:path";
 import { normalizeSingleLine, truncateVisual } from "./text-display.js";
 import { BUBBLE_WORDMARK } from "./tui/wordmark.js";
 import { configureDebugTrace, summarizeAgentEventForTrace, summarizeTraceMessage, traceEvent, } from "./debug-trace.js";
+// OpenTUI is the default renderer. The React Ink implementation (alt-screen
+// viewport, src/tui-ink) is feature-complete but still maturing — opt in with
+// BUBBLE_TUI=ink.
+const USE_OPENTUI = process.env.BUBBLE_TUI !== "ink";
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (process.argv.includes("-h") || process.argv.includes("--help")) {
@@ -163,6 +167,8 @@ async function main() {
         toolSearchController,
         lspService,
         fileStateTracker,
+        // Lazy: sessionManager is resolved after tools are created.
+        checkpoints: () => sessionManager?.getCheckpoints(),
     });
     // Bring up MCP servers (if any). Failures are captured per-server and never
     // block the rest of startup; /mcp surfaces status at runtime.
@@ -225,7 +231,9 @@ async function main() {
             else {
                 preResolvedTheme = themeConfig.mode;
             }
-            const { runSessionPicker } = await import("./tui-opentui/run-session-picker.js");
+            const { runSessionPicker } = USE_OPENTUI
+                ? await import("./tui-opentui/run-session-picker.js")
+                : await import("./tui-ink/run-session-picker.js");
             const picked = await runSessionPicker({
                 currentCwd: args.cwd,
                 currentSessions,
@@ -304,7 +312,7 @@ async function main() {
         sessionFile: sessionManager?.getSessionFile(),
         provider: activeProviderId || "none",
         model: activeModel || "none",
-        renderer: printMode ? "print" : "opentui-core",
+        renderer: printMode ? "print" : USE_OPENTUI ? "opentui-core" : "ink",
     });
     if (traceInfo.enabled) {
         traceEvent("run_start", {
@@ -523,19 +531,37 @@ async function main() {
         };
         const { getStartupUpdateNotice } = await import("./update/index.js");
         const updateNotice = await getStartupUpdateNotice();
-        const { runTui } = await import("./tui/run.js");
-        await runTui(agent, args, {
-            ...commonOptions,
-            themeMode: themeConfig.mode,
-            themeOverrides: themeConfig.overrides,
-            detectedTheme,
-            onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
-            updateNotice: updateNotice ?? undefined,
-        });
+        // Two explicit branches (not a dynamic ternary import) so TypeScript
+        // checks each renderer's RunTuiOptions shape independently.
+        let exitWallMs;
+        if (USE_OPENTUI) {
+            const { runTui } = await import("./tui/run.js");
+            await runTui(agent, args, {
+                ...commonOptions,
+                themeMode: themeConfig.mode,
+                themeOverrides: themeConfig.overrides,
+                detectedTheme,
+                onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
+                updateNotice: updateNotice ?? undefined,
+            });
+        }
+        else {
+            const { runTui } = await import("./tui-ink/run.js");
+            const summary = await runTui(agent, args, {
+                ...commonOptions,
+                themeMode: themeConfig.mode,
+                themeOverrides: themeConfig.overrides,
+                detectedTheme,
+                onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
+                updateNotice: updateNotice ?? undefined,
+            });
+            exitWallMs = summary?.wallMs;
+        }
         if (sessionManager) {
-            printOpenTuiExitSummary(sessionManager, {
+            printExitSummary(sessionManager, {
                 resumed: resumedExistingSession,
                 theme: detectedTheme,
+                wallMs: exitWallMs,
             });
         }
     }
@@ -545,7 +571,7 @@ async function main() {
         traceEvent("run_shutdown_end");
     }
 }
-function printOpenTuiExitSummary(sessionManager, options) {
+function printExitSummary(sessionManager, options) {
     if (!process.stdout.isTTY)
         return;
     const sessionName = basename(sessionManager.getSessionFile());
@@ -589,6 +615,21 @@ function printOpenTuiExitSummary(sessionManager, options) {
     console.log();
     console.log(`${label("Session")}${colors.value(sessionLabel)}`);
     console.log(`${label("Continue")}${colors.value(continueCommand)}`);
+    if (options.wallMs !== undefined) {
+        console.log(`${label("Duration")}${colors.value(formatWallDuration(options.wallMs))}`);
+    }
+}
+function formatWallDuration(ms) {
+    const totalSeconds = Math.max(0, Math.round(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes < 60)
+        return `${minutes}m ${seconds}s`;
+    const hours = Math.floor(minutes / 60);
+    const minutesRest = minutes % 60;
+    return `${hours}h ${minutesRest}m ${seconds}s`;
 }
 async function readPipedStdin() {
     if (process.stdin.isTTY)

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 /**
  * Session Manager - Append-only JSONL persistence over a structured session log.
  */
+import { CheckpointStore } from "./checkpoints.js";
 import { type CompactOptions, type CompactResult } from "./context/compact.js";
 import type { Message, Todo } from "./types.js";
 import type { SessionLogEntry, SessionMarkerKind, SessionMetadata } from "./session-types.js";
@@ -16,9 +17,25 @@ export interface SessionSummary {
     mtime: number;
 }
 export type { SessionLogEntry, SessionMarkerKind, SessionMetadata } from "./session-types.js";
+export interface UserTurn {
+    /** Session log entry id of the user message that starts the turn. */
+    id: string;
+    /** Single-line preview of the user message. */
+    preview: string;
+    /** Full text of the user message. */
+    text: string;
+    timestamp: number;
+}
+export interface RewindResult {
+    /** Number of log entries removed. */
+    removedEntries: number;
+    /** Full text of the user message the session was rewound to (for re-editing). */
+    targetText: string;
+}
 export declare class SessionManager {
     private sessionFile;
     private log;
+    private checkpoints?;
     constructor(sessionFile: string);
     static create(cwd: string, sessionName?: string): SessionManager;
     static resume(cwd: string, sessionName?: string): SessionManager | undefined;
@@ -41,6 +58,20 @@ export declare class SessionManager {
     getTodos(): Todo[];
     compact(options?: CompactOptions): CompactResult;
     getMessages(): Message[];
+    /**
+     * Pre-edit file snapshot store for this session, used by /rewind.
+     * Lives next to the session JSONL as `<session>.checkpoints/`.
+     */
+    getCheckpoints(): CheckpointStore;
+    /** Entry id of the most recent user message, or "0" before the first one. */
+    lastUserEntryId(): string;
+    /** User messages after the latest /clear, oldest first — the valid rewind anchors. */
+    listUserTurns(): UserTurn[];
+    /**
+     * Truncate the session to just before the user message with the given
+     * entry id. Returns undefined when the id does not name a user message.
+     */
+    rewindToEntry(entryId: string): RewindResult | undefined;
     getEntries(): SessionLogEntry[];
     getSessionFile(): string;
     private maybeAutoCompact;

package/dist/session.js

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { mkdirSync, appendFileSync, existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { getBubbleHome } from "./bubble-home.js";
+import { CheckpointStore } from "./checkpoints.js";
 import { compactSessionEntries } from "./context/compact.js";
 import { SessionLog } from "./session-log.js";
 import { normalizeSingleLine, truncateVisual } from "./text-display.js";
@@ -14,6 +15,7 @@ const AUTO_COMPACT_KEEP_RECENT_TURNS = 3;
 export class SessionManager {
     sessionFile;
     log = new SessionLog();
+    checkpoints;
     constructor(sessionFile) {
         this.sessionFile = sessionFile;
         if (existsSync(sessionFile)) {
@@ -163,6 +165,73 @@ export class SessionManager {
     getMessages() {
         return this.log.toMessages();
     }
+    /**
+     * Pre-edit file snapshot store for this session, used by /rewind.
+     * Lives next to the session JSONL as `<session>.checkpoints/`.
+     */
+    getCheckpoints() {
+        if (!this.checkpoints) {
+            this.checkpoints = new CheckpointStore(this.sessionFile.replace(/\.jsonl$/, "") + ".checkpoints", () => this.lastUserEntryId());
+        }
+        return this.checkpoints;
+    }
+    /** Entry id of the most recent user message, or "0" before the first one. */
+    lastUserEntryId() {
+        const entries = this.log.list();
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const entry = entries[i];
+            if (entry.type === "user_message")
+                return entry.id;
+        }
+        return "0";
+    }
+    /** User messages after the latest /clear, oldest first — the valid rewind anchors. */
+    listUserTurns() {
+        const entries = this.log.list();
+        let start = 0;
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const entry = entries[i];
+            if (entry.type === "marker" && entry.kind === "conversation_clear") {
+                start = i + 1;
+                break;
+            }
+        }
+        const turns = [];
+        for (let i = start; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.type !== "user_message")
+                continue;
+            const text = messageText(entry.message);
+            turns.push({
+                id: entry.id,
+                text,
+                preview: truncateVisual(normalizeSingleLine(text), 80) || "(empty message)",
+                timestamp: entry.timestamp,
+            });
+        }
+        return turns;
+    }
+    /**
+     * Truncate the session to just before the user message with the given
+     * entry id. Returns undefined when the id does not name a user message.
+     */
+    rewindToEntry(entryId) {
+        const entries = this.log.list();
+        const index = entries.findIndex((entry) => entry.id === entryId && entry.type === "user_message");
+        if (index < 0)
+            return undefined;
+        const target = entries[index];
+        const removed = entries.slice(index);
+        this.rewrite(entries.slice(0, index));
+        const metadata = this.log.getMetadata();
+        if (metadata.titleUserMessageId && removed.some((entry) => entry.id === metadata.titleUserMessageId)) {
+            this.clearTitleMetadata();
+        }
+        return {
+            removedEntries: removed.length,
+            targetText: target.type === "user_message" ? messageText(target.message) : "",
+        };
+    }
     getEntries() {
         return this.log.list();
     }

package/dist/slash-commands/commands.js

@@ -399,6 +399,86 @@ const builtinSlashCommandEntries = [
             ctx.clearMessages();
         },
     },
+    {
+        name: "rewind",
+        description: "Rewind conversation and/or file edits to before an earlier message. Usage: /rewind [n] [--code|--chat]",
+        async handler(args, ctx) {
+            const session = ctx.sessionManager;
+            if (!session) {
+                return "Rewind requires an active session.";
+            }
+            const turns = session.listUserTurns();
+            if (turns.length === 0) {
+                return "Nothing to rewind: no user messages in this session.";
+            }
+            const tokens = args.trim().split(/\s+/).filter(Boolean);
+            const flags = tokens.filter((token) => token.startsWith("--"));
+            const positional = tokens.filter((token) => !token.startsWith("--"));
+            const checkpoints = session.getCheckpoints();
+            if (positional.length === 0) {
+                if (ctx.openRewindPicker) {
+                    ctx.openRewindPicker();
+                    return;
+                }
+                const lines = ["Rewind points (oldest first):", ""];
+                turns.forEach((turn, index) => {
+                    const time = new Date(turn.timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+                    const files = checkpoints.filesTouchedAt(turn.id).length;
+                    const fileNote = files > 0 ? `  [${files} file${files === 1 ? "" : "s"} changed]` : "";
+                    lines.push(`  ${index + 1}. ${time}  ${turn.preview}${fileNote}`);
+                });
+                lines.push("", "Usage:", "  /rewind <n>         restore conversation AND files to just before message n", "  /rewind <n> --chat  conversation only", "  /rewind <n> --code  files only", "", "Note: only edits made by the edit/write tools are tracked; changes from", "bash commands are not. Checkpoints complement git, they don't replace it.");
+                return lines.join("\n");
+            }
+            const n = Number(positional[0]);
+            if (!Number.isInteger(n) || n < 1 || n > turns.length) {
+                return `Invalid rewind point "${positional[0]}". Run /rewind to list points (1-${turns.length}).`;
+            }
+            const target = turns[n - 1];
+            const codeOnly = flags.includes("--code");
+            const chatOnly = flags.includes("--chat") || flags.includes("--conversation");
+            if (codeOnly && chatOnly) {
+                return "Pick at most one of --code / --chat.";
+            }
+            // The "⏪" prefix is recognized by the TUIs: they rebuild the visible
+            // transcript from the rewound agent.messages before showing this text.
+            const lines = [
+                codeOnly
+                    ? `Files restored to just before: ${target.preview}`
+                    : `⏪ Rewound to before: ${target.preview}`,
+            ];
+            if (!chatOnly) {
+                const restore = await checkpoints.restoreTo(target.id);
+                const touched = restore.restored.length + restore.deleted.length;
+                if (touched === 0 && restore.failed.length === 0) {
+                    lines.push("Files: no tracked edits to undo.");
+                }
+                else {
+                    for (const file of restore.restored)
+                        lines.push(`Restored ${file}`);
+                    for (const file of restore.deleted)
+                        lines.push(`Deleted ${file} (created after this point)`);
+                    for (const file of restore.failed)
+                        lines.push(`FAILED to restore ${file}`);
+                }
+            }
+            if (!codeOnly) {
+                session.rewindToEntry(target.id);
+                const head = ctx.agent.messages.filter((m) => m.role === "system" || m.role === "meta");
+                ctx.agent.messages = [...head, ...session.getMessages()];
+                ctx.agent.setTodos(session.getTodos());
+                ctx.agent.resetContextUsageAnchor();
+                if (ctx.fillComposer) {
+                    // Put the rewound message back into the input box for re-editing.
+                    ctx.fillComposer(target.text);
+                }
+                else {
+                    lines.push("", "Rewound message (copy to re-edit):", target.text);
+                }
+            }
+            return lines.join("\n");
+        },
+    },
     {
         name: "session",
         description: "Show current session information",

package/dist/slash-commands/types.d.ts

@@ -48,6 +48,10 @@ export interface SlashCommandContext {
     setSidebarMode?: (mode: SidebarMode) => SidebarCommandState;
     /** Open the feedback dialog. `initialDescription` prefills the description field. */
     openFeedback?: (initialDescription: string) => void;
+    /** Open the interactive rewind picker. When absent, /rewind falls back to a text listing. */
+    openRewindPicker?: () => void;
+    /** Replace the composer/input box content (e.g. /rewind restores the rewound message for re-editing). */
+    fillComposer?: (text: string) => void;
     /** Open the interactive usage stats panel. */
     openStats?: () => void;
 }

package/dist/tools/bash.js

@@ -21,6 +21,10 @@ export function createBashTool(cwd, approval, _fileState) {
             type: "object",
             properties: {
                 command: { type: "string", description: "Bash command to execute" },
+                description: {
+                    type: "string",
+                    description: "One short sentence (5-10 words) describing what this command does, shown to the user in the UI. Write it in the same language the user is conversing in.",
+                },
                 timeout: { type: "number", description: "Timeout in seconds (optional)" },
             },
             required: ["command"],

package/dist/tools/edit.d.ts

@@ -4,6 +4,7 @@
  * This is the safest way to edit files: old_string must exist exactly once.
  */
 import type { ApprovalController } from "../approval/types.js";
+import type { CheckpointStore } from "../checkpoints.js";
 import type { ToolRegistryEntry } from "../types.js";
 import { type LspService } from "../lsp/index.js";
 import { type FileStateTracker } from "./file-state.js";
@@ -14,4 +15,4 @@ export interface EditArgs {
         newText: string;
     }>;
 }
-export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;
+export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker, checkpoints?: () => CheckpointStore | undefined): ToolRegistryEntry;

package/dist/tools/edit.js

@@ -60,7 +60,7 @@ function firstString(...values) {
     }
     return undefined;
 }
-export function createEditTool(cwd, approval, lsp, fileState) {
+export function createEditTool(cwd, approval, lsp, fileState, checkpoints) {
     return {
         name: "edit",
         effect: "write_direct",
@@ -178,6 +178,7 @@ export function createEditTool(cwd, approval, lsp, fileState) {
                         },
                     };
                 }
+                await checkpoints?.()?.captureBefore(filePath, original);
                 await writeFile(filePath, applied.content, "utf-8");
                 await fileState?.observe(filePath, "edit", applied.content).catch(() => undefined);
                 let output = `Edited ${filePath}${formatEditMatchNotes(applied.matches)}\n\nDiff:\n${diff}`;

package/dist/tools/index.d.ts

@@ -28,6 +28,7 @@ import { type LspService } from "../lsp/index.js";
 import { type TodoStore } from "./todo.js";
 import { type ToolSearchController } from "./tool-search.js";
 import type { QuestionController } from "../question/index.js";
+import type { CheckpointStore } from "../checkpoints.js";
 import { FileStateTracker } from "./file-state.js";
 export interface CreateAllToolsOptions {
     todoStore?: TodoStore;
@@ -37,5 +38,11 @@ export interface CreateAllToolsOptions {
     toolSearchController?: ToolSearchController;
     lspService?: LspService;
     fileStateTracker?: FileStateTracker;
+    /**
+     * Lazy accessor for the session's checkpoint store (the session manager may
+     * not exist yet when tools are created). Used by edit/write to snapshot
+     * files before mutating them so /rewind can restore.
+     */
+    checkpoints?: () => CheckpointStore | undefined;
 }
 export declare function createAllTools(cwd: string, skillRegistry?: SkillRegistry, options?: CreateAllToolsOptions): ToolRegistryEntry[];

package/dist/tools/index.js

@@ -48,8 +48,8 @@ export function createAllTools(cwd, skillRegistry, options = {}) {
         createReadTool(cwd, approval, lsp, fileState),
         createBashTool(cwd, approval, fileState),
         ...createManagedServerTools(cwd, approval),
-        createWriteTool(cwd, {}, approval, lsp, fileState),
-        createEditTool(cwd, approval, lsp, fileState),
+        createWriteTool(cwd, {}, approval, lsp, fileState, options.checkpoints),
+        createEditTool(cwd, approval, lsp, fileState, options.checkpoints),
         createGlobTool(cwd),
         createGrepTool(cwd),
         createLspTool(cwd, lsp, approval),

package/dist/tools/write.d.ts

@@ -2,8 +2,9 @@
  * Write tool - create files or replace full file contents.
  */
 import type { ApprovalController } from "../approval/types.js";
+import type { CheckpointStore } from "../checkpoints.js";
 import type { ToolRegistryEntry } from "../types.js";
 import { type LspService } from "../lsp/index.js";
 import { type FileStateTracker } from "./file-state.js";
 export type WriteToolOptions = Record<string, never>;
-export declare function createWriteTool(cwd: string, _options?: WriteToolOptions, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;
+export declare function createWriteTool(cwd: string, _options?: WriteToolOptions, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker, checkpoints?: () => CheckpointStore | undefined): ToolRegistryEntry;

package/dist/tools/write.js

@@ -18,7 +18,7 @@ function prepareWriteArguments(input) {
     }
     return args;
 }
-export function createWriteTool(cwd, _options = {}, approval, lsp, fileState) {
+export function createWriteTool(cwd, _options = {}, approval, lsp, fileState, checkpoints) {
     return {
         name: "write",
         effect: "write_direct",
@@ -76,6 +76,7 @@ export function createWriteTool(cwd, _options = {}, approval, lsp, fileState) {
                     return changedDuringApprovalResult(filePath, changed);
                 }
                 try {
+                    await checkpoints?.()?.captureBefore(filePath, existed ? oldContent : null);
                     await mkdir(dirname(filePath), { recursive: true });
                     await writeFile(filePath, args.content, "utf-8");
                     await fileState?.observe(filePath, "write", args.content).catch(() => undefined);

package/dist/tui/image-paste.d.ts

@@ -44,6 +44,12 @@ export declare function isImageFilePath(raw: string): boolean;
 export declare function extractImagePathTokens(input: string): ImagePathToken[];
 export declare function removeImagePathTokens(input: string, tokens: ImagePathToken[]): string;
 export declare function imageAttachmentLabel(att: ImageAttachment, index: number): string;
+/**
+ * Label for an image path before ingestion runs. Matches what
+ * imageAttachmentLabel produces for the same file, so a label inserted at
+ * paste time stays a valid key once the attachment is registered.
+ */
+export declare function imageLabelForPath(rawPath: string, index: number): string;
 export declare function imageAttachmentReference(att: ImageAttachment, index: number): string;
 export declare function imageAttachmentLabelPattern(): RegExp;
 export declare function buildImageContentParts(promptText: string, attachments: ImageAttachment[]): ContentPart[];
@@ -61,6 +67,18 @@ export declare function buildImageContentPartsFromLabels(input: string, attachme
  * only on a space that is followed by the start of a new absolute path.
  */
 export declare function splitPastedPaths(pasted: string): string[];
+/**
+ * True when a pasted blob consists solely of image file paths (drag from
+ * Finder, or a terminal that converts clipboard images to temp-file paths).
+ */
+export declare function isImagePathPaste(pasted: string): boolean;
+/**
+ * Bare image filename with no directory, e.g. "Screenshot ... AM.png".
+ * Copying an image file in Finder puts only the file's NAME in the
+ * clipboard's plain-text flavor — the actual bits arrive as a file-url or
+ * image flavor that must be read from the clipboard separately.
+ */
+export declare function bareImageFilenameFromPaste(pasted: string): string | null;
 export declare function readImageFromPath(rawPath: string): Promise<ImageAttachment | null>;
 /** macOS screenshot shortcut writes to these paths and they may be auto-cleaned. */
 export declare function isScreenshotTempPath(s: string): boolean;