@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/context/overflow.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+const OVERFLOW_PATTERNS = [
+    /context[_ ]length[_ ]exceeded/i,
+    /exceeds the context window/i,
+    /exceeds the limit of\s+\d+/i,
+    /prompt is too long/i,
+    /prompt exceeds max(?:imum)? length/i,
+    /maximum prompt length/i,
+    /maximum context length/i,
+    /too many tokens/i,
+    // Gemini: "The input token count (N) exceeds the maximum number of tokens allowed (M)."
+    /input token count.*exceeds the maximum/i,
+];
+export function isContextOverflowError(error) {
+    if (!error)
+        return false;
+    const messages = [];
+    if (typeof error === "string") {
+        messages.push(error);
+    }
+    else if (error instanceof Error) {
+        messages.push(error.message);
+        const cause = error.cause;
+        if (cause instanceof Error)
+            messages.push(cause.message);
+        else if (typeof cause === "string")
+            messages.push(cause);
+    }
+    else if (typeof error === "object") {
+        const anyErr = error;
+        if (typeof anyErr.message === "string")
+            messages.push(anyErr.message);
+        const nested = anyErr.error;
+        if (nested && typeof nested === "object" && typeof nested.message === "string") {
+            messages.push(nested.message);
+        }
+    }
+    return messages.some((msg) => OVERFLOW_PATTERNS.some((re) => re.test(msg)));
+}
+export function isContextOverflowByUsage(inputTokens, contextWindow) {
+    if (!inputTokens || !contextWindow)
+        return false;
+    return inputTokens > contextWindow;
+}

package/dist/context/projector.d.ts

@@ -0,0 +1,34 @@
+import type { Message, ProviderMessage } from "../types.js";
+export interface ProjectionOptions {
+    mode?: "full" | "pruned" | "budgeted";
+    providerId?: string;
+    modelId?: string;
+    usageAnchorTokens?: number;
+    anchorMessageCount?: number;
+    /** Request tokens not represented by messages, such as active tool schemas. */
+    additionalInputTokens?: number;
+}
+export declare function projectMessages(messages: Message[], options?: ProjectionOptions): ProviderMessage[];
+/**
+ * Re-bound restored tool messages and divide a hard aggregate budget fairly
+ * across sibling calls. A historical 6MB JSONL entry therefore becomes safe
+ * at projection time even if it predates live-result normalization.
+ */
+export declare function boundToolOutputBatches(messages: ProviderMessage[], providerId: string, modelId: string): ProviderMessage[];
+/**
+ * Ensures every assistant `tool_calls` is followed (in order) by tool messages
+ * responding to each tool_call_id, with no foreign messages interleaved.
+ *
+ * This is a defensive sanitizer for the OpenAI/Kimi API contract — any drift
+ * (a meta system-reminder injected mid-turn, a streaming bug, a session
+ * resumed mid-tool-execution, a compaction split that drops a tool result)
+ * would otherwise produce a 400 like:
+ *
+ *   "tool_call_ids did not have response messages: edit:6"
+ *
+ * Strategy: for each assistant with tool_calls, gather any matching tool
+ * messages from the trailing window, drop orphan/interleaving entries, and
+ * synthesize placeholder tool messages for any tool_call_id with no captured
+ * result. Other messages keep their original order.
+ */
+export declare function repairToolCallChains(messages: ProviderMessage[]): ProviderMessage[];

package/dist/context/projector.js

