@bubblebrain-ai/bubble 0.0.21 → 0.0.22

package/dist/tools/child-tools.js

@@ -0,0 +1,106 @@
+/**
+ * Per-child tool factory for write_worktree subagents (design doc §8).
+ *
+ * Parent tools close over the parent cwd at creation, so a write child needs
+ * fresh instances bound to its worktree — with their own FileStateTracker —
+ * plus a worktree-scoped approval policy: file operations are runtime-checked
+ * to stay under the worktree root (the tools' own workspace fence does this
+ * structurally), bash auto-approves inside the worktree when the command
+ * passes a deny-list of escaping operations, and everything else fails fast.
+ */
+import { isAbsolute, resolve, sep } from "node:path";
+import { createBashTool } from "./bash.js";
+import { createEditTool } from "./edit.js";
+import { createGlobTool } from "./glob.js";
+import { createGrepTool } from "./grep.js";
+import { createReadTool } from "./read.js";
+import { createWriteTool } from "./write.js";
+import { FileStateTracker } from "./file-state.js";
+/** Operations a worktree child may never run, regardless of cwd. */
+const WORKTREE_BASH_DENY_PATTERNS = [
+    { pattern: /\bgit\s+push\b/, reason: "pushing from a subagent worktree is not allowed; the parent reviews and applies changes." },
+    { pattern: /\bgit\s+remote\b/, reason: "remote configuration is not allowed inside a subagent worktree." },
+    { pattern: /\bgit\s+worktree\b/, reason: "managing worktrees from inside a subagent worktree is not allowed." },
+    { pattern: /\bsudo\b/, reason: "privileged commands are not allowed inside a subagent worktree." },
+];
+export function isPathInsideWorktree(worktreeRoot, candidate) {
+    const resolved = isAbsolute(candidate) ? resolve(candidate) : resolve(worktreeRoot, candidate);
+    const root = resolve(worktreeRoot);
+    return resolved === root || resolved.startsWith(root + sep);
+}
+/**
+ * Approval policy for a worktree child: containment is enforced by code
+ * (path checks, deny-list), never by prompt text. There is no interactive
+ * fallback — anything outside the policy fails fast (design §11).
+ */
+export class WorktreeApprovalController {
+    worktreeRoot;
+    constructor(worktreeRoot) {
+        this.worktreeRoot = worktreeRoot;
+    }
+    async request(req) {
+        switch (req.type) {
+            case "bash": {
+                for (const { pattern, reason } of WORKTREE_BASH_DENY_PATTERNS) {
+                    if (pattern.test(req.command)) {
+                        return { action: "reject", feedback: `Blocked by worktree policy: ${reason}` };
+                    }
+                }
+                if (!isPathInsideWorktree(this.worktreeRoot, req.cwd)) {
+                    return { action: "reject", feedback: "Blocked by worktree policy: commands must run inside the subagent worktree." };
+                }
+                // Absolute paths reaching outside the worktree are an escape attempt.
+                const absolutePaths = req.command.match(/(?<=^|[\s"'=])\/[^\s"';|&]+/g) ?? [];
+                for (const path of absolutePaths) {
+                    if (path.startsWith("/dev/") || path.startsWith("/tmp/") || path.startsWith("/usr/") || path.startsWith("/bin/") || path.startsWith("/opt/") || path.startsWith("/etc/"))
+                        continue;
+                    if (!isPathInsideWorktree(this.worktreeRoot, path)) {
+                        return {
+                            action: "reject",
+                            feedback: `Blocked by worktree policy: the command references a path outside the worktree (${path}).`,
+                        };
+                    }
+                }
+                return { action: "approve" };
+            }
+            case "edit":
+            case "write":
+                return isPathInsideWorktree(this.worktreeRoot, req.path)
+                    ? { action: "approve" }
+                    : { action: "reject", feedback: `Blocked by worktree policy: ${req.path} is outside the subagent worktree.` };
+            case "patch":
+                return req.paths.every((path) => isPathInsideWorktree(this.worktreeRoot, path))
+                    ? { action: "approve" }
+                    : { action: "reject", feedback: "Blocked by worktree policy: the patch touches paths outside the subagent worktree." };
+            case "lsp":
+                return { action: "approve" };
+            case "agent_profile":
+                return { action: "reject", feedback: "Subagents cannot approve agent profiles." };
+        }
+    }
+    checkRules() {
+        return { decision: "ask" };
+    }
+}
+const WORKTREE_TOOL_NAMES = new Set(["read", "glob", "grep", "edit", "write", "bash"]);
+/**
+ * Builds the write child's toolset bound to its worktree: fresh instances
+ * with their own FileStateTracker and the worktree approval policy. A
+ * profile's tools list can narrow the set but never widen it.
+ */
+export function createWorktreeChildTools(worktreeCwd, include) {
+    const approval = new WorktreeApprovalController(worktreeCwd);
+    const fileState = new FileStateTracker(worktreeCwd);
+    const tools = [
+        createReadTool(worktreeCwd, approval, undefined, fileState),
+        createGlobTool(worktreeCwd),
+        createGrepTool(worktreeCwd),
+        createEditTool(worktreeCwd, approval, undefined, fileState),
+        createWriteTool(worktreeCwd, {}, approval, undefined, fileState),
+        createBashTool(worktreeCwd, approval, fileState),
+    ];
+    if (!include || include.length === 0)
+        return tools;
+    const requested = new Set(include.filter((name) => WORKTREE_TOOL_NAMES.has(name)));
+    return requested.size > 0 ? tools.filter((tool) => requested.has(tool.name)) : tools;
+}

package/dist/tools/index.js

@@ -57,7 +57,7 @@ export function createAllTools(cwd, skillRegistry, options = {}) {
         createWebFetchTool(approval),
         createMemorySearchTool(cwd),
         createMemoryReadSummaryTool(cwd),
-        ...createAgentLifecycleTools(),
+        ...createAgentLifecycleTools({ cwd, approval }),
         ...(options.questionController ? [createQuestionTool(options.questionController)] : []),
         ...(skillRegistry ? [createSkillSearchTool(skillRegistry), createSkillTool(skillRegistry)] : []),
         ...(options.todoStore ? [createTodoTool(options.todoStore)] : []),

package/dist/tui/run.d.ts

@@ -2,7 +2,7 @@ import { type Agent } from "../agent.js";
 import type { CliArgs } from "../cli.js";
 import type { ThemeMode } from "../config.js";
 import type { ExternalHookController } from "../hooks/controller.js";
-import type { SessionManager } from "../session.js";
+import { SessionManager } from "../session.js";
 import type { PlanDecision, Provider } from "../types.js";
 import type { ProviderRegistry } from "../provider-registry.js";
 import type { SkillRegistry } from "../skills/registry.js";
@@ -45,5 +45,15 @@ export interface RunTuiOptions {
     runMemoryRefresh?: (scope?: MemoryScope) => Promise<string>;
     /** One-line "update available" notice shown on the home screen, if any. */
     updateNotice?: string;
+    /**
+     * Swap the active session in place (driven by the /session picker).
+     * Rebinds persistence to the picked session file and replaces the agent's
+     * message history; the TUI rebuilds its transcript from the result.
+     */
+    switchSession?: (sessionFile: string) => {
+        manager: SessionManager;
+    } | {
+        error: string;
+    };
 }
 export declare function runTui(agent: Agent, args: CliArgs, options?: RunTuiOptions): Promise<void>;

package/dist/tui/run.js

@@ -12,6 +12,8 @@ import { debugReasoningStream, summarizeDebugText } from "../reasoning-debug.js"
 import { isHiddenToolMetadata } from "../agent/discovery-barrier.js";
 import { createStreamingInternalReminderSanitizer, sanitizeInternalReasoningText, sanitizeInternalReminderBlocks, } from "../agent/internal-reminder-sanitizer.js";
 import { summarizeAgentEventForTrace, summarizeTraceError, summarizeTraceValue, traceEvent, } from "../debug-trace.js";
+import { SessionManager } from "../session.js";
+import { buildSessionPickerEntries, preferredSessionPickerIndex } from "./session-picker-data.js";
 import { BUILTIN_PROVIDERS, decodeModel, displayModel, isUserVisibleProvider } from "../provider-registry.js";
 import { calculateUsageCost } from "../model-pricing.js";
 import { getAvailableThinkingLevels } from "../provider-transform.js";
@@ -1177,7 +1179,13 @@ function OpenTuiApp(props) {
             promptModelLabels.delete(ref);
     };
     const cycleMode = () => {
-        if (picker || pendingPlan() || isRunning())
+        // Mode switching is intentionally allowed while the agent is running:
+        // Agent.setMode() is safe mid-run and the approval controller reads the
+        // live mode on every request, so flipping to bypass (or into plan) takes
+        // effect from the very next tool call — no need to wait for the turn to
+        // finish. Only pickers and the plan-approval dialog still block it,
+        // because those surfaces own the keyboard.
+        if (picker || pendingPlan())
             return false;
         const next = getNextPermissionMode(props.agent.mode);
         props.agent.setMode(next);
@@ -3042,7 +3050,10 @@ function OpenTuiApp(props) {
                 // "(current)" sits at the bottom of the rewind list and is the safe default.
                 : step === "rewind"
                     ? Math.max(0, items.length - 1)
-                    : 0,
+                    // Sessions: start on the most recent conversation that is not the active one.
+                    : step === "sessions"
+                        ? preferredSessionPickerIndex(items)
+                        : 0,
             apiKey: "",
         };
         activePrompt()?.clear();
@@ -3077,6 +3088,8 @@ function OpenTuiApp(props) {
             return buildRewindPickerItems();
         if (step === "rewind-action")
             return buildRewindActionItems(providerId);
+        if (step === "sessions")
+            return buildSessionPickerItems();
         if (step === "models") {
             if (providerDialogModelItems?.key === modelPickerCacheKey(providerId)) {
                 return providerDialogModelItems.items;
@@ -3319,6 +3332,8 @@ function OpenTuiApp(props) {
             return "Rewind — restore to the point before…";
         if (state.step === "rewind-action")
             return "Rewind — what to restore?";
+        if (state.step === "sessions")
+            return "Resume a session";
         const provider = providerDisplayName(state.providerId);
         if (state.step === "auth")
             return `${provider} auth method`;
@@ -3343,6 +3358,8 @@ function OpenTuiApp(props) {
             return `↑/↓ move · enter continue · esc cancel${count}`;
         if (state.step === "rewind-action")
             return "↑/↓ move · enter confirm · esc back";
+        if (state.step === "sessions")
+            return `↑/↓ move · enter resume · esc close${count}`;
         const escLabel = state.step === "providers" ? "esc close" : "esc back";
         return `↑/↓ move · enter select · ${escLabel}${count}`;
     }
@@ -3360,7 +3377,7 @@ function OpenTuiApp(props) {
     }
     function providerDialogColumnWidths(state, panelWidth) {
         const contentWidth = Math.max(24, panelWidth - PROVIDER_DIALOG_ROW_RESERVED_WIDTH);
-        const footer = state.step === "skills" ? 10 : state.step === "providers" ? 9 : 8;
+        const footer = state.step === "skills" || state.step === "sessions" ? 10 : state.step === "providers" ? 9 : 8;
         const minLabel = state.step === "skills" ? 18 : 24;
         const desiredDetail = state.step === "skills"
             ? 30
@@ -3370,7 +3387,9 @@ function OpenTuiApp(props) {
                     ? 40
                     : state.step === "rewind"
                         ? 18
-                        : 16;
+                        : state.step === "sessions"
+                            ? 14
+                            : 16;
         const detail = Math.max(8, Math.min(desiredDetail, contentWidth - footer - minLabel));
         const label = Math.max(8, contentWidth - detail - footer);
         return { label, detail, footer };
@@ -3579,6 +3598,15 @@ function OpenTuiApp(props) {
             openProviderDialog("rewind-action", item.value);
             return;
         }
+        if (state.step === "sessions") {
+            closeProviderDialog();
+            if (!item.value || item.value === props.options.sessionManager?.getSessionFile()) {
+                // Selecting the active session keeps everything as is.
+                return;
+            }
+            await switchToSession(item.value);
+            return;
+        }
         if (state.step === "rewind-action") {
             closeProviderDialog();
             await executeSlash(item.command);
@@ -4909,6 +4937,9 @@ function OpenTuiApp(props) {
             openRewindPicker: () => {
                 openProviderDialog("rewind");
             },
+            openSessionPicker: () => {
+                openProviderDialog("sessions");
+            },
             fillComposer: (text) => {
                 resetPromptHistoryBrowse();
                 setPromptText(text);
@@ -5256,6 +5287,44 @@ function OpenTuiApp(props) {
         items.push({ label: "(current)", value: "", command: "" });
         return items;
     }
+    function buildSessionPickerItems() {
+        const activeFile = props.options.sessionManager?.getSessionFile();
+        const summaries = SessionManager.summarizeSessionsForCwd(props.args.cwd);
+        return buildSessionPickerEntries(summaries, activeFile).map((entry) => ({
+            label: entry.label,
+            detail: entry.detail,
+            value: entry.value,
+            command: "",
+            footer: entry.footer,
+            gutter: entry.gutter,
+        }));
+    }
+    async function switchToSession(sessionFile) {
+        const switchSession = props.options.switchSession;
+        if (!switchSession) {
+            addMessage("error", "Session switching is not available in this mode.");
+            return;
+        }
+        if (isRunning()) {
+            setNotice("Stop the current run before switching sessions.");
+            return;
+        }
+        const result = switchSession(sessionFile);
+        if ("error" in result) {
+            addMessage("error", `Failed to switch session: ${result.error}`);
+            return;
+        }
+        props.options.sessionManager = result.manager;
+        // Same rebuild path as /rewind: the agent history was replaced wholesale,
+        // so reconstruct the transcript from it instead of patching the display.
+        displayMessages = reconstructDisplayMessages(props.agent.messages);
+        streamingDisplay = undefined;
+        redrawTranscript(undefined, displayMessages);
+        syncTodosFromAgent();
+        bumpSidebar();
+        syncPromptSurfaces(true);
+        addMessage("assistant", `⤷ Resumed session: ${sessionDisplayName(result.manager)}`);
+    }
     function buildRewindActionItems(turnNumber) {
         if (!turnNumber)
             return [];
@@ -9340,6 +9409,17 @@ function getApprovalPanelMeta(request) {
             path: request.path,
         };
     }
+    if (request.type === "agent_profile") {
+        return {
+            icon: "@",
+            title: `Trust project agent profile "${request.name}"`,
+            subtitle: "from .bubble/agents — its prompt will drive a subagent",
+            preview: `${shortCwd(request.path)}\n${request.promptPreview}`,
+            previewHeight: 8,
+            previewColor: theme.toolText,
+            path: request.path,
+        };
+    }
     const path = shortCwd(request.path);
     if (request.type === "edit") {
         return {
@@ -9454,6 +9534,8 @@ function displayToolName(name) {
         wait_agent: "WaitAgent",
         send_input: "SendInput",
         close_agent: "CloseAgent",
+        list_agents: "ListAgents",
+        agent_team: "AgentTeam",
         task: "Task",
         todo: "Todo",
         question: "Questions",
@@ -9476,6 +9558,12 @@ function toolHeader(tool) {
         const agentId = args.agent_id ?? (Array.isArray(args.agent_ids) ? `${args.agent_ids.length} agents` : undefined);
         return agentId ? `(${truncate(String(agentId), 64)})` : "";
     }
+    if (tool.name === "agent_team") {
+        const items = Array.isArray(args.items) ? `${args.items.length} items` : "";
+        const description = typeof args.description === "string" ? args.description : "";
+        const label = [description, items].filter(Boolean).join(", ");
+        return label ? `(${truncate(label, 64)})` : "";
+    }
     const value = args.path ?? args.command ?? args.pattern ?? args.url ?? args.query ?? toolPath(tool);
     return value ? `(${truncate(String(value).replace(/\n/g, " "), 64)})` : "";
 }

package/dist/tui/session-picker-data.d.ts

@@ -0,0 +1,18 @@
+import type { SessionSummary } from "../session.js";
+export interface SessionPickerEntry {
+    /** Session title (or first-message preview when untitled). */
+    label: string;
+    /** Message count, e.g. "12 messages". */
+    detail: string;
+    /** Absolute path to the session .jsonl file. */
+    value: string;
+    /** "current" for the active session, otherwise a relative timestamp. */
+    footer: string;
+    /** "●" marks the active session. */
+    gutter?: string;
+}
+export declare function buildSessionPickerEntries(summaries: SessionSummary[], activeFile: string | undefined, now?: number): SessionPickerEntry[];
+/** Default selection: the most recent session that is not the active one. */
+export declare function preferredSessionPickerIndex(entries: Array<{
+    gutter?: string;
+}>): number;

package/dist/tui/session-picker-data.js

@@ -0,0 +1,21 @@
+import { normalizeSingleLine, truncateVisual } from "../text-display.js";
+import { formatRelativeTime } from "./recent-activity.js";
+const SESSION_PICKER_LABEL_MAX_WIDTH = 72;
+export function buildSessionPickerEntries(summaries, activeFile, now = Date.now()) {
+    return summaries.map((summary) => {
+        const isCurrent = summary.file === activeFile;
+        const label = truncateVisual(normalizeSingleLine(summary.title || summary.preview || summary.name), SESSION_PICKER_LABEL_MAX_WIDTH) || summary.name;
+        return {
+            label,
+            detail: `${summary.messageCount} message${summary.messageCount === 1 ? "" : "s"}`,
+            value: summary.file,
+            footer: isCurrent ? "current" : formatRelativeTime(summary.mtime, now),
+            gutter: isCurrent ? "●" : undefined,
+        };
+    });
+}
+/** Default selection: the most recent session that is not the active one. */
+export function preferredSessionPickerIndex(entries) {
+    const firstOther = entries.findIndex((entry) => entry.gutter !== "●");
+    return firstOther >= 0 ? firstOther : 0;
+}

package/dist/tui/wordmark.d.ts

@@ -8,6 +8,8 @@ export interface BubbleWordmarkLine {
     tone?: BubbleWordmarkTone;
     segments?: BubbleWordmarkSegment[];
 }
+export declare const BUBBLE_CAT: BubbleWordmarkLine[];
+export declare const BUBBLE_CAT_LARGE: BubbleWordmarkLine[];
 export declare const BUBBLE_WORDMARK: BubbleWordmarkLine[];
 export declare const BUBBLE_WORDMARK_LARGE: BubbleWordmarkLine[];
 export declare const BUBBLE_COMPACT_WORDMARK: BubbleWordmarkLine[];

package/dist/tui/wordmark.js

@@ -22,6 +22,27 @@ const LOWER_B = {
         "    ",
     ],
 };
+// Pixel cat mascot, drawn on the same half-block pixel grid as the letters:
+// pointy ears, 2x2-pixel eyes, tiny mouth, round chin (10x14 pixels). It is
+// stacked above the wordmark (icon-over-name lockup) rather than inlined, so
+// its solid fill doesn't compete with the thin letter strokes.
+const CAT_LINES = [
+    " █▄    ▄█ ",
+    " ███▄▄███ ",
+    "██████████",
+    "█  ████  █",
+    "████▀▀████",
+    "██████████",
+    " ▀██████▀ ",
+];
+export const BUBBLE_CAT = CAT_LINES.map((text) => ({
+    text,
+    tone: "brand",
+}));
+export const BUBBLE_CAT_LARGE = CAT_LINES.map((text) => ({
+    text: text.split("").map((ch) => ch + ch).join(""),
+    tone: "brand",
+}));
 const GLYPHS = {
     u: {
         tone: "ink",
@@ -172,10 +193,16 @@ export function bubbleWordmarkLineText(line) {
 export function bubbleWordmarkMaxWidth(lines = BUBBLE_WORDMARK) {
     return Math.max(...lines.map((line) => bubbleWordmarkLineText(line).length));
 }
+const LOGO_GAP = { text: "", tone: "caption" };
+// Icon-over-name lockup: pixel cat centered above the wordmark. Both render
+// sites center every line independently, which is what stacks the cat over
+// the text without any per-line padding here.
 export function bubbleWordmarkForWidth(width) {
-    if (width >= bubbleWordmarkMaxWidth(BUBBLE_WORDMARK_LARGE) + 4)
-        return BUBBLE_WORDMARK_LARGE;
-    if (width >= bubbleWordmarkMaxWidth() + 4)
-        return BUBBLE_WORDMARK;
+    if (width >= bubbleWordmarkMaxWidth(BUBBLE_WORDMARK_LARGE) + 4) {
+        return [...BUBBLE_CAT_LARGE, LOGO_GAP, ...BUBBLE_WORDMARK_LARGE];
+    }
+    if (width >= bubbleWordmarkMaxWidth() + 4) {
+        return [...BUBBLE_CAT, LOGO_GAP, ...BUBBLE_WORDMARK];
+    }
     return BUBBLE_COMPACT_WORDMARK;
 }

package/dist/tui-ink/approval/approval-dialog.js

@@ -77,6 +77,8 @@ function dialogTitle(req) {
             return "Bash command";
         case "lsp":
             return "Language server operation";
+        case "agent_profile":
+            return "Project agent profile";
     }
 }
 function dialogQuestion(req) {
@@ -91,6 +93,8 @@ function dialogQuestion(req) {
             return "Do you want to proceed?";
         case "lsp":
             return `Do you want to run ${req.operation} on ${basename(req.path)}?`;
+        case "agent_profile":
+            return `Trust the repository profile "${req.name}" to drive a subagent? It is remembered for this session until the file changes.`;
     }
 }
 function basename(p) {
@@ -107,8 +111,14 @@ function RequestPreview({ request }) {
             return _jsx(DiffView, { diff: request.diff });
         case "write":
             return _jsx(WritePreview, { path: request.path, content: request.content });
+        case "agent_profile":
+            return _jsx(AgentProfilePreview, { path: request.path, promptPreview: request.promptPreview });
     }
 }
+function AgentProfilePreview({ path, promptPreview }) {
+    const theme = useTheme();
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: theme.muted, children: compressHome(path) }), _jsx(Text, { children: promptPreview }), _jsx(Text, { color: theme.warning, children: "This prompt comes from the repository's .bubble/agents and will drive a subagent." })] }));
+}
 function BashPreview({ command, cwd }) {
     const theme = useTheme();
     const danger = classifyBashDanger(command);

package/dist/tui-opentui/approval/approval-dialog.js

@@ -84,6 +84,8 @@ function dialogTitle(req) {
             return "Bash command";
         case "lsp":
             return "Language server operation";
+        case "agent_profile":
+            return "Project agent profile";
     }
 }
 function dialogQuestion(req) {
@@ -98,6 +100,8 @@ function dialogQuestion(req) {
             return "Do you want to proceed?";
         case "lsp":
             return `Do you want to run ${req.operation} on ${basename(req.path)}?`;
+        case "agent_profile":
+            return `Trust the repository profile "${req.name}" to drive a subagent? It is remembered for this session until the file changes.`;
     }
 }
 function basename(p) {
@@ -114,8 +118,14 @@ function RequestPreview({ request }) {
             return _jsx(DiffView, { diff: request.diff });
         case "write":
             return _jsx(WritePreview, { path: request.path, content: request.content });
+        case "agent_profile":
+            return _jsx(AgentProfilePreview, { path: request.path, promptPreview: request.promptPreview });
     }
 }
+function AgentProfilePreview({ path, promptPreview }) {
+    const theme = useTheme();
+    return (_jsxs("box", { style: { flexDirection: "column" }, children: [_jsx("text", { fg: theme.muted, children: compressHome(path) }), _jsx("text", { children: promptPreview }), _jsx("box", { style: { marginTop: 1 }, children: _jsx("text", { fg: theme.warning, children: "This prompt comes from the repository's .bubble/agents and will drive a subagent." }) })] }));
+}
 function BashPreview({ command, cwd }) {
     const theme = useTheme();
     const danger = classifyBashDanger(command);

package/dist/types.d.ts

@@ -199,6 +199,16 @@ export interface ToolContext {
         }) => Promise<import("./agent/subagent-control.js").SubagentThreadSnapshot>;
         closeSubAgent?: (agentId: string) => Promise<import("./agent/subagent-control.js").SubagentThreadSnapshot>;
         listSubAgents?: () => import("./agent/subagent-control.js").SubagentThreadSnapshot[];
+        runAgentTeam?: (cwd: string, options: {
+            profile: import("./agent/profiles.js").AgentProfile;
+            category?: string;
+            promptTemplate: string;
+            items: string[];
+            parentToolCallId: string;
+            emitUpdate?: (update: ToolUpdate) => void;
+            abortSignal?: AbortSignal;
+            approval?: "fail" | "disabled";
+        }) => Promise<import("./agent/subagent-control.js").SubagentThreadSnapshot[]>;
     };
     emitUpdate?: (update: ToolUpdate) => void;
 }
@@ -291,6 +301,13 @@ export interface Provider {
         temperature?: number;
         thinkingLevel?: ThinkingLevel;
         abortSignal?: AbortSignal;
+        /**
+         * How the transport treats HTTP 429 (design doc §4.5). "handle"
+         * (default): retry inside the transport. "defer": throw a typed
+         * RateLimitError immediately so the caller owns the backoff — used by
+         * subagent routes where the scheduler is the single 429 backoff layer.
+         */
+        rateLimitPolicy?: import("./network/errors.js").RateLimitPolicy;
     }): AsyncIterable<StreamChunk>;
     complete(messages: ProviderMessage[], options?: {
         model?: string;

package/package.json

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