@bubblebrain-ai/bubble 0.0.1

package/dist/config.js

@@ -0,0 +1,144 @@
+/**
+ * User-level configuration manager.
+ *
+ * Uses a single JSON file in Bubble home, normally ~/.bubble/config.json.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getBubbleHome } from "./bubble-home.js";
+const HIDDEN_PROVIDER_IDS = new Set(["openrouter", "openai-codex"]);
+function getConfigPath() {
+    return join(getBubbleHome(), "config.json");
+}
+function isHiddenProviderId(providerId) {
+    return !!providerId && HIDDEN_PROVIDER_IDS.has(providerId);
+}
+function modelProviderId(model) {
+    if (!model.includes(":"))
+        return undefined;
+    return model.split(":", 1)[0];
+}
+function sanitizeRecentModels(models) {
+    if (!models)
+        return undefined;
+    return models.filter((model) => !isHiddenProviderId(modelProviderId(model)));
+}
+function sanitizeProviders(providers) {
+    if (!providers)
+        return undefined;
+    return providers.filter((provider) => !isHiddenProviderId(provider.id));
+}
+function sanitizeDefaultModel(model) {
+    if (!model)
+        return undefined;
+    return isHiddenProviderId(modelProviderId(model)) ? undefined : model;
+}
+function sanitizeDefaultProvider(providerId) {
+    return isHiddenProviderId(providerId) ? undefined : providerId;
+}
+export class UserConfig {
+    data = {};
+    constructor() {
+        this.load();
+    }
+    load() {
+        const configPath = getConfigPath();
+        if (!existsSync(configPath))
+            return;
+        try {
+            const raw = readFileSync(configPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            this.data = {
+                ...parsed,
+                defaultModel: sanitizeDefaultModel(parsed.defaultModel),
+                recentModels: sanitizeRecentModels(parsed.recentModels),
+                providers: sanitizeProviders(parsed.providers),
+                defaultProvider: sanitizeDefaultProvider(parsed.defaultProvider),
+            };
+        }
+        catch {
+            this.data = {};
+        }
+    }
+    save() {
+        const configPath = getConfigPath();
+        const dir = dirname(configPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(configPath, JSON.stringify(this.data, null, 2) + "\n");
+    }
+    getDefaultModel() {
+        return sanitizeDefaultModel(this.data.defaultModel)
+            ?? sanitizeRecentModels(this.data.recentModels)?.[0];
+    }
+    setDefaultModel(model) {
+        this.data.defaultModel = sanitizeDefaultModel(model);
+        this.save();
+    }
+    getDefaultThinkingLevel() {
+        return this.data.defaultThinkingLevel;
+    }
+    setDefaultThinkingLevel(level) {
+        this.data.defaultThinkingLevel = level;
+        this.save();
+    }
+    getRecentModels() {
+        return sanitizeRecentModels(this.data.recentModels)?.slice() ?? [];
+    }
+    pushRecentModel(model) {
+        if (isHiddenProviderId(modelProviderId(model))) {
+            return;
+        }
+        const recent = this.data.recentModels ?? [];
+        const uniq = [model, ...recent.filter((m) => m !== model)];
+        const sanitized = sanitizeRecentModels(uniq.slice(0, 10));
+        this.data.recentModels = sanitized;
+        this.data.defaultModel = sanitized?.[0];
+        this.save();
+    }
+    getApiKey() {
+        return this.data.apiKey;
+    }
+    setApiKey(key) {
+        this.data.apiKey = key;
+        this.save();
+    }
+    getProviders() {
+        return sanitizeProviders(this.data.providers)?.slice() ?? [];
+    }
+    setProviders(providers) {
+        this.data.providers = sanitizeProviders(providers);
+        this.save();
+    }
+    getDefaultProvider() {
+        return sanitizeDefaultProvider(this.data.defaultProvider);
+    }
+    setDefaultProvider(id) {
+        this.data.defaultProvider = sanitizeDefaultProvider(id);
+        this.save();
+    }
+    getSkillPaths() {
+        return Array.isArray(this.data.skillPaths) ? this.data.skillPaths.slice() : [];
+    }
+    setSkillPaths(paths) {
+        this.data.skillPaths = paths.slice();
+        this.save();
+    }
+    getTheme() {
+        const theme = this.data.theme;
+        if (!theme || typeof theme !== "object" || Array.isArray(theme))
+            return {};
+        return Object.fromEntries(Object.entries(theme).filter(([, value]) => typeof value === "string"));
+    }
+    setTheme(theme) {
+        this.data.theme = { ...theme };
+        this.save();
+    }
+}
+/** Mask an API key for safe display. */
+export function maskKey(key) {
+    if (key.length <= 12)
+        return "****";
+    return key.slice(0, 6) + "..." + key.slice(-4);
+}

