@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/approval/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Approval flow: tools that want a gating UI construct an ApprovalRequest and
+ * await an ApprovalDecision from the harness (via ApprovalController).
+ *
+ * Mirrors Claude Code's per-tool Permission Request components in that each
+ * request carries tool-typed data so the UI can render a meaningful preview.
+ */
+import type { PermissionCheckResult, PermissionQuery } from "../permissions/types.js";
+export interface EditApprovalRequest {
+    type: "edit";
+    path: string;
+    /** Unified patch (with context lines) to show the user. */
+    diff: string;
+    fileExists: boolean;
+    /**
+     * The path resolves outside the session workspace. Escalates the request
+     * past default-mode auto-approval so the user explicitly confirms it
+     * (bypassPermissions still auto-approves, consistent with bash).
+     */
+    outsideWorkspace?: boolean;
+    /**
+     * Set by the approval controller: the path is a workspace file that can
+     * grant further capabilities (permission settings, git hooks/config), so
+     * it is never auto-approved in default mode. Hosts must not auto-approve it.
+     */
+    protectedPath?: boolean;
+}
+export interface WriteApprovalRequest {
+    type: "write";
+    path: string;
+    /** Full pending file contents. */
+    content: string;
+    /** Unified patch from existing contents to pending contents. */
+    diff?: string;
+    fileExists: boolean;
+    /** See EditApprovalRequest.outsideWorkspace. */
+    outsideWorkspace?: boolean;
+    /** See EditApprovalRequest.protectedPath. */
+    protectedPath?: boolean;
+}
+export interface PatchApprovalRequest {
+    type: "patch";
+    /** Human-readable path summary for compact UIs. */
+    path: string;
+    /** All absolute paths touched by the patch. */
+    paths: string[];
+    files: Array<{
+        path: string;
+        kind: "add" | "update" | "delete";
+    }>;
+    /** Combined unified diff for all file changes. */
+    diff: string;
+    /** See EditApprovalRequest.protectedPath. */
+    protectedPath?: boolean;
+}
+export interface BashApprovalRequest {
+    type: "bash";
+    command: string;
+    cwd: string;
+    /**
+     * The command will run as a background task that outlives the turn
+     * (background-tasks design §2.4). Shown in the approval dialog and passed
+     * to permission hooks so org policy can discriminate; allow rules, the
+     * session allowlist, and bypass approve it like foreground by design.
+     */
+    background?: boolean;
+    /**
+     * Set by the approval controller when this request may be approved for the
+     * rest of the session: the exact scope the grant would cover (a bash
+     * command prefix, an MCP tool name). Absent = hosts offer only "once".
+     */
+    sessionGrant?: string;
+}
+export interface LspApprovalRequest {
+    type: "lsp";
+    path: string;
+    operation: string;
+}
+/**
+ * Trust gate for project-local agent profiles (.bubble/agents). The user —
+ * not the model — decides whether a repository's profile prompt may drive a
+ * subagent; approvals are remembered per content hash for the session.
+ */
+export interface AgentProfileApprovalRequest {
+    type: "agent_profile";
+    /** Profile name as referenced by spawn_agent. */
+    name: string;
+    /** Absolute path of the profile file inside the repository. */
+    path: string;
+    /** Content hash; a changed file re-prompts. */
+    contentHash: string;
+    /** First lines of the profile prompt so the user can judge it. */
+    promptPreview: string;
+}
+/**
+ * Permission gate for a tool Bubble does not implement itself: a tool
+ * exposed by an external ACP runtime (kind = ACP tool category) or an MCP
+ * server tool (kind = "mcp", title = the namespaced mcp__server__tool name).
+ *
+ * Keep this structural rather than importing ACP SDK types so the approval
+ * layer remains provider-agnostic. External runtimes are responsible for
+ * copying the relevant, user-visible fields from the protocol request.
+ */
+export interface ExternalToolApprovalRequest {
+    type: "external_tool";
+    toolCallId: string;
+    /** Human-readable tool name supplied by the external runtime. */
+    title: string;
+    /** ACP tool category (for example execute, edit, read, or other). */
+    kind: string;
+    rawInput?: unknown;
+    locations?: Array<{
+        path: string;
+        line?: number | null;
+    }>;
+    /** See BashApprovalRequest.sessionGrant. */
+    sessionGrant?: string;
+}
+export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest | AgentProfileApprovalRequest | ExternalToolApprovalRequest;
+export type ApprovalDecision = {
+    action: "approve";
+    feedback?: string;
+    /**
+     * "session": also approve future requests covered by the request's
+     * `sessionGrant` for the rest of the session. Ignored when the request
+     * carried no sessionGrant.
+     */
+    remember?: "session";
+} | {
+    action: "reject";
+    feedback?: string;
+};
+export interface ApprovalController {
+    /**
+     * Decide whether a tool call should proceed. May consult the current
+     * permission mode, configured allow/deny rules, session-level allowlists,
+     * and — as a final fallback — a user-interactive UI handler.
+     */
+    request(req: ApprovalRequest): Promise<ApprovalDecision>;
+    /**
+     * Pure rule evaluation (no UI, no mode gates). Tools that silently execute
+     * unless explicitly denied (e.g. Read, WebFetch) call this to honor
+     * user-configured deny rules without changing the UX for the common case.
+     */
+    checkRules(query: PermissionQuery): PermissionCheckResult;
+}