@@ -0,0 +1,251 @@
+import { getContextBudget } from "./budget.js";
+import { compactCurrentTurnToolGroups, compactMessages } from "./compact.js";
+import { pruneMessages } from "./prune.js";
+import { formatInternalContextBlock, formatInternalReminderBlock } from "../agent/internal-reminder-sanitizer.js";
+import { DEFAULT_TOOL_OUTPUT_BYTE_LIMIT, TOOL_OUTPUT_BATCH_BYTE_LIMIT, truncateToolOutputForModel, } from "./tool-output-truncate.js";
+// Prefix-cache invariant: only the leading static system prompt is promoted to
+// the first provider message. Runtime meta reminders stay in the conversational
+// body at their original relative position, so a new per-turn reminder does not
+// rewrite the cacheable prefix before the existing history.
+export function projectMessages(messages, options = {}) {
+    const mode = options.mode ?? "full";
+    const projectedBody = [];
+    const systemContext = [];
+    let inLeadingSystemPrefix = true;
+    for (const message of messages) {
+        if (message.role === "system" && inLeadingSystemPrefix) {
+            systemContext.push(message.content);
+            continue;
+        }
+        if (message.role === "meta") {
+            inLeadingSystemPrefix = false;
+            if (message.includeInLlm !== false) {
+                projectedBody.push({
+                    role: "user",
+                    content: formatMetaMessage(message),
+                });
+            }
+            continue;
+        }
+        inLeadingSystemPrefix = false;
+        if (message.role === "system") {
+            projectedBody.push({
+                role: "user",
+                content: formatRuntimeSystemMessage(message),
+            });
+            continue;
+        }
+        if (message.role === "assistant" && isEmptyAssistantMessage(message)) {
+            continue;
+        }
+        projectedBody.push(cloneMessage(message));
+    }
+    const projected = [
+        ...(systemContext.length > 0
+            ? [{
+                    role: "system",
+                    content: systemContext.join("\n\n"),
+                }]
+            : []),
+        ...projectedBody,
+    ];
+    const repaired = repairToolCallChains(projected);
+    const bounded = options.providerId && options.modelId
+        ? boundToolOutputBatches(repaired, options.providerId, options.modelId)
+        : repaired;
+    if (mode === "pruned") {
+        return pruneMessages(bounded);
+    }
+    if (mode === "budgeted") {
+        const pruned = pruneMessages(bounded);
+        if (!options.providerId || !options.modelId) {
+            return pruned;
+        }
+        const budget = getContextBudget(options.providerId, options.modelId, pruned, options.usageAnchorTokens !== undefined && options.anchorMessageCount !== undefined
+            ? {
+                usageAnchorTokens: options.usageAnchorTokens,
+                tailMessages: pruned.slice(Math.min(options.anchorMessageCount, pruned.length)),
+                additionalInputTokens: options.additionalInputTokens,
+            }
+            : { additionalInputTokens: options.additionalInputTokens });
+        if (!budget.shouldCompact) {
+            return pruned;
+        }
+        // Escalating compaction: turn-level passes first, then sub-turn (single-turn
+        // bloat from many tool calls) as a finer-grained fallback. Each step only
+        // advances `working` if compaction actually fired, and re-checks the budget
+        // before deciding to escalate further.
+        let working = pruned;
+        const passes = [
+            () => compactMessages(working, { keepRecentTurns: 2 }).messages,
+            () => compactMessages(working, { keepRecentTurns: 1 }).messages,
+            () => compactCurrentTurnToolGroups(working, { keepRecentGroups: 2 }).messages,
+            () => compactCurrentTurnToolGroups(working, { keepRecentGroups: 1 }).messages,
+        ];
+        for (const pass of passes) {
+            const next = pass();
+            if (next)
+                working = next;
+            const after = getContextBudget(options.providerId, options.modelId, working, {
+                additionalInputTokens: options.additionalInputTokens,
+            });
+            if (!after.shouldCompact)
+                break;
+        }
+        // Compaction passes emit summaries as meta messages (first-class identity);
+        // the provider payload must stay provider-safe, so render them here the
+        // same way body meta messages are rendered above.
+        const providerSafe = working.map((message) => message.role === "meta"
+            ? { role: "user", content: formatMetaMessage(message) }
+            : message);
+        return boundToolOutputBatches(repairToolCallChains(providerSafe), options.providerId, options.modelId);
+    }
+    return bounded;
+}
+/**
+ * Re-bound restored tool messages and divide a hard aggregate budget fairly
+ * across sibling calls. A historical 6MB JSONL entry therefore becomes safe
+ * at projection time even if it predates live-result normalization.
+ */
+export function boundToolOutputBatches(messages, providerId, modelId) {
+    const bounded = [];
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        bounded.push(message);
+        if (message.role !== "assistant" || !message.toolCalls?.length)
+            continue;
+        const siblingCount = message.toolCalls.length;
+        const perResultByteLimit = Math.min(DEFAULT_TOOL_OUTPUT_BYTE_LIMIT, Math.floor(TOOL_OUTPUT_BATCH_BYTE_LIMIT / siblingCount));
+        for (let sibling = 0; sibling < siblingCount; sibling++) {
+            const toolMessage = messages[index + 1 + sibling];
+            if (!toolMessage || toolMessage.role !== "tool")
+                break;
+            const result = truncateToolOutputForModel(toolMessage.content, providerId, modelId, { hardByteLimit: perResultByteLimit });
+            bounded.push(result.truncated
+                ? {
+                    ...toolMessage,
+                    content: result.content,
+                    metadata: {
+                        ...toolMessage.metadata,
+                        truncated: true,
+                        toolOutputTruncation: {
+                            originalBytes: result.originalBytes,
+                            finalBytes: result.finalBytes,
+                            originalTokens: result.originalTokens,
+                            finalTokens: result.finalTokens,
+                            hardByteLimit: result.hardByteLimit,
+                            ...(result.limit ? { modelTokenLimit: result.limit } : {}),
+                        },
+                    },
+                }
+                : toolMessage);
+        }
+        index += siblingCount;
+    }
+    return bounded;
+}
+/**
+ * Ensures every assistant `tool_calls` is followed (in order) by tool messages
+ * responding to each tool_call_id, with no foreign messages interleaved.
+ *
+ * This is a defensive sanitizer for the OpenAI/Kimi API contract — any drift
+ * (a meta system-reminder injected mid-turn, a streaming bug, a session
+ * resumed mid-tool-execution, a compaction split that drops a tool result)
+ * would otherwise produce a 400 like:
+ *
+ *   "tool_call_ids did not have response messages: edit:6"
+ *
+ * Strategy: for each assistant with tool_calls, gather any matching tool
+ * messages from the trailing window, drop orphan/interleaving entries, and
+ * synthesize placeholder tool messages for any tool_call_id with no captured
+ * result. Other messages keep their original order.
+ */
+export function repairToolCallChains(messages) {
+    const result = [];
+    const consumed = new Set();
+    for (let i = 0; i < messages.length; i++) {
+        if (consumed.has(i))
+            continue;
+        const msg = messages[i];
+        if (msg.role === "tool") {
+            // Orphan tool message (no preceding assistant tool_call claims it). Drop it —
+            // the API rejects orphan tool messages too.
+            continue;
+        }
+        result.push(msg);
+        if (msg.role !== "assistant" || !msg.toolCalls || msg.toolCalls.length === 0) {
+            continue;
+        }
+        // Collect tool messages immediately following the assistant turn (allowing
+        // foreign messages in between to be skipped, then re-emitted in their
+        // original positions later).
+        const matched = new Map();
+        const expected = new Set(msg.toolCalls.map((tc) => tc.id));
+        for (let j = i + 1; j < messages.length && expected.size > 0; j++) {
+            const next = messages[j];
+            if (next.role !== "tool")
+                continue;
+            if (!expected.has(next.toolCallId)) {
+                // Orphan tool message — mark consumed so we don't emit it later.
+                consumed.add(j);
+                continue;
+            }
+            matched.set(next.toolCallId, next);
+            expected.delete(next.toolCallId);
+            consumed.add(j);
+        }
+        for (const tc of msg.toolCalls) {
+            const existing = matched.get(tc.id);
+            if (existing) {
+                result.push(existing);
+            }
+            else {
+                result.push({
+                    role: "tool",
+                    toolCallId: tc.id,
+                    content: `[no result captured for tool call ${tc.name} (${tc.id})]`,
+                });
+            }
+        }
+    }
+    return result;
+}
+function isEmptyAssistantMessage(message) {
+    const hasContent = message.content.trim().length > 0;
+    const hasToolCalls = !!message.toolCalls && message.toolCalls.length > 0;
+    // Reasoning-only assistant messages are not valid ChatCompletions history:
+    // providers require assistant history to contain user-visible content or
+    // tool_calls. Keep reasoning attached to real assistant/tool-call messages,
+    // but drop standalone thinking-only turns before provider projection.
+    return !hasContent && !hasToolCalls;
+}
+function formatMetaMessage(message) {
+    switch (message.kind) {
+        case "system-reminder":
+            return formatInternalReminderBlock(message.kind, message.content);
+        case "runtime-context":
+        default:
+            return formatInternalContextBlock(message.kind, message.content);
+    }
+}
+function formatRuntimeSystemMessage(message) {
+    return formatInternalContextBlock("runtime-system", message.content);
+}
+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/prune.d.ts

