@bubblebrain-ai/bubble 0.0.49 → 0.0.50

package/dist/agent/abort-errors.d.ts

@@ -12,3 +12,7 @@ export declare class SubagentAbortError extends AgentAbortError {
 }
 /** Shown when the model produced no user-visible content despite recovery attempts. */
 export declare const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function isAbortLikeError(error: unknown, signal?: AbortSignal): boolean;
+export declare function isAbortError(error: unknown, signal?: AbortSignal): boolean;
+export declare function summarizeInterruptError(error: unknown): string;

package/dist/agent/abort-errors.js

@@ -19,3 +19,33 @@ export class SubagentAbortError extends AgentAbortError {
 }
 /** Shown when the model produced no user-visible content despite recovery attempts. */
 export const EMPTY_ASSISTANT_FALLBACK = "The model returned no user-visible response. Please retry, or switch models if this keeps happening.";
+export function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        throw reason;
+    throw new AgentAbortError(typeof reason === "string" ? reason : undefined);
+}
+export function isAbortLikeError(error, signal) {
+    if (signal?.aborted)
+        return true;
+    if (error instanceof AgentAbortError)
+        return true;
+    if (error instanceof DOMException && error.name === "AbortError")
+        return true;
+    if (typeof error === "object" && error !== null && error.name === "AbortError")
+        return true;
+    return false;
+}
+export function isAbortError(error, signal) {
+    return isAbortLikeError(error, signal);
+}
+export function summarizeInterruptError(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : String(error);
+    return message.replace(/\s+/g, " ").trim().slice(0, 240) || "unknown error";
+}

package/dist/agent/provider-fingerprint.d.ts

@@ -0,0 +1,6 @@
+import type { Message, ProviderMessage, ProviderMetadataProvider, ProviderRawContentBlock, ToolDefinition } from "../types.js";
+export declare function appendProviderContentBlock(message: Extract<Message, {
+    role: "assistant";
+}>, provider: ProviderMetadataProvider, block: ProviderRawContentBlock): void;
+export declare function buildProviderRequestFingerprint(messages: ProviderMessage[], tools: ToolDefinition[], providerId: string, toolChoice?: string): Record<string, unknown>;
+export declare function cloneProviderRawContentBlock(block: ProviderRawContentBlock): ProviderRawContentBlock;

package/dist/agent/provider-fingerprint.js

@@ -0,0 +1,89 @@
+/**
+ * Provider-request fingerprints and raw content-block plumbing.
+ *
+ * The fingerprint is a structural digest of the projected request (roles,
+ * char volumes, JSON byte sizes) used to detect whether a retried request
+ * actually changed, and to trace what the model saw.
+ */
+import { estimateContextTokens } from "../context/budget.js";
+export function appendProviderContentBlock(message, provider, block) {
+    const current = message.providerMetadata?.[provider]?.contentBlocks ?? [];
+    message.providerMetadata = {
+        ...message.providerMetadata,
+        [provider]: {
+            ...message.providerMetadata?.[provider],
+            contentBlocks: [...current, cloneProviderRawContentBlock(block)],
+        },
+    };
+}
+export function buildProviderRequestFingerprint(messages, tools, providerId, toolChoice) {
+    const roleCounts = {};
+    let contentChars = 0;
+    let reasoningChars = 0;
+    let toolResultChars = 0;
+    let maxToolResultChars = 0;
+    let assistantToolCalls = 0;
+    let rawAnthropicBlocks = 0;
+    let rawAnthropicThinkingBlocks = 0;
+    let rawAnthropicSignatureChars = 0;
+    for (const message of messages) {
+        roleCounts[message.role] = (roleCounts[message.role] ?? 0) + 1;
+        if (message.role === "assistant") {
+            contentChars += message.content.length;
+            reasoningChars += message.reasoning?.length ?? 0;
+            assistantToolCalls += message.toolCalls?.length ?? 0;
+            const blocks = message.providerMetadata?.anthropic?.contentBlocks ?? [];
+            rawAnthropicBlocks += blocks.length;
+            for (const block of blocks) {
+                if (block.type === "thinking" || block.type === "redacted_thinking") {
+                    rawAnthropicThinkingBlocks += 1;
+                }
+                if (typeof block.signature === "string") {
+                    rawAnthropicSignatureChars += block.signature.length;
+                }
+            }
+        }
+        else if (message.role === "tool") {
+            toolResultChars += message.content.length;
+            maxToolResultChars = Math.max(maxToolResultChars, message.content.length);
+        }
+        else if (message.role === "user") {
+            contentChars += typeof message.content === "string"
+                ? message.content.length
+                : message.content.reduce((sum, part) => sum + (part.type === "text" ? part.text.length : part.image_url.url.length), 0);
+        }
+        else {
+            contentChars += message.content.length;
+        }
+    }
+    const systemMessages = messages.filter((message) => message.role === "system");
+    const bodyMessages = messages.filter((message) => message.role !== "system");
+    const systemJsonBytes = Buffer.byteLength(JSON.stringify(systemMessages), "utf8");
+    const bodyJsonBytes = Buffer.byteLength(JSON.stringify(bodyMessages), "utf8");
+    const toolSchemaJsonBytes = Buffer.byteLength(JSON.stringify(tools), "utf8");
+    return {
+        roleCounts,
+        estimatedTokens: estimateContextTokens(messages, providerId),
+        projectedJsonBytes: Buffer.byteLength(JSON.stringify(messages), "utf8"),
+        systemJsonBytes,
+        bodyJsonBytes,
+        toolSchemaJsonBytes,
+        staticPrefixJsonBytes: Buffer.byteLength(JSON.stringify({
+            system: systemMessages,
+            tools,
+            tool_choice: toolChoice,
+        }), "utf8"),
+        toolChoice,
+        contentChars,
+        reasoningChars,
+        toolResultChars,
+        maxToolResultChars,
+        assistantToolCalls,
+        rawAnthropicBlocks,
+        rawAnthropicThinkingBlocks,
+        rawAnthropicSignatureChars,
+    };
+}
+export function cloneProviderRawContentBlock(block) {
+    return JSON.parse(JSON.stringify(block));
+}

