@bubblebrain-ai/bubble 0.0.7 → 0.0.9

package/dist/tools/agent-lifecycle.js

@@ -1,4 +1,5 @@
 import { discoverAgentProfiles, findAgentProfile } from "../agent/profiles.js";
+import { formatSubagentRoute } from "../agent/subagent-route-format.js";
 export function createSpawnAgentTool() {
     return {
         name: "spawn_agent",
@@ -16,6 +17,7 @@ export function createSpawnAgentTool() {
             properties: {
                 agent_type: { type: "string", description: "Subagent profile or role name. Defaults to default." },
                 agent: { type: "string", description: "Alias for agent_type." },
+                category: { type: "string", description: "Optional semantic category for model/thinking routing, such as quick, deep, explore, review, frontend, or writing." },
                 message: { type: "string", description: "Initial task for the subagent." },
                 task: { type: "string", description: "Alias for message." },
                 fork_context: { type: "boolean", description: "When true, copy recent parent conversation into the child thread." },
@@ -55,15 +57,18 @@ export function createSpawnAgentTool() {
                 const snapshot = await ctx.agent.spawnSubAgent(message, ctx.cwd, {
                     profile: resolved.profile,
                     parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
+                    category: stringArg(args.category),
                     approval: parseApproval(args.approval),
                     abortSignal: ctx.abortSignal,
                     forkContext: args.fork_context === true,
                 });
                 return formatLifecycleResult("spawn_agent", [snapshot], [
-                    `Spawned ${snapshot.nickname} (${snapshot.agentName})`,
+                    `Spawned ${snapshot.nickname} (${formatSnapshotRole(snapshot)})`,
                     `agent_id: ${snapshot.agentId}`,
                     `status: ${snapshot.status}`,
-                    `next: call wait_agent for ${snapshot.agentId} to collect the delegated result`,
+                    ...formatRouteLines(snapshot),
+                    `next: call wait_agent for ${snapshot.agentId} before reporting this subagent's current status or final result`,
+                    "counting: this spawn result creates one unique subagent; later wait_agent results for the same agent_id are updates, not additional subagents",
                 ]);
             }
             catch (error) {
@@ -278,13 +283,17 @@ function isFinalSnapshotStatus(status) {
         || status === "closed";
 }
 function formatSnapshot(snapshot) {
-    const label = `${snapshot.nickname} (${snapshot.agentName})`;
+    const label = `${snapshot.nickname} (${formatSnapshotRole(snapshot)})`;
     const lines = [
         `## ${label}`,
         `agent_id: ${snapshot.agentId}`,
         `status: ${snapshot.status}`,
-        `task: ${snapshot.task}`,
     ];
+    if (snapshot.category) {
+        lines.push(`category: ${snapshot.category}`);
+    }
+    lines.push(...formatRouteLines(snapshot));
+    lines.push(`task: ${snapshot.task}`);
     if (snapshot.summary) {
         lines.push("", "Summary:", snapshot.summary);
     }
@@ -299,6 +308,13 @@ function formatSnapshot(snapshot) {
     }
     return lines;
 }
+function formatSnapshotRole(snapshot) {
+    return [snapshot.agentName, snapshot.category ? `/${snapshot.category}` : ""].join("") || "default";
+}
+function formatRouteLines(snapshot) {
+    const route = formatSubagentRoute(snapshot.route, { includeThinking: true });
+    return route ? [`route: ${route}`] : [];
+}
 function snapshotToMetadata(snapshot) {
     return {
         subAgentId: snapshot.agentId,
@@ -306,6 +322,8 @@ function snapshotToMetadata(snapshot) {
         nickname: snapshot.nickname,
         status: snapshot.status === "closed" ? "cancelled" : snapshot.status,
         profileSource: snapshot.profileSource,
+        category: snapshot.category,
+        route: snapshot.route,
         task: snapshot.task,
         summary: snapshot.summary,
         toolNotes: snapshot.toolNotes,

package/dist/tools/edit.js

@@ -5,13 +5,14 @@
  */
 import { constants } from "node:fs";
 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";
 import { isWithinWorkspace } from "./file-state.js";
+import { resolveToolPath } from "./path-utils.js";
 export function createEditTool(cwd, approval, lsp, fileState) {
     return {
         name: "edit",
@@ -38,7 +39,7 @@ export function createEditTool(cwd, approval, lsp, fileState) {
             required: ["path", "edits"],
         },
         async execute(args) {
-            const filePath = resolve(cwd, args.path);
+            const filePath = resolveToolPath(cwd, args.path);
             if (!isWithinWorkspace(cwd, filePath)) {
                 return {
                     content: `Error: Edit path is outside the workspace: ${filePath}`,
@@ -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/glob.js

@@ -5,6 +5,7 @@ import { readdir, stat } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import picomatch from "picomatch";
 import { isSensitivePath } from "./sensitive-paths.js";
+import { resolveToolPath } from "./path-utils.js";
 const MAX_RESULTS = 100;
 const DEFAULT_IGNORES = new Set([
     ".git",
@@ -31,7 +32,7 @@ export function createGlobTool(cwd) {
             required: ["pattern"],
         },
         async execute(args, ctx) {
-            const root = resolve(cwd, typeof args.path === "string" && args.path.trim() ? args.path : ".");
+            const root = resolveToolPath(cwd, typeof args.path === "string" && args.path.trim() ? args.path : ".");
             const pattern = String(args.pattern || "").trim();
             if (!pattern) {
                 return { content: "Error: glob pattern is required", isError: true, status: "command_error" };

package/dist/tools/grep.js

@@ -2,9 +2,9 @@
  * Grep tool - search file contents using ripgrep.
  */
 import { execFile } from "node:child_process";
-import { resolve } from "node:path";
 import { isSensitivePath } from "./sensitive-paths.js";
 import { analyzeToolIntent } from "../agent/tool-intent.js";
+import { resolveToolPath } from "./path-utils.js";
 const MAX_MATCHES = 100;
 export function createGrepTool(cwd) {
     return {
@@ -22,7 +22,7 @@ export function createGrepTool(cwd) {
             required: ["pattern"],
         },
         async execute(args) {
-            const searchPath = args.path ? resolve(cwd, args.path) : cwd;
+            const searchPath = args.path ? resolveToolPath(cwd, args.path) : cwd;
             const pattern = String(args.pattern);
             const intent = analyzeToolIntent({
                 name: "grep",

package/dist/tools/lsp.js

@@ -1,8 +1,8 @@
 import { access } from "node:fs/promises";
 import { constants } from "node:fs";
-import { resolve } from "node:path";
 import { gateToolAction } from "../approval/tool-helper.js";
 import { getLspService } from "../lsp/index.js";
+import { resolveToolPath } from "./path-utils.js";
 const OPERATIONS = [
     "goToDefinition",
     "findReferences",
@@ -37,7 +37,7 @@ export function createLspTool(cwd, lsp = getLspService(cwd), approval) {
             if (!OPERATIONS.includes(operation)) {
                 return { content: `Error: Unsupported LSP operation: ${args.operation}`, isError: true };
             }
-            const file = resolve(cwd, String(args.filePath));
+            const file = resolveToolPath(cwd, args.filePath);
             try {
                 await access(file, constants.R_OK);
             }

package/dist/tools/path-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function expandHomePath(value: unknown): string;
+export declare function resolveToolPath(cwd: string, value: unknown, fallback?: string): string;

package/dist/tools/path-utils.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function expandHomePath(value) {
+    const text = String(value ?? "");
+    if (text === "~")
+        return homedir();
+    if (text.startsWith("~/") || text.startsWith("~\\")) {
+        return join(homedir(), text.slice(2));
+    }
+    return text;
+}
+export function resolveToolPath(cwd, value, fallback = ".") {
+    const text = String(value ?? "");
+    const path = text === "" ? fallback : text;
+    return resolve(cwd, expandHomePath(path));
+}

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,29 @@
 /**
- * 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 { resolve } from "node:path";
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, relative } from "node:path";
 import { isSensitivePath } from "./sensitive-paths.js";
-const MAX_LINES = 250;
-const MAX_BYTES = 100 * 1024;
+import { resolveToolPath } from "./path-utils.js";
+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: {
@@ -23,7 +34,7 @@ export function createReadTool(cwd, approval, lsp, fileState) {
             required: ["path"],
         },
         async execute(args) {
-            const filePath = resolve(cwd, args.path);
+            const filePath = resolveToolPath(cwd, args.path);
             if (isSensitivePath(filePath)) {
                 return {
                     content: `Error: Access to sensitive credential storage is blocked: ${filePath}`,
@@ -48,14 +59,68 @@ export function createReadTool(cwd, approval, lsp, fileState) {
             try {
                 await access(filePath, constants.R_OK);
             }
+            catch (error) {
+                return {
+                    content: await readFileNotFoundMessage(filePath, cwd, error),
+                    isError: true,
+                };
+            }
+            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 {
-                return { content: `Error: Cannot read file: ${filePath}`, isError: true };
+                currentMtimeMs = undefined;
             }
-            let content = await readFile(filePath, "utf-8");
+            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 +132,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,8 +164,118 @@ export function createReadTool(cwd, approval, lsp, fileState) {
                 metadata: {
                     kind: "read",
                     path: filePath,
+                    ...(autoAdvanceNote ? { autoAdvanced: true } : {}),
+                    ...(truncated ? { truncated: true } : {}),
                 },
             };
         },
     };
 }
+async function readFileNotFoundMessage(filePath, cwd, error) {
+    const message = [`Error: Cannot read file: ${filePath}`];
+    const code = typeof error?.code === "string" ? error.code : undefined;
+    if (code && code !== "ENOENT" && code !== "ENOTDIR")
+        return message[0];
+    const suggestions = await suggestReadPaths(filePath, cwd);
+    if (suggestions.length === 1) {
+        message.push(`Did you mean ${suggestions[0]}?`);
+    }
+    else if (suggestions.length > 1) {
+        message.push("Did you mean one of these?");
+        message.push(...suggestions.map((suggestion) => `- ${suggestion}`));
+    }
+    return message.join("\n");
+}
+async function suggestReadPaths(filePath, cwd) {
+    const suggestions = new Set();
+    const underCwd = await suggestPathUnderCwd(filePath, cwd);
+    if (underCwd)
+        suggestions.add(underCwd);
+    for (const suggestion of await suggestSimilarFiles(filePath)) {
+        suggestions.add(suggestion);
+    }
+    return [...suggestions].slice(0, 5);
+}
+async function suggestPathUnderCwd(filePath, cwd) {
+    const parent = dirname(cwd);
+    const parentPrefix = parent.endsWith("/") ? parent : `${parent}/`;
+    if (!filePath.startsWith(parentPrefix) || filePath === cwd || filePath.startsWith(`${cwd}/`)) {
+        return undefined;
+    }
+    const candidate = join(cwd, relative(parent, filePath));
+    try {
+        const stats = await stat(candidate);
+        return stats.isFile() ? candidate : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function suggestSimilarFiles(filePath) {
+    const dir = dirname(filePath);
+    const target = basename(filePath);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isFile() || entry.isSymbolicLink())
+        .map((entry) => {
+        const score = similarFileScore(target, entry.name);
+        return score === undefined ? undefined : { path: join(dir, entry.name), score };
+    })
+        .filter((entry) => entry !== undefined)
+        .sort((a, b) => a.score - b.score || a.path.length - b.path.length || a.path.localeCompare(b.path))
+        .map((entry) => entry.path)
+        .slice(0, 5);
+}
+function similarFileScore(target, candidate) {
+    if (candidate === target)
+        return undefined;
+    const targetExt = extname(target).toLowerCase();
+    const candidateExt = extname(candidate).toLowerCase();
+    const targetStem = basename(target, targetExt).toLowerCase();
+    const candidateStem = basename(candidate, candidateExt).toLowerCase();
+    if (!targetStem || !candidateStem)
+        return undefined;
+    if (candidateExt === targetExt &&
+        (candidateStem.startsWith(`${targetStem}_`) || candidateStem.startsWith(`${targetStem}-`))) {
+        return 0;
+    }
+    if (candidateExt === targetExt && (candidateStem.startsWith(targetStem) || targetStem.startsWith(candidateStem))) {
+        return 5;
+    }
+    if (candidateStem === targetStem) {
+        return 10;
+    }
+    if (candidateStem.includes(targetStem) || targetStem.includes(candidateStem)) {
+        return candidateExt === targetExt ? 15 : 20;
+    }
+    const distance = levenshteinDistance(targetStem, candidateStem, 3);
+    if (distance <= 2) {
+        return (candidateExt === targetExt ? 30 : 35) + distance;
+    }
+    return undefined;
+}
+function levenshteinDistance(a, b, maxDistance) {
+    if (Math.abs(a.length - b.length) > maxDistance)
+        return maxDistance + 1;
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        let rowMin = current[0];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const value = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+            current[j] = value;
+            rowMin = Math.min(rowMin, value);
+        }
+        if (rowMin > maxDistance)
+            return maxDistance + 1;
+        previous = current;
+    }
+    return previous[b.length];
+}

package/dist/tools/write.js

@@ -2,12 +2,13 @@
  * Write tool - create files or safely replace full file contents.
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { gateToolAction } from "../approval/tool-helper.js";
 import { formatDiagnosticBlocks } from "../lsp/index.js";
 import { isWithinWorkspace } from "./file-state.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { resolveToolPath } from "./path-utils.js";
 export function createWriteTool(cwd, options = {}, approval, lsp, fileState) {
     return {
         name: "write",
@@ -27,7 +28,7 @@ export function createWriteTool(cwd, options = {}, approval, lsp, fileState) {
             required: ["path", "content"],
         },
         async execute(args) {
-            const filePath = resolve(cwd, args.path);
+            const filePath = resolveToolPath(cwd, args.path);
             const overwrite = args.overwrite === true;
             if (!isWithinWorkspace(cwd, filePath)) {
                 return {

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;
+}

package/dist/tui/escape-confirmation.js

@@ -0,0 +1,30 @@
+export class EscapeConfirmationGate {
+    windowMs;
+    armedRunId;
+    deadline = 0;
+    constructor(windowMs) {
+        this.windowMs = windowMs;
+    }
+    press(runId, now = Date.now()) {
+        if (this.armedRunId === runId && now <= this.deadline) {
+            this.clear();
+            return { action: "confirm" };
+        }
+        this.armedRunId = runId;
+        this.deadline = now + this.windowMs;
+        return { action: "arm", expiresAt: this.deadline };
+    }
+    isArmed(runId, now = Date.now()) {
+        if (this.armedRunId !== runId)
+            return false;
+        if (now > this.deadline) {
+            this.clear();
+            return false;
+        }
+        return true;
+    }
+    clear() {
+        this.armedRunId = undefined;
+        this.deadline = 0;
+    }
+}