@@ -0,0 +1,26 @@
+import type { Message, ToolMessage } from "../types.js";
+export declare function pruneMessages<T extends Message>(messages: T[]): T[];
+/**
+ * Stamp a tool result as "projected in full" at the moment it is appended.
+ *
+ * markStableCurrentToolResultsForCache does the same thing one turn later, which
+ * is too late for the session log: the message is serialized to disk when it is
+ * appended, so a mark added afterwards never reaches the file and a resumed
+ * session re-prunes history the model had already been shown in full.
+ */
+export declare function markToolResultCacheStable(toolName: string, message: ToolMessage): void;
+export declare function markStableCurrentToolResultsForCache(messages: Message[]): void;
+/**
+ * Aggressive variant of pruneMessages: drops the content of every prunable
+ * tool output except the latest unresolved tool turn that the model still
+ * needs to reason over. Used as a last-resort microcompact pass when a
+ * standard prune hasn't reclaimed enough budget.
+ *
+ * Deliberately ignores `cacheStableProjection`, unlike pruneMessages. Honouring
+ * it here would make this a no-op — every result that has been sent once is
+ * marked — which is fine for the prefix cache and fatal for the two callers that
+ * depend on it: context-overflow (HTTP 400) recovery and the hard resident-memory
+ * limit. Losing the cache is the correct trade when the alternative is a run that
+ * cannot recover.
+ */
+export declare function aggressivePruneMessages<T extends Message>(messages: T[]): T[];

