@bubblebrain-ai/bubble 0.0.45 → 0.0.47

package/dist/agent/child-runner.js

@@ -37,6 +37,17 @@ export class ChildRunner {
             return { kind: "final" };
         }
         const tools = selectToolsForAgentProfile(allTools, record.profile, options.approval);
+        // A write child whose worktree was reclaimed (unchanged → removed at a
+        // terminal outcome) must NOT reuse its live instance: the instance's
+        // tools are fenced to the deleted directory, so every write would be
+        // rejected while the run itself falls back to the parent cwd. Carry the
+        // conversation over and rebuild through createInstance, which allocates
+        // a fresh worktree. Mid-run retries (attempt > 1) never hit this — the
+        // worktree is only reclaimed at terminal outcomes.
+        if (record.profile.mode === "write_worktree" && !record.worktree && record.agent) {
+            record.messages = record.agent.messages.map((message) => ({ ...message }));
+            record.agent = undefined;
+        }
         const reuseExistingAgent = (options.reuseAgent || attempt > 1) && !!record.agent;
         let subAgent;
         try {

package/dist/agent/internal-reminder-sanitizer.d.ts

@@ -7,6 +7,13 @@ export declare const INTERNAL_BLOCK_PREFIX = "<bubble_internal_";
  * the user actually typed.
  */
 export declare function isInternalBlockContent(text: string): boolean;
+/**
+ * True when the ENTIRE content is one internal block (start- and end-anchored)
+ * — the shape harness-injected user-role messages (goal kicks, task wakes)
+ * have. Display surfaces drop these rows outright; anything looser (a block
+ * plus trailing text) must instead be sanitized, never dropped.
+ */
+export declare function isInternalBlockOnlyContent(content: unknown): boolean;
 export declare function formatInternalReminderBlock(kind: string, content: string): string;
 export declare function formatInternalContextBlock(kind: string, content: string): string;
 export declare function sanitizeInternalReminderBlocks(text: string): string;

package/dist/agent/internal-reminder-sanitizer.js

@@ -37,6 +37,19 @@ export const INTERNAL_BLOCK_PREFIX = "<bubble_internal_";
 export function isInternalBlockContent(text) {
     return text.trimStart().startsWith(INTERNAL_BLOCK_PREFIX);
 }
+/**
+ * True when the ENTIRE content is one internal block (start- and end-anchored)
+ * — the shape harness-injected user-role messages (goal kicks, task wakes)
+ * have. Display surfaces drop these rows outright; anything looser (a block
+ * plus trailing text) must instead be sanitized, never dropped.
+ */
+export function isInternalBlockOnlyContent(content) {
+    if (typeof content !== "string")
+        return false;
+    const trimmed = content.trim();
+    return /^<bubble_internal_(?:context|reminder)\b/.test(trimmed)
+        && /<\/bubble_internal_(?:context|reminder)>$/.test(trimmed);
+}
 export function formatInternalReminderBlock(kind, content) {
     return formatInternalBlock("reminder", kind, content);
 }

package/dist/agent/subagent/router.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Subagent model routing (design §3-§7).
+ *
+ * Extracted from Agent so the routing decision chain and the routing prompt
+ * rendering live in one place: before this, the decision side sat next to the
+ * subagent dispatch code while `buildModelRoutingPromptSection` /
+ * `renderModelRoutingPromptFor` sat 2,000 lines away at the top of the class,
+ * with both halves reading the same `agentRouting` / `routingSnapshot` fields.
+ *
+ * The parent route is supplied as a thunk, never a snapshot: `/model` mutates
+ * the parent's provider, model and thinking level mid-session, and children
+ * spawned afterwards must inherit the CURRENT values.
+ */
+import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "../categories.js";
+import { type AgentRoutingConfig, type RoutableModelEntry, type RoutableModelIndex, type RoutingSnapshot, type RoutingSnapshotAccessor } from "../routing-catalog.js";
+import type { AgentProfile } from "../profiles.js";
+import type { ThinkingLevel } from "../../types.js";
+export interface ParentRoute {
+    providerId: string;
+    /** The API-facing model id — already stripped of any "provider:" prefix. */
+    model: string;
+    thinkingLevel: ThinkingLevel;
+}
+export interface SubagentRouterDeps {
+    /**
+     * Live parent route. MUST read through to the agent on every call — `/model`
+     * reassigns provider/model/thinking mid-session (see slash-commands), and a
+     * captured snapshot would route children to the pre-switch model.
+     */
+    parentRoute(): ParentRoute;
+    categories: AgentCategoriesConfig;
+    routing: AgentRoutingConfig;
+    snapshot?: RoutingSnapshotAccessor;
+    routableModels?: RoutableModelIndex;
+}
+export declare class SubagentRouter {
+    private readonly deps;
+    constructor(deps: SubagentRouterDeps);
+    /** Live snapshot for the CURRENT parent route; undefined when no accessor is wired. */
+    currentSnapshot(): RoutingSnapshot | undefined;
+    resolve(profile: AgentProfile, category: string | undefined, override?: {
+        model?: string;
+        effort?: ThinkingLevel;
+    }): ResolvedSubagentRoute;
+    /**
+     * Early route validation at dispatch time (design §7). Throws with an
+     * actionable message so the model self-corrects in the same turn. The
+     * cross-provider lock (§7.2.1) is snapshot-independent; catalog checks
+     * degrade silently when no snapshot is available (§7.0).
+     */
+    validateForDispatch(route: ResolvedSubagentRoute): string | undefined;
+    /** Routable catalog across runnable providers (design v3.6); undefined when unwired. */
+    listRoutableModels(): RoutableModelEntry[] | undefined;
+    /** Current routing menu (design §4); undefined when no accessor is wired. */
+    promptSection(): string | undefined;
+    /**
+     * Routing menu rendered for a prospective parent route — used by model-
+     * switch transactions to build the NEXT prompt before mutating the agent
+     * (design §1.5).
+     */
+    promptSectionFor(parent: {
+        providerId: string;
+        model: string;
+    }): string | undefined;
+}

package/dist/agent/subagent/router.js

@@ -0,0 +1,198 @@
+/**
+ * Subagent model routing (design §3-§7).
+ *
+ * Extracted from Agent so the routing decision chain and the routing prompt
+ * rendering live in one place: before this, the decision side sat next to the
+ * subagent dispatch code while `buildModelRoutingPromptSection` /
+ * `renderModelRoutingPromptFor` sat 2,000 lines away at the top of the class,
+ * with both halves reading the same `agentRouting` / `routingSnapshot` fields.
+ *
+ * The parent route is supplied as a thunk, never a snapshot: `/model` mutates
+ * the parent's provider, model and thinking level mid-session, and children
+ * spawned afterwards must inherit the CURRENT values.
+ */
+import { mergeAgentCategories, resolveModelRoute, resolveSubagentRoute } from "../categories.js";
+import { nearModelMatches, tierContextFromSnapshot } from "../routing-catalog.js";
+import { buildModelRoutingPrompt } from "../../prompt/routing.js";
+import { getBuiltinModel } from "../../model-catalog.js";
+import { getAvailableThinkingLevels, getDefaultThinkingLevel, normalizeInheritedThinkingLevel, normalizeThinkingLevel } from "../../variant/variant-resolver.js";
+export class SubagentRouter {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Live snapshot for the CURRENT parent route; undefined when no accessor is wired. */
+    currentSnapshot() {
+        if (!this.deps.snapshot)
+            return undefined;
+        const parent = this.deps.parentRoute();
+        try {
+            return this.deps.snapshot({ providerId: parent.providerId, model: parent.model });
+        }
+        catch {
+            // Catalog data is an enhancement, never a spawn blocker.
+            return undefined;
+        }
+    }
+    resolve(profile, category, override) {
+        const parentRoute = this.deps.parentRoute();
+        const snapshot = this.currentSnapshot();
+        const resolved = resolveSubagentRoute(category ?? profile.category, { ...parentRoute }, this.deps.categories, snapshot ? tierContextFromSnapshot(snapshot, this.deps.routing) : undefined);
+        if ("error" in resolved) {
+            throw new Error(resolved.error);
+        }
+        let route = resolved.route;
+        // modelSource is assigned while applying the chain (design §3.4): an
+        // explicit layer naming the parent's own model is indistinguishable from
+        // inherit by final-value comparison, yet carries different authority.
+        let modelSource = route.categoryModelSource ?? "inherit";
+        if (profile.model && profile.model !== "inherit") {
+            const model = resolveModelRoute(profile.model, parentRoute.providerId);
+            if (model.model !== "inherit") {
+                route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
+                modelSource = "profile";
+            }
+        }
+        // Call-site override beats profile and category. Bare names resolve
+        // against the PARENT provider per the tool contract (design §3.5) — not
+        // against a provider that category/profile may already have switched.
+        if (override?.model) {
+            const model = resolveModelRoute(override.model, parentRoute.providerId);
+            if (model.model !== "inherit") {
+                route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
+                modelSource = "callsite";
+            }
+        }
+        const supportedLevels = getAvailableThinkingLevels(route.providerId, route.model);
+        const modelMetadata = getBuiltinModel(route.providerId, route.model);
+        const hasTrustedEffortMetadata = !!modelMetadata
+            && modelMetadata.reasoningLevels.some((level) => level !== "off");
+        if (override?.effort) {
+            // A call-site effort is explicit user/model intent: preserve the existing
+            // value for legacy/unknown models, and downward-clamp only when the
+            // catalog declares real effort capabilities (for example Luna ultra -> max).
+            route = {
+                ...route,
+                thinkingLevel: hasTrustedEffortMetadata
+                    ? normalizeThinkingLevel(override.effort, supportedLevels)
+                    : override.effort,
+                inherited: false,
+            };
+        }
+        else if (hasTrustedEffortMetadata) {
+            const categoryThinkingLevel = route.category
+                ? mergeAgentCategories(this.deps.categories)[route.category]?.thinkingLevel
+                : undefined;
+            // A category's thinkingLevel is calibrated for the model the CATEGORY
+            // resolved. When a later layer (profile/call-site) replaced the model,
+            // that level is no longer explicit intent for the final model: keep it
+            // only if supported, else use the final model's own default — never
+            // downward-clamp a thinking-default model to "off" (v3.6; live case:
+            // explore's "low" + call-site glm-5.2 [high/max/off] silently landed
+            // on "off").
+            const modelReplacedAfterCategory = modelSource === "profile" || modelSource === "callsite";
+            route = {
+                ...route,
+                thinkingLevel: categoryThinkingLevel
+                    ? (modelReplacedAfterCategory && !supportedLevels.includes(route.thinkingLevel)
+                        ? getDefaultThinkingLevel(route.providerId, route.model)
+                        : normalizeThinkingLevel(route.thinkingLevel, supportedLevels))
+                    : normalizeInheritedThinkingLevel(route.providerId, route.model, route.thinkingLevel),
+            };
+        }
+        return {
+            ...route,
+            modelSource,
+            modelInherited: route.providerId === parentRoute.providerId && route.model === parentRoute.model,
+        };
+    }
+    /**
+     * Early route validation at dispatch time (design §7). Throws with an
+     * actionable message so the model self-corrects in the same turn. The
+     * cross-provider lock (§7.2.1) is snapshot-independent; catalog checks
+     * degrade silently when no snapshot is available (§7.0).
+     */
+    validateForDispatch(route) {
+        const parentProviderId = this.deps.parentRoute().providerId;
+        const snapshot = this.currentSnapshot();
+        const crossProvider = !!route.providerId && route.providerId !== parentProviderId;
+        if (crossProvider) {
+            // §7.2.1 — the lock. Profile/user-category routes are standing user
+            // authorization and always pass; only call-site routes are lockable.
+            if (!this.deps.routing.allowCrossProvider && route.modelSource === "callsite") {
+                throw new Error("Cross-provider routing is disabled in this session's config (agentRouting.allowCrossProvider). "
+                    + "Use a model from the parent provider, or ask the user to unlock cross-provider routing.");
+            }
+            // §7.2.2 — credentials, when a snapshot is available.
+            if (snapshot && !snapshot.runnableProviderIds.includes(route.providerId)) {
+                throw new Error(`Provider "${route.providerId}" is not configured with active credentials. `
+                    + `Available: ${snapshot.runnableProviderIds.join(", ") || "(none)"}.`);
+            }
+            // §7.2.3 amended (v3.6): the provider stays the authority — no hard
+            // catalog rejection — but a near-match against the target provider's
+            // local catalog is positive evidence of a mistyped id (a Grok parent
+            // invented "openai:gpt-5.6" for gpt-5.6-sol), so soft-reject with the
+            // correction and let the model fix it this turn. Genuinely unknown ids
+            // (no near candidates) still pass through with a note.
+            const targetCatalog = this.deps.routableModels?.()
+                .filter((entry) => entry.providerId === route.providerId) ?? [];
+            if (targetCatalog.length > 0 && !targetCatalog.some((entry) => entry.id === route.model)) {
+                const near = nearModelMatches(route.model, targetCatalog, { mode: "truncation" });
+                if (near.length > 0) {
+                    throw new Error(`Unknown model "${route.model}" for provider "${route.providerId}". Did you mean: ${near.join(", ")}?`);
+                }
+                return `model ${route.providerId}:${route.model} is not in the local catalog; the provider validates it`;
+            }
+            return `model ${route.providerId}:${route.model} is not locally verifiable; the provider validates it`;
+        }
+        // §7.1 — same-provider unknown model, resolved-provider based (never
+        // input-syntax based; qualified same-provider ids land here too).
+        if (snapshot && route.modelSource === "callsite") {
+            const known = snapshot.models.some((model) => model.id === route.model);
+            if (!known) {
+                if (snapshot.authoritative) {
+                    const available = snapshot.models
+                        .map((model) => (model.tier ? `${model.id} (${model.tier})` : model.id))
+                        .join(", ");
+                    throw new Error(`Unknown model "${route.model}" for provider "${parentProviderId}". Available: ${available}.`);
+                }
+                const near = nearModelMatches(route.model, snapshot.models.map((model) => ({ providerId: parentProviderId, id: model.id, name: model.name })));
+                return near.length > 0
+                    ? `model id "${route.model}" is unrecognized locally (did you mean: ${near.join(", ")}?); the provider validates it`
+                    : `model id "${route.model}" is unrecognized locally; the provider validates it`;
+            }
+        }
+        return undefined;
+    }
+    /** Routable catalog across runnable providers (design v3.6); undefined when unwired. */
+    listRoutableModels() {
+        try {
+            return this.deps.routableModels?.();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Current routing menu (design §4); undefined when no accessor is wired. */
+    promptSection() {
+        const snapshot = this.currentSnapshot();
+        if (!snapshot)
+            return undefined;
+        return buildModelRoutingPrompt(snapshot, this.deps.routing);
+    }
+    /**
+     * Routing menu rendered for a prospective parent route — used by model-
+     * switch transactions to build the NEXT prompt before mutating the agent
+     * (design §1.5).
+     */
+    promptSectionFor(parent) {
+        if (!this.deps.snapshot)
+            return undefined;
+        try {
+            return buildModelRoutingPrompt(this.deps.snapshot(parent), this.deps.routing);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

package/dist/agent/subagent/runtime.d.ts

@@ -0,0 +1,203 @@
+import { type AgentProfile, type SubagentRunResult } from "../profiles.js";
+import { type SubagentThreadRecord, type SubagentThreadSnapshot } from "../subagent-control.js";
+import { SubagentStore } from "../subagent-store.js";
+import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "../categories.js";
+import type { SubagentRouter } from "./router.js";
+import type { AgentEvent, ContentPart, Message, PermissionMode, Provider, ThinkingLevel, ToolRegistryEntry, ToolUpdate } from "../../types.js";
+import type { AgentSubagentRuntimeConfig } from "../../agent.js";
+import type { HookCombinedResult } from "../../hooks/index.js";
+/** The child agent surface the runtime drives; structurally satisfied by Agent. */
+export type ChildAgentLike = NonNullable<SubagentThreadRecord["agent"]>;
+export interface ChildAgentSpec {
+    provider: Provider;
+    providerId: string;
+    model: string;
+    tools: ToolRegistryEntry[];
+    thinkingLevel: ThinkingLevel;
+    mode: PermissionMode;
+    maxTurns?: number;
+    budgetSource: {
+        runId: string;
+        subAgentId?: string;
+    };
+    systemPrompt: string;
+    subAgentId: string;
+    /** Cross-restart resume history (design §7); already detached from the record. */
+    resumeMessages?: Message[];
+    /** Seed the child with the parent's recent context under its own system prompt. */
+    forkContext?: boolean;
+}
+export interface SubagentRuntimeParent {
+    /** LIVE — /model reassigns these mid-session. */
+    readonly provider: Provider;
+    readonly providerId: string;
+    /** API-facing model id, already stripped of any "provider:" prefix. */
+    readonly apiModel: string;
+    readonly thinkingLevel: ThinkingLevel;
+    readonly memoryPrompt: string | undefined;
+    readonly providerFactory: ((route: ResolvedSubagentRoute) => Provider | Promise<Provider>) | undefined;
+    /**
+     * The UNFILTERED tool map — deferred-but-unlocked entries included. Profile
+     * admission and child tool selection both depend on seeing every registered
+     * tool; handing them the active (deferred-filtered) list would block
+     * profiles that explicitly include an MCP or otherwise deferred tool.
+     */
+    allTools(): ToolRegistryEntry[];
+    createChild(spec: ChildAgentSpec): ChildAgentLike;
+    runExternalHook(input: {
+        eventName: string;
+        cwd: string;
+        runId?: string;
+        target?: string;
+        payload?: Record<string, unknown>;
+    }, abortSignal?: AbortSignal): Promise<{
+        result: HookCombinedResult;
+        events: AgentEvent[];
+    }>;
+}
+export interface SubagentRuntimeDeps {
+    parent: SubagentRuntimeParent;
+    router: SubagentRouter;
+    categories: AgentCategoriesConfig;
+    config: AgentSubagentRuntimeConfig;
+    /**
+     * Initial persist directory. Session switches repoint it through
+     * `repointPersistDir` (the TUI reuses one Agent across switches).
+     */
+    persistDir?: string;
+}
+export declare class SubagentRuntime {
+    private readonly parent;
+    private readonly router;
+    private readonly categories;
+    private readonly subagentsConfig;
+    /** Public so Agent can expose the same private-field access tests rely on. */
+    readonly store: SubagentStore;
+    private readonly scheduler;
+    private readonly childRunner;
+    private readonly resultIntegrator;
+    private pendingUpdates;
+    private readonly updateWakers;
+    constructor(deps: SubagentRuntimeDeps);
+    /** True when a background child has queued an update the loop should drain. */
+    hasPendingUpdates(): boolean;
+    /** Follows a session switch: evicts the old session's final children and loads the new one's. */
+    repointPersistDir(persistDir: string | undefined): void;
+    /**
+     * Inspects and cleans up a child's worktree at ANY terminal outcome:
+     * unchanged → removed; changed → kept for the parent to review, with a
+     * diff stat in the handoff (§8). Called from ChildRunner's onFinal and
+     * from all three scheduler-terminal callbacks — the scheduler paths used
+     * to skip reclamation entirely, leaking the directory and its git
+     * registration whenever a write child exhausted its retries
+     * (known-defects #1).
+     *
+     * When the directory was removed (= the child left no changes, so there
+     * is no file state to lose), the record's worktree reference is cleared:
+     * a kept reference would send a later resume into a deleted directory —
+     * clearing it makes the resume path rebuild a fresh worktree instead
+     * (see ChildRunner's reuse guard).
+     */
+    private reclaimWorktree;
+    /** Registers a waker so a blocked tool-execution loop learns about updates. */
+    subscribe(wake: () => void): () => void;
+    /**
+     * Completed background children whose summaries should reach parent context
+     * before the next inference turn (design §5). Pulled, not injected.
+     */
+    drainIngestionNotices(): string[];
+    runSubAgent(input: string | ContentPart[], cwd: string, options: {
+        profile: AgentProfile;
+        runId: string;
+        subAgentId: string;
+        parentToolCallId: string;
+        category?: string;
+        route?: ResolvedSubagentRoute;
+        approval?: "fail" | "disabled";
+        emitUpdate?: (update: ToolUpdate) => void;
+        description?: string;
+        abortSignal?: AbortSignal;
+        nickname?: string;
+        forkContext?: boolean;
+    }): Promise<SubagentRunResult>;
+    spawnSubAgent(input: string | ContentPart[], cwd: string, options: {
+        profile: AgentProfile;
+        parentToolCallId: string;
+        category?: string;
+        model?: string;
+        effort?: ThinkingLevel;
+        route?: ResolvedSubagentRoute;
+        approval?: "fail" | "disabled";
+        description?: string;
+        abortSignal?: AbortSignal;
+        forkContext?: boolean;
+    }): Promise<SubagentThreadSnapshot>;
+    waitSubAgents(options?: {
+        agentIds?: string[];
+        timeoutMs?: number;
+    }): Promise<SubagentThreadSnapshot[]>;
+    sendSubAgentInput(agentId: string, input: string | ContentPart[], cwd: string, options?: {
+        interrupt?: boolean;
+        parentToolCallId?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<SubagentThreadSnapshot>;
+    closeSubAgent(agentId: string): Promise<SubagentThreadSnapshot>;
+    /**
+     * Live (non-final) children only — the delegation-nudge gate
+     * (large-task-delegation design §2). listSubAgents() is a grows-only
+     * session history (finished + resumed children stay forever), so it must
+     * never be used to answer "am I currently delegating?".
+     */
+    activeSubAgentCount(): number;
+    listSubAgents(): SubagentThreadSnapshot[];
+    executeWorkflow(cwd: string, options: {
+        script: string;
+        args?: unknown;
+        parentToolCallId: string;
+        abortSignal?: AbortSignal;
+        directEmit?: (update: ToolUpdate) => void;
+        queueUpdates?: boolean;
+        ensureProfileTrusted?: (profile: AgentProfile) => Promise<{
+            content: string | unknown;
+        } | undefined>;
+    }): Promise<{
+        result: {
+            ok: true;
+            value: unknown;
+        } | {
+            ok: false;
+            error: string;
+        };
+        agentCount: number;
+        logs: string[];
+        snapshots: SubagentThreadSnapshot[];
+    }>;
+    markSubagentDelivered(agentId: string): void;
+    private snapshotSubagent;
+    /** Returns the blocking diagnostic message when the profile cannot run, else undefined. */
+    private admitSubagentProfile;
+    /**
+     * Background children (queueUpdates) get their results ingested before the
+     * parent's next inference turn (design §5); foreground children (team,
+     * legacy task) deliver through their tool result instead.
+     */
+    private maybeEnqueueIngestion;
+    private finalizeSubagentBlocked;
+    private dispatchSubagentRun;
+    private emitSubagentLifecycle;
+    /** Lets a blocked tool-execution loop drain freshly queued subagent updates. */
+    private wakeSubagentUpdateWaiters;
+    private runSubagentLifecycleHookFor;
+    private createSubagentThreadRecord;
+    private runSubagentThread;
+    private createSubAgentInstance;
+    private resolveProviderForRoute;
+    private buildSubagentUpdate;
+    private queueSubagentUpdate;
+    /** Queued background-child updates for Agent.run() to emit. */
+    drainToolUpdates(): AgentEvent[];
+    private activeSubagentNicknames;
+    private resolveSubagentTargets;
+}
+export declare function isFinalSubagentStatus(status: SubagentThreadRecord["status"]): boolean;
+export declare function normalizeWaitTimeout(value: number | undefined): number;