package/dist/context/budget.d.ts

@@ -0,0 +1,21 @@
+import type { Message } from "../types.js";
+export declare const OUTPUT_RESERVE_TOKENS = 20000;
+export declare const AUTOCOMPACT_BUFFER_TOKENS = 13000;
+export declare const PRUNE_BUFFER_TOKENS = 50000;
+export declare const MIN_WINDOW_FOR_RESERVE = 40000;
+export interface ContextBudget {
+    estimatedTokens: number;
+    contextWindow?: number;
+    percent?: number;
+    shouldPrune: boolean;
+    shouldCompact: boolean;
+}
+export interface ContextBudgetOptions {
+    /** Authoritative input-token count from the most recent response usage. */
+    usageAnchorTokens?: number;
+    /** Messages appended after the anchor (their tokens are estimated and added). */
+    tailMessages?: Message[];
+}
+export declare function estimateMessageTokens(message: Message): number;
+export declare function estimateContextTokens(messages: Message[]): number;
+export declare function getContextBudget(providerId: string, modelId: string, messages: Message[], options?: ContextBudgetOptions): ContextBudget;

package/dist/context/budget.js

@@ -0,0 +1,72 @@
+import { getModelContextWindow } from "../model-catalog.js";
+export const OUTPUT_RESERVE_TOKENS = 20_000;
+export const AUTOCOMPACT_BUFFER_TOKENS = 13_000;
+export const PRUNE_BUFFER_TOKENS = 50_000;
+export const MIN_WINDOW_FOR_RESERVE = 40_000;
+export function estimateMessageTokens(message) {
+    switch (message.role) {
+        case "system":
+        case "tool":
+            return estimateTextTokens(message.content);
+        case "assistant":
+            return estimateTextTokens(message.content)
+                + estimateTextTokens(message.reasoning ?? "")
+                + (message.toolCalls?.reduce((sum, toolCall) => sum + estimateTextTokens(toolCall.arguments) + 12, 0) ?? 0)
+                + 8;
+        case "user":
+            if (typeof message.content === "string") {
+                return estimateTextTokens(message.content) + 8;
+            }
+            return message.content.reduce((sum, part) => {
+                if (part.type === "text") {
+                    return sum + estimateTextTokens(part.text);
+                }
+                return sum + 256;
+            }, 8);
+    }
+}
+export function estimateContextTokens(messages) {
+    return messages.reduce((sum, message) => sum + estimateMessageTokens(message), 0);
+}
+export function getContextBudget(providerId, modelId, messages, options = {}) {
+    const estimatedTokens = computeEstimatedTokens(messages, options);
+    const contextWindow = getModelContextWindow(providerId, modelId);
+    const percent = contextWindow ? Math.min(100, (estimatedTokens / contextWindow) * 100) : undefined;
+    return {
+        estimatedTokens,
+        contextWindow,
+        percent,
+        shouldPrune: shouldTriggerPrune(estimatedTokens, contextWindow),
+        shouldCompact: shouldTriggerCompact(estimatedTokens, contextWindow),
+    };
+}
+function computeEstimatedTokens(messages, options) {
+    if (options.usageAnchorTokens !== undefined && options.tailMessages) {
+        return options.usageAnchorTokens + estimateContextTokens(options.tailMessages);
+    }
+    return estimateContextTokens(messages);
+}
+function shouldTriggerPrune(estimatedTokens, contextWindow) {
+    if (!contextWindow) {
+        return estimatedTokens >= 16_000;
+    }
+    const threshold = contextWindow >= MIN_WINDOW_FOR_RESERVE
+        ? contextWindow - OUTPUT_RESERVE_TOKENS - PRUNE_BUFFER_TOKENS
+        : contextWindow * 0.55;
+    return estimatedTokens >= threshold;
+}
+function shouldTriggerCompact(estimatedTokens, contextWindow) {
+    if (!contextWindow) {
+        return estimatedTokens >= 32_000;
+    }
+    const threshold = contextWindow >= MIN_WINDOW_FOR_RESERVE
+        ? contextWindow - OUTPUT_RESERVE_TOKENS - AUTOCOMPACT_BUFFER_TOKENS
+        : contextWindow * 0.75;
+    return estimatedTokens >= threshold;
+}
+function estimateTextTokens(text) {
+    if (!text) {
+        return 0;
+    }
+    return Math.ceil(text.length / 4);
+}