package/dist/context/prune.js

@@ -0,0 +1,171 @@
+const PRUNEABLE_TOOLS = new Set([
+    "read", "bash", "grep", "web_search", "web_fetch", "edit", "write", "glob",
+]);
+const TOOL_RESULT_KEEP_COUNT = 2;
+const MIN_PRUNE_LENGTH = 240;
+const CACHE_STABLE_PROJECTION_KEY = "cacheStableProjection";
+const CACHE_STABLE_FULL_PROJECTION = "full";
+export function pruneMessages(messages) {
+    const toolNameByCallId = new Map();
+    const pruneCandidates = [];
+    const protectedToolCallIds = collectProtectedToolCallIds(messages);
+    let protectedRetainedCount = 0;
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role === "assistant" && message.toolCalls) {
+            for (const toolCall of message.toolCalls) {
+                toolNameByCallId.set(toolCall.id, toolCall.name);
+            }
+            continue;
+        }
+        if (message.role !== "tool") {
+            continue;
+        }
+        if (isCacheStableFullToolResult(message)) {
+            continue;
+        }
+        if (protectedToolCallIds.has(message.toolCallId)) {
+            const toolName = toolNameByCallId.get(message.toolCallId);
+            if (toolName && shouldPruneToolResult(toolName, message.content)) {
+                protectedRetainedCount += 1;
+            }
+            continue;
+        }
+        const toolName = toolNameByCallId.get(message.toolCallId);
+        if (!toolName || !shouldPruneToolResult(toolName, message.content)) {
+            continue;
+        }
+        pruneCandidates.push({ index, toolName, message });
+    }
+    const keepBudget = Math.max(0, TOOL_RESULT_KEEP_COUNT - protectedRetainedCount);
+    const keepFrom = Math.max(0, pruneCandidates.length - keepBudget);
+    const keepIndexes = new Set(pruneCandidates.slice(keepFrom).map((candidate) => candidate.index));
+    return messages.map((message, index) => {
+        if (message.role !== "tool" || keepIndexes.has(index)) {
+            return message;
+        }
+        const candidate = pruneCandidates.find((item) => item.index === index);
+        if (!candidate) {
+            return message;
+        }
+        return {
+            ...message,
+            content: summarizePrunedToolResult(candidate.toolName, candidate.message.content),
+        };
+    });
+}
+/**
+ * Stamp a tool result as "projected in full" at the moment it is appended.
+ *
+ * markStableCurrentToolResultsForCache does the same thing one turn later, which
+ * is too late for the session log: the message is serialized to disk when it is
+ * appended, so a mark added afterwards never reaches the file and a resumed
+ * session re-prunes history the model had already been shown in full.
+ */
+export function markToolResultCacheStable(toolName, message) {
+    if (!shouldPruneToolResult(toolName, message.content))
+        return;
+    message.metadata = {
+        ...message.metadata,
+        [CACHE_STABLE_PROJECTION_KEY]: CACHE_STABLE_FULL_PROJECTION,
+    };
+}
+export function markStableCurrentToolResultsForCache(messages) {
+    const protectedToolCallIds = collectProtectedToolCallIds(messages);
+    if (protectedToolCallIds.size === 0)
+        return;
+    const toolNameByCallId = new Map();
+    for (const message of messages) {
+        if (message.role !== "assistant" || !message.toolCalls)
+            continue;
+        for (const toolCall of message.toolCalls) {
+            toolNameByCallId.set(toolCall.id, toolCall.name);
+        }
+    }
+    for (const message of messages) {
+        if (message.role !== "tool" || !protectedToolCallIds.has(message.toolCallId))
+            continue;
+        const toolName = toolNameByCallId.get(message.toolCallId);
+        if (!toolName || !shouldPruneToolResult(toolName, message.content))
+            continue;
+        message.metadata = {
+            ...message.metadata,
+            [CACHE_STABLE_PROJECTION_KEY]: CACHE_STABLE_FULL_PROJECTION,
+        };
+    }
+}
+function shouldPruneToolResult(toolName, content) {
+    if (!PRUNEABLE_TOOLS.has(toolName)) {
+        return false;
+    }
+    if (content.length < MIN_PRUNE_LENGTH) {
+        return false;
+    }
+    if (content.startsWith("Error")) {
+        return false;
+    }
+    return true;
+}
+function summarizePrunedToolResult(toolName, content) {
+    return `[${toolName} output omitted to control context size; original length ${content.length} chars]`;
+}
+function isCacheStableFullToolResult(message) {
+    return message.metadata?.[CACHE_STABLE_PROJECTION_KEY] === CACHE_STABLE_FULL_PROJECTION;
+}
+/**
+ * Aggressive variant of pruneMessages: drops the content of every prunable
+ * tool output except the latest unresolved tool turn that the model still
+ * needs to reason over. Used as a last-resort microcompact pass when a
+ * standard prune hasn't reclaimed enough budget.
+ *
+ * Deliberately ignores `cacheStableProjection`, unlike pruneMessages. Honouring
+ * it here would make this a no-op — every result that has been sent once is
+ * marked — which is fine for the prefix cache and fatal for the two callers that
+ * depend on it: context-overflow (HTTP 400) recovery and the hard resident-memory
+ * limit. Losing the cache is the correct trade when the alternative is a run that
+ * cannot recover.
+ */
+export function aggressivePruneMessages(messages) {
+    const toolNameByCallId = new Map();
+    const protectedToolCallIds = collectProtectedToolCallIds(messages);
+    for (const message of messages) {
+        if (message.role === "assistant" && message.toolCalls) {
+            for (const toolCall of message.toolCalls) {
+                toolNameByCallId.set(toolCall.id, toolCall.name);
+            }
+        }
+    }
+    return messages.map((message) => {
+        if (message.role !== "tool")
+            return message;
+        if (protectedToolCallIds.has(message.toolCallId)) {
+            return message;
+        }
+        const toolName = toolNameByCallId.get(message.toolCallId);
+        if (!toolName || !shouldPruneToolResult(toolName, message.content)) {
+            return message;
+        }
+        return { ...message, content: summarizePrunedToolResult(toolName, message.content) };
+    });
+}
+function collectProtectedToolCallIds(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        // A trailing user message is steered input (or a resumed session's new
+        // instruction), not the end of the tool batch. Stopping on it left the
+        // just-finished batch unmarked forever, so it stayed a live prune candidate
+        // and later batches rewrote its content mid-history — which both loses tool
+        // output the model may still need and invalidates the provider prefix cache.
+        if (message.role === "tool"
+            || message.role === "system"
+            || message.role === "meta"
+            || message.role === "user") {
+            continue;
+        }
+        if (message.role === "assistant" && message.toolCalls && message.toolCalls.length > 0) {
+            return new Set(message.toolCalls.map((toolCall) => toolCall.id));
+        }
+        break;
+    }
+    return new Set();
+}