package/dist/agent/resident-history.d.ts

@@ -0,0 +1,7 @@
+import type { Message } from "../types.js";
+export declare const RESIDENT_HISTORY_KEEP_RECENT_TURNS = 3;
+export declare const RESIDENT_HISTORY_HEAP_HARD_LIMIT: number;
+export declare function estimateResidentChars(messages: Message[]): number;
+export declare function estimateToolPayloadChars(messages: Message[]): number;
+export declare function countUserTurns(messages: Message[]): number;
+export declare function getCurrentHeapUsed(): number;

package/dist/agent/resident-history.js

@@ -0,0 +1,61 @@
+/**
+ * Resident-history size estimation and the cliff-edge guards that decide when
+ * in-memory history is compacted (see docs/harness-thinning.md, wave 2).
+ */
+import { isRealUserMessage } from "../context/compact.js";
+export const RESIDENT_HISTORY_KEEP_RECENT_TURNS = 3;
+export const RESIDENT_HISTORY_HEAP_HARD_LIMIT = 768 * 1024 * 1024;
+export function estimateResidentChars(messages) {
+    let total = 0;
+    for (const message of messages) {
+        switch (message.role) {
+            case "system":
+            case "meta":
+                total += message.content.length;
+                break;
+            case "tool":
+                total += message.content.length + message.toolCallId.length;
+                break;
+            case "assistant":
+                total += message.content.length + (message.reasoning?.length ?? 0);
+                total += message.toolCalls?.reduce((sum, toolCall) => sum + toolCall.id.length + toolCall.name.length + toolCall.arguments.length, 0) ?? 0;
+                break;
+            case "user":
+                if (typeof message.content === "string") {
+                    total += message.content.length;
+                }
+                else {
+                    total += message.content.reduce((sum, part) => {
+                        if (part.type === "text") {
+                            return sum + part.text.length;
+                        }
+                        return sum + part.image_url.url.length;
+                    }, 0);
+                }
+                break;
+        }
+    }
+    return total;
+}
+export function estimateToolPayloadChars(messages) {
+    return messages.reduce((sum, message) => {
+        if (message.role !== "tool") {
+            return sum;
+        }
+        return sum + message.content.length;
+    }, 0);
+}
+export function countUserTurns(messages) {
+    // Real user turns only: projected reminders and summary envelopes are
+    // user-ROLE but not user TURNS — counting them used to shrink the keep
+    // window and fire compaction almost every turn.
+    return messages.reduce((count, message) => count + (isRealUserMessage(message) ? 1 : 0), 0);
+}
+export function getCurrentHeapUsed() {
+    try {
+        return process.memoryUsage().heapUsed;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/agent/transcript-helpers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Transcript-level helpers: interrupted-run boundaries, the cancelled-tool
+ * sentinel, required-arg validation and the subagent-lifecycle tool-name
+ * predicate used when forking context for children.
+ */
+import type { Message, ToolResult } from "../types.js";
+export declare function findMissingRequiredArgs(schema: {
+    required?: string[];
+} | undefined, args: Record<string, any> | undefined): string[];
+export declare function shouldAppendModelInterruptedBoundary(messages: Message[]): boolean;
+export declare function createModelInterruptedMessage(error: unknown, metadata: {
+    model: string;
+    providerId: string;
+    modelId: string;
+}): Extract<Message, {
+    role: "assistant";
+}>;
+export declare function lastProviderMessage(messages: Message[]): Message | undefined;
+export declare function cancelledToolResult(toolName: string): ToolResult;
+export declare function isSubagentLifecycleTool(name: string): boolean;

package/dist/agent/transcript-helpers.js

@@ -0,0 +1,62 @@
+import { summarizeInterruptError } from "./abort-errors.js";
+export function findMissingRequiredArgs(schema, args) {
+    const required = schema?.required;
+    if (!required || required.length === 0)
+        return [];
+    const missing = [];
+    for (const name of required) {
+        const value = args ? args[name] : undefined;
+        // Empty strings/arrays are intentionally allowed — writing an empty file
+        // or passing an empty list can be legitimate. Only undefined/null counts
+        // as "missing", because the observed failure mode is `finalArgs: "{}"`
+        // where the field is entirely absent.
+        if (value === undefined || value === null) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+export function shouldAppendModelInterruptedBoundary(messages) {
+    return messages.at(-1)?.role === "tool";
+}
+export function createModelInterruptedMessage(error, metadata) {
+    return {
+        role: "assistant",
+        content: `[model request interrupted before a final answer was produced: ${summarizeInterruptError(error)}]`,
+        model: metadata.model,
+        providerId: metadata.providerId,
+        modelId: metadata.modelId,
+    };
+}
+export function lastProviderMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role === "system" || message.role === "meta")
+            continue;
+        return message;
+    }
+    return undefined;
+}
+export function cancelledToolResult(toolName) {
+    return {
+        content: `Tool "${toolName}" was cancelled.`,
+        isError: true,
+        status: "cancelled",
+        metadata: { reason: "cancelled" },
+    };
+}
+export function isSubagentLifecycleTool(name) {
+    return name === "subagent"
+        || name === "spawn_agent"
+        || name === "wait_agent"
+        || name === "send_input"
+        || name === "close_agent"
+        || name === "list_agents"
+        || name === "run_workflow"
+        || name === "wait_workflow"
+        // Legacy names: still present in transcripts recorded before the tools
+        // were removed (2026-07-06); forked children must not inherit their
+        // dangling tool_calls either.
+        || name === "agent_team"
+        || name === "agent_batch";
+}

package/dist/agent/update-queue.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wake-latched update queue shared by the agent run loop: tool updates,
+ * subagent deliveries and workflow completions all park here until the loop
+ * is ready to drain them.
+ */
+/** Exported for tests: the wake latch below is easiest to pin directly. */
+export declare function createUpdateQueue<T>(): {
+    push(item: T): void;
+    drain(): T[];
+    hasItems(): boolean;
+    wait(signal?: AbortSignal): Promise<"woken" | "aborted">;
+    wake(): void;
+};

package/dist/agent/update-queue.js

@@ -0,0 +1,69 @@
+/**
+ * Wake-latched update queue shared by the agent run loop: tool updates,
+ * subagent deliveries and workflow completions all park here until the loop
+ * is ready to drain them.
+ */
+/** Exported for tests: the wake latch below is easiest to pin directly. */
+export function createUpdateQueue() {
+    const items = [];
+    let waiter;
+    let abortCleanup;
+    // Latch for wakes that arrive with no parked waiter — a wake() fired while
+    // the consuming generator is suspended at a yield would otherwise be lost.
+    // Callers today each pair their wake with a synchronously-checked flag
+    // (items / settled / pendingSubagentUpdates), so no wake is currently
+    // dropped; the latch keeps that correctness inside the queue instead of
+    // depending on every future caller repeating the pairing.
+    let signaled = false;
+    return {
+        push(item) {
+            items.push(item);
+            this.wake();
+        },
+        drain() {
+            return items.splice(0, items.length);
+        },
+        hasItems() {
+            return items.length > 0;
+        },
+        wait(signal) {
+            if (items.length > 0)
+                return Promise.resolve("woken");
+            if (signaled) {
+                signaled = false;
+                return Promise.resolve("woken");
+            }
+            if (signal?.aborted)
+                return Promise.resolve("aborted");
+            return new Promise((resolve) => {
+                abortCleanup?.();
+                abortCleanup = undefined;
+                const finish = (status) => {
+                    if (waiter !== resolve)
+                        return;
+                    waiter = undefined;
+                    abortCleanup?.();
+                    abortCleanup = undefined;
+                    resolve(status);
+                };
+                if (signal) {
+                    const onAbort = () => finish("aborted");
+                    signal.addEventListener("abort", onAbort, { once: true });
+                    abortCleanup = () => signal.removeEventListener("abort", onAbort);
+                }
+                waiter = resolve;
+            });
+        },
+        wake() {
+            const resolve = waiter;
+            if (!resolve) {
+                signaled = true;
+                return;
+            }
+            waiter = undefined;
+            abortCleanup?.();
+            abortCleanup = undefined;
+            resolve("woken");
+        },
+    };
+}

package/dist/agent.d.ts

@@ -6,13 +6,15 @@ import { type ContextUsageSnapshot } from "./context/usage.js";
 import type { AgentEvent, AgentInputController, ContentPart, PermissionMode, Message, Provider, ThinkingLevel, Todo, ToolResult, ToolRegistryEntry, ToolUpdate } from "./types.js";
 import { type TurnHooks } from "./orchestrator/hooks.js";
 import type { ExternalHookController } from "./hooks/controller.js";
-import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "./agent/categories.js";
+import type { AgentCategoriesConfig, ResolvedSubagentRoute } from "./agent/categories.js";
 import { type AgentRoutingConfig, type RoutableModelEntry, type RoutableModelIndex, type RoutingSnapshotAccessor } from "./agent/routing-catalog.js";
 import { SubagentRuntime } from "./agent/subagent/runtime.js";
-import { type WorkflowRunSnapshot } from "./agent/workflow/control.js";
 import { BudgetLedger } from "./agent/budget-ledger.js";
-import { type AgentProfile, type SubagentRunResult } from "./agent/profiles.js";
-import { type SubagentThreadSnapshot } from "./agent/subagent-control.js";
+import { type WorkflowRunSnapshot } from "./agent/workflow/control.js";
+import type { AgentProfile, SubagentRunResult } from "./agent/profiles.js";
+import type { SubagentThreadSnapshot } from "./agent/subagent-control.js";
+import { SubagentStore } from "./agent/subagent-store.js";
+export { createUpdateQueue } from "./agent/update-queue.js";
 import { type RateLimitPolicy } from "./network/errors.js";
 import type { SkillSummary } from "./skills/types.js";
 import type { FileStateTracker } from "./tools/file-state.js";
@@ -108,7 +110,18 @@ export interface AgentRunOptions {
     resumeWithoutInput?: boolean;
 }
 export declare class Agent {
-    messages: Message[];
+    /**
+     * Backing store for the public `messages` accessor. All whole-array
+     * rewrites (clear/compact/rewind/session switch/subagent fork) go through
+     * the setter, which notifies `onContextChanged` subscribers — that push
+     * channel is what keeps derived UI (e.g. the footer usage readout) in sync
+     * without per-path refresh calls that are easy to forget.
+     */
+    private _messages;
+    private contextChangedListeners;
+    private notifyingContextChange;
+    get messages(): Message[];
+    set messages(value: Message[]);
     private provider;
     private sessionID?;
     /**
@@ -226,6 +239,15 @@ export declare class Agent {
         providerId: string;
         model: string;
     }): string | undefined;
+    /**
+     * Push subscription for derived-context consumers (TUI footer, hosts).
+     * Fires whenever resident context mutates in a way that changes a
+     * `getContextUsageSnapshot()` reading: whole-array message rewrites,
+     * appended messages, system-prompt replacement, or model/provider switches
+     * (window size / estimation basis). Returns an unsubscribe function.
+     */
+    onContextChanged(listener: () => void): () => void;
+    private notifyContextChanged;
     getContextUsageSnapshot(): ContextUsageSnapshot;
     resetContextUsageAnchor(): void;
     /** Whether a given tool is deferred and not yet unlocked. */
@@ -326,7 +348,7 @@ export declare class Agent {
      * `(agent as any).subagentStore`; keeping this forward means the extraction
      * changed no caller, test or otherwise.
      */
-    private get subagentStore();
+    get subagentStore(): SubagentStore;
     /** run_workflow children are workflowInternal and invisible to listSubAgents. */
     hasRunningWorkflow(): boolean;
     /**
@@ -393,7 +415,10 @@ export declare class Agent {
      * haiku for these twenty scouts" per spawn/batch member at request time.
      */
     /** Kept as a thin delegator: routing decisions now live in SubagentRouter. */
-    private resolveRouteForSubagent;
+    resolveRouteForSubagent(profile: AgentProfile, category: string | undefined, override?: {
+        model?: string;
+        effort?: ThinkingLevel;
+    }): ResolvedSubagentRoute;
     /** Routable catalog across runnable providers (design v3.6); undefined when unwired. */
     listRoutableModels(): RoutableModelEntry[] | undefined;
     /**
@@ -418,11 +443,3 @@ export declare class Agent {
     private clearTodosAfterInterruptedRun;
     private executeTool;
 }
-/** Exported for tests: the wake latch below is easiest to pin directly. */
-export declare function createUpdateQueue<T>(): {
-    push(item: T): void;
-    drain(): T[];
-    hasItems(): boolean;
-    wait(signal?: AbortSignal): Promise<"woken" | "aborted">;
-    wake(): void;
-};