package/dist/approval/types.js

@@ -0,0 +1,8 @@
+/**
+ * Approval flow: tools that want a gating UI construct an ApprovalRequest and
+ * await an ApprovalDecision from the harness (via ApprovalController).
+ *
+ * Mirrors Claude Code's per-tool Permission Request components in that each
+ * request carries tool-typed data so the UI can render a meaningful preview.
+ */
+export {};

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+await import("./main.js");
+export {};

package/dist/bubble-home.d.ts

@@ -0,0 +1,8 @@
+export type BubbleEnvironment = "production" | "dev" | "custom";
+export interface BubbleHomeInfo {
+    home: string;
+    environment: BubbleEnvironment;
+}
+export declare function getBubbleHome(): string;
+export declare function getBubbleHomeInfo(): BubbleHomeInfo;
+export declare function isBubbleDevMode(): boolean;

package/dist/bubble-home.js

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function getBubbleHome() {
+    return getBubbleHomeInfo().home;
+}
+export function getBubbleHomeInfo() {
+    const explicitHome = process.env.BUBBLE_HOME?.trim();
+    if (explicitHome) {
+        return { home: explicitHome, environment: "custom" };
+    }
+    if (isBubbleDevMode()) {
+        return { home: join(homedir(), ".bubble-dev"), environment: "dev" };
+    }
+    return { home: join(homedir(), ".bubble"), environment: "production" };
+}
+export function isBubbleDevMode() {
+    const value = process.env.BUBBLE_DEV?.trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes" || value === "on";
+}

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/cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CLI argument parsing.
+ */
+import { type PermissionMode, type ThinkingLevel } from "./types.js";
+export type CliCommand = "default" | "serve" | "update";
+export interface CliArgs {
+    command: CliCommand;
+    model?: string;
+    cwd: string;
+    apiKey?: string;
+    resume?: boolean;
+    sessionName?: string;
+    print?: boolean;
+    /** Print-mode output: plain (default) or a single JSON object on stdout. */
+    outputFormat?: "plain" | "json" | "stream-json";
+    inputFormat?: "text" | "stream-json";
+    prompt?: string;
+    thinkingLevel?: ThinkingLevel;
+    mode?: PermissionMode;
+    /** `serve` subcommand: which host to run. */
+    serveHost?: "feishu";
+    /** `serve` subcommand: force wizard. */
+    setup?: boolean;
+    /** `serve` subcommand: kill stale instance (non-interactive). */
+    killOld?: boolean;
+    /** `serve` subcommand: connect then exit. */
+    dryRun?: boolean;
+    /** `update` subcommand: only report whether an update exists, don't install. */
+    checkOnly?: boolean;
+}
+export declare function parseArgs(argv: string[]): CliArgs;
+export declare function printHelp(): void;
+/**
+ * Make `cwd` the process working directory, so --cwd behaves exactly like
+ * launching Bubble there. Returns an error message instead of throwing.
+ */
+export declare function enterWorkingDirectory(cwd: string): string | undefined;