package/dist/context/compact-llm.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LLM-backed structured conversation compaction.
+ *
+ * Generates a 9-section summary of the older turns via the provider's
+ * completion API, replacing the dropped history with a single system
+ * message. Falls back to the heuristic `compactMessages` if the LLM call
+ * fails.
+ */
+import type { CompactOptions, CompactResult } from "./compact.js";
+import type { Message, Provider } from "../types.js";
+export interface LLMCompactOptions extends CompactOptions {
+    provider: Provider;
+    model: string;
+    thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+export declare function compactMessagesWithLLM(messages: Message[], options: LLMCompactOptions): Promise<CompactResult>;

package/dist/context/compact-llm.js

@@ -0,0 +1,132 @@
+/**
+ * LLM-backed structured conversation compaction.
+ *
+ * Generates a 9-section summary of the older turns via the provider's
+ * completion API, replacing the dropped history with a single system
+ * message. Falls back to the heuristic `compactMessages` if the LLM call
+ * fails.
+ */
+import { compactMessages as compactMessagesHeuristic } from "./compact.js";
+const COMPACT_SYSTEM_PROMPT = `You are a conversation summarizer. Your job is to produce a structured
+summary of an earlier portion of a software-engineering assistant's
+conversation so that the assistant can continue working without the full
+history. Preserve fidelity over brevity where the user's intent, file
+paths, or decisions are concerned. Output ONLY the summary, no preamble.`;
+const COMPACT_INSTRUCTIONS = `Summarize the conversation above using exactly these 9 sections, each
+preceded by the literal heading on its own line. If a section has no
+content, write "None".
+
+1. Primary Request and Intent
+   - What the user ultimately wants, in their own framing.
+
+2. Key Technical Concepts
+   - Libraries, frameworks, architectural patterns referenced.
+
+3. Files and Code Sections
+   - Files read, written, or discussed. Include full paths and a one-line note.
+
+4. Errors and Fixes
+   - Bugs encountered and how they were resolved.
+
+5. Problem Solving
+   - Non-trivial debugging or design decisions.
+
+6. All User Messages
+   - Every user message, verbatim, in order. Do not summarize here.
+
+7. Pending Tasks
+   - Work that was planned but not yet completed.
+
+8. Current Work
+   - What was being actively worked on when the summary was taken.
+
+9. Optional Next Step
+   - The single most natural next action, if obvious.`;
+export async function compactMessagesWithLLM(messages, options) {
+    const keepRecentTurns = options.keepRecentTurns ?? 2;
+    const systemMessages = messages.filter((m) => m.role === "system");
+    const nonSystemMessages = messages.filter((m) => m.role !== "system");
+    const turnStartIndexes = nonSystemMessages
+        .map((m, i) => (m.role === "user" ? i : -1))
+        .filter((i) => i >= 0);
+    if (turnStartIndexes.length <= keepRecentTurns) {
+        return { compacted: false };
+    }
+    const keepStartIndex = turnStartIndexes[Math.max(0, turnStartIndexes.length - keepRecentTurns)];
+    if (keepStartIndex <= 0) {
+        return { compacted: false };
+    }
+    const oldMessages = nonSystemMessages.slice(0, keepStartIndex);
+    const keptMessages = nonSystemMessages.slice(keepStartIndex);
+    let summary;
+    try {
+        summary = await generateSummary(oldMessages, options);
+    }
+    catch {
+        return compactMessagesHeuristic(messages, { keepRecentTurns, maxSummaryItems: options.maxSummaryItems });
+    }
+    if (!summary.trim()) {
+        return compactMessagesHeuristic(messages, { keepRecentTurns, maxSummaryItems: options.maxSummaryItems });
+    }
+    return {
+        compacted: true,
+        summary,
+        messages: [
+            ...systemMessages,
+            { role: "system", content: `Previous conversation summary:\n${summary}` },
+            ...keptMessages,
+        ],
+        droppedEntries: oldMessages.length,
+    };
+}
+async function generateSummary(oldMessages, options) {
+    const transcript = serializeTranscript(oldMessages);
+    const messages = [
+        { role: "system", content: COMPACT_SYSTEM_PROMPT },
+        {
+            role: "user",
+            content: `Conversation to summarize:\n\n${transcript}\n\n---\n\n${COMPACT_INSTRUCTIONS}`,
+        },
+    ];
+    return options.provider.complete(messages, {
+        model: options.model,
+        temperature: 0.2,
+        thinkingLevel: options.thinkingLevel ?? "off",
+    });
+}
+function serializeTranscript(messages) {
+    const lines = [];
+    for (const message of messages) {
+        switch (message.role) {
+            case "user":
+                lines.push(`[user] ${contentToText(message.content)}`);
+                break;
+            case "assistant":
+                if (message.content)
+                    lines.push(`[assistant] ${message.content}`);
+                for (const toolCall of message.toolCalls ?? []) {
+                    lines.push(`[assistant tool_call] ${toolCall.name}(${toolCall.arguments})`);
+                }
+                break;
+            case "tool":
+                lines.push(`[tool] ${truncate(message.content, 800)}`);
+                break;
+            case "system":
+                break;
+        }
+    }
+    return lines.join("\n");
+}
+function contentToText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .filter((p) => p.type === "text")
+        .map((p) => p.text)
+        .join(" ");
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}

