@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/sdk/index.js

@@ -0,0 +1,1068 @@
+/**
+ * Bubble SDK — the programmatic embedding surface for external hosts.
+ *
+ * Two layers:
+ *  1. `BubbleSdk` — a high-level facade that owns config/provider resolution and
+ *     assembles a full agent turn (tools, approvals, questions, plan mode, MCP,
+ *     skills, hooks, session persistence) behind a single `runTurn()` async
+ *     iterator of `AgentEvent`s. This is what a host like an Electron app should
+ *     consume: wire the three interaction callbacks (approval / question / plan)
+ *     to its own UI and map the event stream to its own message format.
+ *  2. Curated re-exports of the underlying building blocks, for hosts that need
+ *     to assemble a custom loop the facade doesn't cover.
+ *
+ * Runs under plain Node (>=20); nothing here touches the TUI layer.
+ */
+import os from "node:os";
+import { rmSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { Agent, AgentAbortError } from "../agent.js";
+import { AgentRunInputQueue } from "../agent/input-controller.js";
+import { SessionTurnCoordinator, } from "./session-turn-coordinator.js";
+import { ReplayEventLog } from "./replay-event-log.js";
+import { SessionManager } from "../session.js";
+import { isPermissionModeReminder } from "../prompt/reminders.js";
+import { PermissionAwareApprovalController } from "../approval/controller.js";
+import { BashAllowlist } from "../approval/session-cache.js";
+import { SettingsManager } from "../permissions/settings.js";
+import { isRepoConfigTrusted, mergedRepoCapabilities, readRepoSettings, trustRepoConfig, } from "../permissions/trust.js";
+import { createAllTools, buildToolPromptOptions } from "../tools/index.js";
+import { buildSystemPrompt } from "../system-prompt.js";
+import { FileStateTracker } from "../tools/file-state.js";
+import { BudgetLedger } from "../agent/budget-ledger.js";
+import { UserConfig } from "../config.js";
+import { ProviderRegistry, encodeModel, decodeModel, displayModel } from "../provider-registry.js";
+import { createProviderInstance } from "../provider.js";
+import { getDefaultThinkingLevel } from "../variant/variant-resolver.js";
+import { QuestionController } from "../question/controller.js";
+import { assertProviderModelAllowed } from "../provider-model-policy.js";
+import { SkillRegistry } from "../skills/registry.js";
+import { parseSkillInvocation } from "../skills/invocation.js";
+import { GoalStore } from "../goal/store.js";
+import { McpManager, gateMcpTools } from "../mcp/manager.js";
+import { loadMcpConfig } from "../mcp/config.js";
+import { ExternalHookController } from "../hooks/controller.js";
+import { buildMemoryPrompt } from "../memory/store.js";
+import { calculateUsageCost } from "../model-pricing.js";
+import { purgeUnsafeMemorySources } from "../memory/session-policy.js";
+import { recordMemoryCitations } from "../memory/usage.js";
+// ── Facade ─────────────────────────────────────────────────────────────────
+export class BubbleSdk {
+    userConfig = new UserConfig();
+    registry = new ProviderRegistry(this.userConfig);
+    defaultCwd;
+    mcpEnabled;
+    sessionEventRetention;
+    cwdBySession = new Map();
+    bashAllowlists = new Map();
+    sessionGrants = new Map();
+    turnCoordinator = new SessionTurnCoordinator();
+    turnRuntimes = new Map();
+    lastTurnOptions = new Map();
+    mcpToolsByCwd = new Map();
+    mcpManagersByCwd = new Map();
+    /** Folders whose trust question was already put to the host. */
+    projectTrustAsked = new Set();
+    inputIdNonce = randomUUID().slice(0, 6);
+    nextTurnInputPrefix = 0;
+    nextDetachedInputId = 0;
+    /** id -> {cwd,file} rebuilt from disk so sessions survive host restarts. */
+    sessionIndex = new Map();
+    constructor(options = {}) {
+        this.defaultCwd = options.defaultCwd || process.env.BUBBLE_CWD || os.homedir();
+        this.mcpEnabled = options.mcp !== false;
+        this.sessionEventRetention = options.sessionEventRetention ?? Infinity;
+        if (this.sessionEventRetention !== Infinity && (!Number.isSafeInteger(this.sessionEventRetention) || this.sessionEventRetention < 1)) {
+            throw new Error('sessionEventRetention must be a positive integer');
+        }
+    }
+    // ── Sessions ─────────────────────────────────────────────────────────────
+    listSessions() {
+        const sessions = SessionManager.listAllSessions().filter((session) => !this.turnCoordinator.isDeleted(session.name));
+        this.sessionIndex = new Map(sessions.map((s) => [s.name, { cwd: s.cwd ?? s.cwdLabel ?? this.defaultCwd, file: s.file }]));
+        return sessions;
+    }
+    createSession(options = {}) {
+        const cwd = options.cwd || this.defaultCwd;
+        const id = options.id || `sdk-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+        this.turnCoordinator.revive(id);
+        SessionManager.create(cwd, sessionFileName(id));
+        processSessionLocations.set(id, cwd);
+        this.cwdBySession.set(id, cwd);
+        return { id, cwd };
+    }
+    openSession(sessionId) {
+        const resolved = this.resolveSession(sessionId);
+        if (!resolved)
+            throw new Error(`Unknown session: ${sessionId}`);
+        const ownerKey = resolved.manager.getSessionFile();
+        const eventLog = sessionEventLogFor(ownerKey, this.sessionEventRetention);
+        const closed = new AbortController();
+        return {
+            id: sessionId,
+            cwd: resolved.cwd,
+            get latestSequence() { return eventLog.length; },
+            get events() { return eventLog.iterate({ signal: closed.signal }); },
+            eventsFrom: (afterSequence) => eventLog.iterate({
+                from: Math.max(0, afterSequence),
+                signal: closed.signal,
+            }),
+            send: (options) => this.runTurn(sessionId, options),
+            steer: (content) => this.steer(sessionId, content),
+            stop: (options) => this.stop(sessionId, options),
+            close: () => closed.abort(),
+        };
+    }
+    getHistory(sessionId) {
+        if (this.turnCoordinator.isDeleted(sessionId))
+            return [];
+        return this.resolveSession(sessionId)?.manager.getMessages() ?? [];
+    }
+    /** Preserve an accepted desktop input cancelled before runTurn was admitted. */
+    recordInterruptedInput(sessionId, prompt) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.recordInterruptedInput(sessionId, prompt);
+        if (this.turnCoordinator.isDeleted(sessionId) || this.getSessionRunState(sessionId).active) {
+            throw new Error(`Cannot record interrupted input while session is active or deleted: ${sessionId}`);
+        }
+        const resolved = this.resolveSession(sessionId);
+        if (!resolved)
+            throw new Error(`Unknown session: ${sessionId}`);
+        this.persistInterruptedInput(resolved, prompt);
+    }
+    persistInterruptedInput(resolved, prompt) {
+        const session = resolved.manager;
+        session.getMessages();
+        const revision = session.getRevision();
+        session.updateMetadata({ cwd: resolved.cwd });
+        session.appendMessage({ role: "user", content: prompt }, revision);
+        session.appendMessage({
+            role: "assistant",
+            content: "[Interrupted by user before execution started.]",
+            error: { name: "MessageAbortedError", message: "Turn stopped during initialization.", aborted: true },
+        }, session.getRevision());
+    }
+    async deleteSession(sessionId) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.deleteSession(sessionId);
+        const resolved = this.resolveSession(sessionId);
+        for (const runtime of this.runtimesForSession(sessionId))
+            runtime.inputController.closePendingInputs();
+        await this.turnCoordinator.delete(sessionId);
+        if (resolved)
+            rmSync(resolved.manager.getSessionFile(), { force: true });
+        this.cwdBySession.delete(sessionId);
+        this.bashAllowlists.delete(sessionId);
+        this.sessionGrants.delete(sessionId);
+        this.lastTurnOptions.delete(sessionId);
+        this.sessionIndex.delete(sessionId);
+        processSessionLocations.delete(sessionId);
+        if (resolved) {
+            releaseSessionEventLog(resolved.manager.getSessionFile());
+            releaseProcessOwner(resolved.manager.getSessionFile(), this);
+        }
+    }
+    /** Interrupt the active turn. Queued turns survive unless cancelQueued is true. */
+    stop(sessionId, options = {}) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.stop(sessionId, options);
+        const current = this.turnCoordinator.getCurrent(sessionId);
+        const runtime = current ? this.turnRuntimes.get(current.id) : undefined;
+        runtime?.inputController.closePendingInputs();
+        // A reserved turn can release its slot synchronously when cancelled.
+        // Clear the queue first so cancellation cannot promote an unwanted input.
+        const queued = options.cancelQueued ? this.turnCoordinator.clearQueue(sessionId) : 0;
+        return queued + this.turnCoordinator.stopCurrent(sessionId);
+    }
+    /** Stop and wait for persistence, cleanup, and terminal event publication. */
+    async stopAndWait(sessionId, options = {}) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.stopAndWait(sessionId, options);
+        const current = this.turnCoordinator.getCurrent(sessionId);
+        const stopping = this.runtimesForSession(sessionId).filter(runtime => options.cancelQueued || runtime.reservation.id === current?.id);
+        const stopped = this.stop(sessionId, options);
+        await Promise.all(stopping.map(runtime => runtime.finished));
+        return stopped;
+    }
+    /** Cancel queued turns without interrupting the turn that owns the session slot. */
+    clearQueue(sessionId) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.clearQueue(sessionId);
+        return this.turnCoordinator.clearQueue(sessionId);
+    }
+    getSessionRunState(sessionId) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.getSessionRunState(sessionId);
+        const state = this.turnCoordinator.getState(sessionId);
+        const current = this.turnCoordinator.getCurrent(sessionId);
+        const runtime = current ? this.turnRuntimes.get(current.id) : undefined;
+        return {
+            active: state.active,
+            queuedTurns: state.queued,
+            pendingSteers: runtime?.outcomes.size ?? 0,
+            phase: state.phase,
+        };
+    }
+    /**
+     * 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, content) {
+        if (this.turnCoordinator.isDeleted(sessionId)) {
+            return { accepted: false, disposition: "rejected", reason: "session_deleted" };
+        }
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.steer(sessionId, content);
+        const resolved = this.resolveSession(sessionId);
+        if (!resolved) {
+            return { accepted: false, disposition: "rejected", reason: "unknown_session" };
+        }
+        const current = this.turnCoordinator.getCurrent(sessionId);
+        const runtime = current ? this.turnRuntimes.get(current.id) : undefined;
+        if (runtime) {
+            const input = runtime.inputController.tryEnqueue(content);
+            if (input) {
+                const pending = pendingSteerOutcome(input);
+                runtime.outcomes.set(input.id, pending);
+                return { accepted: true, disposition: "steered", input, outcome: pending.promise };
+            }
+        }
+        return this.queueDetachedInput(sessionId, content, resolved);
+    }
+    enqueueTurn(sessionId, options) {
+        return this.runTurn(sessionId, options);
+    }
+    queueTurn(sessionId, options) {
+        return this.enqueueTurn(sessionId, options);
+    }
+    // ── Discovery (composer pickers) ─────────────────────────────────────────
+    listSkills(cwd, skillPaths = []) {
+        const registry = new SkillRegistry({
+            cwd: cwd || this.defaultCwd,
+            skillPaths: [...this.userConfig.getSkillPaths(), ...skillPaths],
+            disabledSkills: this.userConfig.getDisabledSkills(),
+        });
+        return registry.summaries();
+    }
+    /**
+     * Ask the host once per folder (onProjectTrust) before this turn loads the
+     * repository's allow rules, MCP servers and LSP servers. Trusting restarts
+     * the folder's MCP servers so newly trusted ones are available right away.
+     */
+    async resolveProjectTrust(cwd, options, signal) {
+        if (!options.onProjectTrust || this.projectTrustAsked.has(cwd))
+            return;
+        // Read once: what gets trusted is exactly what the host was shown.
+        const raw = readRepoSettings(cwd);
+        if (isRepoConfigTrusted(cwd, raw))
+            return;
+        this.projectTrustAsked.add(cwd);
+        const trusted = await awaitWithAbort(options.onProjectTrust({ cwd, pending: mergedRepoCapabilities(raw) }), signal);
+        if (!trusted)
+            return;
+        trustRepoConfig(cwd, raw);
+        const manager = this.mcpManagersByCwd.get(cwd);
+        this.mcpManagersByCwd.delete(cwd);
+        this.mcpToolsByCwd.delete(cwd);
+        await (await manager?.catch(() => null))?.shutdown().catch(() => undefined);
+    }
+    /** Configured providers + default model, for a host's model picker. */
+    getModelConfig() {
+        const configured = this.registry.getConfigured().filter((p) => p.enabled);
+        return {
+            defaultProviderId: this.registry.getDefault()?.id ?? "",
+            defaultModel: this.userConfig.getDefaultModel() ?? "",
+            providers: configured.map((p) => ({ id: p.id, baseURL: p.baseURL, hasApiKey: Boolean(p.apiKey) })),
+        };
+    }
+    // ── The turn ─────────────────────────────────────────────────────────────
+    /**
+     * 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, options) {
+        const resolved = this.resolveSession(sessionId);
+        if (!resolved)
+            throw new Error(`Unknown session: ${sessionId}`);
+        const ownerKey = resolved.manager.getSessionFile();
+        const owner = processSessionOwners.get(ownerKey);
+        if (owner && owner !== this)
+            return owner.runTurn(sessionId, options);
+        claimProcessOwner(ownerKey, this);
+        try {
+            const runtime = this.startOwnedTurn(sessionId, options, resolved, ownerKey);
+            return runtime.events.iterate();
+        }
+        catch (error) {
+            // A synchronous reserve() failure (e.g. pre-aborted signal) must not
+            // leave this SDK pinned as process owner of a session it never ran.
+            if (!this.turnCoordinator.getState(sessionId).active) {
+                releaseProcessOwner(ownerKey, this);
+            }
+            throw error;
+        }
+    }
+    startOwnedTurn(sessionId, options, resolved, ownerKey) {
+        const reservation = this.turnCoordinator.reserve(sessionId, options.signal);
+        const runtime = {
+            sessionId,
+            ownerKey,
+            reservation,
+            inputController: new AgentRunInputQueue(`sdk-turn-${this.inputIdNonce}-${++this.nextTurnInputPrefix}`),
+            outcomes: new Map(),
+            options,
+            events: new ReplayEventLog(),
+            started: reservation.phase !== "queued",
+            inputRecorded: false,
+            finished: Promise.resolve(),
+        };
+        this.lastTurnOptions.set(sessionId, inheritableTurnOptions(options));
+        this.turnRuntimes.set(reservation.id, runtime);
+        runtime.finished = this.pumpTurn(runtime, resolved);
+        return runtime;
+    }
+    async pumpTurn(runtime, resolved) {
+        let failure;
+        let completedEvent;
+        try {
+            for await (const event of this.runReservedTurn(runtime, runtime.options, resolved)) {
+                runtime.events.append(event);
+                // Publish success after the pump's finally releases its slot.
+                // A host can then distinguish idle from an automatically queued steer.
+                if (event.type === "agent_end")
+                    completedEvent = event;
+                else
+                    this.publishSessionEvent(runtime, event);
+            }
+        }
+        catch (error) {
+            failure = error;
+            // Setup can fail before runReservedTurn installs its own cleanup.
+            for (const event of this.rejectOutstandingSteers(runtime, runtime.reservation.signal.aborted ? "turn_cancelled" : "turn_failed")) {
+                runtime.events.append(event);
+                this.publishSessionEvent(runtime, event);
+            }
+            // Desktop users already submitted this input. Even if setup was
+            // interrupted before Agent.run appended it, keep it for a later resume.
+            // Cancelled queued inputs never owned the turn and must stay discarded.
+            if (runtime.options.preserveInterruptedInput && runtime.started && !runtime.inputRecorded
+                && runtime.reservation.signal.aborted && !this.turnCoordinator.isDeleted(runtime.sessionId)) {
+                try {
+                    this.persistInterruptedInput(resolved, runtime.options.prompt);
+                }
+                catch (persistError) {
+                    failure = persistError;
+                }
+            }
+        }
+        finally {
+            runtime.inputController.closePendingInputs();
+            // Release only after the interrupted input is durable. Keep the runtime
+            // discoverable until the terminal event is published for stopAndWait.
+            runtime.reservation.finish();
+            if (failure !== undefined) {
+                // The session-level log never closes per turn, so replay subscribers
+                // need an explicit terminal record — otherwise a failed turn is
+                // indistinguishable from one that is still running.
+                this.publishSessionEvent(runtime, { type: "turn_end", willContinue: false }, {
+                    kind: failure instanceof AgentAbortError || runtime.reservation.signal.aborted
+                        ? "cancelled"
+                        : "failed",
+                    message: failure instanceof Error ? failure.message : String(failure),
+                });
+            }
+            else {
+                this.publishSessionEvent(runtime, completedEvent ?? { type: "agent_end" }, { kind: "completed" });
+            }
+            runtime.events.close(failure);
+            if (this.turnRuntimes.get(runtime.reservation.id) === runtime) {
+                this.turnRuntimes.delete(runtime.reservation.id);
+            }
+            if (!this.turnCoordinator.getState(runtime.sessionId).active) {
+                releaseProcessOwner(runtime.ownerKey, this);
+            }
+        }
+    }
+    async *runReservedTurn(runtime, options, resolved) {
+        const { sessionId, reservation, inputController } = runtime;
+        const { manager: session, cwd } = resolved;
+        const mode = options.mode ?? "default";
+        const planExitMode = options.planExitMode === "bypassPermissions" ? "bypassPermissions" : "default";
+        const abortSignal = reservation.signal;
+        await reservation.waitForStart();
+        runtime.started = true;
+        let agentRef;
+        let streamCompleted = false;
+        const hookController = new ExternalHookController({ cwd, sessionId });
+        await this.resolveProjectTrust(cwd, options, abortSignal);
+        // Same allow/deny rules as the TUI (user, project and local settings;
+        // repository allow rules only once trusted). Deny rules bind even under
+        // bypassPermissions.
+        const ruleSet = new SettingsManager(cwd).getMerged().ruleSet;
+        // Settles as reject the moment the turn aborts, so a tool blocked on a
+        // host approval (or question) can never hang the abort path.
+        const abortedDecision = new Promise((resolve) => {
+            const decide = () => resolve({ action: "reject", feedback: "Turn aborted" });
+            if (abortSignal.aborted)
+                decide();
+            else
+                abortSignal.addEventListener("abort", decide, { once: true });
+        });
+        const approvalController = new PermissionAwareApprovalController({
+            getMode: () => agentRef?.mode ?? mode,
+            handlerRef: {
+                current: (req) => options.onApproval
+                    ? Promise.race([options.onApproval(req), abortedDecision])
+                    : Promise.resolve({
+                        action: "reject",
+                        feedback: "Host provided no approval handler",
+                    }),
+            },
+            bashAllowlist: this.bashAllowlistFor(sessionId),
+            sessionGrants: this.sessionGrantsFor(sessionId),
+            cwd,
+            // Read once per turn: edits to settings files apply from the next turn.
+            getRuleSet: () => ruleSet,
+            externalHooks: hookController,
+        });
+        const fileStateTracker = new FileStateTracker(cwd);
+        const planController = {
+            getMode: () => agentRef?.mode ?? mode,
+            requestApproval: async (plan) => {
+                const approved = options.onPlanApproval
+                    ? await awaitWithAbort(options.onPlanApproval(plan), abortSignal)
+                    : false;
+                // exit_plan_mode applies getExitMode() itself on approval.
+                return approved
+                    ? { action: "approve", plan }
+                    : { action: "reject", reason: "Plan rejected by host" };
+            },
+            setMode: (m) => agentRef?.setMode(m),
+            getExitMode: () => planExitMode,
+        };
+        const questionController = new QuestionController();
+        const unsubscribeQuestions = questionController.subscribe((event) => {
+            if (event.type !== "asked")
+                return;
+            const request = event.request;
+            if (!options.onQuestion) {
+                questionController.reject(request.id);
+                return;
+            }
+            options.onQuestion(request).then((answers) => answers ? questionController.reply(request.id, answers) : questionController.reject(request.id), () => questionController.reject(request.id));
+        });
+        abortSignal.addEventListener("abort", () => questionController.rejectAll(), { once: true });
+        try {
+            const skillRegistry = new SkillRegistry({
+                cwd,
+                skillPaths: [...this.userConfig.getSkillPaths(), ...(options.skillPaths ?? [])],
+                disabledSkills: this.userConfig.getDisabledSkills(),
+            });
+            const tools = createAllTools(cwd, skillRegistry, {
+                approvalController,
+                fileStateTracker,
+                planController,
+                questionController,
+                goalStore: new GoalStore(),
+                checkpoints: () => session.getCheckpoints(),
+            });
+            tools.push(...gateMcpTools(await awaitWithAbort(this.mcpToolsFor(cwd), abortSignal), approvalController));
+            const hostTools = options.hostTools ?? [];
+            const registered = new Set(tools.map(tool => tool.name));
+            for (const tool of hostTools) {
+                if (registered.has(tool.name))
+                    throw new Error(`Duplicate host tool: ${tool.name}`);
+                registered.add(tool.name);
+                const guarded = {
+                    ...tool,
+                    execute: async (args, ctx) => {
+                        throwAbortSignal(abortSignal);
+                        return tool.execute(args, { ...ctx, abortSignal });
+                    },
+                    cloneForChild: () => ({ ...tool, enabled: () => false, execute: async () => ({ content: "Host capability is not available to this child.", isError: true }) }),
+                };
+                tools.push(...(tool.readOnly ? [guarded] : gateMcpTools([guarded], approvalController)));
+            }
+            throwAbortSignal(abortSignal);
+            const promptCacheKey = session.getOrCreatePromptCacheKey();
+            if (!this.turnCoordinator.isDeleted(sessionId)) {
+                session.updateMetadata({ cwd }); // recoverable by cwd after host restart
+            }
+            const { provider, providerId, model } = this.resolveProvider(promptCacheKey, options.model);
+            const thinkingLevel = options.thinkingLevel ??
+                this.userConfig.getDefaultThinkingLevel() ??
+                getDefaultThinkingLevel(providerId, decodeModel(model).modelId);
+            // Same ordering as the TUI: the provenance gate must run before memories
+            // enter the system prompt.
+            purgeUnsafeMemorySources(cwd);
+            const memoryPrompt = buildMemoryPrompt(cwd);
+            const builtSystemPrompt = buildSystemPrompt({
+                agentName: "Bubble",
+                skills: skillRegistry.summaries(),
+                skillCatalogChars: this.userConfig.getSkillCatalogChars(),
+                configuredProvider: providerId || "none",
+                configuredModel: model ? displayModel(model) : "none",
+                configuredModelId: model || "none",
+                thinkingLevel,
+                mode,
+                workingDir: cwd,
+                ...buildToolPromptOptions(tools.filter((t) => !t.deferred)),
+                memoryPrompt,
+            });
+            const systemPrompt = options.appendSystemPrompt
+                ? `${builtSystemPrompt}\n\n${options.appendSystemPrompt.trim()}`
+                : builtSystemPrompt;
+            // Host-driven mode changes (picker, /plan, leaving plan) go into the log
+            // as markers, so the rebuilt history states the mode where it changed —
+            // after any older tool result that claimed a different mode.
+            if (latestRecordedMode(session) !== mode && !this.turnCoordinator.isDeleted(sessionId)) {
+                session.appendMarker("mode_switch", mode);
+            }
+            const history = session.getMessages();
+            let contextRevision = session.getRevision();
+            // The constructor's leading context minus its mode reminder: the history
+            // carries the mode timeline itself (session-log toMessages).
+            let leadingContext = [];
+            // A fence rejection means the durable log diverged from this turn's
+            // resident snapshot (a foreign append or clear landed mid-flight). Refuse
+            // the write, then roll the resident transcript back to the file's truth so
+            // the rejected message does not linger and later writes are not wedged
+            // behind the stale revision.
+            const persistFenced = (write) => {
+                try {
+                    write();
+                }
+                catch (error) {
+                    // Any refused write (fence rejection, busy lock, I/O) leaves the agent's
+                    // already-pushed message unpersisted. getMessages() refreshes, so read
+                    // the history first and adopt the revision of that same snapshot.
+                    try {
+                        const reloaded = session.getMessages();
+                        contextRevision = session.getRevision();
+                        agent.messages = [...leadingContext, ...reloaded];
+                    }
+                    catch { /* surface the original write failure */ }
+                    throw error;
+                }
+            };
+            const agent = new Agent({
+                provider,
+                providerId,
+                model,
+                sessionID: session.getSessionFile(),
+                tools,
+                systemPrompt,
+                temperature: 0.2,
+                thinkingLevel,
+                mode,
+                budgetLedger: new BudgetLedger(),
+                fileStateTracker,
+                skills: skillRegistry.summaries(),
+                skillCatalogChars: this.userConfig.getSkillCatalogChars(),
+                memoryPrompt,
+                externalHooks: hookController,
+                // Cross-provider subagent routes (spawn_agent with "provider:model")
+                // need a factory; without one the child blocks with
+                // "no provider factory is configured". Default mirrors the TUI's
+                // createProviderForRoute (OAuth prepare + configured+enabled+keyed
+                // profile lookup); hosts may override per turn.
+                providerFactory: options.providerFactory ?? this.defaultProviderFactory(),
+                onMessageAppend: (message) => {
+                    if (message.role === "system" || message.role === "meta")
+                        return;
+                    if (this.turnCoordinator.isDeleted(sessionId))
+                        return;
+                    if (message.role === "user")
+                        runtime.inputRecorded = true;
+                    persistFenced(() => {
+                        session.appendMessage(message, contextRevision);
+                        contextRevision = session.getRevision();
+                    });
+                    if (message.role === "assistant")
+                        recordMemoryCitations(cwd, message.content);
+                },
+                onProviderError: (error) => {
+                    if (this.turnCoordinator.isDeleted(sessionId))
+                        return;
+                    persistFenced(() => session.appendProviderError(error, contextRevision));
+                },
+                getContextRevision: () => contextRevision,
+                onContextCheckpoint: (checkpoint) => {
+                    if (this.turnCoordinator.isDeleted(sessionId))
+                        throw new Error("Session deleted before context commit");
+                    persistFenced(() => {
+                        session.commitContextCheckpoint(checkpoint, contextRevision);
+                        contextRevision = session.getRevision();
+                    });
+                },
+                onModeUpdate: (m) => {
+                    if (!this.turnCoordinator.isDeleted(sessionId)) {
+                        persistFenced(() => {
+                            session.appendMarker("mode_switch", m, contextRevision);
+                            contextRevision = session.getRevision();
+                        });
+                    }
+                },
+            });
+            agentRef = agent;
+            leadingContext = agent.messages.filter((message) => !(message.role === "meta" && isPermissionModeReminder(message.content)));
+            if (history.length > 0) {
+                // Leading context (system prompt + deferred-tools reminder, never
+                // persisted) stays ahead of the history, at the same position every
+                // turn, so the provider's prefix cache covers the previous turn. The
+                // mode reminder comes from the history's own mode markers instead, so
+                // it is ordered after anything older that mentioned a mode.
+                agent.messages = [...leadingContext, ...history];
+            }
+            reservation.markActive();
+            options.onStart?.({
+                providerId,
+                model,
+                thinkingLevel,
+                mode,
+                tools: tools.map((t) => t.name),
+                skills: skillRegistry.summaries().map((s) => s.name),
+            });
+            // Match the TUI: a leading "/<skill-name> <task>" becomes an explicit
+            // load-this-skill instruction, so invocation never depends on the model
+            // recognizing the slash syntax on its own.
+            const prompt = rewriteSkillInvocationPrompt(options.prompt, skillRegistry);
+            const bareModelId = decodeModel(model).modelId;
+            for await (const event of agent.run(prompt, cwd, {
+                abortSignal,
+                inputController,
+            })) {
+                const sdkEvent = this.handleSteerEvent(runtime, event, resolved);
+                yield attachTurnCost(sdkEvent, providerId, bareModelId);
+            }
+            streamCompleted = true;
+            for (const event of this.rejectOutstandingSteers(runtime, "no_continuation", resolved))
+                yield event;
+        }
+        catch (error) {
+            const reason = abortSignal.aborted ? "turn_cancelled" : "turn_failed";
+            for (const event of this.rejectOutstandingSteers(runtime, reason))
+                yield event;
+            throw error;
+        }
+        finally {
+            inputController.closePendingInputs();
+            this.rejectOutstandingSteers(runtime, streamCompleted ? "no_continuation" : abortSignal.aborted ? "turn_cancelled" : "turn_failed", streamCompleted ? resolved : undefined);
+            unsubscribeQuestions();
+            questionController.rejectAll();
+        }
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    runtimesForSession(sessionId) {
+        return [...this.turnRuntimes.values()].filter((runtime) => runtime.sessionId === sessionId);
+    }
+    settleSteerFromEvent(runtime, event) {
+        if (event.type !== "input_applied" && event.type !== "input_rejected")
+            return;
+        const pending = runtime.outcomes.get(event.id);
+        if (!pending)
+            return;
+        runtime.outcomes.delete(event.id);
+        pending.resolve(event);
+    }
+    handleSteerEvent(runtime, event, resolved) {
+        if (event.type === "input_rejected" && event.reason === "no_continuation") {
+            const pending = runtime.outcomes.get(event.id);
+            if (pending)
+                return this.queuePendingSteer(runtime, pending, resolved, event);
+        }
+        this.settleSteerFromEvent(runtime, event);
+        return event;
+    }
+    rejectOutstandingSteers(runtime, reason, resolved) {
+        runtime.inputController.closePendingInputs();
+        const events = [];
+        for (const [id, pending] of runtime.outcomes) {
+            const event = {
+                type: "input_rejected",
+                id,
+                content: pending.input.content,
+                reason,
+                target: "next_turn",
+            };
+            runtime.outcomes.delete(id);
+            if (reason === "no_continuation" && resolved) {
+                events.push(this.queuePendingSteer(runtime, pending, resolved, event));
+            }
+            else {
+                pending.resolve(event);
+                events.push(event);
+            }
+        }
+        return events;
+    }
+    queuePendingSteer(runtime, pending, resolved, rejected) {
+        try {
+            const queuedRuntime = this.startOwnedTurn(runtime.sessionId, { ...inheritableTurnOptions(runtime.options), prompt: pending.input.content }, resolved, runtime.ownerKey);
+            const queued = {
+                type: "input_queued",
+                id: pending.input.id,
+                content: pending.input.content,
+                turnId: queuedRuntime.reservation.id,
+                target: "next_turn",
+            };
+            // The follow-up turn's own subscribers also see the queue marker; the
+            // session-level log already gets it once via this turn's yielded event.
+            queuedRuntime.events.append(queued);
+            runtime.outcomes.delete(pending.input.id);
+            pending.resolve(queued);
+            return queued;
+        }
+        catch {
+            runtime.outcomes.delete(pending.input.id);
+            pending.resolve(rejected);
+            return rejected;
+        }
+    }
+    queueDetachedInput(sessionId, content, resolved) {
+        const ownerKey = resolved.manager.getSessionFile();
+        try {
+            claimProcessOwner(ownerKey, this);
+            const input = {
+                id: `sdk-steer-${this.inputIdNonce}-${++this.nextDetachedInputId}`,
+                content,
+                submittedAt: Date.now(),
+            };
+            const runtime = this.startOwnedTurn(sessionId, { ...(this.lastTurnOptions.get(sessionId) ?? {}), prompt: content }, resolved, ownerKey);
+            const queued = {
+                type: "input_queued",
+                id: input.id,
+                content,
+                turnId: runtime.reservation.id,
+                target: "next_turn",
+            };
+            runtime.events.append(queued);
+            this.publishSessionEvent(runtime, queued);
+            return {
+                accepted: true,
+                disposition: "queued",
+                input,
+                turnId: runtime.reservation.id,
+                outcome: Promise.resolve(queued),
+            };
+        }
+        catch {
+            releaseProcessOwner(ownerKey, this);
+            return { accepted: false, disposition: "rejected", reason: "ownership_conflict" };
+        }
+    }
+    publishSessionEvent(runtime, event, terminal) {
+        const log = sessionEventLogFor(runtime.ownerKey, this.sessionEventRetention);
+        log.append({
+            sequence: log.length + 1,
+            sessionId: runtime.sessionId,
+            turnId: runtime.reservation.id,
+            event,
+            ...(terminal ? { terminal } : {}),
+        });
+    }
+    ownerForSession(sessionId) {
+        const resolved = this.resolveSession(sessionId);
+        return resolved ? processSessionOwners.get(resolved.manager.getSessionFile()) : undefined;
+    }
+    bashAllowlistFor(sessionId) {
+        let allowlist = this.bashAllowlists.get(sessionId);
+        if (!allowlist) {
+            allowlist = new BashAllowlist();
+            this.bashAllowlists.set(sessionId, allowlist);
+        }
+        return allowlist;
+    }
+    sessionGrantsFor(sessionId) {
+        let grants = this.sessionGrants.get(sessionId);
+        if (!grants) {
+            grants = new Set();
+            this.sessionGrants.set(sessionId, grants);
+        }
+        return grants;
+    }
+    /**
+     * Default cross-provider subagent factory over this SDK instance's own
+     * registry — the same semantics as the TUI's createProviderForRoute. The
+     * registry is reloaded first so a key added after construction works.
+     */
+    defaultProviderFactory() {
+        return async (route) => {
+            const providerId = route.providerId;
+            if (!providerId) {
+                throw new Error(`Subagent route for model "${route.model}" did not include a provider.`);
+            }
+            // getConfigured() reads config.json from disk every call, so keys
+            // added after SDK construction are picked up without a reload call.
+            const target = this.registry.getConfigured().find((item) => item.id === providerId);
+            if (target?.authType === "oauth") {
+                await this.registry.prepareProvider(providerId);
+            }
+            if (!target?.enabled || !target.apiKey) {
+                throw new Error(`Subagent route requires provider "${providerId}", but it is not configured or has no active credentials.`);
+            }
+            return createProviderInstance({
+                providerId,
+                apiKey: target.apiKey,
+                baseURL: target.baseURL,
+                protocol: target.protocol,
+                headers: target.headers,
+                openAICodexAuth: this.registry.createOpenAICodexAuthAdapter(providerId),
+                grokAuth: this.registry.createGrokAuthAdapter(providerId),
+            });
+        };
+    }
+    /**
+     * MCP servers are started lazily, once per cwd, and restarted only when the
+     * repository's settings get trusted (resolveProjectTrust).
+     */
+    mcpToolsFor(cwd) {
+        if (!this.mcpEnabled)
+            return Promise.resolve([]);
+        let cached = this.mcpToolsByCwd.get(cwd);
+        if (!cached) {
+            const managerPromise = (async () => {
+                const loaded = loadMcpConfig({ cwd });
+                if (loaded.servers.length === 0)
+                    return null;
+                const manager = new McpManager({ servers: loaded.servers });
+                await manager.start();
+                return manager;
+            })().catch(() => null);
+            this.mcpManagersByCwd.set(cwd, managerPromise);
+            cached = managerPromise.then((manager) => manager?.getToolEntries() ?? []);
+            this.mcpToolsByCwd.set(cwd, cached);
+        }
+        return cached;
+    }
+    resolveSession(sessionId) {
+        if (this.turnCoordinator.isDeleted(sessionId))
+            return undefined;
+        const memCwd = this.cwdBySession.get(sessionId);
+        if (memCwd) {
+            // create() only resolves the path and loads iff the file exists, so this
+            // covers both fresh (lazily persisted, not yet on disk) and resumed sessions.
+            return { manager: SessionManager.create(memCwd, sessionFileName(sessionId)), cwd: memCwd };
+        }
+        if (this.sessionIndex.size === 0)
+            this.listSessions();
+        const entry = this.sessionIndex.get(sessionId);
+        if (!entry) {
+            // A session created in this process but not yet persisted to disk is
+            // still resolvable (and routable) for other SDK instances.
+            const registeredCwd = processSessionLocations.get(sessionId);
+            if (!registeredCwd)
+                return undefined;
+            this.cwdBySession.set(sessionId, registeredCwd);
+            return {
+                manager: SessionManager.create(registeredCwd, sessionFileName(sessionId)),
+                cwd: registeredCwd,
+            };
+        }
+        // The disk entry supersedes the pre-persistence registry entry.
+        processSessionLocations.delete(sessionId);
+        this.cwdBySession.set(sessionId, entry.cwd);
+        return { manager: new SessionManager(entry.file), cwd: entry.cwd };
+    }
+    resolveProvider(promptCacheKey, explicitModel) {
+        const configuredModel = explicitModel || this.userConfig.getDefaultModel();
+        const defaultProvider = this.registry.getDefault();
+        const fallbackProviderId = defaultProvider?.id ?? "";
+        const normalized = configuredModel
+            ? configuredModel.includes(":")
+                ? configuredModel
+                : fallbackProviderId
+                    ? encodeModel(fallbackProviderId, configuredModel)
+                    : ""
+            : "";
+        const { providerId: effId, modelId: effModelId } = normalized
+            ? decodeModel(normalized)
+            : { providerId: undefined, modelId: "" };
+        const activeProviderId = effId || fallbackProviderId;
+        if (effModelId)
+            assertProviderModelAllowed(activeProviderId, effModelId);
+        const target = this.registry.getConfigured().find((p) => p.id === activeProviderId) || defaultProvider;
+        if (!target?.apiKey) {
+            throw new Error("No provider with an API key configured — run the Bubble CLI once to set one up");
+        }
+        const activeModel = effModelId ? encodeModel(activeProviderId, effModelId) : "";
+        const provider = createProviderInstance({
+            providerId: activeProviderId,
+            apiKey: target.apiKey,
+            baseURL: target.baseURL,
+            promptCacheKey,
+            protocol: target.protocol,
+            headers: target.headers,
+            // Main SDK turns need the same per-request OAuth renewal as the TUI
+            // and child provider factory, including calls after a long-running tool.
+            openAICodexAuth: this.registry.createOpenAICodexAuthAdapter(activeProviderId),
+            grokAuth: this.registry.createGrokAuthAdapter(activeProviderId),
+        });
+        return { provider, providerId: activeProviderId, model: activeModel };
+    }
+}
+/**
+ * Process-local ownership routes every producer to one SDK runner. Hosts that
+ * run multiple OS processes still need a broker or distributed per-session
+ * lease; two processes cannot safely share a local JSONL transcript directly.
+ */
+const processSessionOwners = new Map();
+const sessionEventLogs = new Map();
+/** sessionId -> cwd for sessions created in this process but not yet on disk. */
+const processSessionLocations = new Map();
+function claimProcessOwner(ownerKey, sdk) {
+    const existing = processSessionOwners.get(ownerKey);
+    if (existing && existing !== sdk) {
+        throw new Error(`SDK session is owned by another runner: ${ownerKey}`);
+    }
+    processSessionOwners.set(ownerKey, sdk);
+}
+function releaseProcessOwner(ownerKey, sdk) {
+    if (processSessionOwners.get(ownerKey) === sdk)
+        processSessionOwners.delete(ownerKey);
+}
+function sessionEventLogFor(ownerKey, retention = Infinity) {
+    let log = sessionEventLogs.get(ownerKey);
+    if (!log) {
+        log = new ReplayEventLog(retention);
+        sessionEventLogs.set(ownerKey, log);
+    }
+    return log;
+}
+/** End live iterators and drop the buffered events of a deleted session. */
+function releaseSessionEventLog(ownerKey) {
+    const log = sessionEventLogs.get(ownerKey);
+    if (!log)
+        return;
+    log.close();
+    sessionEventLogs.delete(ownerKey);
+}
+function inheritableTurnOptions(options) {
+    const { prompt: _prompt, signal: _signal, ...inherited } = options;
+    return inherited;
+}
+function sessionFileName(sessionId) {
+    return sessionId.endsWith(".jsonl") ? sessionId : `${sessionId}.jsonl`;
+}
+function pendingSteerOutcome(input) {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { input, promise, resolve };
+}
+function throwAbortSignal(signal) {
+    if (!signal.aborted)
+        return;
+    if (signal.reason instanceof Error)
+        throw signal.reason;
+    throw new AgentAbortError(typeof signal.reason === "string" ? signal.reason : "SDK turn cancelled.");
+}
+/** The mode the session log last recorded ("default" before any switch). */
+function latestRecordedMode(session) {
+    const entries = session.getEntries();
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type === "marker" && entry.kind === "mode_switch"
+            && (entry.value === "default" || entry.value === "plan" || entry.value === "bypassPermissions")) {
+            return entry.value;
+        }
+    }
+    return "default";
+}
+function awaitWithAbort(promise, signal) {
+    if (signal.aborted) {
+        try {
+            throwAbortSignal(signal);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            cleanup();
+            try {
+                throwAbortSignal(signal);
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+/**
+ * Attach a `cost` field to turn_end events that carry usage, priced via the
+ * static pricing table. Pricing is an accounting concern, so it rides along
+ * here in the SDK rather than in the agent core. Multi-step turns emit several
+ * turn_end events; each cost covers only that step's usage, so hosts sum them.
+ * Events for unpriced models (or without usage) pass through untouched.
+ */
+export function attachTurnCost(event, providerId, modelId, at = new Date()) {
+    if (event.type !== "turn_end" || !event.usage)
+        return event;
+    const cost = calculateUsageCost(providerId, modelId, event.usage, at);
+    return cost ? { ...event, cost } : event;
+}
+/**
+ * If the prompt (or its first text part) is a "/<skill-name> <task>" skill
+ * invocation, rewrite it into the same explicit execution prompt the TUI
+ * sends. Non-matching prompts pass through untouched.
+ */
+export function rewriteSkillInvocationPrompt(prompt, registry) {
+    if (typeof prompt === "string") {
+        return parseSkillInvocation(prompt, registry)?.actualPrompt ?? prompt;
+    }
+    const index = prompt.findIndex((part) => part.type === "text");
+    if (index === -1)
+        return prompt;
+    const part = prompt[index];
+    const rewritten = parseSkillInvocation(part.text, registry)?.actualPrompt;
+    if (!rewritten)
+        return prompt;
+    const next = prompt.slice();
+    next[index] = { ...part, text: rewritten };
+    return next;
+}
+// ── Building blocks (escape hatch for custom hosts) ────────────────────────
+export { Agent, AgentAbortError } from "../agent.js";
+export { AgentRunInputQueue } from "../agent/input-controller.js";
+export { SessionManager, getSessionsDir, } from "../session.js";
+export { PermissionAwareApprovalController } from "../approval/controller.js";
+export { BashAllowlist } from "../approval/session-cache.js";
+export { createAllTools, buildToolPromptOptions } from "../tools/index.js";
+export { buildSystemPrompt } from "../system-prompt.js";
+export { FileStateTracker } from "../tools/file-state.js";
+export { BudgetLedger } from "../agent/budget-ledger.js";
+export { UserConfig } from "../config.js";
+export { ProviderRegistry, encodeModel, decodeModel, displayModel, } from "../provider-registry.js";
+export { createProviderInstance } from "../provider.js";
+export { getDefaultThinkingLevel } from "../variant/variant-resolver.js";
+export { QuestionController, QuestionRejectedError, } from "../question/controller.js";
+export { SkillRegistry } from "../skills/registry.js";
+export { parseSkillInvocation } from "../skills/invocation.js";
+export { GoalStore } from "../goal/store.js";
+export { McpManager } from "../mcp/manager.js";
+export { loadMcpConfig } from "../mcp/config.js";
+export { ExternalHookController } from "../hooks/controller.js";
+export { calculateUsageCost, getModelPricing, } from "../model-pricing.js";
+export { registry as slashCommandRegistry } from "../slash-commands/index.js";