@bubblebrain-ai/bubble 0.0.14 → 0.0.15

package/dist/cli.d.ts

@@ -2,7 +2,7 @@
  * CLI argument parsing.
  */
 import type { PermissionMode, ThinkingLevel } from "./types.js";
-export type CliCommand = "default" | "serve";
+export type CliCommand = "default" | "serve" | "update";
 export interface CliArgs {
     command: CliCommand;
     model?: string;
@@ -22,6 +22,8 @@ export interface CliArgs {
     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;

package/dist/cli.js

@@ -14,6 +14,10 @@ export function parseArgs(argv) {
             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];
@@ -72,6 +76,9 @@ export function parseArgs(argv) {
             case "--dry-run":
                 args.dryRun = true;
                 break;
+            case "--check":
+                args.checkOnly = true;
+                break;
             default:
                 if (!arg.startsWith("-") && !args.prompt) {
                     args.prompt = arg;
@@ -85,6 +92,7 @@ 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):
@@ -99,8 +107,12 @@ Options (default):
   --dangerously-skip-permissions
                            Enable bypass mode (auto-approve EVERY tool; disables all safety prompts)
   -p, --print              Non-interactive mode (single prompt)
+  -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

package/dist/main.js

@@ -34,6 +34,16 @@ async function main() {
         printHelp();
         process.exit(0);
     }
+    if (process.argv.includes("-v") || process.argv.includes("--version")) {
+        const { getCurrentVersion } = await import("./update/index.js");
+        console.log(`v${getCurrentVersion()}`);
+        process.exit(0);
+    }
+    if (args.command === "update") {
+        const { runUpdateCommand } = await import("./update/index.js");
+        const code = await runUpdateCommand({ checkOnly: args.checkOnly });
+        process.exit(code);
+    }
     if (args.command === "serve") {
         if (args.serveHost !== "feishu") {
             console.error(chalk.red("Usage: bubble serve --feishu [--setup | --kill-old | --dry-run]"));
@@ -475,6 +485,8 @@ async function main() {
             runMemorySummary,
             runMemoryRefresh,
         };
+        const { getStartupUpdateNotice } = await import("./update/index.js");
+        const updateNotice = await getStartupUpdateNotice();
         const { runTui } = await import("./tui/run.js");
         await runTui(agent, args, {
             ...commonOptions,
@@ -482,6 +494,7 @@ async function main() {
             themeOverrides: themeConfig.overrides,
             detectedTheme,
             onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
+            updateNotice: updateNotice ?? undefined,
         });
         if (sessionManager) {
             printOpenTuiExitSummary(sessionManager, {

package/dist/tui/run.d.ts

@@ -41,5 +41,7 @@ export interface RunTuiOptions {
     runMemoryCompaction?: () => Promise<string>;
     runMemorySummary?: (scope?: MemoryScope) => Promise<string>;
     runMemoryRefresh?: (scope?: MemoryScope) => Promise<string>;
+    /** One-line "update available" notice shown on the home screen, if any. */
+    updateNotice?: string;
 }
 export declare function runTui(agent: Agent, args: CliArgs, options?: RunTuiOptions): Promise<void>;

package/dist/tui/run.js

@@ -13,6 +13,7 @@ import { summarizeAgentEventForTrace, summarizeTraceError, summarizeTraceValue,
 import { BUILTIN_PROVIDERS, decodeModel, displayModel, isUserVisibleProvider } from "../provider-registry.js";
 import { calculateUsageCost } from "../model-pricing.js";
 import { getAvailableThinkingLevels } from "../provider-transform.js";
+import { getCurrentVersion } from "../update/index.js";
 import { collectUsageStatsBundle, formatStatsPanelBody } from "../stats/usage.js";
 import { parseSkillInvocation } from "../skills/invocation.js";
 import { registry as slashRegistry } from "../slash-commands/index.js";
@@ -181,7 +182,7 @@ const PROMPT_SCANNER_IDLE_FRAMES = ["        "];
 const PROMPT_SCANNER_INTERVAL_MS = 80;
 const SESSION_SIDEBAR_WIDTH = 42;
 const SESSION_SIDEBAR_AUTO_WIDTH = 120;
-const PROVIDER_DIALOG_ROWS = 11;
+const PROVIDER_DIALOG_ROWS = 13;
 const QUESTION_MAX_TABS = 4;
 const QUESTION_MAX_OPTIONS = 10;
 const QUESTION_MAX_CONFIRM_ROWS = 3;
@@ -1104,7 +1105,7 @@ function OpenTuiApp(props) {
         if (!safeSetText(ref, promptModeBadge()))
             promptModeLabels.delete(ref);
     };
-    const promptModelTitle = () => displayModel(props.agent.model) || "no model";
+    const promptModelTitle = () => displayModelWithThinking(props.agent.model, props.agent.thinking) || "no model";
     const syncModelChrome = () => {
         if (uiDisposed)
             return;
@@ -3046,6 +3047,31 @@ function OpenTuiApp(props) {
             // Keep the already-rendered local catalog when remote model discovery fails.
         }
     }
+    function providerDialogMatchScore(item, query) {
+        const label = (item.label || "").toLowerCase();
+        const value = (item.value || "").toLowerCase();
+        const haystack = [
+            item.label,
+            item.detail,
+            item.value,
+            item.category,
+            item.footer,
+        ].filter(Boolean).join(" ").toLowerCase();
+        if (label.startsWith(query))
+            return 100;
+        if (label.includes(query))
+            return 80;
+        if (value.includes(query))
+            return 60;
+        if (haystack.includes(query))
+            return 40;
+        // Fuzzy (subsequence) match is a last resort, and only against label+value
+        // so long provider descriptions (e.g. "platform.moonshot.cn") don't produce
+        // spurious hits like "gpt" matching "kimi-k2-thinking".
+        if (fuzzyMatch(`${label} ${value}`, query))
+            return 20;
+        return 0;
+    }
     function providerDialogFilteredItems(state = providerDialog) {
         if (!state || state.step === "key")
             return [];
@@ -3053,16 +3079,12 @@ function OpenTuiApp(props) {
         const query = state.query.trim().toLowerCase();
         if (!query)
             return items;
-        return items.filter((item) => {
-            const haystack = [
-                item.label,
-                item.detail,
-                item.value,
-                item.category,
-                item.footer,
-            ].filter(Boolean).join(" ").toLowerCase();
-            return haystack.includes(query) || fuzzyMatch(haystack, query);
-        });
+        const scored = items
+            .map((item, order) => ({ item, order, score: providerDialogMatchScore(item, query) }))
+            .filter((entry) => entry.score > 0);
+        // Stable sort by score desc, preserving original catalog order within a tier.
+        scored.sort((a, b) => b.score - a.score || a.order - b.order);
+        return scored.map((entry) => entry.item);
     }
     function providerDialogVisibleRows(state = providerDialog) {
         if (!state)
@@ -3103,7 +3125,7 @@ function OpenTuiApp(props) {
             providerDialogRoot.requestRender();
             return;
         }
-        const width = Math.max(48, Math.min(60, dimensions().width - 2));
+        const width = Math.max(56, Math.min(76, dimensions().width - 4));
         const height = PROVIDER_DIALOG_ROWS + 7;
         providerDialogRoot.visible = true;
         providerDialogRoot.width = dimensions().width;
@@ -5494,6 +5516,10 @@ function OpenTuiApp(props) {
             paddingRight: 2,
         }, [
             h("box", { flexShrink: 0, flexDirection: "column", alignItems: "center" }, ...logoLines.map((line) => renderHomeLogoLine(line))),
+            h("box", { flexShrink: 0, flexDirection: "column", alignItems: "center", paddingTop: 1 }, h("text", { fg: theme.textMuted, content: `v${getCurrentVersion()}` })),
+            ...(props.options.updateNotice
+                ? [h("box", { flexShrink: 0, flexDirection: "column", alignItems: "center" }, h("text", { fg: theme.accent, content: props.options.updateNotice }))]
+                : []),
             h("box", { height: 1, minHeight: 0, flexShrink: 1 }),
             h("box", {
                 ref: (ref) => {
@@ -5996,7 +6022,8 @@ function OpenTuiApp(props) {
                 width: "100%",
                 value: "",
                 placeholder: "",
-                fg: theme.text,
+                textColor: theme.text,
+                focusedTextColor: theme.text,
                 backgroundColor: theme.backgroundElement,
                 focusedBackgroundColor: theme.backgroundElement,
                 cursorColor: theme.primary,
@@ -6141,7 +6168,7 @@ function OpenTuiApp(props) {
             },
             visible: false,
             position: "absolute",
-            width: 60,
+            width: 76,
             height: PROVIDER_DIALOG_ROWS + 7,
             backgroundColor: theme.backgroundPanel,
             flexDirection: "column",
@@ -6178,7 +6205,8 @@ function OpenTuiApp(props) {
                 width: "100%",
                 value: "",
                 placeholder: "Search",
-                fg: theme.textMuted,
+                textColor: theme.text,
+                focusedTextColor: theme.text,
                 backgroundColor: theme.backgroundPanel,
                 focusedBackgroundColor: theme.backgroundPanel,
                 cursorColor: theme.primary,
@@ -6191,15 +6219,11 @@ function OpenTuiApp(props) {
                         providerDialog = { ...state, apiKey: value, error: undefined };
                     }
                     else {
+                        const query = value.trim().toLowerCase();
                         const items = providerDialogItemsFor(state.step, state.providerId).filter((item) => {
-                            const query = value.trim().toLowerCase();
                             if (!query)
                                 return true;
-                            const haystack = [item.label, item.detail, item.value, item.category, item.footer]
-                                .filter(Boolean)
-                                .join(" ")
-                                .toLowerCase();
-                            return haystack.includes(query) || fuzzyMatch(haystack, query);
+                            return providerDialogMatchScore(item, query) > 0;
                         });
                         providerDialog = {
                             ...state,
@@ -7054,7 +7078,7 @@ function renderMarkdownContent(content, syntaxStyle, options) {
         bg: theme.background,
         width: "100%",
         tableOptions: {
-            widthMode: "full",
+            widthMode: "content",
             columnFitter: "balanced",
             wrapMode: "word",
             cellPadding: 1,
@@ -7274,7 +7298,13 @@ function syncMarkdownRenderable(markdown, content, streaming) {
         return;
     markdown.content = content;
     markdown.streaming = streaming;
-    markdown.clearCache();
+    // While streaming, let OpenTUI's incremental markdown/code-block rendering do
+    // its job — clearing the parse cache every delta forces the (syntax-
+    // highlighted) code blocks to be rebuilt and re-highlighted on every token,
+    // which is the source of the visible flicker on streamed code blocks. Clear
+    // the cache only once streaming ends, to fully reparse the finalized content.
+    if (!streaming)
+        markdown.clearCache();
 }
 function updateAssistantPartEntries(entry, parts, options, streaming) {
     const partsBox = entry.refs.partsBox;
@@ -7613,7 +7643,7 @@ function createMarkdown(ctx, content, syntaxStyle, options) {
         width: "100%",
         flexShrink: 0,
         tableOptions: {
-            widthMode: "full",
+            widthMode: "content",
             columnFitter: "balanced",
             wrapMode: "word",
             cellPadding: 1,
@@ -8293,7 +8323,7 @@ function renderTool(tool, syntaxStyle, width = 80) {
     const color = toolColor(tool);
     const diff = extractToolDiff(tool);
     if (diff && !tool.resultCollapsed && !tool.isError && (tool.name === "edit" || tool.name === "apply_patch")) {
-        return h("box", { paddingLeft: 3, marginTop: 1, flexDirection: "column", flexShrink: 0 }, h("text", { fg: color }, `${icon} ${displayToolName(tool.name)}${toolHeader(tool) ? ` ${toolHeader(tool)}` : ""}`), h("box", { paddingLeft: 1, marginTop: 1, border: ["left"], borderColor: theme.borderSubtle, flexDirection: "column", flexShrink: 0 }, renderDiffContent(diff, toolPath(tool), syntaxStyle, width)));
+        return h("box", { paddingLeft: 3, marginTop: 1, flexDirection: "column", flexShrink: 0 }, h("text", { fg: color }, `${icon} ${displayToolName(tool.name)}${toolHeader(tool) ? ` ${toolHeader(tool)}` : ""}`), h("box", { paddingLeft: 1, marginTop: 1, border: ["left"], borderColor: theme.borderSubtle, flexDirection: "column", flexShrink: 0, backgroundColor: theme.diffContextBg }, renderDiffContent(diff, toolPath(tool), syntaxStyle, width)));
     }
     if (!tool.resultCollapsed && isWritePreviewTool(tool)) {
         const hasContent = typeof tool.args.content === "string";
@@ -8401,10 +8431,18 @@ function pickerTitle(kind, providerId) {
     }
 }
 function getModelPickerReasoningLevels(providerId, modelId) {
-    if (providerId !== "deepseek" || (modelId !== "deepseek-v4-flash" && modelId !== "deepseek-v4-pro")) {
+    // Only expand into one picker row per effort for models that genuinely have a
+    // reasoning-effort spectrum: OpenAI's reasoning models (codex gpt-5.x:
+    // off/minimal/low/medium/high/xhigh) and DeepSeek's v4 models. Other providers
+    // (e.g. GLM, Moonshot/Kimi) only have a thinking on/off toggle, not an effort
+    // control, so they stay as a single row.
+    const isOpenAIReasoning = providerId === "openai" || providerId === "openai-codex";
+    const isDeepseekReasoning = providerId === "deepseek" && (modelId === "deepseek-v4-flash" || modelId === "deepseek-v4-pro");
+    if (!isOpenAIReasoning && !isDeepseekReasoning)
         return [];
-    }
-    return getAvailableThinkingLevels(providerId, modelId);
+    const levels = getAvailableThinkingLevels(providerId, modelId);
+    // gpt-4o and friends report only ["off"] — keep those as a single row too.
+    return levels.length > 1 ? levels : [];
 }
 function displayModelWithThinking(model, thinkingLevel) {
     if (!model)
@@ -8412,7 +8450,10 @@ function displayModelWithThinking(model, thinkingLevel) {
     const { providerId, modelId } = decodeModel(model);
     if (!providerId)
         return displayModel(model);
-    const levels = getAvailableThinkingLevels(providerId, modelId);
+    // Use the same scoping as the picker: only models with a real reasoning-effort
+    // spectrum (OpenAI codex gpt-5.x, deepseek v4) get the "(level)" suffix. The
+    // on/off thinking toggle on GLM / Moonshot(Kimi) is not an effort control.
+    const levels = getModelPickerReasoningLevels(providerId, modelId);
     if (levels.length > 1 && thinkingLevel !== "off") {
         return `${displayModel(model)} (${thinkingLevel})`;
     }
@@ -9066,11 +9107,18 @@ function toolPath(tool) {
         ?? (Array.isArray(tool.metadata?.paths) ? tool.metadata.paths[0] : undefined);
     return typeof value === "string" ? value : undefined;
 }
+// Strip only leading/trailing newlines — NOT a full .trim(). A blank context
+// line in a unified diff is a single space (" "); plain .trim() would delete a
+// trailing blank context line, leaving the hunk body shorter than its @@ header
+// count and breaking the diff parser ("Added line count did not match").
+function stripDiffEdgeNewlines(diff) {
+    return diff.replace(/^\n+/, "").replace(/\n+$/, "");
+}
 function extractToolDiff(tool) {
     if (tool.resultCollapsed)
         return undefined;
     if (typeof tool.metadata?.diff === "string" && tool.metadata.diff.trim().length > 0) {
-        return tool.metadata.diff.trim();
+        return stripDiffEdgeNewlines(tool.metadata.diff);
     }
     if (!tool.result)
         return undefined;
@@ -9086,10 +9134,14 @@ function extractToolDiff(tool) {
     const rawDiff = tool.result.slice(index + marker.length);
     const diagnosticsIndex = rawDiff.search(/\n\nLSP diagnostics in /);
     const diff = diagnosticsIndex === -1 ? rawDiff : rawDiff.slice(0, diagnosticsIndex);
-    return diff.trim().length > 0 ? diff : undefined;
-}
-function diffViewMode(width = 80) {
-    return width > 120 ? "split" : "unified";
+    return diff.trim().length > 0 ? stripDiffEdgeNewlines(diff) : undefined;
+}
+function diffViewMode(_width = 80) {
+    // Always unified: split view pads the shorter side with empty filler rows that
+    // OpenTUI's DiffRenderable leaves uncolored, which shows up as bright white
+    // blocks in light mode. Unified view has no filler rows — every line is
+    // add/remove/context and gets a background — so the edit area stays uniform.
+    return "unified";
 }
 function filetype(filePath) {
     if (!filePath)

package/dist/update/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Self-update: `bubble update` / `bubble upgrade`, plus a cached startup
+ * "update available" check.
+ *
+ * Bubble ships as the npm package `@bubblebrain-ai/bubble`. Updating just means
+ * re-installing it globally with whatever package manager put it there, so we
+ * detect the install method and run the matching command.
+ */
+export declare const PACKAGE_NAME = "@bubblebrain-ai/bubble";
+export declare function getCurrentVersion(): string;
+export declare function fetchLatestVersion(timeoutMs?: number): Promise<string | null>;
+/**
+ * Compare two semver-ish strings. Returns 1 if a > b, -1 if a < b, 0 if equal.
+ * Handles `x.y.z` and a single pre-release tag (`x.y.z-beta.1`); a release
+ * always outranks a pre-release of the same numeric version.
+ */
+export declare function compareVersions(a: string, b: string): number;
+export type PackageManager = "npm" | "bun" | "pnpm" | "yarn" | "homebrew" | "unknown";
+export interface InstallInfo {
+    manager: PackageManager;
+    isGlobal: boolean;
+    isLocalCheckout: boolean;
+    installPath: string;
+}
+/**
+ * Figure out how this copy of Bubble was installed by inspecting the real path
+ * of the package directory (two levels up from this module: dist/update -> pkg).
+ */
+export declare function detectInstall(): InstallInfo;
+export declare function upgradeCommandFor(manager: PackageManager): {
+    cmd: string;
+    args: string[];
+} | null;
+/**
+ * `bubble update` entry point. Returns a process exit code.
+ */
+export declare function runUpdateCommand(opts?: {
+    checkOnly?: boolean;
+}): Promise<number>;
+/**
+ * Returns a one-line "update available" notice if the cached latest version is
+ * newer than the running one. Reads only a local cache file (fast, no network
+ * on the hot path); a stale cache triggers a fire-and-forget refresh so the
+ * next launch is accurate. Never throws.
+ */
+export declare function getStartupUpdateNotice(): Promise<string | null>;

package/dist/update/index.js

@@ -0,0 +1,240 @@
+/**
+ * Self-update: `bubble update` / `bubble upgrade`, plus a cached startup
+ * "update available" check.
+ *
+ * Bubble ships as the npm package `@bubblebrain-ai/bubble`. Updating just means
+ * re-installing it globally with whatever package manager put it there, so we
+ * detect the install method and run the matching command.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+const require = createRequire(import.meta.url);
+export const PACKAGE_NAME = "@bubblebrain-ai/bubble";
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // once a day
+export function getCurrentVersion() {
+    try {
+        const pkg = require("../../package.json");
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export async function fetchLatestVersion(timeoutMs = 5000) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(REGISTRY_URL, {
+                signal: controller.signal,
+                headers: { accept: "application/json" },
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            return data.version ?? null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare two semver-ish strings. Returns 1 if a > b, -1 if a < b, 0 if equal.
+ * Handles `x.y.z` and a single pre-release tag (`x.y.z-beta.1`); a release
+ * always outranks a pre-release of the same numeric version.
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const cleaned = v.trim().replace(/^v/, "");
+        const [core, pre] = cleaned.split("-", 2);
+        const nums = core.split(".").map((n) => parseInt(n, 10) || 0);
+        while (nums.length < 3)
+            nums.push(0);
+        return { nums, pre: pre ?? "" };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i++) {
+        if (pa.nums[i] > pb.nums[i])
+            return 1;
+        if (pa.nums[i] < pb.nums[i])
+            return -1;
+    }
+    // Equal numeric core: no pre-release beats a pre-release.
+    if (pa.pre === pb.pre)
+        return 0;
+    if (!pa.pre)
+        return 1;
+    if (!pb.pre)
+        return -1;
+    return pa.pre > pb.pre ? 1 : -1;
+}
+/**
+ * Figure out how this copy of Bubble was installed by inspecting the real path
+ * of the package directory (two levels up from this module: dist/update -> pkg).
+ */
+export function detectInstall() {
+    const rawRoot = fileURLToPath(new URL("../../", import.meta.url));
+    let installPath = rawRoot;
+    try {
+        installPath = realpathSync(rawRoot);
+    }
+    catch {
+        // keep rawRoot
+    }
+    const lower = installPath.replace(/\\/g, "/").toLowerCase();
+    const isUnderNodeModules = lower.includes("/node_modules/");
+    // A dev/source checkout has src/ alongside dist/ and isn't under node_modules.
+    const isLocalCheckout = !isUnderNodeModules;
+    let manager = "unknown";
+    if (lower.includes("/cellar/") || lower.includes("/homebrew/")) {
+        manager = "homebrew";
+    }
+    else if (lower.includes("/.bun/") || lower.includes("/bun/install/")) {
+        manager = "bun";
+    }
+    else if (lower.includes("/pnpm/") || lower.includes("/.pnpm/")) {
+        manager = "pnpm";
+    }
+    else if (lower.includes("/.yarn/") || lower.includes("/yarn/global")) {
+        manager = "yarn";
+    }
+    else if (isUnderNodeModules) {
+        manager = "npm";
+    }
+    return { manager, isGlobal: isUnderNodeModules, isLocalCheckout, installPath };
+}
+export function upgradeCommandFor(manager) {
+    const spec = `${PACKAGE_NAME}@latest`;
+    switch (manager) {
+        case "npm":
+        case "unknown": // default to npm
+            return { cmd: "npm", args: ["install", "-g", spec] };
+        case "bun":
+            return { cmd: "bun", args: ["add", "-g", spec] };
+        case "pnpm":
+            return { cmd: "pnpm", args: ["add", "-g", spec] };
+        case "yarn":
+            return { cmd: "yarn", args: ["global", "add", spec] };
+        case "homebrew":
+            return null; // handled separately (brew upgrade)
+    }
+}
+function spawnInherit(cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: "inherit", env: process.env });
+        child.on("error", () => resolve(127));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+/**
+ * `bubble update` entry point. Returns a process exit code.
+ */
+export async function runUpdateCommand(opts = {}) {
+    const current = getCurrentVersion();
+    process.stdout.write(`Bubble v${current}\n`);
+    process.stdout.write("Checking npm for the latest version…\n");
+    const latest = await fetchLatestVersion();
+    if (!latest) {
+        process.stderr.write("Could not reach the npm registry. Check your connection and try again.\n");
+        return 1;
+    }
+    if (compareVersions(latest, current) <= 0) {
+        process.stdout.write(`You're already on the latest version (v${current}).\n`);
+        return 0;
+    }
+    process.stdout.write(`Update available: v${current} → v${latest}\n`);
+    if (opts.checkOnly) {
+        process.stdout.write("Run `bubble update` to install it.\n");
+        return 0;
+    }
+    const info = detectInstall();
+    if (info.isLocalCheckout) {
+        process.stderr.write("This looks like a local/development checkout, not a global install.\n" +
+            "Update it with:\n  git pull && npm run build\n");
+        return 1;
+    }
+    if (info.manager === "homebrew") {
+        process.stderr.write("Bubble was installed via Homebrew. Update it with:\n  brew upgrade bubble\n");
+        return 1;
+    }
+    const command = upgradeCommandFor(info.manager);
+    if (!command) {
+        process.stderr.write(`Couldn't determine how to update automatically. Run:\n  npm install -g ${PACKAGE_NAME}@latest\n`);
+        return 1;
+    }
+    process.stdout.write(`\nUpdating via ${command.cmd}…\n\n`);
+    const code = await spawnInherit(command.cmd, command.args);
+    if (code === 0) {
+        process.stdout.write(`\n✓ Updated to v${latest}. Restart bubble to use the new version.\n`);
+        return 0;
+    }
+    process.stderr.write(`\nUpdate failed (exit ${code}). Try running it manually:\n  ${command.cmd} ${command.args.join(" ")}\n` +
+        "If this is a permissions error, you may need elevated privileges or to fix your global install prefix.\n");
+    return code;
+}
+function cacheFile() {
+    return join(getBubbleHome(), "update-check.json");
+}
+async function readCache() {
+    try {
+        const raw = await readFile(cacheFile(), "utf8");
+        const data = JSON.parse(raw);
+        if (typeof data.lastCheck === "number" && typeof data.latest === "string") {
+            return { lastCheck: data.lastCheck, latest: data.latest };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(cache) {
+    try {
+        const file = cacheFile();
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, JSON.stringify(cache), "utf8");
+    }
+    catch {
+        // best-effort; never fail startup over a cache write
+    }
+}
+async function refreshCacheInBackground(now) {
+    const latest = await fetchLatestVersion(4000);
+    if (latest) {
+        await writeCache({ lastCheck: now, latest });
+    }
+}
+/**
+ * Returns a one-line "update available" notice if the cached latest version is
+ * newer than the running one. Reads only a local cache file (fast, no network
+ * on the hot path); a stale cache triggers a fire-and-forget refresh so the
+ * next launch is accurate. Never throws.
+ */
+export async function getStartupUpdateNotice() {
+    try {
+        const current = getCurrentVersion();
+        const now = Date.now();
+        const cache = await readCache();
+        if (!cache || now - cache.lastCheck > CHECK_INTERVAL_MS) {
+            void refreshCacheInBackground(now);
+        }
+        if (cache && compareVersions(cache.latest, current) > 0) {
+            return `Update available: v${current} → v${cache.latest} · run \`bubble update\``;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bubblebrain-ai/bubble",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "A terminal coding agent",
   "type": "module",
   "engines": {