package/dist/context/compact.d.ts

@@ -0,0 +1,15 @@
+import type { Message } from "../types.js";
+import type { SessionLogEntry } from "../session-types.js";
+export interface CompactOptions {
+    keepRecentTurns?: number;
+    maxSummaryItems?: number;
+}
+export interface CompactResult {
+    compacted: boolean;
+    summary?: string;
+    entries?: SessionLogEntry[];
+    messages?: Message[];
+    droppedEntries?: number;
+}
+export declare function compactSessionEntries(entries: SessionLogEntry[], options?: CompactOptions): CompactResult;
+export declare function compactMessages(messages: Message[], options?: CompactOptions): CompactResult;

package/dist/context/compact.js

@@ -0,0 +1,251 @@
+export function compactSessionEntries(entries, options = {}) {
+    const keepRecentTurns = options.keepRecentTurns ?? 2;
+    const maxSummaryItems = options.maxSummaryItems ?? 4;
+    const metadataEntries = entries.filter((entry) => entry.type === "metadata");
+    const nonMetadataEntries = entries.filter((entry) => entry.type !== "metadata");
+    const latestSummaryIndex = findLatestSummaryIndex(nonMetadataEntries);
+    const baseIndex = latestSummaryIndex >= 0 ? latestSummaryIndex + 1 : 0;
+    const activeEntries = nonMetadataEntries.slice(baseIndex);
+    const turnStartIndexes = activeEntries
+        .map((entry, index) => (entry.type === "user_message" ? index : -1))
+        .filter((index) => index >= 0);
+    if (turnStartIndexes.length <= keepRecentTurns) {
+        return { compacted: false };
+    }
+    const keepStartIndex = turnStartIndexes[Math.max(0, turnStartIndexes.length - keepRecentTurns)];
+    if (keepStartIndex <= 0) {
+        return { compacted: false };
+    }
+    const oldEntries = activeEntries.slice(0, keepStartIndex);
+    const keptEntries = activeEntries.slice(keepStartIndex);
+    const summary = buildCompactionSummary(oldEntries, maxSummaryItems);
+    if (!summary) {
+        return { compacted: false };
+    }
+    const summaryEntry = {
+        id: nextSummaryId(entries),
+        type: "summary",
+        summary,
+        timestamp: Date.now(),
+    };
+    const nextEntries = [
+        ...metadataEntries,
+        summaryEntry,
+        ...keptEntries,
+    ];
+    return {
+        compacted: true,
+        summary,
+        entries: nextEntries,
+        droppedEntries: oldEntries.length,
+    };
+}
+export function compactMessages(messages, options = {}) {
+    const keepRecentTurns = options.keepRecentTurns ?? 2;
+    const maxSummaryItems = options.maxSummaryItems ?? 4;
+    const systemMessages = messages.filter((message) => message.role === "system");
+    const nonSystemMessages = messages.filter((message) => message.role !== "system");
+    const turnStartIndexes = nonSystemMessages
+        .map((message, index) => (message.role === "user" ? index : -1))
+        .filter((index) => index >= 0);
+    if (turnStartIndexes.length <= keepRecentTurns) {
+        return { compacted: false };
+    }
+    const keepStartIndex = turnStartIndexes[Math.max(0, turnStartIndexes.length - keepRecentTurns)];
+    if (keepStartIndex <= 0) {
+        return { compacted: false };
+    }
+    const oldMessages = nonSystemMessages.slice(0, keepStartIndex);
+    const keptMessages = nonSystemMessages.slice(keepStartIndex);
+    const summary = buildMessageSummary(oldMessages, maxSummaryItems);
+    if (!summary) {
+        return { compacted: false };
+    }
+    const compactedMessages = [
+        ...systemMessages.map((message) => cloneMessage(message)),
+        {
+            role: "system",
+            content: `Previous conversation summary:\n${summary}`,
+        },
+        ...keptMessages.map((message) => cloneMessage(message)),
+    ];
+    return {
+        compacted: true,
+        summary,
+        messages: compactedMessages,
+        droppedEntries: oldMessages.length,
+    };
+}
+function buildCompactionSummary(entries, maxSummaryItems) {
+    const messages = entriesToMessages(entries);
+    return buildMessageSummary(messages, maxSummaryItems);
+}
+function buildMessageSummary(messages, maxSummaryItems) {
+    if (messages.length === 0) {
+        return "";
+    }
+    const userMessages = messages.filter((message) => message.role === "user");
+    const assistantMessages = messages.filter((message) => message.role === "assistant");
+    const toolCalls = collectToolCalls(messages);
+    const relevantFiles = collectRelevantFiles(toolCalls);
+    const toolFindings = collectToolFindings(messages, maxSummaryItems);
+    const goal = userMessages[0] ? summarizeContent(userMessages[0].content) : "Unknown";
+    const progress = userMessages.slice(0, maxSummaryItems).map((message) => `- ${summarizeContent(message.content)}`);
+    const decisions = assistantMessages
+        .map((message) => message.content.trim())
+        .filter(Boolean)
+        .slice(0, maxSummaryItems)
+        .map((content) => `- ${summarizeText(content)}`);
+    const lines = [
+        "Goal:",
+        `- ${goal}`,
+        "",
+        "Progress:",
+        ...(progress.length > 0 ? progress : ["- No user progress recorded"]),
+        "",
+        "Key Decisions:",
+        ...(decisions.length > 0 ? decisions : ["- No assistant decisions recorded"]),
+        "",
+        "Next Steps:",
+        ["- Continue from the most recent preserved turn"],
+        "",
+        "Relevant Files:",
+        ...(relevantFiles.length > 0 ? relevantFiles.map((file) => `- ${file}`) : ["- None captured"]),
+        "",
+        "Tool Findings:",
+        ...(toolFindings.length > 0 ? toolFindings.map((item) => `- ${item}`) : ["- None captured"]),
+    ];
+    return lines.flat().join("\n");
+}
+function entriesToMessages(entries) {
+    const messages = [];
+    for (const entry of entries) {
+        switch (entry.type) {
+            case "user_message":
+                messages.push({ ...entry.message });
+                break;
+            case "assistant_message":
+                messages.push({
+                    role: "assistant",
+                    content: entry.message.content,
+                    reasoning: entry.message.reasoning,
+                });
+                break;
+            case "tool_call": {
+                const last = messages[messages.length - 1];
+                if (last?.role === "assistant") {
+                    last.toolCalls = [...(last.toolCalls ?? []), { ...entry.toolCall }];
+                }
+                else {
+                    messages.push({
+                        role: "assistant",
+                        content: "",
+                        toolCalls: [{ ...entry.toolCall }],
+                    });
+                }
+                break;
+            }
+            case "tool_result":
+                messages.push({ ...entry.message });
+                break;
+            default:
+                break;
+        }
+    }
+    return messages;
+}
+function collectToolCalls(messages) {
+    return messages.flatMap((message) => message.role === "assistant" ? (message.toolCalls ?? []) : []);
+}
+function collectRelevantFiles(toolCalls) {
+    const files = new Set();
+    for (const toolCall of toolCalls) {
+        let parsed = {};
+        try {
+            parsed = JSON.parse(toolCall.arguments || "{}");
+        }
+        catch {
+            parsed = {};
+        }
+        for (const key of ["file", "path", "paths"]) {
+            const value = parsed[key];
+            if (typeof value === "string" && value) {
+                files.add(value);
+            }
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (typeof item === "string" && item) {
+                        files.add(item);
+                    }
+                }
+            }
+        }
+    }
+    return [...files].slice(0, 12);
+}
+function collectToolFindings(messages, maxItems) {
+    const findings = [];
+    const toolNameByCallId = new Map();
+    for (const message of messages) {
+        if (message.role === "assistant" && message.toolCalls) {
+            for (const toolCall of message.toolCalls) {
+                toolNameByCallId.set(toolCall.id, toolCall.name);
+            }
+            continue;
+        }
+        if (message.role !== "tool") {
+            continue;
+        }
+        const toolName = toolNameByCallId.get(message.toolCallId) ?? "tool";
+        findings.push(`${toolName}: ${summarizeText(message.content)}`);
+        if (findings.length >= maxItems) {
+            break;
+        }
+    }
+    return findings;
+}
+function summarizeContent(content) {
+    if (typeof content === "string") {
+        return summarizeText(content);
+    }
+    const textParts = content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text);
+    return summarizeText(textParts.join(" "));
+}
+function summarizeText(value) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= 140) {
+        return normalized || "(empty)";
+    }
+    return `${normalized.slice(0, 137)}...`;
+}
+function findLatestSummaryIndex(entries) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        if (entries[index].type === "summary") {
+            return index;
+        }
+    }
+    return -1;
+}
+function nextSummaryId(entries) {
+    return `${entries.length + 1}`;
+}
+function cloneMessage(message) {
+    if (message.role === "assistant") {
+        return {
+            ...message,
+            toolCalls: message.toolCalls?.map((toolCall) => ({ ...toolCall })),
+        };
+    }
+    if (message.role === "user" && Array.isArray(message.content)) {
+        return {
+            ...message,
+            content: message.content.map((part) => ({
+                ...part,
+                ...(part.type === "image_url" ? { image_url: { ...part.image_url } } : {}),
+            })),
+        };
+    }
+    return { ...message };
+}

package/dist/context/overflow.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Context-overflow detection.
+ *
+ * When the upstream provider rejects a request because the prompt exceeds
+ * the effective context window, we catch the error here so the agent can
+ * compact history and retry automatically.
+ */
+export declare function isContextOverflowError(error: unknown): boolean;
+export declare function isContextOverflowByUsage(inputTokens: number | undefined, contextWindow: number | undefined): boolean;