package/dist/cli.js

@@ -0,0 +1,175 @@
+/**
+ * CLI argument parsing.
+ */
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { THINKING_LEVELS } from "./types.js";
+import { isThinkingLevel } from "./variant/thinking-level.js";
+export function parseArgs(argv) {
+    const args = {
+        command: "default",
+        cwd: process.cwd(),
+    };
+    // Subcommand detection: first non-flag argv item.
+    let startIndex = 0;
+    if (argv.length > 0 && !argv[0].startsWith("-")) {
+        if (argv[0] === "serve") {
+            args.command = "serve";
+            startIndex = 1;
+        }
+        else if (argv[0] === "update" || argv[0] === "upgrade") {
+            args.command = "update";
+            startIndex = 1;
+        }
+    }
+    for (let i = startIndex; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--model":
+            case "-m":
+                args.model = argv[++i];
+                break;
+            case "--cwd": {
+                // Absolute, so it survives the chdir in main() and matches session metadata.
+                const dir = argv[++i];
+                if (dir)
+                    args.cwd = resolve(dir);
+                break;
+            }
+            case "--api-key":
+            case "-k":
+                args.apiKey = argv[++i];
+                break;
+            case "--resume":
+            case "-r":
+                args.resume = true;
+                break;
+            case "--session":
+                args.sessionName = argv[++i];
+                break;
+            case "--reasoning":
+                args.thinkingLevel = "medium";
+                break;
+            case "--reasoning-effort": {
+                const value = argv[++i];
+                if (isThinkingLevel(value)) {
+                    args.thinkingLevel = value;
+                }
+                break;
+            }
+            case "--print":
+            case "-p":
+                args.print = true;
+                break;
+            case "--output-format": {
+                const value = argv[++i];
+                if (value !== "plain" && value !== "json" && value !== "stream-json") {
+                    console.error(`Invalid --output-format: ${value ?? "(missing)"}. Expected plain, json, or stream-json.`);
+                    process.exit(1);
+                }
+                args.outputFormat = value;
+                break;
+            }
+            case "--input-format": {
+                const value = argv[++i];
+                if (value !== "text" && value !== "stream-json") {
+                    throw new Error("--input-format expects text or stream-json");
+                }
+                args.inputFormat = value;
+                break;
+            }
+            case "--plan":
+                args.mode = "plan";
+                break;
+            case "--accept-edits":
+                // Backward-compatible no-op: Build mode now includes edit/write auto-approval.
+                args.mode = "default";
+                break;
+            case "--dangerously-skip-permissions":
+                args.mode = "bypassPermissions";
+                break;
+            case "--feishu":
+                args.serveHost = "feishu";
+                break;
+            case "--setup":
+                args.setup = true;
+                break;
+            case "--kill-old":
+                args.killOld = true;
+                break;
+            case "--dry-run":
+                args.dryRun = true;
+                break;
+            case "--check":
+                args.checkOnly = true;
+                break;
+            default:
+                if (!arg.startsWith("-") && !args.prompt) {
+                    args.prompt = arg;
+                }
+                break;
+        }
+    }
+    const streamingInput = args.inputFormat === "stream-json";
+    const streamingOutput = args.outputFormat === "stream-json";
+    if (streamingInput || streamingOutput) {
+        if (!streamingInput || !streamingOutput || !args.print || args.prompt || args.command !== "default") {
+            throw new Error("Persistent mode requires -p --input-format stream-json --output-format stream-json and prompts on stdin");
+        }
+        if (args.resume && !args.sessionName) {
+            throw new Error("Persistent mode requires --session when using --resume (no interactive picker)");
+        }
+    }
+    return args;
+}
+export function printHelp() {
+    console.log(`
+Usage:
+  bubble [options] [prompt]              Start interactive TUI
+  bubble update [--check]                Update to the latest version (alias: upgrade)
+  bubble serve --feishu [options]        Run as a Feishu bot host
+
+Options (default):
+  -m, --model <model>      Model to use
+  --cwd <dir>              Working directory (default: current)
+  -k, --api-key <key>      API key for the active provider
+  -r, --resume             Resume a previous session (latest by default)
+  --session <name>         Session name to create or resume
+  --reasoning              Enable reasoning mode at medium effort
+  --reasoning-effort <l>   Set reasoning effort: ${THINKING_LEVELS.join("|")}
+  --plan                   Start in plan mode (read-only investigation; propose before executing)
+  --dangerously-skip-permissions
+                           Enable bypass mode (auto-approve EVERY tool; disables all safety prompts)
+  -p, --print              Non-interactive mode (single prompt)
+  --output-format <fmt>    Print-mode output: plain (default), json, or stream-json
+                           (one JSON object on stdout: text, usage, num_turns)
+  --input-format <fmt>     text (default) or stream-json; use both stream-json flags with -p\n                           for a persistent session (one user JSON message per line)
+  -v, --version            Print the installed version and exit
+  -h, --help               Show this help
+
+Options (update):
+  --check                  Only report whether a newer version exists
+
+Options (serve --feishu):
+  --setup                  Force the wizard (scan QR + bind first scope)
+  --kill-old               Kill any conflicting bubble instance for the same App ID
+  --dry-run                Connect once, then exit (smoke test)
+`);
+}
+/**
+ * Make `cwd` the process working directory, so --cwd behaves exactly like
+ * launching Bubble there. Returns an error message instead of throwing.
+ */
+export function enterWorkingDirectory(cwd) {
+    if (cwd === process.cwd())
+        return undefined;
+    try {
+        if (!statSync(cwd).isDirectory())
+            return `--cwd ${cwd} is not a directory.`;
+        process.chdir(cwd);
+        return undefined;
+    }
+    catch {
+        return `--cwd ${cwd} does not exist or cannot be opened.`;
+    }
+}

