@bubblebrain-ai/bubble 0.0.21 → 0.0.23

package/README.md

@@ -1,38 +1,37 @@
 # Bubble
 
-Bubble is a terminal coding agent for working inside local project folders. It can read and edit files, run commands with approval controls, use project skills, connect MCP tools, and keep persistent memory across sessions.
+Bubble is a terminal coding agent. It works inside a local project folder: it reads and edits files, runs commands behind configurable approval controls, searches and navigates code with language-server intelligence, browses the web, loads reusable skills, connects MCP tools, fans work out to subagents, and keeps persistent memory across sessions.
+
+It is provider-agnostic. Bring an API key for OpenAI, Anthropic, Google, DeepSeek, Moonshot/Kimi, Zhipu, Z.AI, MiniMax, Groq, Together, Fireworks, a local OpenAI-compatible endpoint, and more — or sign in to ChatGPT with OAuth and drive the Codex models directly.
+
+---
 
 ## Requirements
 
-- Node.js 20+ and npm for installation
-- Bun for running Bubble
+- Node.js 20 or newer (used to install the launcher)
+- [Bun](https://bun.sh) (used to run the agent)
 
-Install Bun if it is not already available:
+Install Bun if you do not already have it:
 
 ```bash
 curl -fsSL https://bun.sh/install | bash
 ```
 
-## Install
+The `npm install` step puts a small Node.js launcher named `bubble` on your PATH. When you run `bubble`, the launcher locates Bun and starts the real runtime under it. If Bun is missing, it prints the install command above instead of failing with a low-level error.
 
-From npm:
+## Install
 
 ```bash
 npm install -g @bubblebrain-ai/bubble
 ```
 
-From a local package tarball:
+To install from a local tarball:
 
 ```bash
-npm install -g ./bubblebrain-ai-bubble-0.0.3.tgz
+npm install -g ./bubblebrain-ai-bubble-<version>.tgz
 ```
 
-The npm command installs a small Node.js launcher named `bubble`. When you run
-`bubble`, the launcher checks for Bun and starts the real Bubble runtime with
-`bun`. If Bun is missing, it prints the install command above instead of failing
-with a low-level runtime error.
-
-## Usage
+## Quick start
 
 Start Bubble in the current directory:
 
@@ -40,31 +39,192 @@ Start Bubble in the current directory:
 bubble
 ```
 
-Start Bubble for a specific project:
+On first launch, connect a model:
+
+- Run `/login` to sign in to ChatGPT (OAuth) and use the Codex models, or
+- Run `/provider` to add any other provider with an API key.
+
+Then just type what you want done. Bubble plans, edits files, and runs commands, asking for approval where the current permission mode requires it.
+
+Point Bubble at a different project:
 
 ```bash
 bubble --cwd /path/to/project
 ```
 
-Show CLI options:
+Resume your last conversation:
 
 ```bash
-bubble --help
+bubble --resume
+```
+
+## Model providers
+
+Bubble ships with a catalog of built-in providers. Configure them inside the app — no environment variables required.
+
+| How | What it does |
+| --- | --- |
+| `/login` | OAuth sign-in for ChatGPT; unlocks the OpenAI Codex models without an API key. |
+| `/provider` | Open a picker to connect, switch, add, or remove a provider. |
+| `/key <provider> <key>` | Set the API key for a provider. |
+| `/model` | Pick the active model and reasoning effort. |
+
+Built-in providers include OpenAI, Anthropic, Google, DeepSeek, Moonshot (CN and international), Kimi for Coding, Zhipu AI, Z.AI, Alibaba DashScope, MiniMax, StepFun, Groq, Together AI, Fireworks, and a `local` profile for any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, etc.).
+
+### Custom providers and models
+
+For full control — custom base URLs, self-hosted gateways, extra models, or pinning a protocol — define providers in `~/.bubble/models.json`:
+
+```json
+{
+  "providers": {
+    "my-gateway": {
+      "baseURL": "https://gateway.internal/v1",
+      "apiKey": "sk-...",
+      "protocol": "openai-chat",
+      "models": [
+        { "id": "my-model", "name": "My Model" }
+      ]
+    }
+  }
+}
+```
+
+`protocol` accepts `openai-chat` (default) or `anthropic-messages`. Entries in `models.json` take precedence over the built-in catalog.
+
+### Reasoning effort
+
+Models that support it expose a reasoning-effort control: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Set it with `/model <id> --reasoning-effort <level>` in the app, or at launch with `--reasoning` (medium) or `--reasoning-effort <level>`.
+
+## Permission modes
+
+Bubble gates risky actions behind a permission mode. Press `Tab` to cycle modes during a session, or set a default with `--plan` / `--dangerously-skip-permissions` / project settings.
+
+| Mode | Behavior |
+| --- | --- |
+| Default (Build) | File edits and writes auto-approve; bash and other tools prompt unless covered by an allow rule. |
+| Plan | Read-only investigation. The agent proposes a plan and waits for your approval before making changes. |
+| Bypass | Auto-approves every tool and disables all safety prompts. Enable deliberately with `--dangerously-skip-permissions`. |
+
+Allow/deny rules are configured per scope and persisted across sessions. Manage them in-app with `/permissions`, or edit the settings files directly:
+
+- `~/.bubble/settings.json` — user scope (applies everywhere)
+- `<project>/.bubble/settings.json` — project scope (commit to share with your team)
+- `<project>/.bubble/settings.local.json` — local overrides (gitignore)
+
+Rules use a simple pattern syntax, for example:
+
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Bash(git status)",
+      "Bash(npm run:*)",
+      "Read(./src/**)",
+      "WebFetch(domain:github.com)"
+    ],
+    "deny": ["Read(~/.ssh/**)"]
+  }
+}
 ```
 
-## Configuration
+## What Bubble can do
 
-Bubble stores user configuration, sessions, permissions, skills, and memory under:
+**Files and code.** Read, write, and make targeted edits; find files by glob; search contents with ripgrep; and navigate with language-server operations (go-to-definition, find references, hover, document/workspace symbols, call hierarchy).
+
+**Shell and dev servers.** Run bounded bash commands with streaming output, and start/stop/inspect long-running dev servers (`npm run dev`, Vite, Next, etc.) with readiness checks and captured logs.
+
+**Web.** Search the web and fetch/extract page contents on demand.
+
+**Skills.** Drop reusable instructions and assets into a `SKILL.md`-based directory and invoke them with `/<skill-name>`. Bubble discovers skills from `~/.bubble/skills`, `~/.agents/skills`, `~/.claude/skills`, and the project's `.bubble/skills`. Browse them with `/skills`.
+
+**MCP tools.** Connect Model Context Protocol servers (stdio, HTTP, or SSE) under the `mcpServers` key of any settings file. Their tools and prompts become available to the agent; manage connections with `/mcp`.
+
+**Subagents.** Bubble can spawn background subagents with independent context, send them follow-ups, wait on their results, and fan a task out across a team — with concurrency limits and token budgets. Define custom agent profiles in `~/.bubble/agents` or a project's `.bubble/agents`.
+
+**Persistent memory.** A background pipeline distills durable facts, preferences, and decisions from past sessions and recalls them later. Inspect and maintain it with `/memory status`, `/memory search <query>`, and `/memory refresh`.
+
+**Sessions.** Every conversation is saved. Resume the latest with `bubble --resume`, or browse and switch sessions in-app with `/session`. Use `/rewind` to roll the conversation — and optionally your file edits — back to an earlier point.
+
+## Useful slash commands
+
+| Command | Description |
+| --- | --- |
+| `/help` | List available commands. |
+| `/model` | Switch model and reasoning effort. |
+| `/provider`, `/login`, `/logout`, `/key` | Connect and manage providers. |
+| `/session`, `/rewind`, `/clear` | Manage conversation history. |
+| `/skills` | Open the searchable skills picker. |
+| `/mcp` | List or reconnect MCP servers. |
+| `/memory` | Inspect and maintain persistent memory. |
+| `/permissions` | View or edit allow/deny rules. |
+| `/context`, `/stats`, `/compact` | Inspect context usage, model stats, and compact the session. |
+| `/lsp`, `/hooks` | Manage language servers and lifecycle hooks. |
+| `/theme`, `/sidebar` | Adjust the interface. |
+| `/feedback` | Send feedback or report a bug. |
+
+## Non-interactive mode
+
+Run a single prompt and print the result — useful for scripts and pipelines:
+
+```bash
+bubble --print "summarize what this repo does"
+echo "fix the failing test" | bubble --print
+```
+
+Combine with `--model`, `--cwd`, and `--plan` as needed.
+
+## CLI reference
 
 ```text
-~/.bubble
+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: off|minimal|low|medium|high|xhigh|max
+  --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)
+  -v, --version            Print the installed version and exit
+  -h, --help               Show this help
 ```
 
-In the app, use `/login` or provider commands to configure model access.
+Run `bubble update` at any time to upgrade to the latest published version.
+
+## Configuration and storage
 
-### ChatGPT Network Configuration
+Bubble keeps everything under `~/.bubble`:
+
+```text
+~/.bubble/
+  config.json          User preferences (theme, default model, recent models)
+  models.json          Custom providers and models
+  auth.json            OAuth credentials (file mode 0600)
+  settings.json        User-scope permissions, MCP servers, hooks
+  sessions/            Saved conversations, grouped by project directory
+  memories/            Persistent memory store
+  skills/              User skills
+  agents/              Custom subagent profiles
+```
 
-ChatGPT OAuth and GPT/Codex requests respect standard proxy variables:
+Environment variables:
+
+- `BUBBLE_HOME` — override the data directory (defaults to `~/.bubble`).
+- `BUBBLE_DEV=1` — use `~/.bubble-dev` instead, for development.
+
+### Network configuration
+
+ChatGPT OAuth and GPT/Codex requests respect the standard proxy variables:
 
 ```bash
 export HTTPS_PROXY=http://proxy.example.com:8080
@@ -72,28 +232,31 @@ export HTTP_PROXY=http://proxy.example.com:8080
 export NO_PROXY=localhost,127.0.0.1
 ```
 
-If your network uses a corporate or custom HTTPS CA, start Bubble with:
+If your network uses a corporate or custom HTTPS CA:
 
 ```bash
 NODE_EXTRA_CA_CERTS=/absolute/path/to/ca.pem bubble
 ```
 
-You can also use `BUBBLE_EXTRA_CA_CERTS` for Bubble's ChatGPT requests:
+`BUBBLE_EXTRA_CA_CERTS` applies the same trust to Bubble's ChatGPT requests specifically. Do not disable TLS verification with `NODE_TLS_REJECT_UNAUTHORIZED=0`.
+
+## Development
 
 ```bash
-BUBBLE_EXTRA_CA_CERTS=/absolute/path/to/ca.pem bubble
+bun install        # install dependencies
+npm run build      # compile TypeScript to dist/
+npm test           # run the test suite (vitest)
+npm start          # run the built agent
 ```
 
-Do not disable TLS verification with `NODE_TLS_REJECT_UNAUTHORIZED=0`.
+`npm run dev` compiles and launches in one step. The TUI is built on [OpenTUI](https://github.com/anomalyco/opentui) and Solid.
 
-## Memory
+## Feishu host (optional)
 
-Bubble maintains persistent memory automatically from prior sessions. Useful commands:
+Bubble can also run as a Feishu (Lark) bot host:
 
-```text
-/memory status
-/memory search <query>
-/memory refresh
+```bash
+bubble serve --feishu --setup
 ```
 
-Memory is maintained by a background pipeline and can be refreshed manually when you want new session information to be indexed immediately.
+`--setup` runs the binding wizard, `--kill-old` replaces a conflicting instance for the same App ID, and `--dry-run` connects once and exits as a smoke test.

package/dist/agent/abort-errors.d.ts

@@ -0,0 +1,14 @@
+export declare class AgentAbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Abort tagged with why the runtime stopped a child, so finalization can map
+ * it to a SubagentFinalReason (design doc §3.1) instead of guessing from
+ * message strings.
+ */
+export declare class SubagentAbortError extends AgentAbortError {
+    readonly subagentReason: "interrupt" | "user_close" | "budget";
+    constructor(message: string, subagentReason: "interrupt" | "user_close" | "budget");
+}
+/** Shown when the model produced no user-visible content despite recovery attempts. */
+export declare const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";

package/dist/agent/abort-errors.js

@@ -0,0 +1,21 @@
+export class AgentAbortError extends Error {
+    constructor(message = "Agent run cancelled.") {
+        super(message);
+        this.name = "AgentAbortError";
+    }
+}
+/**
+ * Abort tagged with why the runtime stopped a child, so finalization can map
+ * it to a SubagentFinalReason (design doc §3.1) instead of guessing from
+ * message strings.
+ */
+export class SubagentAbortError extends AgentAbortError {
+    subagentReason;
+    constructor(message, subagentReason) {
+        super(message);
+        this.subagentReason = subagentReason;
+        this.name = "SubagentAbortError";
+    }
+}
+/** Shown when the model produced no user-visible content despite recovery attempts. */
+export const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";

package/dist/agent/budget-ledger.d.ts

@@ -1,4 +1,5 @@
 import type { TokenUsage } from "../types.js";
+import type { SubagentTokenCap } from "./subagent-control.js";
 export interface BudgetUsageSource {
     runId: string;
     subAgentId?: string;
@@ -8,13 +9,53 @@ export interface BudgetSnapshot {
     limit?: number;
     exhausted: boolean;
 }
+/**
+ * Shared token ledger for a parent and all of its children, with per-source
+ * accounting so the runtime can enforce per-child caps (design doc §6).
+ * The shared pool limit is optional — both production hosts construct the
+ * ledger without one — so per-child caps must never be derived solely from
+ * "pool remaining"; see computeChildTokenCap.
+ */
 export declare class BudgetLedger {
     private readonly limit?;
     private spent;
+    private readonly spentBySource;
     private readonly controller;
     constructor(limit?: number | undefined);
     get signal(): AbortSignal;
     recordUsage(usage: TokenUsage, source: BudgetUsageSource): void;
+    /** Tokens attributed to one child (or the parent when subAgentId is omitted). */
+    spentBy(subAgentId?: string): number;
+    /** Pool tokens remaining, or undefined when the pool has no limit. */
+    remaining(): number | undefined;
+    get poolLimit(): number | undefined;
     snapshot(): BudgetSnapshot;
 }
+/** Default absolute per-child soft cap; applies even on limit-free hosts. */
+export declare const DEFAULT_CHILD_TOKEN_CAP = 200000;
+/** Share of a limited pool reserved for the parent's own turns. */
+export declare const PARENT_POOL_RESERVE_RATIO = 0.2;
+/** Hard cap sits at least this many tokens above the soft cap (≈ 2 turns). */
+export declare const CHILD_HARD_CAP_FLOOR = 20000;
+/**
+ * Per-child token cap, fixed at dispatch (design doc §6). The soft cap is an
+ * absolute number (config default 200k) so it is effective on limit-free
+ * hosts; when the pool *is* limited, the fair share of what remains after the
+ * parent's reserve further bounds it. The cap never shrinks mid-run because
+ * siblings spawned later.
+ */
+export declare function computeChildTokenCap(options: {
+    ledger?: BudgetLedger;
+    subAgentId: string;
+    activeChildren: number;
+    configCap?: number;
+    profileMaxTokens?: number;
+}): SubagentTokenCap;
+/**
+ * Hard cap recomputed at each turn-boundary check: at least ~2 of this
+ * child's average turns above the soft cap, never below the absolute floor
+ * (design doc §6 — replaces the fixed 25% ratio that could be smaller than a
+ * single turn).
+ */
+export declare function childHardCap(soft: number, avgTurnTokens: number): number;
 export declare function composeAbortSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined;

package/dist/agent/budget-ledger.js

@@ -1,6 +1,15 @@
+const PARENT_SOURCE_KEY = "__parent__";
+/**
+ * Shared token ledger for a parent and all of its children, with per-source
+ * accounting so the runtime can enforce per-child caps (design doc §6).
+ * The shared pool limit is optional — both production hosts construct the
+ * ledger without one — so per-child caps must never be derived solely from
+ * "pool remaining"; see computeChildTokenCap.
+ */
 export class BudgetLedger {
     limit;
     spent = 0;
+    spentBySource = new Map();
     controller = new AbortController();
     constructor(limit) {
         this.limit = limit;
@@ -11,10 +20,25 @@ export class BudgetLedger {
     recordUsage(usage, source) {
         const delta = usage.promptTokens + usage.completionTokens;
         this.spent += delta;
+        const key = source.subAgentId ?? PARENT_SOURCE_KEY;
+        this.spentBySource.set(key, (this.spentBySource.get(key) ?? 0) + delta);
         if (this.limit !== undefined && this.spent >= this.limit && !this.controller.signal.aborted) {
             this.controller.abort(budgetAbortError("Budget exhausted"));
         }
     }
+    /** Tokens attributed to one child (or the parent when subAgentId is omitted). */
+    spentBy(subAgentId) {
+        return this.spentBySource.get(subAgentId ?? PARENT_SOURCE_KEY) ?? 0;
+    }
+    /** Pool tokens remaining, or undefined when the pool has no limit. */
+    remaining() {
+        if (this.limit === undefined)
+            return undefined;
+        return Math.max(0, this.limit - this.spent);
+    }
+    get poolLimit() {
+        return this.limit;
+    }
     snapshot() {
         return {
             spent: this.spent,
@@ -23,6 +47,46 @@ export class BudgetLedger {
         };
     }
 }
+/** Default absolute per-child soft cap; applies even on limit-free hosts. */
+export const DEFAULT_CHILD_TOKEN_CAP = 200_000;
+/** Share of a limited pool reserved for the parent's own turns. */
+export const PARENT_POOL_RESERVE_RATIO = 0.2;
+/** Hard cap sits at least this many tokens above the soft cap (≈ 2 turns). */
+export const CHILD_HARD_CAP_FLOOR = 20_000;
+/**
+ * Per-child token cap, fixed at dispatch (design doc §6). The soft cap is an
+ * absolute number (config default 200k) so it is effective on limit-free
+ * hosts; when the pool *is* limited, the fair share of what remains after the
+ * parent's reserve further bounds it. The cap never shrinks mid-run because
+ * siblings spawned later.
+ */
+export function computeChildTokenCap(options) {
+    let soft = options.configCap ?? DEFAULT_CHILD_TOKEN_CAP;
+    if (options.profileMaxTokens !== undefined && options.profileMaxTokens > 0) {
+        soft = Math.min(soft, options.profileMaxTokens);
+    }
+    const limit = options.ledger?.poolLimit;
+    if (options.ledger && limit !== undefined) {
+        const reserve = Math.floor(limit * PARENT_POOL_RESERVE_RATIO);
+        const available = Math.max(0, (options.ledger.remaining() ?? 0) - reserve);
+        const share = Math.floor(available / (options.activeChildren + 1));
+        soft = Math.max(1, Math.min(soft, share));
+    }
+    return {
+        soft,
+        hard: soft + CHILD_HARD_CAP_FLOOR,
+        baseline: options.ledger?.spentBy(options.subAgentId) ?? 0,
+    };
+}
+/**
+ * Hard cap recomputed at each turn-boundary check: at least ~2 of this
+ * child's average turns above the soft cap, never below the absolute floor
+ * (design doc §6 — replaces the fixed 25% ratio that could be smaller than a
+ * single turn).
+ */
+export function childHardCap(soft, avgTurnTokens) {
+    return soft + Math.max(CHILD_HARD_CAP_FLOOR, Math.ceil(avgTurnTokens * 2));
+}
 function budgetAbortError(message) {
     const error = new Error(message);
     error.name = "AbortError";

package/dist/agent/child-runner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ChildRunner — executes one logical run of a subagent thread and reports the
+ * outcome to the scheduler (design doc §2, extracted in Phase 3).
+ *
+ * A logical run spans dispatch → final state; a rate-limit re-entry is the
+ * same logical run (no second SubagentStart), while a send_input restart is a
+ * new one. The runner owns: tool validation defense, instance reuse,
+ * turn-boundary budget enforcement, the handoff completeness guard, and the
+ * mapping of failures to SubagentFinalReason.
+ */
+import { BudgetLedger } from "./budget-ledger.js";
+import type { SubagentRunOutcome } from "./subagent-scheduler.js";
+import type { SubagentFinalReason, SubagentThreadRecord } from "./subagent-control.js";
+import type { AgentEvent, Message, ToolRegistryEntry, ToolUpdate } from "../types.js";
+export interface ChildRunOptions {
+    approval: "fail" | "disabled";
+    abortSignal?: AbortSignal;
+    forkContext?: boolean;
+    directEmit?: (update: ToolUpdate) => void;
+    queueUpdates?: boolean;
+    reuseAgent?: boolean;
+    /** 1-based scheduler attempt; >1 means rate-limit re-entry of the same logical run. */
+    attempt?: number;
+}
+export interface ChildRunnerHost {
+    allTools(): ToolRegistryEntry[];
+    budgetLedger(): BudgetLedger | undefined;
+    emit(record: SubagentThreadRecord, options: ChildRunOptions, status: ToolUpdate["status"], event?: AgentEvent, message?: string): void;
+    runLifecycleHook(record: SubagentThreadRecord, cwd: string, eventName: "SubagentStart" | "SubagentStop", status?: string, error?: string, abortSignal?: AbortSignal): Promise<void>;
+    finalizeBlocked(record: SubagentThreadRecord, error: string, options: ChildRunOptions): void;
+    createInstance(record: SubagentThreadRecord, tools: ToolRegistryEntry[], cwd: string, forkContext?: boolean): Promise<NonNullable<SubagentThreadRecord["agent"]>>;
+    notifyWaiters(record: SubagentThreadRecord): void;
+    /** Called on every final state so background results can be ingested (§5). */
+    onFinal(record: SubagentThreadRecord, options: ChildRunOptions): void;
+}
+export declare class ChildRunner {
+    private readonly host;
+    constructor(host: ChildRunnerHost);
+    run(record: SubagentThreadRecord, input: string | import("../types.js").ContentPart[], cwd: string, options: ChildRunOptions): Promise<SubagentRunOutcome>;
+    private runFinalSummaryTurn;
+}
+export declare function sanitizeSubagentSummary(value: string): string;
+/**
+ * Handoff completeness guard (design §3.2): a deterministic CJK-aware token
+ * floor and a cheap intermediate-narration prefix check run in parallel.
+ * Both only apply after the child actually used tools — a short direct answer
+ * to a trivial question is a complete handoff.
+ */
+export declare function needsExplicitFinalSummary(record: SubagentThreadRecord, executedAnyTool: boolean): boolean;
+export declare function classifySubagentAbortReason(reason: unknown, parentSignal: AbortSignal | undefined, ledger: BudgetLedger | undefined): SubagentFinalReason;
+/**
+ * Drops trailing "[model request interrupted ...]" boundary messages so a
+ * rate-limit re-entry resumes from clean history (design §4.5).
+ */
+export declare function stripTrailingModelInterruptedBoundary(messages: Message[]): void;