@bubblebrain-ai/bubble 0.0.54 → 0.0.56

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";