package/dist/clipboard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build the OSC 52 escape sequence for the given text. Returns `null` when the
+ * base64 payload exceeds {@link MAX_OSC52_ENCODED_LENGTH}.
+ *
+ * Format: ESC ] 52 ; c ; <base64> BEL  =>  `\x1b]52;c;<base64>\x07`
+ *
+ * Exported for unit testing the encoding/cap logic in isolation.
+ */
+export declare function encodeOsc52(text: string): string | null;
+/**
+ * Copy `text` to the system clipboard. Resolves once a copy path succeeds and
+ * throws only when no path (native tools nor OSC 52) could place the text.
+ */
+export declare function copyToClipboard(text: string): Promise<void>;

package/dist/clipboard.js

@@ -0,0 +1,132 @@
+import { execSync, spawn } from "node:child_process";
+import { platform } from "node:os";
+/**
+ * Maximum length of the base64-encoded payload we are willing to emit via
+ * OSC 52. Very large payloads can desynchronize terminal rendering and many
+ * terminals silently drop sequences past ~100k, so we cap and skip instead.
+ */
+const MAX_OSC52_ENCODED_LENGTH = 100_000;
+function copyToX11Clipboard(options) {
+    try {
+        execSync("xclip -selection clipboard", options);
+    }
+    catch {
+        execSync("xsel --clipboard --input", options);
+    }
+}
+/**
+ * True when we appear to be running over SSH/Mosh, i.e. the host running this
+ * process is not the machine whose clipboard the user is looking at.
+ */
+function isRemoteSession(env = process.env) {
+    return Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.MOSH_CONNECTION);
+}
+/**
+ * True when running inside a tmux session. tmux intercepts/relays terminal
+ * clipboard escapes, so OSC 52 is the reliable path to reach the outer
+ * terminal's clipboard (especially tmux-over-ssh). Native pbcopy still works
+ * locally, so we treat this as "also emit OSC 52", never as a replacement.
+ */
+function isTmuxSession(env = process.env) {
+    return Boolean(env.TMUX);
+}
+/**
+ * Build the OSC 52 escape sequence for the given text. Returns `null` when the
+ * base64 payload exceeds {@link MAX_OSC52_ENCODED_LENGTH}.
+ *
+ * Format: ESC ] 52 ; c ; <base64> BEL  =>  `\x1b]52;c;<base64>\x07`
+ *
+ * Exported for unit testing the encoding/cap logic in isolation.
+ */
+export function encodeOsc52(text) {
+    const encoded = Buffer.from(text).toString("base64");
+    if (encoded.length > MAX_OSC52_ENCODED_LENGTH) {
+        return null;
+    }
+    return `\x1b]52;c;${encoded}\x07`;
+}
+/**
+ * Write the OSC 52 sequence to stdout. Returns false (without writing) when the
+ * payload is too large to emit safely.
+ */
+function emitOsc52(text) {
+    const sequence = encodeOsc52(text);
+    if (sequence === null) {
+        return false;
+    }
+    process.stdout.write(sequence);
+    return true;
+}
+/**
+ * Copy `text` to the system clipboard. Resolves once a copy path succeeds and
+ * throws only when no path (native tools nor OSC 52) could place the text.
+ */
+export async function copyToClipboard(text) {
+    let copied = false;
+    const p = platform();
+    const options = { input: text, timeout: 5000, stdio: ["pipe", "ignore", "ignore"] };
+    try {
+        if (p === "darwin") {
+            execSync("pbcopy", options);
+            copied = true;
+        }
+        else if (p === "win32") {
+            execSync("clip", options);
+            copied = true;
+        }
+        else {
+            // Linux/other. Try Termux, Wayland, then X11 clipboard tools.
+            if (process.env.TERMUX_VERSION) {
+                try {
+                    execSync("termux-clipboard-set", options);
+                    copied = true;
+                }
+                catch {
+                    // Fall back to Wayland or X11 tools.
+                }
+            }
+            if (!copied) {
+                const hasWaylandDisplay = Boolean(process.env.WAYLAND_DISPLAY);
+                const hasX11Display = Boolean(process.env.DISPLAY);
+                if (hasWaylandDisplay) {
+                    try {
+                        // Verify wl-copy exists (spawn errors are async and won't be caught).
+                        execSync("which wl-copy", { stdio: "ignore" });
+                        // wl-copy with execSync hangs due to fork behavior; use spawn instead.
+                        const proc = spawn("wl-copy", [], { stdio: ["pipe", "ignore", "ignore"] });
+                        proc.stdin.on("error", () => {
+                            // Ignore EPIPE errors if wl-copy exits early.
+                        });
+                        proc.stdin.write(text);
+                        proc.stdin.end();
+                        proc.unref();
+                        copied = true;
+                    }
+                    catch {
+                        if (hasX11Display) {
+                            copyToX11Clipboard(options);
+                            copied = true;
+                        }
+                    }
+                }
+                else if (hasX11Display) {
+                    copyToX11Clipboard(options);
+                    copied = true;
+                }
+            }
+        }
+    }
+    catch {
+        // Fall through to the OSC 52 fallback.
+    }
+    // Emit OSC 52 when the native clipboard may be unreachable from this host
+    // (remote sessions, tmux relaying to an outer terminal) or when no native
+    // tool succeeded. This is additive — never throw if a native copy worked.
+    if (isRemoteSession() || isTmuxSession() || !copied) {
+        const osc52Copied = emitOsc52(text);
+        copied = copied || osc52Copied;
+    }
+    if (!copied) {
+        throw new Error("Failed to copy to clipboard");
+    }
+}