@bubblebrain-ai/bubble 0.0.53 → 0.0.55

package/README.md

@@ -67,6 +67,49 @@ Resume your last conversation:
 bubble --resume
 ```
 
+## Embed with the SDK
+
+The npm package exports `BubbleSdk` from both `@bubblebrain-ai/bubble` and
+`@bubblebrain-ai/bubble/sdk`. Turns are serialized FIFO within one session and
+remain parallel across different sessions.
+
+```ts
+import { BubbleSdk } from "@bubblebrain-ai/bubble/sdk";
+
+const sdk = new BubbleSdk({ defaultCwd: process.cwd() });
+const session = sdk.createSession();
+const events = sdk.runTurn(session.id, { prompt: "Inspect this project" });
+
+for await (const event of events) {
+  if (event.type === "text_delta") process.stdout.write(event.content);
+}
+
+const queued = sdk.enqueueTurn(session.id, { prompt: "Run the tests next" });
+void (async () => {
+  for await (const event of queued) {
+    // Render the queued turn's events.
+  }
+})();
+```
+
+While a turn owns the session slot, `sdk.steer(session.id, text)` adds text at
+the next model-call boundary and returns a receipt: `steered` (injected into
+the active turn), `queued` (the session is idle or the active turn can no
+longer accept input, so the text becomes the next FIFO turn automatically),
+or `rejected`. Every accepted receipt includes an `outcome` promise that
+settles exactly once to `input_applied`, `input_queued`, or `input_rejected` —
+even if the host drops the event iterator early.
+
+Turns are driven by the SDK itself, not by iterator consumption: a returned
+iterator is a replay subscription, so dropping it never stalls or cancels the
+turn. `openSession(sessionId)` returns a durable handle whose `events` iterable
+replays the whole session log from sequence 1 and `eventsFrom(n)` resumes after
+the last sequence the host durably processed. `stop(sessionId)` is
+Claude-style: it interrupts the active turn and keeps the queue; pass
+`{ cancelQueued: true }` to clear both. `clearQueue(sessionId)` cancels only
+queued turns, and `deleteSession(sessionId)` awaits teardown before the JSONL
+file is removed.
+
 ## Model providers
 
 Bubble ships with a catalog of built-in providers. Configure them inside the app — no environment variables required.

package/dist/agent/input-controller.d.ts

@@ -3,9 +3,12 @@ export declare class AgentRunInputQueue implements AgentInputController {
     private readonly idPrefix;
     private pending;
     private nextInputId;
+    private accepting;
     constructor(idPrefix?: string);
     enqueue(content: string): AgentRunInput;
+    tryEnqueue(content: string): AgentRunInput | undefined;
     drainPendingInputs(): AgentRunInput[];
     pendingInputCount(): number;
     clear(): AgentRunInput[];
+    closePendingInputs(): AgentRunInput[];
 }

package/dist/agent/input-controller.js

@@ -2,10 +2,19 @@ export class AgentRunInputQueue {
     idPrefix;
     pending = [];
     nextInputId = 0;
+    accepting = true;
     constructor(idPrefix = "input") {
         this.idPrefix = idPrefix;
     }
     enqueue(content) {
+        const input = this.tryEnqueue(content);
+        if (!input)
+            throw new Error("Agent input queue is closed");
+        return input;
+    }
+    tryEnqueue(content) {
+        if (!this.accepting)
+            return undefined;
         const input = {
             id: `${this.idPrefix}-${++this.nextInputId}`,
             content,
@@ -27,4 +36,8 @@ export class AgentRunInputQueue {
     clear() {
         return this.drainPendingInputs();
     }
+    closePendingInputs() {
+        this.accepting = false;
+        return this.drainPendingInputs();
+    }
 }

package/dist/agent.js

@@ -644,7 +644,11 @@ export class Agent {
             return events;
         };
         const rejectPendingInputs = async (reason) => {
-            const pendingInputs = inputController?.drainPendingInputs() ?? [];
+            // Seal before the first await. A host can submit in reaction to the final
+            // turn boundary; accepting after this drain would orphan that input.
+            const pendingInputs = inputController?.closePendingInputs?.()
+                ?? inputController?.drainPendingInputs()
+                ?? [];
             if (pendingInputs.length === 0)
                 return [];
             const events = [];
@@ -697,6 +701,8 @@ export class Agent {
                 yield emit({ type: "turn_start" });
                 yield emit({ type: "text_delta", content: message });
                 yield emit({ type: "turn_end", willContinue: false });
+                for (const event of await rejectPendingInputs("no_continuation"))
+                    yield emit(event);
                 yield emit({ type: "agent_end" });
                 return;
             }

package/dist/model-catalog.js

@@ -87,6 +87,9 @@ const ANTHROPIC_CHAT_LEVELS = ["off"];
 const GROK_45_LEVELS = ["low", "medium", "high"];
 const GEMINI_3_LEVELS = ["low", "medium", "high"];
 const GEMINI_3_FLASH_LEVELS = ["minimal", "low", "medium", "high"];
+// Verified against the native API on 2026-09-02: Gemini 3.7/3.8 Flash reject
+// thinkingLevel=minimal but accept thinkingBudget=0 plus low/medium/high.
+const GEMINI_37_38_FLASH_LEVELS = ["off", "low", "medium", "high"];
 const GEMINI_25_PRO_LEVELS = ["low", "medium", "high"];
 const GEMINI_25_FLASH_LEVELS = ["off", "low", "medium", "high"];
 export const BUILTIN_MODELS = [
@@ -126,8 +129,10 @@ export const BUILTIN_MODELS = [
     { id: "deepseek-v4-pro", name: "deepseek-v4-pro", providerId: "deepseek", tier: "strong", reasoningLevels: DEEPSEEK_V4_LEVELS, defaultReasoningLevel: "high", contextWindow: 1048576 },
     // Offline/no-key fallback only: with an API key the registry replaces this
     // list via fetchGeminiModels (GET /v1beta/models, newest five). Gemini 3
-    // exposes thinking_level (minimal/low/medium/high); 2.5 Pro cannot disable
-    // thinking (no "off"), 2.5 Flash can (thinkingBudget 0).
+    // thinking support varies by release: 3.7/3.8 Flash support off/low/medium/high
+    // while older Flash releases expose minimal/low/medium/high.
+    { id: "gemini-3.8-flash", name: "Gemini 3.8 Flash", providerId: "google", tier: "fast", reasoningLevels: GEMINI_37_38_FLASH_LEVELS, contextWindow: 1048576 },
+    { id: "gemini-3.7-flash", name: "Gemini 3.7 Flash", providerId: "google", tier: "fast", reasoningLevels: GEMINI_37_38_FLASH_LEVELS, contextWindow: 1048576 },
     { id: "gemini-3.5-flash", name: "Gemini 3.5 Flash", providerId: "google", tier: "fast", reasoningLevels: GEMINI_3_FLASH_LEVELS, contextWindow: 1048576 },
     { id: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro", providerId: "google", tier: "strong", reasoningLevels: GEMINI_3_LEVELS, defaultReasoningLevel: "high", contextWindow: 1048576 },
     { id: "gemini-3-flash-preview", name: "Gemini 3 Flash", providerId: "google", tier: "fast", reasoningLevels: GEMINI_3_FLASH_LEVELS, contextWindow: 1048576 },

package/dist/model-pricing.d.ts

@@ -35,11 +35,7 @@ export interface ModelPricing extends ModelPricingRate {
     /** Rate used before `effectiveFrom` (for historical session statistics). */
     prior?: ModelPricingRate;
     effectiveUntil?: string;
-    original?: {
-        inputCacheHitPerMillion: number;
-        inputCacheMissPerMillion: number;
-        outputPerMillion: number;
-    };
+    original?: ModelPricingRate;
 }
 /**
  * Hand-maintained corrections layered over the generated models.dev snapshot.

package/dist/provider-ai-sdk.js

@@ -509,6 +509,11 @@ export function selectLatestGeminiModels(entries, limit = 5) {
 export function geminiReasoningLevels(modelId) {
     const version = Number.parseFloat(/^gemini-(\d+(?:\.\d+)?)/.exec(modelId)?.[1] ?? "0");
     const isPro = modelId.includes("-pro");
+    // Live probes show 3.7 and 3.8 Flash share this newer ladder. Keep the
+    // exception bounded to verified releases instead of guessing for 3.9+.
+    if (!isPro && (version === 3.7 || version === 3.8)) {
+        return ["off", "low", "medium", "high"];
+    }
     if (version >= 3) {
         return isPro ? ["low", "medium", "high"] : ["minimal", "low", "medium", "high"];
     }

package/dist/provider-registry.js

@@ -11,7 +11,7 @@ import { getBubbleHome } from "./bubble-home.js";
 import { BUILTIN_PROVIDERS as CATALOG_PROVIDERS, clearDynamicModelMetadata, getBuiltinModel, getBuiltinProvider, inferGrokModelMetadata, listBuiltinModels, replaceDynamicModelMetadata, } from "./model-catalog.js";
 import { ModelConfig } from "./model-config.js";
 import { AuthStorage } from "./oauth/index.js";
-import { fetchGeminiModels } from "./provider-ai-sdk.js";
+import { fetchGeminiModels, geminiReasoningLevels } from "./provider-ai-sdk.js";
 import { extractChatGptAccountId, fetchOpenAICodexModelCatalog } from "./provider-openai-codex.js";
 import { fetchGrokSubscriptionModels } from "./provider-grok.js";
 import { refreshOpenAICodex } from "./oauth/openai-codex.js";
@@ -169,18 +169,23 @@ export class ProviderRegistry {
                     continue;
                 if (!entry.result || !Array.isArray(entry.result.models))
                     continue;
+                const provider = { id: entry.providerId ?? "", authType: entry.authType, protocol: entry.protocol };
+                // Capability fields may have been derived by an older Bubble build.
+                // Recompute them with the current code while retaining cached remote
+                // membership, display names and context windows.
+                const result = normalizeProviderDiscoveryMetadata(provider, entry.result);
                 this.modelDiscoveryCache.set(key, {
-                    result: entry.result,
+                    result,
                     expiresAt: entry.expiresAt,
                     identityKey: entry.identityKey ?? "unknown",
-                    providerId: entry.providerId ?? "",
+                    providerId: provider.id,
                     authType: entry.authType,
                     protocol: entry.protocol,
                 });
                 // Rebuild the dynamic overlay so context window / reasoning levels
                 // resolve from the cached catalog at startup, not only on /model open.
                 if (entry.providerId) {
-                    this.applyDynamicDiscoveryMetadata({ id: entry.providerId, authType: entry.authType, protocol: entry.protocol }, entry.result);
+                    this.applyDynamicDiscoveryMetadata(provider, result);
                 }
             }
         }
@@ -513,6 +518,8 @@ export class ProviderRegistry {
         if (!options.forceRefresh) {
             const cached = this.modelDiscoveryCache.get(key);
             if (cached && cached.expiresAt > now) {
+                const cachedResult = normalizeProviderDiscoveryMetadata(provider, cached.result);
+                cached.result = cachedResult;
                 // A disk cache can outlive the application version that wrote it. Keep
                 // the current curated catalog authoritative over stale cached metadata,
                 // then retain cached remote-only ids for non-authoritative union results.
@@ -520,12 +527,12 @@ export class ProviderRegistry {
                 // without waiting up to 24 hours or requiring a manual Ctrl+R refresh.
                 const local = this.localModelsForProvider(provider);
                 const localIds = new Set(local.map((model) => model.id));
-                const models = cached.result.source === "static"
+                const models = cachedResult.source === "static"
                     ? local
-                    : cached.result.authoritative
-                        ? cached.result.models
-                        : [...local, ...cached.result.models.filter((model) => !localIds.has(model.id))];
-                const result = { ...cached.result, models, source: "cache" };
+                    : cachedResult.authoritative
+                        ? cachedResult.models
+                        : [...local, ...cachedResult.models.filter((model) => !localIds.has(model.id))];
+                const result = { ...cachedResult, models, source: "cache" };
                 const current = this.getConfigured().find((item) => item.id === provider.id);
                 if (!current || this.modelDiscoveryKey(current) === key) {
                     this.applyDynamicDiscoveryMetadata(provider, result);
@@ -544,7 +551,8 @@ export class ProviderRegistry {
         const generation = (this.modelDiscoveryGeneration.get(provider.id) ?? 0) + 1;
         this.modelDiscoveryGeneration.set(provider.id, generation);
         let pending;
-        pending = this.performModelDiscovery(provider).then((result) => {
+        pending = this.performModelDiscovery(provider).then((rawResult) => {
+            const result = normalizeProviderDiscoveryMetadata(provider, rawResult);
             if (!this.isCurrentModelDiscovery(provider, key, generation)) {
                 return {
                     models: this.localModelsForProvider(this.getConfigured().find((item) => item.id === provider.id) ?? provider),
@@ -879,6 +887,22 @@ export class ProviderRegistry {
         })));
     }
 }
+/**
+ * Remote Gemini discovery does not expose Bubble's reasoning ladder; that
+ * metadata is inferred locally. Never trust a persisted inference across app
+ * upgrades, or a corrected capability matrix can remain stale for the cache
+ * TTL after restart.
+ */
+function normalizeProviderDiscoveryMetadata(provider, result) {
+    if (provider.id !== "google" || provider.protocol !== "ai-sdk")
+        return result;
+    return {
+        ...result,
+        models: result.models.map((model) => model.id.startsWith("gemini-")
+            ? { ...model, reasoningLevels: geminiReasoningLevels(model.id) }
+            : model),
+    };
+}
 function modelDiscoveryError(error) {
     if (error instanceof Error && error.message.trim())
         return error.message;

package/dist/sdk/index.d.ts

@@ -21,7 +21,7 @@ import type { ResolvedSubagentRoute } from "../agent/categories.js";
 import { type QuestionAnswer, type QuestionRequest } from "../question/controller.js";
 import { SkillRegistry } from "../skills/registry.js";
 import type { SkillSummary } from "../skills/types.js";
-import type { AgentEvent, ContentPart, Message, PermissionMode, Provider, ThinkingLevel } from "../types.js";
+import type { AgentEvent, AgentRunInput, ContentPart, Message, PermissionMode, Provider, ThinkingLevel } from "../types.js";
 export interface BubbleSdkOptions {
     /** Fallback working directory for sessions created without an explicit cwd. */
     defaultCwd?: string;
@@ -81,6 +81,62 @@ export interface SdkSessionRef {
     id: string;
     cwd: string;
 }
+export interface SdkSessionRunState {
+    /** A turn owns the session slot, including setup and teardown. */
+    active: boolean;
+    queuedTurns: number;
+    pendingSteers: number;
+    phase: "idle" | "reserved" | "starting" | "active" | "stopping" | "deleted";
+}
+export type SdkSteerOutcome = Extract<AgentEvent, {
+    type: "input_applied" | "input_queued" | "input_rejected";
+}>;
+export type SdkSteerResult = {
+    accepted: true;
+    disposition: "steered";
+    input: AgentRunInput;
+    outcome: Promise<SdkSteerOutcome>;
+} | {
+    accepted: true;
+    disposition: "queued";
+    input: AgentRunInput;
+    turnId: string;
+    outcome: Promise<SdkSteerOutcome>;
+} | {
+    accepted: false;
+    disposition: "rejected";
+    reason: "unknown_session" | "session_deleted" | "ownership_conflict";
+};
+export interface SdkSessionEvent {
+    sequence: number;
+    sessionId: string;
+    turnId: string;
+    event: AgentEvent;
+    /**
+     * Present only on the synthesized record that ends a turn abnormally.
+     * Replay subscribers use it to tell "turn failed" from "turn still running";
+     * the per-turn runTurn() iterator instead surfaces the thrown error.
+     */
+    terminal?: SdkSessionTerminal;
+}
+export interface SdkSessionTerminal {
+    kind: "failed" | "cancelled";
+    message: string;
+}
+export interface SdkStopOptions {
+    /** Match Claude-style interruption: queued messages survive by default. */
+    cancelQueued?: boolean;
+}
+export interface SdkSessionHandle extends SdkSessionRef {
+    /** Events from every turn in this session. Opening another handle reconnects from sequence 1. */
+    readonly events: AsyncIterable<SdkSessionEvent>;
+    /** Reconnect after the last sequence the host durably processed. */
+    eventsFrom(afterSequence: number): AsyncIterable<SdkSessionEvent>;
+    send(options: RunTurnOptions): AsyncGenerator<AgentEvent>;
+    steer(content: string): SdkSteerResult;
+    stop(options?: SdkStopOptions): number;
+    close(): void;
+}
 export declare class BubbleSdk {
     readonly userConfig: UserConfig;
     readonly registry: ProviderRegistry;
@@ -88,8 +144,13 @@ export declare class BubbleSdk {
     private readonly mcpEnabled;
     private readonly cwdBySession;
     private readonly bashAllowlists;
-    private readonly activeTurns;
+    private readonly turnCoordinator;
+    private readonly turnRuntimes;
+    private readonly lastTurnOptions;
     private readonly mcpToolsByCwd;
+    private readonly inputIdNonce;
+    private nextTurnInputPrefix;
+    private nextDetachedInputId;
     /** id -> {cwd,file} rebuilt from disk so sessions survive host restarts. */
     private sessionIndex;
     constructor(options?: BubbleSdkOptions);
@@ -98,10 +159,21 @@ export declare class BubbleSdk {
         cwd?: string;
         id?: string;
     }): SdkSessionRef;
+    openSession(sessionId: string): SdkSessionHandle;
     getHistory(sessionId: string): Message[];
-    deleteSession(sessionId: string): void;
-    /** Abort the in-flight turn of a session, if any. */
-    stop(sessionId: string): void;
+    deleteSession(sessionId: string): Promise<void>;
+    /** Interrupt the active turn. Queued turns survive unless cancelQueued is true. */
+    stop(sessionId: string, options?: SdkStopOptions): number;
+    /** Cancel queued turns without interrupting the turn that owns the session slot. */
+    clearQueue(sessionId: string): number;
+    getSessionRunState(sessionId: string): SdkSessionRunState;
+    /**
+     * Add text to the turn that currently owns the session slot. Every accepted
+     * input exposes an outcome promise, independent of event-stream consumption.
+     */
+    steer(sessionId: string, content: string): SdkSteerResult;
+    enqueueTurn(sessionId: string, options: RunTurnOptions): AsyncGenerator<AgentEvent>;
+    queueTurn(sessionId: string, options: RunTurnOptions): AsyncGenerator<AgentEvent>;
     listSkills(cwd?: string): SkillSummary[];
     /** Configured providers + default model, for a host's model picker. */
     getModelConfig(): {
@@ -113,7 +185,25 @@ export declare class BubbleSdk {
             hasApiKey: boolean;
         }>;
     };
+    /**
+     * Reserve and start a session turn immediately. Execution is driven by the
+     * SDK's own pump, not by consumption of the returned iterator: the iterator
+     * is a replay subscription, so a host may drop it (or reconnect later via
+     * `openSession`) without stalling or cancelling the turn. Cancel with
+     * `stop()`, the options signal, or `deleteSession()`.
+     */
     runTurn(sessionId: string, options: RunTurnOptions): AsyncGenerator<AgentEvent>;
+    private startOwnedTurn;
+    private pumpTurn;
+    private runReservedTurn;
+    private runtimesForSession;
+    private settleSteerFromEvent;
+    private handleSteerEvent;
+    private rejectOutstandingSteers;
+    private queuePendingSteer;
+    private queueDetachedInput;
+    private publishSessionEvent;
+    private ownerForSession;
     private bashAllowlistFor;
     /**
      * Default cross-provider subagent factory over this SDK instance's own
@@ -141,6 +231,7 @@ export declare function attachTurnCost(event: AgentEvent, providerId: string, mo
  */
 export declare function rewriteSkillInvocationPrompt(prompt: string | ContentPart[], registry: SkillRegistry): string | ContentPart[];
 export { Agent, AgentAbortError, type AgentOptions, type AgentRunOptions } from "../agent.js";
+export { AgentRunInputQueue } from "../agent/input-controller.js";
 export { SessionManager, getSessionsDir, type SessionSummary, type UserTurn, type RewindResult, } from "../session.js";
 export { PermissionAwareApprovalController } from "../approval/controller.js";
 export { BashAllowlist } from "../approval/session-cache.js";
@@ -164,4 +255,4 @@ export { ExternalHookController } from "../hooks/controller.js";
 export { calculateUsageCost, getModelPricing, type ModelPricing, type PricingCurrency, } from "../model-pricing.js";
 export { registry as slashCommandRegistry } from "../slash-commands/index.js";
 export type { SlashCommandContext } from "../slash-commands/types.js";
-export type { AgentEvent, ContentPart, Message, PermissionMode, Provider, ThinkingLevel, TokenUsage, UsageCost, ToolRegistryEntry, ToolResult, ToolUpdate, } from "../types.js";
+export type { AgentEvent, AgentInputController, AgentRunInput, ContentPart, Message, PermissionMode, Provider, ThinkingLevel, TokenUsage, UsageCost, ToolRegistryEntry, ToolResult, ToolUpdate, } from "../types.js";