package/dist/context/session-write-lock.d.ts

@@ -0,0 +1,20 @@
+/** Identity of one incarnation of a pid: the OS start time of the process that
+ * currently has it. Pids are recycled, so a pid that answers kill(0) may be an
+ * unrelated process; only a matching start time proves it is the same owner.
+ * Undefined when the platform cannot say, which callers treat as "unknown",
+ * never as "gone". Exported for tests. */
+export declare function processStartId(pid: number): string | undefined;
+/** Field 22 (starttime) counts clock ticks since boot, and lock files outlive
+ * reboots, so the boot id is part of the identity: the same pid and tick after
+ * another boot is a different process. The comm field may itself contain
+ * spaces and parentheses, hence the split after the last ")". Exported for tests. */
+export declare function linuxStartId(stat: string, bootId: string): string | undefined;
+/** A live owner held the lock past the bounded wait. Nothing was written. */
+export declare class SessionWriteLockBusyError extends Error {
+    constructor(path: string);
+}
+/** Synchronous short transaction lock. An owner is abandoned only when its
+ * process is provably gone: the pid no longer exists, or it now belongs to a
+ * different process incarnation. Live owners are never expired by age;
+ * contenders wait a bounded time for them, since transactions are short. */
+export declare function withSessionWriteLock<T>(path: string, action: () => T, waitMs?: number): T;